Skip to main content
Backup

Kopia Backup

Use the Kopia Backup check to monitor the age, failed files and status of the snapshot sources of a Kopia server through its API.

The Kopia Backup check monitors the snapshot sources of a Kopia server through its API: the age of each source's last snapshot, failed files, incomplete or paused snapshots and the server's repository connection. It runs every 60 minutes on an octoja agent on Windows, Linux or macOS (x64 and Arm64) that can reach the Kopia server, and only reads.

Prerequisites

  • A Kopia server started with kopia server start and fixed credentials. The KopiaUI desktop app uses random one-time passwords and cannot be monitored.
  • Credentials of one of these two server users:
    • the server user (--server-username, default kopia, with --server-password), or
    • the server-control user (--server-control-username, default server-control, with --server-control-password).
  • The running agent reaches the Kopia server on the configured port (default 51515).
  • If the Kopia server runs on a different device than the agent, TLS (https) is required. The check accepts plain http only for this machine (localhost), because the credentials would otherwise travel unencrypted.

Steps

Step 1 – Prepare the Kopia server

Start the Kopia server with fixed credentials, that is with --server-username and --server-password or with --server-control-username and --server-control-password. For TLS, pass your own certificate with --tls-cert-file and --tls-key-file, or let Kopia create a self-signed certificate with --tls-generate-cert. For a self-signed certificate, copy the fingerprint Kopia prints at startup as SERVER CERT SHA256; you enter it in the check.

If the agent monitors a Kopia server on the same device, the address 127.0.0.1 without TLS is enough.

Step 2 – Add the check in octoja

  1. Go to Devices and open the device whose agent reaches the Kopia server.
  2. Click the Checks tab → Add Check → Kopia Backup.
  3. Enter the host name or IP address under Kopia server host, for example 127.0.0.1 for this machine or kopia.example.com, and check the Port.
  4. Leave Use TLS (https) enabled unless the server runs on this machine without TLS.
  5. Enter the Username and Password.
  6. (Optional) For a self-signed certificate, enter the Certificate SHA-256 fingerprint.
  7. Adjust Warning after (hours) and Critical after (hours) if needed and click Add Check.

After the first run, the result appears in the device's Checks tab.

If the Kopia server is already in octoja as an agentless network device, add the check on that device instead. octoja supplies the address from the device's IP, and the agent set as its Monitoring asset runs the check. Because that IP is not localhost, you need TLS. See Add a Network Device Without an Agent.

Settings

FieldTypeRequiredDefaultDescription
Kopia server hoststringYes—Host name or IP of the Kopia server, for example 127.0.0.1 for this machine. IPv6 addresses work without square brackets
PortintegerYes51515Port of the Kopia server, 1 to 65535
Use TLS (https)booleanNoOnConnects over https. Plain http is only accepted for this machine (localhost)
UsernamestringYeskopiaServer user (--server-username) or server-control user (--server-control-username). Must not contain a colon
PasswordpasswordYes—Matching --server-password or --server-control-password
Certificate SHA-256 fingerprintstringNoemptyFingerprint of a self-signed server certificate, as Kopia prints it at startup (SERVER CERT SHA256). 64 hexadecimal characters; spaces, colons and hyphens are ignored. Leave empty for normal certificate validation
Warning after (hours)numberYes26Maximum age of each source's last snapshot before a warning. Must be greater than 0
Critical after (hours)numberYes50Maximum age of each source's last snapshot before a critical alert. Must be greater than 0
Excluded sourceslist of stringsNoemptySources whose user@host:path contains one of these entries are ignored. Matching is case-insensitive

If the warning and critical thresholds are reversed, the check swaps them automatically.

With a fingerprint, the check accepts only the certificate with exactly this SHA-256 value, and only within its validity period. TLS verification is never disabled.

Results

The check evaluates every snapshot source on its own. The source with the worst result sets the overall status and appears in the short message.

Per source

ConditionMessageSeverity
Kopia reports the status FAILED for the sourceKopia cannot read the snapshots or policy of this sourceCritical
The source has no snapshot yetNo snapshot existsCritical
The last snapshot has reached Critical after (hours)Last snapshot is too oldCritical
The last snapshot has reached Warning after (hours)Last snapshot is too oldWarning
Snapshots of the source are paused (PAUSED)Snapshots are pausedWarning
The last snapshot is incompleteLast snapshot is incompleteWarning
Files failed in the last snapshot; the count follows in bracketsFiles failed in the last snapshotWarning
None of these conditions applies—OK

The age is measured from the end of the last snapshot. While an upload runs, Kopia writes intermediate checkpoints. As long as the source is reported as uploading or as a remote client, such a checkpoint does not count as incomplete. If a remote client's upload stalls, the check only reports it once the snapshot ages past a threshold.

For the whole check

ConditionMessageSeverity
A setting is invalid, for example an invalid host, http to another device, an empty password or a fingerprint of the wrong lengthInvalid configuration. Check the URL, credentials, certificate fingerprint and thresholds.Failure
Kopia rejects the username or password (HTTP 401)Kopia rejected the username or password.Failure
The user is neither the server user nor the server-control user (HTTP 403)This user may use neither the Kopia UI nor the server-control API. Use the server user or the server-control user.Failure
The Kopia server is not connected to a repositoryThe Kopia server is not connected to a repository.Critical
The server cannot be reached, its certificate is not accepted, the request takes longer than 30 seconds, or the API answers with another HTTP error. The cause follows in brackets, for example HTTP 500The Kopia server could not be reached.Failure
The API returns a response the check cannot readThe Kopia server returned an unexpected response.Failure
The server reports no sources, or all sources are excludedNo snapshot sources found.Warning

The long message lists every source with its severity, user@host:path and its issues, worst first.

Notes

  • When the check signs in as the server user, it uses the same API as the Kopia web UI. As the server-control user, it reads the sources through the server-control API.
  • On a Kopia repository server, the sources of connected clients also appear, each with its own user and host. Exclude sources you do not want to monitor with Excluded sources.
  • The check does not currently count as a backup check in the backup widgets of reports.

FAQ

No. KopiaUI uses random one-time passwords that you cannot store in the check. Run Kopia as a server with kopia server start and fixed credentials instead.

Check whether Use TLS (https) is disabled while the host is not this machine. Plain http is only accepted for 127.0.0.1, ::1 or localhost. Also check that the fingerprint has exactly 64 hexadecimal characters and that both thresholds are greater than 0.

Enter the fingerprint Kopia prints at startup as SERVER CERT SHA256 under Certificate SHA-256 fingerprint. If you regenerate the certificate, enter the new fingerprint; until then the check reports that the server could not be reached.