Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: borg serve: recommend using a simple shell (closes #3818) #8620

Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions docs/usage/serve.rst
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@ Details about sshd usage: `sshd(8) <https://www.openbsd.org/cgi-bin/man.cgi/Open

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:
Expand All @@ -74,3 +75,16 @@ This will cause the server to send a keep alive to the client every 10 seconds.
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
ThomasWaldmann marked this conversation as resolved.
Show resolved Hide resolved

Because the configured shell is used by `openssh <https://www.openssh.com/>`_
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.
Loading