58. Maintenance windows: approve now, apply in the window

A maintenance window says when approved hardening may change a set of hosts: every week on chosen days (for example Sunday 02:00 for 4 hours), or once on a date, in a time zone you choose. It covers a host group (the hosts listed in the group) or a list of hosts.

A hardening batch (chapter 57) can be started in a window: it is approved now, with the same four-eyes as any batch, and nothing reaches a host until the window opens. When the window opens, every host of the batch that is online is changed; a host that is offline for the whole window, or that does not pick its changes up before the window ends, is missed and left unchanged. Changes that need a restart can be restarted inside the window, only when the batch was approved with Restart in window.

58.1 Procedure: create a window#

1. Open Hardening and press Maintenance windows (top right), then New window.
2. Fill in:
   • Name - unique, for example "Sunday night patching";
   • Time zone - an IANA name such as Europe/Berlin, America/New_York or UTC (the list suggests them as you type);
   • Repeats - Every week with the days ticked, or Once with a Date;
   • Starts at - the local time in the window's time zone, and Length (minutes): 15 to 1440 for a weekly window (it may run past midnight), up to 7 days for a one-off;
   • Covers - Chosen hosts (tick them; Filter hosts narrows the list) or A host group (the hosts listed in the group; a host matched only by a tag is not covered);
   • Enabled - a disabled window has no coming times and no batch can be started in it.
3. Press Save window. What you see: the window's line, for example "Sun 02:00-06:00 Europe/Berlin", "Covers 3 host(s)" and its next three times in your own time zone.

Daylight saving time: the window follows the wall clock of its time zone. A start that falls in the hour the clocks skip (spring) begins at the same instant as the time just before the change - 02:30 on the night clocks jump from 02:00 to 03:00 begins at 03:30. A start in the hour that happens twice (autumn) begins the first time. The length is always real minutes: a 4-hour window is 4 hours long even on the night the clocks change.

58.2 Procedure: start a batch in a window#

1. Start a batch as usual: Hardening > Planner > Plan N hosts (57.2) or a scan's Fix plan (57.3), and choose the controls.
2. Under When the live batch runs, choose:
   • At approval - as before: every host is changed when the batch is approved;
   • In a maintenance window - then pick the window. Every host of the batch must be covered by it, or the batch is refused with "Some chosen hosts are not in the scope of the maintenance window" and the hosts named;
   • In the next window that covers every host - Lawliet picks the enabled window that covers all chosen hosts and opens first.
3. Optional:
   • Try missed hosts again in the window's next occurrence - a missed host waits for the next time the window opens, instead of being left out;
   • Restart in window (off by default; needs Restart hosts after hardening) - see 58.4. Domain controllers too is a separate tick: without it a domain controller is never restarted. Warn users ... minutes before is the warning delay (0 - 60, default 5).
4. Press Enforce on M hosts / Start hardening on M hosts. What you see: "Batch #id: waiting for approval, then applied in the maintenance window <name>". A dry run ignores the window and runs at once.

58.3 Procedure: approve, and follow a batch in a window#

1. On Hardening > Batches the batch reads "after approval, applied in window <name>".
2. Press Approve batch, then Confirm: change M hosts in window <name> (", restarting them" when Restart in window is on). With dual control on, the approval request a second officer signs reads "... applied in maintenance window N '<name>' (waits for the window); RESTART IN WINDOW: on (domain controllers never restarted)" or "restart in window: off".
3. What you see: the batch status waiting for its window and "waiting for window <name> at <time>". Each host reads "Window: waiting for the window (<time>)". Nothing has been sent to any host.
4. When the window opens (Lawliet checks every 30 seconds), each online host is changed exactly as an approved batch would be: the planner's checks run again against the host as it is now, and a host they refuse reads "refused at the window start" with the reason. An offline host keeps waiting while the window lasts and is changed if it comes back in time.
5. When the window ends:
   • a host never reached reads Window: missed the window - "The host was offline for the whole maintenance window: nothing was changed." or "The maintenance window ended before the host picked its changes up: nothing was changed."; its controls read skipped with "Missed the maintenance window ...";
   • a host that picked up some of its changes keeps them (they finish and are validated); the rest are skipped and the host reads "N change(s) did not reach it in time (skipped)";
   • with Try missed hosts again, a missed host reads "waiting for the window (<next time>); missed 1 time(s) before, tried again", and the batch waits again. The batch line adds "N hosts missed the window". Nothing is sent to a host after its window has ended, even between two checks.
