Automation

Scheduled tasks

Scheduled tasks restart, stop, start, update or back up a service, send RCON commands, run scripts or send notifications on a timetable you set with a cron expression.

Tasks run on the node, not on the controller. The controller stores the tasks and sends them to the node with the service’s spec; the agent keeps them on disk and fires them itself. A 06:00 restart therefore happens even while the controller is down for maintenance, and results made while the controller was unreachable are reported when it comes back.

Service tasks live on the service’s Schedule tab; global tasks on the Schedules page (left menu, administrators). The editor offers presets, shows the next runs as you type the cron expression, and only shows the fields the chosen action needs.

Service tasks and global tasks

A service’s schedule view lists its own tasks and, read-only, the global tasks that apply to it. Example of a global task: restart every ArmA 3 server on node 3 at 05:00 Europe/Berlin.

When a task runs

Each task has a cron expression and an IANA time zone (default UTC).

The cron expression has five fields: minute, hour, day of month, month, day of week.

@every and seconds fields are not accepted. Time zones are names like Europe/Berlin or America/Chicago; daylight-saving changes follow the zone. The panel shows the next three runs of each task, and you can check an expression before saving:

curl -s "https://panel.example.com/api/v1/schedule-preview?cron=0%206%20*%20*%20*&timezone=Europe/Berlin" \
  -H "Authorization: Bearer ngcpk_..."

The agent checks its tasks once a minute.

• If the agent’s machine was busy or asleep for up to five minutes, tasks due in that gap still run.
• Tasks missed during a longer gap (the agent or node was off) are not run late. They run at their next time.
• The agent remembers which minute each task last fired, so an agent restart never runs a task twice.

Actions

Only SuperAdmins and Admins can create, change or delete script tasks, and the script text of a global task is hidden from everyone else. Scripts run with the service’s limits and its account’s rights, never as the agent.

A backup task can use any backup target when an administrator creates it; other users can only pick targets marked user selectable.

Only when empty

For restart, stop and update: if the game’s status query reports players online, the run is skipped (“3 players online”). If the player count is unknown (no query, or no answer), the task runs.

Warning players

For restart, stop and update, warn minutes (1-60) sends a message to everyone on the server that many minutes before the task, over RCON:

• with your message if you set one;
• otherwise “Server restart in 10 minute(s).”, “Server shutdown in …” or “Server update and restart in …”.

The warning needs an RCON section in the game definition. If it fails, the console says so and the task still runs on time.

Scheduled updates

Steam logins live on the controller, so the agent cannot update a game by itself. An update task asks the controller to start the service’s Update action:

• If the controller is unreachable when the task is due, the run is skipped (“controller unreachable; updates need it”).
• The controller ignores the request if the service is installing, suspended or being deleted.
• An update of a running server stops it, updates, and starts it again.

Run history

Every run is recorded with its time, whether it succeeded, was skipped or failed, and a message (for example the backup’s file name, the RCON answer, or the error). The service’s console also gets a line such as:

scheduled task "Nightly restart" (restart) done
scheduled task "Nightly restart" (restart) skipped: 2 players online

curl -s https://panel.example.com/api/v1/services/12/schedule-runs -H "Authorization: Bearer ngcpk_..."

Runs that happened while the controller was down are kept in an outbox on the node and delivered when the link returns, with their real time. The history is kept for 90 days.

A failed run (not a skipped one) sends a schedule.failed notification.

Creating a task through the API

curl -s -X POST https://panel.example.com/api/v1/services/12/schedules \
  -H "Authorization: Bearer ngcpk_..." -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly restart",
    "cron": "0 6 * * *",
    "timezone": "Europe/Berlin",
    "action": "restart",
    "params": {"only_when_empty": false, "warn_minutes": 10, "message": "Daily restart in 10 minutes"},
    "enabled": true
  }'

A global task takes the same body plus a selector:

{
  "name": "Update all ArmA servers on node 3",
  "cron": "0 5 * * *",
  "timezone": "UTC",
  "action": "update",
  "params": {"only_when_empty": true, "warn_minutes": 5},
  "selector": {"game_id": "arma3", "node_id": 3},
  "enabled": true
}

An rcon global task on a selection that includes games without RCON reports those runs as failed. Disabled tasks are kept but not sent to the node.

Good to know

• Changing a task sends the new schedule to the node at once; an offline node gets it when it reconnects.
• A deleted service’s tasks stop with it.
• A backup and a restore never run at the same time for one service; a second one is refused with “a backup is already running for this service”.
• Time zones are IANA names (Europe/Stockholm, America/Chicago). The controller and the agent carry their own time-zone database, so they work the same on Windows and Linux, and daylight-saving changes are followed: a 06:00 task runs at 06:00 local time all year.