REST-API: System
Erzeugt aus dem OpenAPI-Dokument des Daemons. Konventionen, Anmeldung, der CSRF-Header und der WebSocket stehen unter API.
GET /api/health
Abschnitt betitelt „GET /api/health“Antworten
- 200:
application/json: HealthResponse
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
POST /api/proxy/tickets
Abschnitt betitelt „POST /api/proxy/tickets“Signed-in users. A one-time ticket (30 seconds) into a proxy host behind the Pithyx sign-in, for the address the browser asked for; the answer is the address to open on that host. Refused with proxy.access.denied when the host does not let the user in.
Anfrage-Body: application/json: ProxyTicketRequest
Antworten
- 200:
application/json: ProxyTicket
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
POST /api/system/backup
Abschnitt betitelt „POST /api/system/backup“Administrators only. The configuration of the box (users, groups, passwords, shared folders, rights, file services, storage schedules, regional settings, certificates and SSH host keys) as one file, encrypted with the password. Files on the pools are not part of it.
Anfrage-Body: application/json: CreateBackupRequest
Antworten
- 200:
application/octet-stream: string (byte)
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
POST /api/system/backup/inspect
Abschnitt betitelt „POST /api/system/backup/inspect“Administrators only. Decrypts and checks a backup file and keeps it for 15 minutes for a restore by the same administrator; returns what it holds.
Anfrage-Body: application/json: InspectBackupRequest
Antworten
- 200:
application/json: BackupSummary
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
POST /api/system/backup/restore
Abschnitt betitelt „POST /api/system/backup/restore“Administrators only. Replaces the chosen parts of the configuration with those of the checked backup, then restarts the daemon. Restoring users signs everybody out.
Anfrage-Body: application/json: RestoreBackupRequest
Antworten
- 200:
application/json: RestoreResult
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
GET /api/system/network
Abschnitt betitelt „GET /api/system/network“Administrators only. What Pithyx configured, every card, bond and VLAN with link, speed, addresses, gateways and name servers, whether Pithyx may change it here, the interface this connection comes in on and the change that waits for its confirmation. The topic system/network sends the same without the connection’s interface.
Antworten
- 200:
application/json: NetworkState
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
PUT /api/system/network
Abschnitt betitelt „PUT /api/system/network“Administrators only. Applies new settings as one change (systemd-networkd and resolved files, host name). The change is rolled back after 60 seconds unless confirmed; open one of the answer’s addresses to confirm when the old address went away.
Anfrage-Body: application/json: NetworkConfig
Antworten
- 200:
application/json: PendingNetworkChange
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
POST /api/system/network/changes/{changeId}/confirm
Abschnitt betitelt „POST /api/system/network/changes/{changeId}/confirm“Administrators only. Keeps the change that waits for its confirmation.
Parameter
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
changeId |
path | string (uuid) | ja |
Antworten
- 204
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
POST /api/system/network/changes/{changeId}/revert
Abschnitt betitelt „POST /api/system/network/changes/{changeId}/revert“Administrators only. Rolls the change that waits for its confirmation back at once.
Parameter
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
changeId |
path | string (uuid) | ja |
Antworten
- 204
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
POST /api/system/network/check
Abschnitt betitelt „POST /api/system/network/check“Administrators only. Checks new settings without applying them: the stored form, the interfaces that change, whether the host name changes, whether this connection’s interface changes, and the static addresses to open afterwards.
Anfrage-Body: application/json: NetworkConfig
Antworten
- 200:
application/json: NetworkCheck
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
GET /api/system/overview
Abschnitt betitelt „GET /api/system/overview“Administrators only. Version and commit, operating system, kernel, machine, processor, memory, host name and uptime.
Antworten
- 200:
application/json: SystemOverview
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
POST /api/system/power
Abschnitt betitelt „POST /api/system/power“Users with the right to restart and shut down, and administrators. Restarts or shuts the box down a few seconds after the answer.
Anfrage-Body: application/json: PowerRequest
Antworten
- 202
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
GET /api/system/proxy
Abschnitt betitelt „GET /api/system/proxy“Administrators only. The ports proxy hosts answer on, what unknown names get, the sign-in address, and every proxy host, redirect host and stream.
Antworten
- 200:
application/json: ProxySettings
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
POST /api/system/proxy/hosts
Abschnitt betitelt „POST /api/system/proxy/hosts“Administrators only. A proxy host: domains on 443 and 80 forwarded to a target. Applies to the next request.
Anfrage-Body: application/json: ProxyHostRequest
Antworten
- 200:
application/json: ProxySettings
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
PUT /api/system/proxy/hosts/{id}
Abschnitt betitelt „PUT /api/system/proxy/hosts/{id}“Administrators only. Replaces a proxy host’s settings; Basic Auth users without a password keep theirs, an uploaded certificate stays unless a new one comes along.
Parameter
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
id |
path | integer (int64) | ja |
Anfrage-Body: application/json: ProxyHostRequest
Antworten
- 200:
application/json: ProxySettings
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
DELETE /api/system/proxy/hosts/{id}
Abschnitt betitelt „DELETE /api/system/proxy/hosts/{id}“Administrators only. Removes a proxy host with its uploaded certificate; its names become unknown.
Parameter
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
id |
path | integer (int64) | ja |
Antworten
- 200:
application/json: ProxySettings
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
POST /api/system/proxy/hosts/{id}/check
Abschnitt betitelt „POST /api/system/proxy/hosts/{id}/check“Administrators only. Whether a proxy host’s target answers one request, with the host’s TLS settings.
Parameter
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
id |
path | integer (int64) | ja |
Antworten
- 200:
application/json: ProxyTargetStatus
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
PUT /api/system/proxy/options
Abschnitt betitelt „PUT /api/system/proxy/options“Administrators only. What a name no enabled host has gets on 443 and 80 (a redirect to 7484, or 404), and where the Pithyx sign-in of a host sends visitors.
Anfrage-Body: application/json: ProxyOptionsRequest
Antworten
- 200:
application/json: ProxySettings
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
POST /api/system/proxy/redirects
Abschnitt betitelt „POST /api/system/proxy/redirects“Administrators only. A redirect host: domains on 443 and 80 redirected to an address.
Anfrage-Body: application/json: ProxyRedirectRequest
Antworten
- 200:
application/json: ProxySettings
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
PUT /api/system/proxy/redirects/{id}
Abschnitt betitelt „PUT /api/system/proxy/redirects/{id}“Administrators only. Replaces a redirect host’s settings.
Parameter
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
id |
path | integer (int64) | ja |
Anfrage-Body: application/json: ProxyRedirectRequest
Antworten
- 200:
application/json: ProxySettings
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
DELETE /api/system/proxy/redirects/{id}
Abschnitt betitelt „DELETE /api/system/proxy/redirects/{id}“Administrators only. Removes a redirect host.
Parameter
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
id |
path | integer (int64) | ja |
Antworten
- 200:
application/json: ProxySettings
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
POST /api/system/proxy/streams
Abschnitt betitelt „POST /api/system/proxy/streams“Administrators only. A stream: a TCP and/or UDP port of the box forwarded to a host and port; the firewall opens the port.
Anfrage-Body: application/json: ProxyStreamRequest
Antworten
- 200:
application/json: ProxySettings
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
PUT /api/system/proxy/streams/{id}
Abschnitt betitelt „PUT /api/system/proxy/streams/{id}“Administrators only. Replaces a stream’s settings.
Parameter
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
id |
path | integer (int64) | ja |
Anfrage-Body: application/json: ProxyStreamRequest
Antworten
- 200:
application/json: ProxySettings
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
DELETE /api/system/proxy/streams/{id}
Abschnitt betitelt „DELETE /api/system/proxy/streams/{id}“Administrators only. Removes a stream; the firewall closes its port.
Parameter
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
id |
path | integer (int64) | ja |
Antworten
- 200:
application/json: ProxySettings
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
GET /api/system/region
Abschnitt betitelt „GET /api/system/region“Administrators only. The system language and the region whose formats every user sees. GET /api/setup carries both for the sign-in page.
Antworten
- 200:
application/json: SystemRegion
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
PUT /api/system/region
Abschnitt betitelt „PUT /api/system/region“Administrators only. Sets the system language (en, de) and the region (an ISO 3166 country code, or null to follow each user’s language).
Anfrage-Body: application/json: SystemRegion
Antworten
- 200:
application/json: SystemRegion
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
GET /api/system/time
Abschnitt betitelt „GET /api/system/time“Administrators only. Time zone, synchronization state, the configured time servers and every time zone the system knows.
Antworten
- 200:
application/json: TimeSettings
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
PUT /api/system/time
Abschnitt betitelt „PUT /api/system/time“Administrators only. Sets the time zone and the time servers (an empty list means the distribution’s defaults).
Anfrage-Body: application/json: TimeSettingsRequest
Antworten
- 200:
application/json: TimeSettings
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
GET /api/system/tls
Abschnitt betitelt „GET /api/system/tls“Administrators only. Whether the web interface speaks HTTPS, the certificate it presents, the box’s certificate authority with its scope, the names of the box’s own certificate, an uploaded certificate and the certificates issued for other devices.
Antworten
- 200:
application/json: TlsSettings
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
POST /api/system/tls/authority
Abschnitt betitelt „POST /api/system/tls/authority“Administrators only. Replaces the certificate authority with a new root and intermediate and issues the box’s certificate from them. Every device has to trust the new root; certificates issued for other devices stay valid only where the old root is still trusted.
Anfrage-Body: application/json: CreateAuthorityRequest
Antworten
- 200:
application/json: TlsSettings
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
PUT /api/system/tls/custom
Abschnitt betitelt „PUT /api/system/tls/custom“Administrators only. Presents a certificate of your own (with its chain and unencrypted key, in PEM) on the web ports and for FTPS while it is valid; after it ends the box presents its own again.
Anfrage-Body: application/json: CustomCertificateRequest
Antworten
- 200:
application/json: TlsSettings
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
DELETE /api/system/tls/custom
Abschnitt betitelt „DELETE /api/system/tls/custom“Administrators only. Removes the uploaded certificate; the box presents its own again.
Antworten
- 200:
application/json: TlsSettings
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
POST /api/system/tls/issued
Abschnitt betitelt „POST /api/system/tls/issued“Administrators only. Issues a server certificate for another device from the box’s authority. The answer holds the private key; the box does not keep it.
Anfrage-Body: application/json: IssueCertificateRequest
Antworten
- 200:
application/json: IssuedCertificateFiles
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
DELETE /api/system/tls/issued/{id}
Abschnitt betitelt „DELETE /api/system/tls/issued/{id}“Administrators only. Removes an issued certificate from the list. The box keeps no revocation list, so the certificate stays valid until it ends.
Parameter
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
id |
path | integer (int64) | ja |
Antworten
- 204
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
GET /api/system/tls/issued/{id}/certificate.pem
Abschnitt betitelt „GET /api/system/tls/issued/{id}/certificate.pem“Administrators only. An issued certificate with the intermediate it was issued under, without its key.
Parameter
| Name | Ort | Typ | Pflicht | Beschreibung |
|---|---|---|---|---|
id |
path | integer (int64) | ja |
Antworten
- 200:
application/x-pem-file: string (byte)
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
PUT /api/system/tls/names
Abschnitt betitelt „PUT /api/system/tls/names“Administrators only. Names (such as a domain pointing at the box) the box’s own certificate covers besides its host name and addresses; they must lie inside the authority’s scope. The certificate is issued again at once.
Anfrage-Body: application/json: TlsNamesRequest
Antworten
- 200:
application/json: TlsSettings
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
GET /api/system/tls/root-ca.crt
Abschnitt betitelt „GET /api/system/tls/root-ca.crt“Anyone, also before signing in. The root of the box’s certificate authority in PEM, to install on a device so it trusts the box.
Antworten
- 200:
application/x-x509-ca-cert: string (byte)
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
GET /api/system/updates
Abschnitt betitelt „GET /api/system/updates“Administrators only. The installed version, the channel and the daily check, what the last check found (the channel’s newer version with its changelog, the Debian updates with the security fixes, or why the channel could not be read), an uploaded file waiting for its installation, the running update, the history and the snapshots that can be restored. Whether updates apply here at all (a machine not installed by the installer cannot). The topic system/updates sends the same.
Antworten
- 200:
application/json: UpdateStatus
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
POST /api/system/updates/check
Abschnitt betitelt „POST /api/system/updates/check“Administrators only. Reads the channel and Debian’s lists now. Installs nothing.
Antworten
- 200:
application/json: UpdateStatus
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
PUT /api/system/updates/file
Abschnitt betitelt „PUT /api/system/updates/file“Administrators only. Streams a .pithyxupdate as the raw body (at most 4 GB) and checks it completely before anything changes: its signature by a key the box trusts for its channel (a development box also takes unsigned files), every package’s size and SHA-256, and that it is newer than the installed version and fits it. Keeps it for “Install” until another upload or a restart.
Antworten
- 200:
application/json: UpdateStatus
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
DELETE /api/system/updates/file
Abschnitt betitelt „DELETE /api/system/updates/file“Administrators only. Forgets the uploaded file.
Antworten
- 200:
application/json: UpdateStatus
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
POST /api/system/updates/install
Abschnitt betitelt „POST /api/system/updates/install“Administrators only. Installs the uploaded file or the channel’s newest version as a job of the box: a snapshot of the system, the packages (optionally Debian’s updates in the same snapshot), GRUB on every disk, then the restart and the health check, which rolls back to the snapshot by itself when the new version does not come up within five minutes.
Anfrage-Body: application/json: InstallUpdateRequest
Antworten
- 202:
application/json: Job
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
POST /api/system/updates/rollback
Abschnitt betitelt „POST /api/system/updates/rollback“Administrators only. Restores a snapshot (the version typed as the confirmation) and restarts into it. Settings changed since the snapshot are lost; pools and their files are not touched.
Anfrage-Body: application/json: RollbackRequest
Antworten
- 202:
application/json: Job
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
PUT /api/system/updates/settings
Abschnitt betitelt „PUT /api/system/updates/settings“Administrators only. Switches the daily check (it only notifies) and the channel (stable or beta).
Anfrage-Body: application/json: UpdateSettingsRequest
Antworten
- 200:
application/json: UpdateStatus
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
PUT /api/system/updates/source
Abschnitt betitelt „PUT /api/system/updates/source“Administrators only. Checks a pithyx-source.json (another update source, for example a fork, D339) sent as the raw body and keeps it for the recovery menu. It changes nothing the box trusts: only the recovery menu at the console (GRUB entry “Pithyx recovery”, “Change the update source”) switches to it.
Antworten
- 200:
application/json: UpdateStatus
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.
DELETE /api/system/updates/source
Abschnitt betitelt „DELETE /api/system/updates/source“Administrators only. Forgets the source file saved for the recovery menu.
Antworten
- 200:
application/json: UpdateStatus
Jeder Fehler antwortet mit Problem Details (application/problem+json) und einem stabilen Code aus der Fehlerreferenz.