Install on Linux and macOS

You install the Restow agent with one command that Restow creates for you. Restow shows a one-time token next to the command, and the install script asks for it with hidden input, so the token never appears on a command line and you never type other credentials on the machine.

Requirements

On the machine

• Linux: systemd, x86_64 or aarch64, root rights (sudo), curl, and sha256sum or shasum. To check the release signature, ssh-keygen from OpenSSH 8.1 or newer, or OpenSSL 3. Debian 11 and newer, Ubuntu 20.04 and newer and RHEL 9 have it. For systems without either, see Systems without a signature tool.
• macOS: macOS 13 (Ventura) or newer, Intel or Apple Silicon, an administrator account (sudo) and curl. The ssh-keygen of every supported macOS checks the release signature.
• HTTPS to Restow. The machine must reach your Restow instance over HTTPS. The agent only connects out. No inbound port is needed or opened.
• A correct clock. Certificate checks fail on a machine whose clock is far off.
• A trusted certificate. The agent uses the operating system’s trust store. If your instance uses a certificate from a private certificate authority, the CA must be in that trust store, or, on Linux, in a file named by SSL_CERT_FILE (see Proxy and private CA). The agent has no setting of its own for this.

In Restow

• Set the public URL of your installation in the settings. The address in the install command comes from it. If none is set, Restow uses the address of your browser and warns you, and the machine must be able to reach exactly that address.
• Use an https:// address. The install scripts refuse a plain http:// instance. The interface warns you about an unencrypted address before you connect a machine, because the token and the secrets of the agent would travel unencrypted.

Create the install command

1. Open Servers & clients → Inventory. The chips All, Servers and Clients filter the list.
2. Choose New server or New client.
3. Choose the operating system: Linux or macOS. Windows is shown as “Planned” and cannot be chosen.
4. Optionally give the machine a name. It is shown in the lists instead of the host name, and you can change it later.
5. Choose Create install command.

The window shows the install command and, below it, the enrollment token, each with its own copy button. It also shows the command for an unattended installation and the commands to remove the agent later. The window shows when the machine has connected. You can close it and find the machine in the list later.

The token is shown only once and cannot be shown again after you close the window. If you lose it, create a new command. Commands that nobody has used yet are listed under Pending enrollments, where you can revoke them.

You find the same buttons, New server and New client, under Tenant settings → Agents, next to the pending commands, the switch for automatic agent updates and, since 0.4.0, the tenant’s agent policy.

A client token on a container or a virtual machine without a desktop (since 0.4.0)

The agent 0.4.0 tells Restow what the machine runs as. A Linux machine that you enroll with a client command, but whose agent reports a container or a virtual machine without a desktop, gets the Server profile, because it runs services. The machine’s page says why. See Profiles.

Run the command

Run it on the machine you want to back up.

# Linux
curl -fsSL 'https://<your instance>/install/linux.sh' | sudo sh
# macOS
curl -fsSL 'https://<your instance>/install/macos.sh' | sudo sh

Restow fills in your instance address when it shows you the command. When the script asks for the enrollment token, paste the token from the window. The input stays hidden.

Unattended installation (RMM, MDM, scripts)

Without a terminal to type into, the script reads the token from a file that only root can read. Write the token into the file (mode 0600, owner root), run the command, and delete the file afterwards.

# Linux
curl -fsSL 'https://<your instance>/install/linux.sh' | sudo RESTOW_TOKEN_FILE=/root/restow-enrollment.token sh
# macOS (the home folder of root is /var/root)
curl -fsSL 'https://<your instance>/install/macos.sh' | sudo RESTOW_TOKEN_FILE=/var/root/restow-enrollment.token sh

To write the file by hand on Linux, run sudo sh -c 'umask 077; cat > /root/restow-enrollment.token', paste the token, press Enter and then Ctrl+D (on macOS use /var/root/restow-enrollment.token). The script reads the first line of the file and warns when other users can read it. Delete the file after the installation, for example with sudo rm /root/restow-enrollment.token.

