borg-serve(1) - Man pages

BORG-SERVE(1) borg backup tool BORG-SERVE(1)

NAME
borg-serve - Start in server mode. This command is usually not used
manually.

SYNOPSIS
borg [common options] serve [options]

DESCRIPTION
This command starts a repository server process. This command is usu-
ally not used manually.

OPTIONS
See borg-common(1) for common options of Borg commands.

options
--restrict-to-path PATH
restrict repository access to PATH. Can be specified multiple
times to allow the client access to several directories. Access
to all sub-directories is granted implicitly; PATH doesn't need
to directly point to a repository.

--restrict-to-repository PATH
restrict repository access. Only the repository located at PATH
(no sub-directories are considered) is accessible. Can be speci-
fied multiple times to allow the client access to several repos-
itories. Unlike --restrict-to-path sub-directories are not ac-
cessible; PATH needs to directly point at a repository location.
PATH may be an empty directory or the last element of PATH may
not exist, in which case the client may initialize a repository
there.

--append-only
only allow appending to repository segment files. Note that this
only affects the low level structure of the repository, and run-
ning delete or prune will still be allowed. See append_only_mode
in Additional Notes for more details.

--storage-quota QUOTA
Override storage quota of the repository (e.g. 5G, 1.5T). When a
new repository is initialized, sets the storage quota on the new
repository as well. Default: no quota.

EXAMPLES
borg serve has special support for ssh forced commands (see autho-
rized_keys example below): if the environment variable SSH_ORIGI-
NAL_COMMAND is set it will ignore some options given on the command
line and use the values from the variable instead. This only applies to
a carefully controlled allowlist of safe options. This list currently
contains:

• Options that control the log level and debug topics printed such as
--verbose, --info, --debug, --debug-topic, etc.

• --lock-wait to allow the client to control how long to wait before
giving up and aborting the operation when another process is holding
a lock.

Environment variables (such as BORG_XXX) contained in the original com-
mand sent by the client are not interpreted, but ignored. If BORG_XXX
environment variables should be set on the borg serve side, then these
must be set in system-specific locations like /etc/environment or in
the forced command itself (example below).

# Allow an SSH keypair to only run borg, and only have access to /path/to/repo.
# Use key options to disable unneeded and potentially dangerous SSH functionality.
# This will help to secure an automated remote backup system.
$ cat ~/.ssh/authorized_keys
command="borg serve --restrict-to-path /path/to/repo",restrict ssh-rsa AAAAB3[...]

# Set a BORG_XXX environment variable on the "borg serve" side
$ cat ~/.ssh/authorized_keys
command="export BORG_XXX=value; borg serve [...]",restrict ssh-rsa [...]

NOTE:
The examples above use the restrict directive. This does automati-
cally block potential dangerous ssh features, even when they are
added in a future update. Thus, this option should be preferred.

If you're using openssh-server < 7.2, however, you have to explic-
itly specify the ssh features to restrict and cannot simply use the
restrict option as it has been introduced in v7.2. We recommend to
use no-port-forwarding,no-X11-forwarding,no-pty,no-agent-forward-
ing,no-user-rc in this case.

Details about sshd usage: sshd(8)

SSH Configuration
borg serve's pipes (stdin/stdout/stderr) are connected to the sshd
process on the server side. In the event that the SSH connection be-
tween borg serve and the client is disconnected or stuck abnormally
(for example, due to a network outage), it can take a long time for
sshd to notice the client is disconnected. In the meantime, sshd con-
tinues running, and as a result so does the borg serve process holding
the lock on the repository. This can cause subsequent borg operations
on the remote repository to fail with the error: Failed to create/ac-
quire the lock.

In order to avoid this, it is recommended to perform the following ad-
ditional SSH configuration:

Either in the client side's ~/.ssh/config file, or in the client's
/etc/ssh/ssh_config file:

Host backupserver
ServerAliveInterval 10
ServerAliveCountMax 30

Replacing backupserver with the hostname, FQDN or IP address of the
borg server.

This will cause the client to send a keepalive to the server every 10
seconds. If 30 consecutive keepalives are sent without a response (a
time of 300 seconds), the ssh client process will be terminated, caus-
ing the borg process to terminate gracefully.

On the server side's sshd configuration file (typically
/etc/ssh/sshd_config):

ClientAliveInterval 10
ClientAliveCountMax 30

This will cause the server to send a keep alive to the client every 10
seconds. If 30 consecutive keepalives are sent without a response (a
time of 300 seconds), the server's sshd process will be terminated,
causing the borg serve process to terminate gracefully and release the
lock on the repository.

If you then run borg commands with --lock-wait 600, this gives suffi-
cient time for the borg serve processes to terminate after the SSH con-
nection is torn down after the 300 second wait for the keepalives to
fail.

You may, of course, modify the timeout values demonstrated above to
values that suit your environment and use case.