Update Schedules
Update schedules automate the maintenance of your hosts. You can plan one-time or recurring updates and combine them with scripts, playbooks, and health checks.
Creating a Schedule
- Navigate to the desired module
- Select the Jobs tab
- Click Create Schedule
Configuration
| Field | Description |
|---|---|
| Name | Name of the schedule |
| Action Type | Update, Script, or Playbook |
| Update Type | Type of update (module-specific, see below) |
| Target | Who will be updated (see target types) |
| Schedule Type | One-time, daily, weekly, monthly, or Cron |
| Date/Time | Execution time |
| Script | Script from the library (for action type "Script") |
| Playbook | Playbook (for action type "Playbook") |
Action Types
Each schedule can have one of three action types:
| Type | Description |
|---|---|
| Update | Execute a system update with the configured update type |
| Script | Execute a script from the library |
| Playbook | Execute a playbook with all steps |
Target Types
Schedules can be applied to different targets:
| Target | Description |
|---|---|
| All Hosts | All hosts of the module are updated |
| Customer | All hosts of a specific customer, optionally of one site only (since v3.38.0) |
| Group | All hosts of a specific host group |
| Single Host | A specific host |
Device Type (Windows and macOS)
Windows and macOS jobs have an additional Device type field: All device types, Servers only (incl. domain controllers) or Workstations only. It applies within the selected target, for example "All Hosts" + "Servers only". It is based on the product type reported by the agent; hosts without a detected type are always included.
This lets you update workstations during the day (while they are switched on) and servers at the weekend without maintaining groups: two jobs on "All Hosts", one with Workstations only daily at 12:00 and one with Servers only weekly at night. The job list shows a badge next to the target, and "Show affected" respects the filter.
Update Types
OPNsense
| Type | Description |
|---|---|
| System Update | Packages only, never a reboot; base/kernel stays open as reboot pending |
| Update + Reboot | Full update incl. base/kernel, reboot only when required; HA pairs rolling (BACKUP → MASTER) |
| Major Upgrade | Major releases step by step up to the target (YY.1/YY.7, Business YY.4/YY.10) or Latest, regular update in between, two reboots per step (details) |
OPNsense-specific options (since v3.7.0, details: OPNsense HA Updates):
| Option | Description | Default |
|---|---|---|
| HA mode | Rolling / skip HA pairs / parallel (dangerous) | Rolling |
| Settle time | Wait between the BACKUP and the MASTER step | 300 s |
| If a peer is offline | Skip the pair or update the online node anyway | skip |
| Retries | Repeated attempts on mirror/network errors | 3 |
| Health check timeout | Wait for the return after the reboot | 900 s |
| Maintenance window | No new steps after it ends; a start > 30 min late counts as missed | 180 min |
Firewalls with agent < 3.7.0 are skipped in runs. The result of every run (steps, error class, output) is shown in the Jobs tab; failed runs can be resumed there.
Proxmox VE
| Type | Description |
|---|---|
| System Update | apt update && apt dist-upgrade without reboot |
| Update + Reboot | Update with reboot |
| Major Upgrade | Proxmox VE version upgrade (e.g., 7.x → 8.x) |
Proxmox Backup Server
| Type | Description |
|---|---|
| System Update | apt update && apt dist-upgrade without reboot |
| Update + Reboot | Update with reboot |
| Garbage Collection | Run datastore GC |
| Verify | Verify backup integrity |
| Prune | Prune old backups |
| Sync | Synchronize datastore |
For PBS datastore actions, the target datastore can also be specified.
Linux
| Type | Description |
|---|---|
| System Update | apt upgrade -y / dnf upgrade -y |
| Update + Reboot | Update with reboot |
Windows
| Type | Description |
|---|---|
| Windows Update | Install all available Windows updates |
| Update + Reboot | Updates with reboot |
macOS
| Type | Description |
|---|---|
| Security updates | Security updates, Rapid Security Responses and XProtect |
| All macOS updates | All offered macOS updates |
| Update Homebrew | brew upgrade including casks as the owner of the Homebrew installation |
The Allow restart option (not for Homebrew) only applies to Intel Macs. Apple Silicon only downloads updates and notifies the logged-in user; without MDM macOS cannot install there without a user. For the device type, Mac mini, Studio and Pro count as servers, MacBooks and iMacs as workstations (changeable in the detail panel). See macOS.
Reboot (since v3.43.0)
Windows, Linux and macOS have the update type Reboot. It restarts the target hosts at the scheduled time without installing updates, e.g. a nightly reboot of terminal servers or a weekly reboot of workstations.
| Option | Effect |
|---|---|
| Only if the computer has been running for at least X days | 0 = always. With 14 and a daily job: reboot as soon as a computer has been up for two weeks |
| Only if a reboot is pending | Windows: pending reboot from updates/installations; Linux: /var/run/reboot-required or needs-restarting -r. Not on macOS |
| Do not reboot while someone is signed in | Windows: active session (incl. RDP); Linux: who; macOS: console user (almost always on workstation Macs) |
| Warning | 1 to 120 minutes. Signed-in users see the message with your text (Windows) or a system message (Linux) |
Control generates a script for this, no agent update is needed. The log says why a host was rebooted or not (e.g. Kein Neustart: angemeldet - anna). Hosts in maintenance or out of service are skipped. New hosts are never rebooted during onboarding.
From v3.48.2: a computer that was switched off at the scheduled time does not catch up on the reboot later. The task expires after the job's maintenance window (60 minutes if none is set) and shows as expired in the log. Before, a workstation switched on in the morning rebooted in the middle of the day.
Patch rings: defer updates (since v3.69.0)
Windows update jobs (Windows Update, Update + Reboot) have the option Install updates only when they are at least X days old. Microsoft's release date counts (last_deployment_change_time). Antivirus definitions still go immediately unless you tick Also defer antivirus definitions. Updates without a date are not deferred.
Build rings like this: one job for the pilot group with 0 days, a second job for everyone else with e.g. 7 days. If the pilot group shows a problem, block the update in the patch policy before the others get it. The deferral works with and without a patch policy (without a policy Control sends the list of updates that are old enough instead of install everything). If nothing is old enough, the job skips the machine.
Feature update (since v3.68.0)
The Windows type Feature update brings workstations to a new Windows 11 version (in-place upgrade, e.g. 23H2 to 25H2), optionally also Windows 10 to Windows 11. Servers are skipped.
| Option | Effect |
|---|---|
| Target version | Latest (default, since v3.68.1) or a specific version like 24H2. Latest = value of the setting windows_feature_latest (Settings > Parameters, currently 25H2); raise it when a new Windows version is released. Machines on this or a newer version are skipped. The Installation Assistant installs the version Microsoft currently ships through it (currently 24H2, build 26100) - see below |
| Also Windows 10 to Windows 11 | Off by default |
| Skip when someone is signed in | On by default (active session, also RDP) |
| Reboot afterwards | On by default, with warning (1 to 120 minutes). Off: the upgrade completes on the next reboot |
| Minimum free on C: | 25 GB by default |
| Source | Installation Assistant (downloaded from Microsoft, signature "Microsoft Corporation" is checked) or own ISO (https://...iso or network share, e.g. for LTSC/Enterprise or a fixed version; setup.exe /auto upgrade /quiet /noreboot). Since v3.72.4 https addresses may carry parameters after .iso (up to 2000 characters). Download links from microsoft.com expire after 24 hours, though - for recurring jobs put the ISO on your own share or web server |
| Allow unsupported hardware (since v3.71.2) | Off by default, own ISO only. setup.exe then runs with /product server (skips the TPM, Secure Boot and CPU list checks) and AllowUpgradesWithUnsupportedTPMOrCPU is set. Microsoft does not support this; such machines may not receive later feature updates. CPUs without POPCNT/SSE4.2 cannot be upgraded either way |
Control generates a PowerShell script (no agent update needed). It checks version, edition, pending reboot, disk space, battery (AC power only), signed-in users as well as TPM 2.0, Secure Boot and 4 GB RAM (since v3.71.2 also on Windows 11; without the bypass = failed with reason), downloads the source to C:\ProgramData\DATAZONE\FeatureUpdate and prepares the upgrade. Progress shows in the live output in Logs. Then the machine reboots and installs the new version (30 to 60 minutes).
If Windows aborts the preparation (since v3.71.2), the script reads the error code (MoSetup\Volatile\BoxResult, e.g. 0xC1900200 = hardware not suitable) and the hard blocks from CompatData*.xml (e.g. CPU not supported, no TPM 2.0, no UEFI/Secure Boot). The attempt is then failed with this reason and the machine does not reboot. Before, it was marked prepared, rebooted and nothing happened.
24H2 and 25H2: the Installation Assistant ships 24H2. 25H2 builds on it and follows as a small enablement package via Windows Update. A machine that lands on 24H2 with target 25H2 therefore counts as done (with a note). Machines already on 24H2 are skipped on the assistant path. To go straight to 25H2, use a 25H2 ISO.
Control decides itself whether it worked, based on the reported version: if the machine reports the target within 6 hours after the reboot, the attempt is done, otherwise failed with a pointer to the logs (C:\$WINDOWS.~BT\Sources\Panther\setuperr.log). The waiting time only runs out against a machine that is online (after a reboot since the attempt only after 1 hour of uptime) - a PC switched off over the weekend does not fail. If an attempt that failed by timeout reaches the target later (up to 30 days), it is corrected to done. Battery mode means the battery is discharging or low (on AC, full or charging = AC). GET /api/windows/feature-updates returns the history (per machine and job). Only one attempt runs per machine; the job never runs when new machines are onboarded.
Tip: schedule the job in the evening or at the weekend and test on a small group first. A run takes 1 to 3 hours per machine (download approx. 4 GB).
Schedule Types
| Type | Description | Configuration |
|---|---|---|
| One-time | Executes once at the scheduled time | Date + Time |
| Daily | Every day at the same time | Time |
| Weekly | On the same day of the week at the same time | Day of week + Time |
| Monthly | On the same day of the month | Day (1-31) + Time |
| Cron | Free cron expression for complex schedules | Cron expression |
Cron Expressions
For advanced schedules, a free cron expression is available:
Minute Hour Day Month Weekday
* * * * *Examples:
| Cron Expression | Meaning |
|---|---|
0 2 * * * | Every day at 02:00 |
0 3 * * 0 | Every Sunday at 03:00 |
0 4 1 * * | On the 1st of every month at 04:00 |
0 22 * * 1-5 | Monday through Friday at 22:00 |
0 */6 * * * | Every 6 hours |
Combining Scripts
Update schedules can be combined with scripts from the script library:
Pre-Update Script
Runs before the update. Typical use cases:
- Stop services
- Create a backup
- Enable maintenance mode
Post-Update Script
Runs after the update (and reboot, if applicable). Typical use cases:
- Verify services
- Adjust configuration
- Send notification
OPNsense Exception
For OPNsense schedules, scripts are available via the playbook mechanism, not as a direct pre-/post-script option.
Managing Schedules
Overview
In the module view under Jobs, you can see all scheduled and completed updates:
- Name and update type
- Next scheduled execution
- Last execution and status
- Target (host, group, customer, all)
- Active/Inactive status
Modifying a Schedule
- Click on a schedule in the list
- Modify the configuration
- Save
Deleting a Schedule
Click the trash icon next to a schedule to remove it.
Offline Hosts and Catch-up
When a host is offline at the scheduled time, the job is not lost. DATAZONE Control provides an intelligent catch-up system:
Catching Up Missed Jobs
For recurring schedules, you can configure whether missed jobs should be caught up:
| Option | Description |
|---|---|
| Catch up missed jobs | Checkbox: Should the job be caught up on reconnect? (Default: Yes) |
| Catch-up window | Maximum time in hours that a missed job remains valid (Default: 24h) |
Available catch-up windows:
| Window | Use case |
|---|---|
| 6 hours | Short-term maintenance jobs |
| 12 hours | Night jobs that should still run the next morning |
| 24 hours (Default) | Daily jobs |
| 48 hours | Cover weekend outages |
| 72 hours | Hosts that may be offline for up to 3 days |
| 1 week | Long-term offline scenarios |
How Does Catch-up Work?
- The scheduler creates the task at the scheduled time, even if the host is offline
- If the host is offline, the task remains pending in the queue
- Older pending tasks for the same schedule are automatically marked as expired (deduplication)
- As soon as the agent reconnects, all valid pending tasks are delivered
- Tasks older than the catch-up window are discarded
Example
A weekly update job is scheduled for Sunday at 03:00. The host is off from Friday to Monday. On Monday at 08:00 the agent connects:
- Catch-up window 24h: Task is discarded (older than 24h)
- Catch-up window 72h: Task is caught up (younger than 72h)
- Catch-up disabled: Task is discarded
Deduplication
If a host is offline for an extended period and the scheduler creates multiple tasks (e.g., 10 daily updates in 10 days), only the newest task is caught up. All older ones are automatically marked as expired.
Disabling Catch-up
Set the catch-up window to 0 (uncheck the checkbox) to completely disable catch-up. In this case, tasks are only delivered if the host is online at the scheduled time.
One-time Jobs Wait for Offline Hosts (since v3.49.0)
One-time jobs now have the option as well, named Wait for offline hosts, with a maximum waiting time of up to 30 days (2 weeks and 30 days added to the choices):
- Hosts that are offline at the start still get their task. It waits until the host reports back and runs then - at most until the waiting time ends.
- With the target All hosts, offline hosts last seen within the waiting time count as well. Hosts that have been dead for longer never get anything. Without the option (and for recurring jobs) "All hosts" still means only hosts that are online right now.
- Customer, group, site or single-host targets always worked this way: the task is created for every target host, offline hosts catch up.
- The 7-day cleanup (see below) closes waiting tasks of a one-time job only after its waiting time.
- OPNsense update runs do not wait: they only plan firewalls that are online at the start.
In the job list a pill waiting for N hosts (offline) shows for how many offline hosts a task of the job is still waiting. This applies to every job, including recurring jobs with catch-up.
Recurring jobs are unchanged: catch-up window up to 1 week, "All hosts" online only.
Stuck Tasks Are Closed Automatically
Since 3.13.0 the scheduler closes tasks every minute that can never finish, so the task bar, the host logs and the "something is still running on this host" lock stay honest:
| State | After | Result |
|---|---|---|
| In progress without a result (e.g. reboot, agent update or crash in the middle of the task) | 24 hours | failed, error text "Kein Ergebnis vom Agent innerhalb von 24 h - automatisch beendet" |
| Script or check in progress without a result (from v3.69.10) | three times the script time limit + 60 min (default limit 5 min = after 75 min) | failed, error text "Keine Rueckmeldung vom Agent ... vermutlich nie beim Agent angekommen" (the task most likely never reached the agent); checks get the result "unknown". The next run happens as usual |
| Pending, never delivered (host permanently offline) | 7 days (one-time job waiting for offline hosts: its waiting time, up to 30 days) | expired |
| Task without a host (host was deleted) | immediately | expired |
| Playbook execution without progress | 24 hours | failed |
Tasks of an active OPNsense update run are excluded; the run decides itself with its own time limits. Every closure is recorded with its reason in the task and as an audit entry auto_expire_tasks with the counts. A result the agent reports after the closure is discarded, as for any other finished task.
Onboarding New Hosts
When a new host registers with DATAZONE Control for the first time, it normally has to wait until the next scheduled time. The onboarding feature can bypass this.
Run Immediately on New Host
Enable the option Run immediately on new host on a recurring schedule. When a new host registers for the first time, the job is automatically created and delivered - also when the host is assigned to a customer, group or site later (up to 30 days after it was added).
| Option | Description |
|---|---|
| Run immediately on new host | Checkbox: Job runs on first connect of a new host, or as soon as the host later enters the job's target (Default: No) |
How Does Onboarding Work?
- A new host registers for the first time (
last_seenis empty) - The system finds all active, recurring schedules with onboarding enabled
- For each matching schedule (directly assigned, via group, customer, site, or global), a task is created
- The tasks are immediately delivered to the agent
- Control remembers per job and host that onboarding ran - every job runs only once per host
Later Assignment (since v3.49.0)
New hosts often arrive without a customer or in the placeholder customer ONBOARDING and without a group. Customer, group and site jobs do not match yet at that point. That is why the scheduler checks every minute:
- all hosts that have been in Control for at most 30 days and are online right now,
- whether an onboarding job now matches them that has not run for this host yet.
So as soon as you assign the host to the customer, group or site, the matching onboarding job runs (for an offline host, as soon as it reports back). The same job never runs twice on the same host.
- Existing hosts get nothing retroactively: only hosts added after the introduction (update to 3.49.0) are considered.
- Hosts in a one-time maintenance or out of service are skipped like for scheduled jobs; onboarding follows once the state ends (within the 30 days).
- As on first contact: no reboot, no major upgrade, reboot jobs are left out.
New onboarding job
If you create a new job with Run immediately on new host (or enable the option later), it also runs on matching hosts that were added within the last 30 days and are online - it has not run for them yet.
Typical Use Case
You have a weekly update schedule for the group "Production Servers". A new server is added to the group and the agent is installed. With onboarding, it gets its first update immediately, instead of waiting until next Sunday.
Bulk Updates
You can also start updates for multiple hosts at once:
- Select multiple hosts using the checkboxes
- Click Bulk Update
- Choose the update type
- Confirm the execution
Note
Bulk updates are started simultaneously on all selected hosts. For critical infrastructure, plan staggered updates via schedules.
Behaviour since v3.14.2
- One-time jobs need a date. Without
schedule_datethe API rejects the job (400). Before, "no date" meant "now", so editing or enabling a job started it on the next tick. - Cron schedules work. The expression is evaluated in the instance timezone (setting
timezone); invalid expressions are rejected with 400. Before, the cron type was ignored and the job fired every minute. - Monthly on the 29th/30th/31st runs on the last day of shorter months instead of silently slipping.
- Editing recalculates the next run only when timing fields change. Pausing/enabling or renaming starts nothing; a one-time job keeps its date.
- Deleted targets deactivate their jobs. Deleting a host, group, customer, check, script or playbook deactivates the affected jobs (status
deaktiviert: ... geloescht). Before, the job stayed active and meant "all hosts" or fell into the update branch. - "All hosts" = hosts with a heartbeat in the last 120 seconds (Windows: 5 minutes). For Proxmox VE, PBS and Linux this case never ran before (bug in the filter).
- Linux jobs get a next run when created (before: never, when the form sent no
next_run). - Script jobs for Linux and Windows now create a task type the agent knows; the scripts' pre-/post-hooks are passed along.
- Jobs on new hosts (
run_on_new_host) create the same tasks as the schedule itself (OPNsense: packages only, no reboot - the CARP state of a new host is unknown). - Run now still takes every host of the target, offline ones included; those tasks are delivered within the catch-up window. Use with care for reboot updates.
- A Windows device type unknown matches every filter (even when the agent literally reports "Unknown").