borg-serve

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 usually 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 specified multiple times  to
          allow  the  client  access  to  several  repositories. Unlike --restrict-to-path sub-directories are not accessible; 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 running 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 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 op‐
   tions. 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 vari‐
   ables 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  (exam‐
   ple 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 automatically block potential dangerous ssh features, even when they are added in a future up‐
      date. Thus, this option should be preferred.

      If you're using openssh-server < 7.2, however, you have to explicitly 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-forwarding,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 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  sec‐
   onds), 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 sec‐
   onds), 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.