Maintenance status
Ask the server whether a restart or Docker update is waiting, whether it is busy right now, and when the next quiet time is, as JSON.
On this page
A tool that wants to restart a server, such as a desktop admin app, needs to know three things first. Is a restart or a Docker update waiting? Is the server busy right now? When is the next quiet time? LibrePortal answers all three in one document. It only reads: nothing here restarts anything, and there is no way to ask for a restart from outside.
Ask for it#
On the server:
sudo -u libreportal libreportal system maintenance --json
Without --json the same facts print as a short list of lines for a person.
From another machine, with an access key that has the system:read scope:
curl -H "Authorization: Bearer <key>" http://<server>/api/v1/system/maintenance
LibrePortal writes the document about once a minute, so the API hands over a recent copy rather than working it out for each request. The generatedAt field says how fresh it is. Just after a start, before the first copy exists, the API answers 503: try again in a minute. A key without system:read is refused with 403.
The document#
{
"schema": "libreportal.maintenance/1",
"server": "home",
"osUpdates": { "mode": "all", "lastRun": "2026-10-25T05:30:12+00:00", "lastResult": "ok", "installed": 4, "nextRun": "2026-10-26T05:00:00+00:00" },
"restart": { "needed": true, "since": "2026-10-25T05:31:00+00:00", "packages": ["linux-image-generic"] },
"engineUpdates": { "waiting": false, "since": null, "packages": [] },
"window": { "start": "03:00", "end": "06:00" },
"safeNow": false,
"blockedBy": ["Backup running"],
"nextGoodTime": "2026-10-26T03:00:00+00:00",
"unlockNeeded": false,
"remoteUnlock": false,
"generatedAt": "2026-10-25T09:00:00+00:00"
}
| Field | Meaning |
|---|---|
osUpdates |
The nightly system updates: the mode chosen, when they last ran and how it went (ok or failed), how many packages were installed, and when they run next. |
restart |
needed is true when the system has flagged that a restart is waiting. since is when it was flagged and packages are the updates that asked for it. |
engineUpdates |
Docker updates that were held back. waiting, since when, and which packages. |
window |
The quiet window for automatic updates as start and end (24-hour, the server's own clock), or null when there is no restriction. |
safeNow |
True when nothing important is running. |
blockedBy |
When safeNow is false, plain-words reasons such as Backup running, Clean-up running, App install running, Restore running, App update running or LibrePortal update running. A task that has not been heard from for 30 minutes is ignored. |
nextGoodTime |
The next time that is inside the window and clear of the daily jobs (clean-up for 30 minutes from its start, app backups for 60), in 5-minute steps, looking two days ahead. null if there is none. |
unlockNeeded |
True when a person will have to type a disk password after a restart, because the disk is encrypted and has no key file. |
remoteUnlock |
True when that password can be typed over SSH. |
generatedAt |
When this copy was made. |
Times are ISO 8601 with the server's offset. Any value that does not apply is null, not left out.
Field names stay. New fields get added; the schema name only changes if one is removed or changes meaning. Ignore fields you do not know.
A sensible check#
Restart only when restart.needed is true, safeNow is true, and the time is inside window if there is one. If safeNow is false, wait for nextGoodTime. If unlockNeeded is true and remoteUnlock is false, tell the person first: the server will sit at a password prompt after the restart.
See Daily clean-up and updates for what the server does by itself.