Restart Policies

Updates, kernel upgrades, renames and deployments often leave machines waiting for a restart. Restart Policies let Athena finish the job on your terms. You choose the maintenance windows, a deadline, the countdown notices users see, how many times they may snooze, and how servers and PIN-protected machines are treated. Each agent applies its policy itself, on its own clock, so a restart still happens on time when the machine can't reach the server. It works on Windows, Linux and macOS agents, and it runs entirely between your Athena server and its agents, so it works on an air-gapped network.

Where Restart Policies appear#

The list, fleet page, landing card and agent tab update live when an agent reports. Nothing on these pages polls. Times on the fleet page and agent tab are each agent's own clock.

Permissions

Restarting a machine on demand is a separate permission, agents.restart (see Permission Model).

Quick start#

1. Open Policies → Restart Policies and click New policy.
2. Give it a name, add one or more maintenance windows, check the deadline and notices, and click Save.
3. Under Assignments, pick the policy and a collection, tag or agent, and click +. Start with a small test collection.
4. Watch the Fleet tiles and the agents' Restart Policy tabs. While enforcement is off, agents report and nothing is restarted, so you can see what would happen.
5. When you are happy, tick Enforce restart policies on agents.

What counts as "restart pending"#

The agent checks for a pending restart every minute. When it finds a reason, a restart becomes pending, and the time it started counts toward the deadline. A restart of the machine closes it. These are the same reasons as the core Restart Pending inventory field.

The enforcement switch and the lease#

Enforce restart policies on agents, at the top of the Restart Policies page, is the master switch. It is off by default. While it is off, agents with a policy report what is pending and what they would do, and the agent tab says "Enforcement is off, so the agent only reports." Turning it on or off is audited as a warning.

Each agent keeps its policy for a lease of 14 days without contact. The server renews the lease when the agent connects, whenever you change a policy, assignment or the switch, and once a day on its own. When a lease runs out with no renewal, the agent stops restarting and only reports ("The agent's policy lease ran out without a refresh, so it only reports."). This means an agent can keep restarting for up to the lease length after the module stops being licensed, because an unlicensed server sends nothing.

• The lease length is set with the REST API only: PUT /api/restart/settings with leaseDays from 1 to 365.
• The daily refresh interval is the Modules:Restart:LeaseRefreshHours setting (default 24, minimum 1) in configuration.
• To re-send every connected agent its policy now, schedule the Restart Policy Lease Refresh task in Scheduled Jobs.

Creating a restart policy#

Click New policy, or the edit icon in a policy's row. The editor has the sections below. The policy list shows each policy's windows (for example Mon-Fri 02:00-04:00, or no window (deadline only)), its deadline and notices (deadline 72 h, notice at 60/15/5, 3 snoozes x 60 min), its server mode, where it is assigned, how many agents hold it, and whether it is enabled.

General

Maintenance windows

Add up to 20 windows. Each has Days (Mon to Sun), a Start and an End. Times are the agent's own local time, so one policy works across time zones. A window whose end is at or before its start crosses midnight and belongs to the day it starts; for example, Sun 22:00-04:00 runs from Sunday night into Monday morning. A start equal to the end is a whole 24 hours.

With no window, the machine restarts only at the deadline (or at a scheduled restart). Spread restarts over (minutes) (default 30, 0-240) moves each machine to its own fixed moment inside the window, so the whole fleet doesn't restart and reconnect at once. A machine always gets the same moment.

On clock changes, a window start that falls in the skipped hour moves to the first valid minute after it. A start in the repeated hour uses its first occurrence, and the window runs once.

Uptime and scheduled restart

• Restart when up longer than (days): off by default; 1-365 days when on (the editor suggests 30). Past this many days since the last boot, the machine gets a pending restart (Maximum uptime reached) that follows all the other rules: windows, notices, snooze and the deadline.
• Scheduled restart (cron): off by default (the editor suggests 0 3 * * 6, Saturday 03:00). It uses the same cron format as the Scheduler, and the editor previews the next 5 times in each agent's local time. Each time opens a 60-minute restart window of its own. If nobody is signed in, the machine restarts at that time (spread by up to 30 minutes, and never more than Spread restarts over). If someone is signed in, the countdown starts. A machine that is asleep, off or skipped during that hour has missed it. A missed restart is recorded but never caught up later. A schedule that fires more often than once an hour is refused. Every-other-week can't be written in cron.

