Kopia smart home integration, free and open source

Your Kopia snapshots in Gladys: their state, and an alert when one fails or stops running.

• Published by guim31
• Devices
• Version 1.0.1
• Requires Gladys >=5.1.0
• ★ 0

View on GitHubAll integrations

Kopia makes encrypted, deduplicated snapshots of your files to a disk, a NAS or a cloud storage. This integration brings the sources of a Kopia server into Gladys: each source (a folder backed up) becomes a device with its state, its last successful snapshot, its size, its files and the errors of its last snapshot. Scenes can react when any snapshot succeeds, fails or is overdue (no success for too long), a dashboard widget lists the failed sources first, and a scene can start a snapshot.

Tested against a real Kopia 0.23 (Docker image kopia/kopia, filesystem repository, Basic authentication, HTTP and self-signed HTTPS): a snapshot that succeeds, one with a file it cannot read, one whose folder was deleted, and a snapshot started from the integration. Not yet tested on a real Gladys: feedback welcome on the issues.

What you need

• Gladys Assistant 5.1.0 or later.
• Kopia running as a server with its web interface, kopia server start, reachable from the Gladys machine (port 51515 by default). KopiaUI, the desktop application, only listens to its own computer: it cannot be used.
• The username and the password of the server, given with --server-username (kopia by default) and --server-password. Not the password of the repository.

The integration reads Kopia every 5 minutes by default (every 30 seconds while a snapshot runs): a handful of light requests on your own network.

Getting started

1. Start the Kopia server

For example, with a certificate generated by Kopia:

kopia server start --address=0.0.0.0:51515 \
  --server-username=kopia --server-password=… \
  --tls-generate-cert

At the first start, Kopia shows SERVER CERT SHA256: …: note this fingerprint. With --insecure instead of a certificate, the server speaks plain HTTP: use it only on a network you trust. The Docker image kopia/kopia takes the same options.

2. Configure the integration

In Gladys, Integrations → Kopia → Configuration:

• Kopia address: https://192.168.1.2:51515 for example (http:// with --insecure). A bare address (192.168.1.2) means http:// on port 51515; an address copied from the browser works too.
• Username and Password: the --server-username and --server-password of the server.
• Certificate fingerprint: only for a self-signed certificate (--tls-generate-cert): the SERVER CERT SHA256 noted above. The integration then accepts this certificate, and no other, always over https://. Leave it empty with http:// or a certificate signed by a known authority.
• Refresh interval: 1, 5 (default) or 15 minutes.
• Overdue after: when a source without a successful snapshot becomes overdue. Automatic (default) follows the scheduling policy of each source: its interval plus a quarter of it (an hour at least) — 30 hours for a daily snapshot, also for "times of day". A source without interval (manual, or a cron expression) is then never overdue. Or a fixed delay, from 12 hours to a week, for every source.
• Allow starting snapshots: lets the scene action "Start a snapshot" work. Disable it if nobody should start a snapshot from Gladys.
• Language of the names: language of the feature names, of the states and of the scene results.

Test the connection reads Kopia and sums up: the number of sources, failed and overdue.

3. Add the sources

In the Discover tab, add the sources to follow, and the "Kopia" device for the server. A source appears once it has a policy or a snapshot in Kopia. Scene triggers work for every source, added or not.

The devices

Each source:

Feature	Value
State	OK, Failed, Overdue, Running or No snapshot
Last successful snapshot	day/month hours:minutes, "-" if none
Hours since last success	in hours
Last snapshot duration	in seconds
Size	size of the files of the last snapshot, in MB
Files	files of the last snapshot
Snapshots	snapshots kept in the repository
Errors of the last snapshot	files it could not read (1 for a snapshot that failed)
Running	1 while a snapshot of this source runs
Next scheduled snapshot	day/month hours:minutes, "-" without schedule

The "Kopia" device, for the server:

• Repository connected: 1, or 0 when the server is not connected to its repository;
• Snapshot running: 1 or 0;
• Progress: in %;
• Current source: its path, "-" if none;
• Failed sources and Overdue sources: how many.

A snapshot "fails" when Kopia could not read some files (it saves the snapshot without them), when it is incomplete, or when it fails completely (a folder deleted, a storage unreachable: no snapshot is saved). The errors the policy of the source ignores do not count. The state shows what needs attention first: a failed source shows "Failed" even when it is also overdue.

