borg [common options] serve [options]
options |
||
|
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 point directly to a repository. |
|
|
restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike |
|
|
Set repository permission mode. Overrides BORG_REPO_PERMISSIONS environment variable. |
|
This command starts a repository server process.
borg serve can currently support:
Getting automatically started via ssh when the borg client uses a ssh://… remote repository. In this mode, borg serve will live until that ssh connection gets terminated.
Getting started by some other means (not by the borg client) as a long-running socket server to be used for borg clients using a socket://… repository (see the --socket option if you do not want to use the default path for the socket and pid file).
Please note that borg serve does not support giving a specific repository via the --repo option or BORG_REPO environment variable. It is always the borg client which specifies the repo to use when talking to borg serve.
The --permissions option allows enforcing repository permissions:
all: All permissions are granted (default, permissions system is not used)
no-delete: Allow reading and writing, disallow deleting and overwriting data. New archives can be created, existing archives can not be deleted. New chunks can be added, existing chunks can not be deleted or overwritten.
write-only: Allow writing, disallow reading data. New archives can be created, existing archives can not be read. New chunks can be added, existing chunks can not be read, deleted or overwritten.
read-only: Allow reading, disallow writing or deleting data. Existing archives can be read, but no archives can be created or deleted.
borg serve
has special support for ssh forced commands (see authorized_keys
example below): if the environment variable SSH_ORIGINAL_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
command 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 run only 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[...]
# Specify repository permissions for an SSH keypair.
$ cat ~/.ssh/authorized_keys
command="borg serve --permissions=read-only",restrict ssh-rsa AAAAB3[...]
# Set a BORG_XXX environment variable on the "borg serve" side
$ cat ~/.ssh/authorized_keys
command="BORG_XXX=value borg serve [...]",restrict ssh-rsa [...]
Note
The examples above use the restrict
directive and assume a POSIX
compliant shell set as the user’s login shell.
This does automatically 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 specify explicitly
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-forwarding,no-user-rc
in this case.
Details about sshd usage: sshd(8)
borg serve
’s pipes (stdin
/stdout
/stderr
) are connected to the sshd
process on the server side. In the event that the SSH connection between 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
continues 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/acquire the lock
.
In order to avoid this, it is recommended to perform the following additional 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, causing 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 sufficient time for the borg serve processes to terminate after the SSH connection 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.
When the client is untrusted, it is a good idea to set the backup
user’s shell to a simple implementation (/bin/sh
is only an example and may or may
not be such a simple implementation):
chsh -s /bin/sh BORGUSER
Because the configured shell is used by openssh
to execute the command configured through the authorized_keys
file
using "$SHELL" -c "$COMMAND"
,
setting a minimal shell implementation reduces the attack surface
compared to when a feature-rich and complex shell implementation is
used.