Deadline

After the deadline, the restart ignores windows, signed-in users and battery, and snooze is no longer offered. Only an Athena remote session in progress delays it, up to the delay above. Servers in Notify only or Exclude mode, and PIN/FileVault machines with nobody signed in, are still not restarted.

Notifications and snooze

With a deadline, no countdown step or final notice may be longer than the deadline, and all snoozes together (snoozes × length) may not be longer than the deadline. Linux shows a terminal message and a desktop notification, but it can't offer snooze (see What users see).

Skip conditions

An Athena remote session in progress always holds off a restart before the deadline. A disconnected session doesn't count as signed in.

Servers

Machines running a server OS has three choices:

• Notify only, never restart (default): the signed-in user gets one information notice per pending restart, and the machine is never restarted by the policy, even after the deadline.
• Restart them like any other machine.
• Leave them out entirely: nothing is shown or restarted.

PIN and FileVault machines

Some machines ask for a PIN or password before Windows or macOS starts: BitLocker TPM+PIN, TPM+startup key, TPM+PIN+startup key, password or USB key protectors, or FileVault on a Mac (on, or about to be turned on). If Athena can't read the protection, it assumes input is needed (Unknown (could not be read)). These machines are never restarted while nobody is signed in, so someone is there to type the PIN. They restart when a user is signed in, for example at the deadline or when the user clicks Restart now. Until then their state is Waiting for a signed-in user.

Allow unattended restart of PIN/FileVault machines is off by default and needs Manage restart policies. Turning it on asks you to confirm, because it lowers disk protection for one boot:

• Windows: BitLocker is suspended for that one restart, so the disk opens without its PIN for that boot.
• macOS: the server sends the escrowed FileVault recovery key to the Mac for that one restart, and rotates it afterwards. This works only for Macs whose key is escrowed (see FileVault Recovery Keys) and while the BitLocker/FileVault module is licensed. Otherwise the Mac waits for a signed-in user as above.

Every use is audited. Saving a policy with this option on, or changing it, is audited as a warning.

How the agent decides#

Every minute, an agent with a pending restart works through these rules in order:

1. Report only if it holds no policy, the lease ran out, the policy is disabled or enforcement is off (Not managed).
2. Nothing to do if no reason is pending (Not pending).
3. Loop guard. The policy restarts a machine at most once per pending restart and at most twice in any 24 hours. If the same reasons are still there after its own restart, the machine is Still pending after restart and needs a person. If a restart was issued but the machine hasn't booted 15 minutes later, it is Restart failed. It isn't retried.
4. Servers follow the server mode.
5. Someone else's restart that is already scheduled on the machine is left alone and never cancelled (Restart scheduled elsewhere). After it, the user is warned again before any restart.
6. PIN/FileVault machines follow the pre-boot rule.
7. After the deadline: the final countdown runs, with no snooze (Overdue).
8. Before the deadline: a snooze is honoured (Snoozed), then the skip conditions apply (Pending). In a window or an open scheduled restart, the countdown starts (Countdown), or the machine restarts at its spread moment. Outside every window it waits for the next one (Scheduled), or for the deadline if there is no window (Pending).

What users see#

Every notice names the product, so users know the restart is genuine. The text is fixed; nothing from the policy is shown. The first sentence says when and why, for example: "Athena Endpoint Platform will restart this computer at 03:00 to finish installing updates." A scheduled restart says "for its scheduled restart", and one for uptime alone says "because its maximum uptime was reached". Then it says how often the user can still postpone, and the latest restart time if there is a deadline. The final countdown says "This restart was postponed as long as your organisation allows. Save your work now."