6. Cancel batch stops a batch that waits for its window: nothing more is sent. Roll back works on the hosts that were changed (57.6).

Lawliet keeps all of this in its database: if the server restarts during a window, it carries on at the next check, and a host is never changed twice.

58.4 Restart in window#

Lawliet never restarts a host on its own (chapter 56). Restart in window is an explicit option of one batch, approved with the batch:

• it is off unless ticked when the batch is started, and the approval names it;
• with dual control on, the second officer who signs the batch signs the restart with it. When the batch approval itself needed no second signature, the restart is held for one under "Restart a host after hardening";
• the warning delay is part of what the second officer signs: the approval reads "RESTART IN WINDOW: on, after a N-minute warning to logged-in users" (or "at once, NO warning" for 0), and the person pressing Approve batch needs Restart hosts after hardening - without it the approval is refused before any request is filed;
• a host is restarted only when everything it was changing has finished and what is left waits for a restart, and only while the window lasts: the warning delay plus 2 minutes must end inside the window, or the host reads "restart: not requested - Too little of the window was left ..." and is left for the next window or Restart needed;
• the restart never happens after the window: a restart the host has not picked up when the window ends is withdrawn ("restart: withdrawn"), and a host that picks it up so late that the warning plus 2 minutes would pass the window's end refuses it ("window would end before the restart");
• a domain controller is restarted only with Domain controllers too ticked; otherwise it reads "restart: not requested - Domain controller: not restarted ...". Which hosts count as domain controllers: a host reporting the domain-controller role; a Windows host whose agent has not reported its domain role (a possible domain controller: "Domain role unknown ..."); a Linux Samba AD domain controller - the 1.5.16.s Linux agent reports the domain-controller role when the samba-ad-dc service is active or smb.conf says server role = active directory domain controller, and as a second signal a host whose host-baseline inventory shows samba-ad-dc active is one too ("Samba AD domain controller ..."). Other Linux hosts and macOS hosts are not domain controllers;
• the restart goes through Restart needed's own path: logged-in users are warned and the host restarts after the delay; the Lawliet server's own host, never-touch hosts and macOS hosts are refused with the same reasons as in 56.4; an offline host is tried again at the next check while the window lasts;
• each host reads "restart: requested", then the changes are validated after the new boot, as in chapter 56.

58.5 Procedure: edit or delete a window#

1. Hardening > Maintenance windows, the window's Edit or Delete.
2. Edit: change what you need and press Save window. Batches that wait for the window and have not started move to its new time ("Window saved: batches waiting for it moved to the new time"). A batch already inside its window keeps that window to its end, unless you tick Also stop the N batch(es) already inside this window (shown when there are some): then nothing more is sent to their hosts (changes already on hosts stay). A change that would leave a waiting batch no time at all (disabling the window, a one-off in the past) is refused: cancel the batch first.
3. Delete: press Delete, then Confirm delete - or Confirm: delete and cancel N batch(es) when batches wait for it: those batches are cancelled, with "The maintenance window '<name>' was deleted" on each host.
4. When batches wait for the window, the change needs Run hardening and a second officer: "Held for a second officer ..." - the approval request reads "Change maintenance window N ...", ending "Batches already inside the window CONTINUE until their current occurrence ends." or "... are STOPPED ...", or "Delete maintenance window N: the hardening batches waiting for it are cancelled". Someone without Run hardening is refused with "N hardening batch(es) wait for this window".

58.6 Sandbox#

On a licence with the sandbox, the sandbox shows a weekly window "Sunday night patching" (Europe/Berlin, Sunday 02:00, 4 hours, three hosts), a batch approved into its next time with Restart in window on, and a batch that ran in last week's window on two hosts while the third was offline and missed it. Lawliet never sends sandbox batches to a host, even inside their window. Clear sandbox data removes all of it.

58.7 API#

Each create, edit and delete is in the audit trail (maintenance_window); a restart the window requested is audited as restart_requested "by maintenance window".