The sources of another computer or user (clients of the same repository) are named user@host:/path.

Dashboard

The Kopia widget shows the number of sources failed, overdue and OK, then one row per source: failed first, then overdue, running, without snapshot, OK, with the last success (or the progress of the one running). Every source by default, or the ones chosen in its settings. The Refresh button reads Kopia again.

Scenes

Triggers

• A snapshot succeeds: a snapshot completes without error. Information: source, duration (minutes), files, size, snapshots kept.
• A snapshot fails: files unreadable, an incomplete snapshot, or a complete failure. Information: source, first error, errors.
• A source is overdue: a source has had no successful snapshot for longer than the "Overdue after" delay. Once per delay exceeded, again after a new success. Information: source, hours since last success, last success.

Each trigger can be limited to some sources (empty: any).

Actions

• State of a source: reads the state of a source for the next actions: failed, overdue, the state in words, the source, the last success, hours since last success (-1 if none), and a ready-made sentence ("/home/anna: Failed, last success 18/10 02:05.").
• Start a snapshot: starts a snapshot of the source now. Refused when "Allow starting snapshots" is disabled.

Scene ideas

• A snapshot fails → send a message with the source and its first error, picked from the information of the trigger.
• A source is overdue → notify with the source and the hours since its last success.
• Every Sunday at 10:00 → State of a source → send the sentence; or start a snapshot of the photos when you leave home, with Start a snapshot.

Troubleshooting

• "Kopia does not answer": check the address and the port from the Gladys machine, and that the server listens to the network (--address=0.0.0.0:51515, not 127.0.0.1).
• "username or password refused by Kopia": type them again; they are the ones of --server-username and --server-password.
• "certificate refused": a self-signed certificate; enter its fingerprint in the configuration.
• "the certificate does not match the fingerprint": the certificate changed (Kopia generates a new one when its files are deleted): enter the new fingerprint.
• "Kopia is not connected to its repository": connect the server to its repository again in its web interface.
• A source never becomes overdue: in Automatic, a source without interval cannot be overdue; choose a fixed delay. A source that never succeeded is not overdue either: it shows Failed or No snapshot.
• A complete failure is no longer shown after Kopia restarted: Kopia keeps its tasks in memory only; the integration still announced it when it happened.
• To see more, set the LOG_LEVEL variable of the integration to debug.

Limits

• One Kopia server per integration.
• A complete failure (no snapshot saved) is only known from the task list of the server, lost when it restarts.
• The integration does not restore, delete or edit snapshots or policies: it watches them, and starts them if allowed.
• Not affiliated with Kopia. Report a problem or an idea on the issues.

Configuration settings

These are the settings Kopia asks for in its configuration screen in Gladys.

Setting	Type	Required	Description
Your Kopia server	section	No	Kopia started as a server with its web interface (kopia server start). Enter its address, its username and its password, then add the sources to follow from the Discover tab.
Kopia address	string	Yes	The address of the web interface, port 51515 by default. https:// if the server uses TLS.
Username	string	No	The --server-username of the server, kopia by default.
Password	secret	Yes	The --server-password of the server (not the password of the repository).
Certificate fingerprint	string	No	Only for a self-signed certificate (--tls-generate-cert): its SHA-256 fingerprint, shown by Kopia at startup (SERVER CERT SHA256). Empty otherwise.
Options	section	No
Refresh interval	select	No	How often Kopia is read. Every 30 seconds while a snapshot runs.
Overdue after	select	No	A source without a successful snapshot for this long is overdue. Automatic: its scheduling interval plus a margin; a source without interval is then never overdue.
Allow starting snapshots	boolean	No	Lets the scene action "Start a snapshot" start a snapshot in Kopia.
Language of the names	select	No	Language of the feature names (set when a device is added), of the states and of the scene results.

How to install Kopia in Gladys

1. In Gladys, open Integrations: Kopia appears in the catalog, next to the native integrations, with a community badge.
2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-kopia:1.0.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
3. Open the Configuration screen of the integration, fill in the settings, and save.
4. You can also install it directly from its repository URL: https://github.com/guim31/gladys-kopia.

Kopia requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations

Kopia is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.

• Browse all integrations, native and community
• Build and publish your own external integration
• Source code on GitHub — source of this documentation

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