settings
General installation settings shared by onboarding and /settings. The backup passphrase is write-only: a response never carries it, only whether one is configured. UPS connection and shutdown thresholds live under /settings/ups; UPS passwords are write-only. Self-update, rollback and Debian update status live under /settings/updates. Host networking, TLS certificate expiry, LAN-only access scope and the listen port live under /settings/network.
Get general installation settings
Hostname, timezone and whether a backup passphrase is configured. The passphrase itself is never returned.
Set general installation settings
Persists hostname, timezone and/or the backup passphrase. Each field is optional: omitted leaves that value unchanged. An empty `hostname` clears a previously set hostname. `backupPassphrase` is write-only and never echoed back — skipping it during onboarding is valid.
Get the container update settings
How long the image a container ran before an update is kept for a revert: 7 days until it is set.
Set the container update settings
Sets how many days the image a container ran before an update is kept for a revert, from 1 to 365. It applies to updates made afterwards; an update already made keeps the deadline it was made with.
Get UPS / NUT settings
The UPS settings: connection mode (USB or a network NUT server), driver fields, and USB-only shutdown thresholds. Passwords are never returned — only `monitorPasswordSet` / `networkPasswordSet`. When no UPS is configured, `configured` is false and every other field is omitted.
Set UPS / NUT settings
Persists UPS settings to SQLite, generates the NUT configuration, and reloads the NUT units. Passwords are write-only: omit to keep an existing secret; a first configure must supply the password the connection mode needs. USB-only thresholds are ignored for network mode. Validation failures return 400; unmanaged or existing host NUT files and a missing `nut` group return 409.
Host network, TLS and access-scope settings
Current network backend, interfaces, any in-flight confirm-or-revert window, the TLS certificate's expiry, LAN-only access scope and the listen port. Editing address, DNS or gateway is only possible when the backend is ifupdown; otherwise `editable` is false and `readOnlyReason` says why.
Apply host network, access-scope or listen-port changes
Address, DNS and gateway changes are written to one managed ifupdown file under `/etc/network/interfaces.d/` and applied with a 60-second confirm-or-revert: unless `confirmNetworkSettings` is called over the new configuration before the window expires (or the daemon dies), the previous file is restored. Access scope and listen port apply without that window — access scope takes effect immediately; a listen-port change is persisted and used on the next daemon start. Addressing fields are refused when the backend is not ifupdown.
Keep the pending network configuration
Called over the new configuration during the confirm-or-revert window. Keeps the managed ifupdown file. An unreachable address cannot be confirmed because this request never arrives. After the window expires, or if the daemon died before confirm, the previous configuration has already been restored and this returns `network_confirm_expired`.
Regenerate the self-signed TLS certificate
Replaces the daemon's TLS certificate with a freshly generated self-signed certificate and hot-reloads it so new connections use the new cert. If Let's Encrypt DNS-01 is configured, unattended renewal is disarmed so this self-signed cert is not overwritten without another explicit setup. Let's Encrypt issue and renew are handled by `configureLetsEncrypt`, not by this operation.
Configure Let's Encrypt DNS-01 and issue a certificate
Stores the domain and DNS-01 provider credentials (encrypted at rest) and queues an `acme_issue` job that talks to the ACME directory over DNS-01 only. Ports 80 and 443 are never claimed. HTTP-01 and TLS-ALPN-01 are not offered. On success the issued certificate replaces the self-signed cert on `:8008`. Unattended renewal stays armed while `letsEncrypt.enabled` is true. A failed issue or renew keeps serving the existing certificate and notifies; it never silently falls back to a new self-signed cert.
Stop unattended Let's Encrypt renewal
Disarms unattended renewal. The certificate currently served on `:8008` is left in place — this does not generate a self-signed replacement. DNS credentials remain stored until overwritten by a later `configureLetsEncrypt` or cleared by regenerating a self-signed certificate.
List recurring job schedules
The nightly maintenance chain and every separately scheduled job, with server-computed next-run times, human-readable schedule previews and conflict warnings. Chain step order is server-defined and not writable.
Update the nightly maintenance chain schedule
Persists the chain's start time, weekly scrub day and per-step enabled flags. Step order is fixed and cannot be changed. Omitted step entries leave that step's enabled state unchanged.
Update a separately scheduled job
Persists enabled state, frequency and start time for one of the recurring jobs outside the nightly chain.
Hoserva and Debian update status
Current Hoserva version, any newer release on the configured channel, update-check on/off, pending Debian updates and whether a reboot is required. The update check reads only the release index on the project site — never the GitHub API and never a system-wide `apt update`. When the check is disabled, `availableVersion` is omitted rather than fetched.
Set update channel and check-enabled
Persists the update channel (stable / beta) and whether the outbound update check is enabled. Omitted fields are left unchanged.
Check the release index for a newer Hoserva
Fetches the release index for the configured channel. A user-initiated check runs even when the periodic outbound check is disabled. Never calls the GitHub API or `apt update`.
Download, verify and install the available Hoserva release
Downloads the `.deb` the release index points to and installs it only if the signed SHA256SUMS names that package at the index entry's version and the version is newer than the running one. It verifies the download against the signed SHA256SUMS, runs a config backup, and installs it in a transient systemd unit. Refused while a Parity, Array-write or Topology job is running; the error names that job. A `.deb` whose checksum does not match is never installed, and a notification is raised.
Roll back to the previous Hoserva release and its snapshot
Downloads the recorded previous version's `.deb`, verifies it against the signed SHA256SUMS naming that version, restores that version's pre-migration database snapshot, and installs the previous package. There are no down migrations — rollback is previous package plus its snapshot. Refused while a Parity, Array-write or Topology job is running; the error names that job.
Reboot after waiting for storage jobs and a clean shutdown
Waits for any running Parity, Array-write or Topology job, runs the clean shutdown sequence, then reboots. Hoserva never reboots on its own — this is always the user's action.
Get the catalog refresh settings
How the catalog checks for updates by itself: the background `refreshInterval` and whether opening the catalog starts a check (`checkOnOpen`). Every install starts at `24h` and on.
Set the catalog refresh settings
Sets either or both settings; a field left out stays as it is. An interval other than `off`, `1h`, `6h`, `12h` or `24h` is refused with 400. With the interval `off` and `checkOnOpen` off, nothing reaches the catalog host except `refreshCatalog`. The background check applies a changed interval without a daemon restart.