What the script does

The script is served by your own instance, with its address, the agent version and the public key of the agent releases filled in.

1. It detects the CPU architecture and downloads SHA256SUMS, its signature SHA256SUMS.sig, restow-agent, restic and the license notices THIRD_PARTY_NOTICES.txt from <instance>/install/agent/<version>/. The files come from your instance, not from the internet.
2. Before it runs anything, it checks the maintainer’s signature over SHA256SUMS and then the SHA-256 of both binaries and of the notices against SHA256SUMS. It prints the fingerprint of the release key it checked against (signature: OK (release key SHA256:...)). An unsigned release, a wrong signature or a checksum that does not match stops the script, and nothing is installed. See Signed releases.
3. It checks that every folder of the install location belongs to root and is not writable by the group or by others, and refuses otherwise. It then installs restow-agent and restic into /opt/restow-agent/bin on Linux or /Library/Application Support/Restow/bin on macOS, staged under random names and renamed into place, and the notices next to that folder as THIRD_PARTY_NOTICES.txt.
4. It installs and enables the service: the systemd unit restow-agent.service on Linux, the LaunchDaemon com.restowbackup.agent on macOS. It links /usr/local/bin/restow-agent to the agent, but only where /usr/local/bin belongs to root.
5. It runs restow-agent enroll. This exchanges the token for credentials and checks that the instance and the backup repository accept them. The script hands the token to this one command in its environment, never on a command line.
6. It starts the service and prints the status.

The token

• It is valid for 24 hours and can be used once.
• Restow stores only a SHA-256 hash of it.
• It is not part of the command. The script reads it with hidden input or from the root-only token file, so it appears neither on a command line nor in the process list or the shell history. It is never printed.
• RESTOW_TOKEN in the environment also works, for example in a root shell. Avoid sudo RESTOW_TOKEN=... sh: that form puts the token in the process list of the machine while the command runs.
• If enrollment fails on the server side (for example because the storage target is not reachable), the server undoes everything and frees the token. You can run the same command again. A request that is invalid (for example an empty host name) does not use the token either.

Hooks at install time

Commands before and after the backup (hooks) run as root, so the machine decides whether it runs them. On a new machine they are off. To allow them while you install, add --hooks=scripts (only scripts in /etc/restow-agent/hooks.d) or --hooks=any (any command):

curl -fsSL 'https://<your instance>/install/linux.sh' | sudo sh -s -- --hooks=scripts

--hooks=off switches them off. You can change the policy later on the machine with sudo restow-agent hooks ....

Safe to run again

You can run the command again at any time. It repairs or upgrades the installation in place, keeps an existing enrollment and never installs twice. On a machine that is already enrolled, the token is not needed. With --hooks=... it also sets the hook policy of the enrolled machine.

Signed releases

Every agent release (the agent and restic, for every platform) is signed by the maintainer with an Ed25519 key in the OpenSSH signature format. The signature covers the release’s SHA256SUMS, which lists the SHA-256 of every binary. The public key is compiled into the agent and written into the install scripts. The install script checks the signature with ssh-keygen -Y verify (OpenSSH 8.1 or newer) or with OpenSSL 3. The agent only installs updates that are signed with this key.

Check the release key fingerprint

The first installation trusts the install script that your instance serves, as with any curl | sh. To rule out a changed script, compare the fingerprint that the script prints in the line signature: OK (release key SHA256:...) with the fingerprint of the agent release key (ED25519, key name restow-agent-release), which is also published in the release notes of the version:

SHA256:2LB7RPpIS0wqbcZ2NA8MjuQN7ZfFPqBX3CwrGFSu76o

If they differ, do not use the installation: remove the agent again (see Uninstall) and check your instance.

Systems without a signature tool