• Closing or ignoring a notice changes nothing. The restart goes ahead on schedule.
• Snooze postpones the restart by the snooze length. When it ends, the policy is checked again; in a window, a new countdown starts.
• Restart now ends the countdown, or the snooze, at once.
• A Notify only server gets an information notice: "…needs to restart this computer… Please save your work and restart when you can." It has only OK and closes by itself after 15 minutes.

Assignments#

An assignment links a policy to a collection, a tag or a single agent. Pick them in the two lists below Assignments and click +. New assignments go to the bottom. One policy can have several assignments.

• A lower priority wins, and the first match wins, whatever the target type. Use the up and down arrows to change the order.
• Assignments to disabled policies are skipped, so the agent gets the next match.
• An agent with no match is Not managed: it reports, and nothing is restarted.
• An assignment to a deleted collection matches nothing. A tag doesn't need to exist yet.
• Deleting a policy also deletes its assignments.

Changes reach connected agents straight away. The editor lists a policy's assignments, but you add and reorder them on the Restart Policies page.

Agents connected to several servers

An agent that talks to more than one Athena server keeps the first restart policy it receives. It ignores other servers' policies until that server withdraws its policy or the lease ends. The agent tab says which server's policy is in force, for example "Another server's policy is in force: …".

Fleet view and states#

The Fleet tiles on the Restart Policies page count agents in each state. Each tile opens the Agents list filtered by that state. Overdue is highlighted as a warning. Still pending after restart and Restart failed are highlighted as critical. The Pending restart page lists every waiting agent, oldest first, with its OS, pending since, reasons, policy, state, next action (and next scheduled restart), snoozes and last reboot.

Agent details → Restart Policy

The read-only Restart Policy tab shows the Effective policy (name and revision, or Not managed with the reason), which server's policy is in force, Pending since, Last reboot and uptime, Next action, Next scheduled restart (and any missed one), Pre-boot input, Why a restart is pending and Recent events. An agent that has never reported shows "This agent has not reported its restart state yet. Agents older than this feature never do."

Filter fields#

These fields work in the Agents list, dynamic collections and monitors, so you can alert on, for example, overdue machines. While the module is not licensed they read as not applicable. See the Filter Field Reference.

For example, /agents?field=Module.restart.State&value=Overdue lists every overdue agent.

Audit events#

See the Audit Event Types Reference and Audit Forwarding to SIEM.

REST API#

All routes are under /api/restart. view routes need restart.view and manage routes need restart.manage. Without the licence every route returns 403. Choices travel as names (for example "serverMode": "Enforce"). Out-of-range values return 400 and are never adjusted.

A policy body uses these fields: name, description, enabled, deadlineHours (null = no deadline; the API's default), finalNoticeMinutes, countdownMinutes, maxSnoozes, snoozeMinutes, skipOnBattery, activeUserBehaviour (Countdown, WaitForNoUser, Ignore), noUserRestartImmediately, serverMode (Enforce, NotifyOnly, Exclude), restartOnFileRenameOnly, jitterMinutes, remoteSessionDeferMinutes, allowUnattendedPrebootRestart, maxUptimeDays (null = off), scheduleCron (null = none) and windows. Each window is dayMask (Mon=1, Tue=2, Wed=4, Thu=8, Fri=16, Sat=32, Sun=64, added together), startMinute (0-1439, minutes after midnight) and durationMinutes (1-1440).

For example, a policy for workstations with a Monday-to-Friday 02:00-04:00 window and a 72-hour deadline:

curl -k -X POST -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"name":"Workstations","deadlineHours":72,
       "windows":[{"dayMask":31,"startMinute":120,"durationMinutes":120}]}' \
  "https://<server>:8443/api/restart/policies"

Then turn enforcement on:

curl -k -X PUT -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"enforcementEnabled":true}' "https://<server>:8443/api/restart/settings"

Troubleshooting#

Related#

• Restarting Computers: restart a machine on demand.
• Policies: the group this module belongs to.
• Collections and Agent Tags: the groups you assign policies to.
• BitLocker Management and FileVault Recovery Keys: pre-boot protection and escrowed keys.
• Windows Update Management: one common source of pending restarts.
• Licensing: separately licensed modules.