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 startand 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, defaultkopia, with--server-password), or - the server-control user (
--server-control-username, defaultserver-control, with--server-control-password).
- the server user (
- 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
- Go to Devices and open the device whose agent reaches the Kopia server.
- Click the Checks tab → Add Check → Kopia Backup.
- Enter the host name or IP address under Kopia server host, for example
127.0.0.1for this machine orkopia.example.com, and check the Port. - Leave Use TLS (https) enabled unless the server runs on this machine without TLS.
- Enter the Username and Password.
- (Optional) For a self-signed certificate, enter the Certificate SHA-256 fingerprint.
- 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
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
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
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
Can I monitor KopiaUI on a workstation?
Can I monitor KopiaUI on a workstation?
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.
Why does the check report "Invalid configuration" although the address is correct?
Why does the check report "Invalid configuration" although the address is correct?
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.
How do I monitor a server with a self-signed certificate?
How do I monitor a server with a self-signed certificate?
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.
Was this helpful?
More in Backup
Acronis BackupAcronis Cyber Protect CloudAltaro BackupArcserve UDPStill need help? Ask the team