RHEL, Rocky Linux and AlmaLinux 8 and Amazon Linux 2 have neither OpenSSH 8.1 nor OpenSSL 3. The script stops there with an explanation and installs nothing. Check the signature on another machine instead and give the script the SHA-256 of the checked SHA256SUMS:

1. On a machine with OpenSSH 8.1 or newer, download SHA256SUMS and SHA256SUMS.sig from https://<your instance>/install/agent/<version>/ (the GitHub release carries the same files as agent-SHA256SUMS and agent-SHA256SUMS.sig), and the public key agent/release-signing.pub from the source code at the release tag.

2. Check the key and the signature, and compute the SHA-256 of the checked file:

   ssh-keygen -l -f release-signing.pub    # must print SHA256:2LB7RPpIS0wqbcZ2NA8MjuQN7ZfFPqBX3CwrGFSu76o
   printf 'restow-agent-release %s\n' "$(cut -d ' ' -f 1-2 release-signing.pub)" > allowed_signers
   ssh-keygen -Y verify -f allowed_signers -I restow-agent-release -n restow-agent-release -s SHA256SUMS.sig < SHA256SUMS
   sha256sum SHA256SUMS                    # on macOS: shasum -a 256 SHA256SUMS

3. On the machine you want to back up, pass that value to the script:

   curl -fsSL 'https://<your instance>/install/linux.sh' | sudo RESTOW_SHA256SUMS_SHA256=<sha256 of SHA256SUMS> sh

The script then accepts only a SHA256SUMS with exactly this hash and checks both binaries against it. The agent itself checks signatures without any external tool, so its updates work on these systems. For checking the files of a release in general, see Verifying a release.

macOS: grant Full Disk Access

macOS protects Desktop, Documents, Downloads, iCloud Drive and other folders. Without access the agent skips those files, the backup ends as partial and the run log says so.

1. Open System Settings > Privacy & Security > Full Disk Access.
2. Add /Library/Application Support/Restow/bin/restow-agent. In the file dialog, Cmd+Shift+G opens a field where you can paste the path.
3. If protected folders are still reported after that, also add /Library/Application Support/Restow/bin/restic.

The next backup then includes those files.

On Macs that are managed through MDM, deploy a Privacy Preferences Policy Control profile instead, which grants the same access without a person clicking through System Settings.

Check the status

On the machine:

restow-agent status

It shows the local state and needs no root rights. With sudo it also shows the hook policy, because the enrollment can be read by root only. It names the binary in use and says so if the installation is not safe. Since 0.4.0 it also shows the agent policy that applies (Policy, only what differs from the default) and, when a due backup waits, why (Waiting). --json gives the same for scripts. In Restow, the endpoint appears in the list and its status changes to Online after the first contact.

The command restow-agent is the link in /usr/local/bin, which the script creates only where that folder belongs to root (on an Intel Mac with Homebrew it belongs to a user, so there is no link). The full path always works:

# Linux
sudo /opt/restow-agent/bin/restow-agent status
# macOS
sudo '/Library/Application Support/Restow/bin/restow-agent' status

Since 0.2.1 a newly enrolled machine is backed up only once it is a member of a backup job: until then Inventory marks it Without backup and offers Create a job and Add to job…. Once it is in a job, it follows the job’s schedule. To start the first backup at once, open the machine under Servers & clients → Inventory and choose Back up now. The machine picks the request up with its next contact, usually within a few minutes. While a Restow update pauses new runs, the request stays queued on the server until the pause is over.

Command line

restow-agent enroll        Enroll this machine (RESTOW_TOKEN and RESTOW_URL from the environment)
restow-agent run           The service main loop (what systemd / launchd execute)
restow-agent status        Local state, no root needed (--json for scripts)
restow-agent backup-now    Run one backup in the foreground (exit 0 ok, 3 partial, 1 failed)
restow-agent update        Install the release the server offers, at once (since 0.4.2)
restow-agent service ...   install | start | stop | restart | status
restow-agent hooks ...     status | off | scripts | any: whether hooks from the server run here
restow-agent uninstall     Remove the agent (--yes, --keep-logs)
restow-agent version       Version, commit, build date (--short for the number only)

