Agent command line
Every agent, on every platform, is the same cvn-agent binary with the same commands. Run them as root on Linux and macOS, or from an elevated prompt on Windows.
Most commands read the agent's configuration with --config. Point it at the installed configuration:
| Platform | Configuration |
|---|---|
| Windows | C:\ProgramData\cvn-agent\agent.json |
| macOS | /Library/Application Support/cvn-agent/agent.json |
| Linux | /etc/cvn-agent/agent.json |
The examples below use the Linux path.
Install and enrol
| Command | What it does |
|---|---|
cvn-agent install --path <folder> |
Enrols the device if needed, saves CVN_PASSPHRASE if it is set, and installs and starts the background service backing up that folder |
cvn-agent enroll |
Enrols the device using the token embedded in the installer, without installing the service |
cvn-agent version |
Prints the agent build |
Back up
| Command | What it does |
|---|---|
cvn-agent backup --config /etc/cvn-agent/agent.json --path /srv/data |
One backup of a folder now |
cvn-agent run --config /etc/cvn-agent/agent.json --path /srv/data |
The service loop: schedule, catch-up, remote commands. The service runs this for you. |
cvn-agent image-backup --config /etc/cvn-agent/agent.json |
A raw image of the system disk (Windows and Linux). --device picks another disk. |
cvn-agent pve-backup --config /etc/cvn-agent/agent.json --all |
Proxmox guests. See Proxmox VE. |
Restore
| Command | What it does |
|---|---|
cvn-agent snapshots --config /etc/cvn-agent/agent.json --json |
Lists the device's restore points with their IDs and kind (file, image or vm) |
cvn-agent browse --config /etc/cvn-agent/agent.json --snapshot latest |
Lists the files inside a restore point as JSON |
cvn-agent restore --config /etc/cvn-agent/agent.json --dest /srv/restore --snapshot latest |
Restores a restore point into a folder. --path restores one file or folder from it. |
cvn-agent image-restore --config /etc/cvn-agent/agent.json --snapshot latest --device /dev/sdb --force |
Writes a disk image to a disk. --out <file> writes it to a file instead. |
cvn-agent pve-restore --config /etc/cvn-agent/agent.json --snapshot latest |
Restores a Proxmox guest |
Maintenance
| Command | What it does |
|---|---|
cvn-agent prune --config /etc/cvn-agent/agent.json |
Applies retention and deletes unused chunks. See Retention. |
cvn-agent verify --config /etc/cvn-agent/agent.json |
Runs the recovery check on the latest restore point now and reports the result |
cvn-agent update --check |
Reports whether your server has a newer agent. Without --check, installs it. |
The passphrase
The agent reads the backup passphrase from the CVN_PASSPHRASE environment variable when it is set, and otherwise from its configuration. To set or change the stored passphrase on a device:
sudo CVN_PASSPHRASE='new passphrase' cvn-agent install --path /srv/data
This also rewrites the service with the folder you give. Changing the passphrase changes the key, so:
- the next backup uploads the device's data in full, and
- older restore points still need the old passphrase. To restore one, set
CVN_PASSPHRASEto the old passphrase for that command only.