Backup

FAQ › EUZOS Server › Backup · Nederlands

What is it?

Backup (package id backup) makes automatic, encrypted backups of the profile directories of the EUZOS PCs in an organisation onto its EUZOS Server. The PC encrypts everything before it leaves; the server stores only encrypted chunks and never sees a key, a file name or a file's contents. Backups are incremental (content-addressed chunks with deduplication), thinned out by a retention policy (by default 7 daily, 4 weekly, 6 monthly) and limited by a quota per account and per device. The design is in docs/PACKAGE-BACKUP.md.

Backup is a role in the EUZOS Server kernel that builds on Workplace management (sign-in at the profile server, organisation, TLS key): turn both on.

How do I…?

How do I install Backup on a server?

Choose Backup in the Packages step of the server installer (next to Workplace management). The installer writes \EOS\FW\BACKUP.TXT (role=backup). At the first start the server makes its store key BKKEY.TXT and an area of its own on partition 2 (the largest free piece minus 4 GiB, or area-gib=).

How do I open the port?

The package listens on TCP 8448, closed in the firewall until you open it with Server Admin:

serveradmin <server> firewall-open allow tcp 8448 lan

firewall shows the suggestion as long as the port is closed.

What does a PC need?

a device key (pckey create) and registration with the organisation on the profile server (pc-register), as for Server Admin;
a user who is logged in (online) with an open profile directory.

Then the PC backs up by itself: 5 minutes after login and then every hour it checks whether the newest backup of this PC is older than 24 hours.

How do I back up now?

In Settings › Backup the button Back up now, or backup now in the terminal. The card also shows the server, the last backup, the usage and the last error.

How do I restore?

In the terminal of any registered PC of the organisation, logged in with the same account (also a new PC: the key comes back with the login):

backup list                                  snapshots of all your PCs
backup files latest                          the files in a snapshot
backup restore latest                        everything
backup restore <time>-<id> bestanden/Documenten/rapport.txt   one file or folder

Restored files go to bestanden/Restored/<date>/… in your profile directory (visible in Files), never over existing files. Restoring in the Explorer itself is planned.

How do I see usage and change retention or quota?

serveradmin <server> backup
serveradmin <server> backup-set daily=7 weekly=4 monthly=6 quota-account-gib=50 quota-device-gib=25

backup on the server's console shows the same state.

How do I turn Backup off?

serveradmin <server> package-off backup confirm: no new sessions, port 8448 closes in the firewall; the stored backups stay. package-on backup turns it on again.

Details

Keys: derived (HKDF) from the data key of the profile directory in the vault, per environment. A chunk id is HMAC-SHA256 of the plaintext; a chunk is ChaCha20-Poly1305 with a nonce from its id (deterministic, so equal chunks deduplicate; SIV style). The manifest of a snapshot (file names, sizes, chunk lists) is encrypted with a random nonce.
Chunking: content-defined (gear hash, FastCDC style), 16–256 KiB, average ~64 KiB, with a gear table derived from the key.
Authentication: the PC asks the profile server for a backup proof (POST /api/workplace/v1/backup-proof, 10 minutes), gets a challenge from the server, signs a session request with its device key and gets a session token (1 hour). TLS with the pinned key of the workplace server.
The server sees: account id, account e-mail, device id and name, snapshot times and sizes, chunk ids and encrypted sizes.
Retention job: after every snapshot (forget for that device) and once a day (forget, then garbage collection of unreferenced chunks per account, except accounts that are uploading).

Reference

Command	Where	What it does
`backup`	server console	state, retention, quota, usage per account and device
`backup [status]`	PC terminal	the state of the backup client
`backup now`	PC terminal	a backup now
`backup list`	PC terminal	snapshots of all PCs of this account
`backup files <snapshot>`	PC terminal	the files in a snapshot
`backup restore <snapshot> [<path>]`	PC terminal	restore into `bestanden/Restored/<date>/`
`serveradmin <server> backup`	Server Admin	the state
`serveradmin <server> backup-set <key>=<value> …`	Server Admin	`daily`, `weekly`, `monthly`, `quota-account-gib`, `quota-device-gib`

<snapshot>: latest (of this PC), <time>-<id> or <device>/<time>-<id>.

File	Contents
`\EOS\FW\BACKUP.TXT`	`role=backup`, `port=8448`, `daily=`, `weekly=`, `monthly=`, `quota-account-gib=`, `quota-device-gib=`, optional `area-gib=`, `package=off`
`\EOS\FW\BKKEY.TXT`	64 hex: the key of the area at rest (made on the server; secret)

The server reads both files from the boot volume itself (the bootloader loads at most 16 files from \EOS\FW\).

Endpoints on port 8448 (POST /backup/v1/…): challenge, session, have, chunks, snapshot, list, get-snapshot, get-chunks; replies ok or error with reason= (English codes, e.g. quota_account, missing_chunks, package_off).