• Since 0.4.0, backup-now waits while a Restow update pauses new runs. It says so and starts when the pause is over; Ctrl-C stops waiting without starting a backup. See The update pause.
• Since 0.4.2, update installs the release your instance offers right away, like restow-pve update on a Proxmox VE node: the signed SHA256SUMS is checked with the key built into the agent, then every file against its signed hash, and only then is anything replaced. It restarts the service so that the new version runs and says what it did (updated from and to, or “No newer release is offered”). It holds the run lock while it works, so no backup starts. While a backup, a restore or a restore test runs it refuses (“A backup is running; the update waits”, exit code 1), and the service installs the update itself once it is idle. Run it as root (sudo).
• --debug, or RESTOW_DEBUG=1, turns on verbose logging.
• enroll --force enrolls the machine again with a new token. The old endpoint stays in Restow until you revoke it, and its backups stay stored until you remove it from Restow and delete them. See Uninstall.
• enroll --hooks=off|scripts|any sets the hook policy of a new enrollment (default off). A new enrollment of an enrolled machine keeps its policy.
• hooks needs root rights. See Profiles, schedule and hooks.
• enroll --allow-insecure-http exists for local development only. The install scripts refuse it unless RESTOW_ALLOW_INSECURE_HTTP=1 is set, and the agent prints a warning every time.

Files

Path	Content
/opt/restow-agent/bin/restow-agent, /opt/restow-agent/bin/restic (macOS: /Library/Application Support/Restow/bin/)	The binaries, in a folder only root can change. restow-agent.prev is the previous agent after an update.
/opt/restow-agent/THIRD_PARTY_NOTICES.txt (macOS: /Library/Application Support/Restow/THIRD_PARTY_NOTICES.txt)	The license notices of the agent, Go, restic and the Go modules compiled into restic. Readable by all, checked against the signed SHA256SUMS like the binaries, replaced by every self-update.
/usr/local/bin/restow-agent	A link to the agent for administrators, only where /usr/local/bin belongs to root.
/etc/restow-agent/state.json	Enrollment: instance URL, endpoint id, agent secret, repository URL and password, hook policy. Mode 0600.
/etc/restow-agent/hooks.d/	The hook scripts that root allowed for the scripts policy.
/var/lib/restow-agent/status.json	Runtime status for restow-agent status. No secrets.
/var/lib/restow-agent/cache	The restic cache. It holds metadata of the repository, can grow to a few GB for large repositories, and can be deleted.
/var/lib/restow-agent/{tmp,restic-tmp,outbox}	Temporary restore copies, restic option files and run reports that could not be delivered yet.
/var/log/restow-agent/agent.log	The agent log, rotated at 5 MB, 3 files kept. On Linux it is also in the journal. On macOS, launchd.log holds crash traces.
/etc/systemd/system/restow-agent.service	The systemd unit (Linux).
/Library/LaunchDaemons/com.restowbackup.agent.plist	The LaunchDaemon (macOS).

Proxy and private CA

The agent passes proxy settings and a private CA bundle on when they are set in the service environment. The variables are HTTPS_PROXY, NO_PROXY and, on Linux, SSL_CERT_FILE. On Linux you set them with a systemd drop-in:

sudo systemctl edit restow-agent

Add, for example:

[Service]
Environment="HTTPS_PROXY=http://proxy.example.com:3128"
Environment="NO_PROXY=localhost,127.0.0.1"
Environment="SSL_CERT_FILE=/etc/ssl/certs/company-ca.pem"

Then restart the service:

sudo systemctl restart restow-agent

Adding a private CA to the operating system’s trust store is the simpler route when you can. The same variables also reach restic and your hooks, because they are on the short list of variables the agent passes on.

After the install

• Profiles, schedule and hooks: choose what is backed up and when.
• Troubleshooting: if the script or the first backup does not work.