Maintenance Mode — Reference
The Maintenance Mode surface is the controlled-downtime plane for SGEN sites. It owns the site-wide toggle that swaps the public front-end for a maintenance page, the IP allowlist that lets named operators bypass the wall, the message shown to blocked visitors, the scheduled-window machinery, and the behind-the-scenes editor access that keeps the admin surface usable during downtime.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or scoping a release procedure. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Maintenance Mode lives under the Settings module in SG-Admin. The module renders three primary views — the current-state panel that shows toggle status and active allowlist, the maintenance-page editor where the operator authors the visitor-facing message, and the schedule manager that defines upcoming maintenance windows — and exposes a small set of write operations for enable, disable, schedule, cancel scheduled, update message, and update allowlist.
The module is paired by convention: one half renders the views and prepares the state and schedule data, the other half handles writes and returns AJAX responses. Engineers reading the SG-Admin source will see this split across two controller files; the reference below describes the combined surface as it appears to a calling integration.
The toggle is binary at the front-end — either the public site is up or visitors see the maintenance page. The behind-the-scenes complexity is in the allowlist (which IPs and which authenticated operators bypass the wall), the scheduled window (auto-toggle on and off at named timestamps), and the admin-surface behavior (SG-Admin always remains reachable for authenticated operators regardless of toggle state).
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Settings → Maintenance Mode
- URL prefix:
/sg-admin/maintenance/ - View templates:
application/views/Admin/Settings/Maintenance/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Settings → Maintenance Mode [ Enable now ] │├──────────────────────────────────────────────────────────────────────┤│ Current state: LIVE (public site reachable) ││ Toggle history: last enabled 2026-04-18, 14 minutes downtime ││ ││ ─── Scheduled window ──────────────────────────────────────────┐ ││ Starts: 2026-05-23 02:00 UTC │ ││ Ends: 2026-05-23 03:30 UTC │ ││ Reason: Release v2.4 — DB migration │ ││ [ Edit ] [ Cancel ] │ ││ ────────────────────────────────────────────────────────────────┘ ││ ││ Allowlist: 3 IPs · 5 authenticated operators ││ Message: "We'll be right back. Maintenance until 03:30 UTC." ││ [ Edit message ] [ Edit allowlist ] [ Preview maintenance page ] │└──────────────────────────────────────────────────────────────────────┘Actions
The Maintenance Mode surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
View current state
Returns the toggle's current state (live or in-maintenance), the active allowlist entries, the configured message, and any scheduled window. Read by the front-end on every request via a cached lookup; the cache invalidates on toggle change.
Enable maintenance mode
Switches the front-end into maintenance state immediately. Captures the operator who triggered the switch, the timestamp, and an optional reason. On submit, the surface writes the new state, invalidates the front-end cache, and the maintenance page is served on the next request. SG-Admin remains reachable for authenticated operators throughout.
Disable maintenance mode
Switches the front-end back to live. Captures the operator who disabled, the timestamp, and the duration of the downtime window. The duration is computed automatically and recorded for reporting.
Schedule maintenance window
Defines a future maintenance window. Required fields: start timestamp, end timestamp, reason. Optional fields: pre-toggle warning message (shown on the public site for a configurable window before the start), allowlist override (applies only during this window). On submit, the surface validates the timestamp order, checks for overlap with other scheduled windows, and persists the schedule.
Cancel scheduled window
Removes a future scheduled window. The cancellation is audit-logged. The scheduled window's pre-toggle warning is removed at the same time.
Auto-toggle (scheduled)
The scheduled job that fires the toggle when a scheduled window's start or end timestamp is reached. Not a user-facing action — described here because integrations querying the toggle state need to know that state can transition without an explicit write.
Engineering note. Auto-toggle writes the same Activity Log entry an explicit enable / disable would, with the acting operator recorded as the scheduler (the operator who created the window).
Update maintenance message
Edits the visitor-facing message shown on the maintenance page. Accepts plain text or a constrained markup subset (headings, bold, links, paragraph). Optionally accepts a banner image reference and a contact email. On submit, the surface validates the markup, persists the message, and the front-end picks it up on the next request.
Preview maintenance page
Renders the maintenance page exactly as a blocked visitor would see it, including the configured message, banner image, and contact email. Used to confirm the page looks correct before toggling. The preview does not affect live state.
Update allowlist
Edits the IP allowlist and the authenticated-operator allowlist. IPs may be added by literal address or by CIDR range; operators are added by user identifier. On submit, the surface validates the IP syntax, persists the allowlist, and the new entries take effect on the next request. Allowlist edits during an active maintenance window are non-disruptive — visitors already inside the allowlist remain inside.
Force-end maintenance
A dedicated path for emergency exit. Disables maintenance mode, removes the active scheduled window if any, and writes a high-severity audit entry. Used when an unplanned event requires the site to come back online ahead of the scheduled end.
Data model
The Maintenance Mode state record carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. Singleton — exactly one state record per site. |
is_enabled | boolean | The current toggle state. |
enabled_at | timestamp | When the current state was entered. |
enabled_by | integer | Operator who triggered the current state. |
reason | string | Optional reason captured at toggle. |
message | text | Visitor-facing maintenance message. Constrained markup. |
banner_image_url | string | Optional. Resolves against the Media library. |
contact_email | string | Optional. Surfaced on the maintenance page. |
pre_toggle_warning | text | Optional. Shown before a scheduled window's start. |
updated_at | timestamp | Touched on any write to the state record. |
starts_at, ends_at, reason, created_by, pre_toggle_warning_offset, allowlist_override, status (scheduled, active, completed, cancelled).Allowlist entry: each entry writes a row with kind (ip, cidr, operator), value, created_by, created_at, expires_at (optional). IP entries may carry an expiry for one-time deploy allowlisting. Operator entries default to no expiry.
Toggle-history entry: each toggle write (enable, disable, auto-toggle, force-end) writes a row with was_enabled, is_enabled, transitioned_at, acting_operator, reason, auto_or_manual. The history is append-only and is the canonical downtime log for the site.
Resolution semantics: the front-end checks the maintenance state on every request via a short-lived cache. If is_enabled is true, the request's source IP is checked against the IP allowlist, and the request's authenticated session (if any) is checked against the operator allowlist. A match in either bypasses the maintenance page; a non-match renders the maintenance page with HTTP status 503.
PUBLIC REQUEST│▼┌────────────────────────────────────────────┐│ Front-end gate ││ ││ read maintenance state (cached) ││ if is_enabled = false → serve live page ││ if is_enabled = true: ││ ▶ check IP allowlist ││ ▶ check operator allowlist ││ ▶ both miss → serve maintenance page ││ ▶ either hit → serve live page ││ ││ SG-Admin requests bypass the gate ││ (always reachable to authenticated ops) │└──────────────────────┬─────────────────────┘│▼HTTP 200 (live) or 503 (maintenance)│▼Cached for request windowPermissions
Access to the Maintenance Mode surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Maintenance Mode surface.
Layer 2 — per-action capability. Within SG-Admin, each Maintenance Mode action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| View current state | ✔ | ✔ | ✔ |
| View schedule | ✔ | ✔ | ✔ |
| View toggle history | ✔ | ✔ | ✔ |
| Enable maintenance | ✔ | — | — |
| Disable maintenance | ✔ | — | — |
| Schedule window | ✔ | — | — |
| Cancel scheduled window | ✔ | — | — |
| Update message | ✔ | ✔ | — |
| Preview maintenance page | ✔ | ✔ | ✔ |
| Update IP allowlist | ✔ | — | — |
| Update operator allowlist | ✔ | — | — |
| Force-end maintenance | ✔ | — | — |
| Export downtime log | ✔ | ✔ | ✔ |
Self-protection rules. A scheduled window cannot start in the past — the surface returns a structured rejection naming the timestamp constraint. Overlapping scheduled windows are rejected; the operator must cancel the prior window first. The acting operator cannot remove their own session from the operator allowlist while maintenance is active (they would lock themselves out of the very surface that controls the toggle). At least one administrator must remain on the operator allowlist at all times during an active maintenance window — the last administrator entry cannot be removed mid-window.
Audit. Every write — enable, disable, schedule, cancel, message edit, allowlist edit, force-end — emits an Activity Log entry. The log records the acting operator, the state change, and the duration when applicable. Auto-toggle writes the same shape with the scheduler recorded as the acting operator. The toggle-history table is the canonical downtime ledger and is retained beyond the standard audit window.
REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Self-protection rules │ past schedule / overlap /│ │ self-lockout / last-admin → reject└─────────────┬─────────────┘│ passes▼action executes│▼Activity Log entry + toggle-history appendRelated references
- Settings — Reference. Owns the global cache window for the maintenance state, the default banner image, the contact-email default, and the audit-log retention.
- Users — Reference. Operator allowlist entries reference user identifiers from this surface. Permanent user delete cascades a removal from the allowlist.
- Media — Reference. Banner image references resolve against the Media library. Asset deletion is blocked while the maintenance message references the asset.
- Activity Log — Reference. Toggle, schedule, and allowlist edits surface here. The toggle-history view is the canonical downtime ledger.
- Site Backups — Reference. Maintenance windows are commonly paired with a pre-window backup. The backup record is correlated by timestamp; the two records are not formally linked.
- Pages — Reference. The maintenance page is rendered by the front-end from the message field, not from a page record. Page editing is unaffected by maintenance state.
- Activity Log — Reference. Force-end events carry a high-severity flag; the audit view surfaces them prominently.
/docs/maintenance-mode.