From 96deffce14370fcf49328ef351cdff80e7058988 Mon Sep 17 00:00:00 2001 From: Martin Richtarsky Date: Mon, 21 Oct 2024 17:32:11 +0200 Subject: [PATCH] docs/FAQ: Clean up entries regarding SSH settings Link to recommended ones (cherry picked from commit 05837fbeb70a14975a040a409c9cdcf3cd3d33dd) --- docs/faq.rst | 60 +++++++++++--------------------------------- docs/quickstart.rst | 3 ++- docs/usage/serve.rst | 2 ++ 3 files changed, 18 insertions(+), 47 deletions(-) diff --git a/docs/faq.rst b/docs/faq.rst index bdc9d6d86..560843251 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -757,31 +757,25 @@ You will also get this error if you try to access a repository that uses the arg We recommend upgrading to the latest stable version and trying again. We are sorry. We should have thought abount forward compatibility and implemented a more helpful error message. -Why does Borg extract hang after some time? -------------------------------------------- +Why am I seeing idle borg serve processes on the repo server? +------------------------------------------------------------- -When I do a ``borg extract``, after a while all activity stops, no cpu usage, -no downloads. +Please see the next question. -This may happen when the SSH connection is stuck on server side. You can -configure SSH on client side to prevent this by sending keep-alive requests, -for example in ~/.ssh/config: +Why does Borg disconnect or hang when backing up to a remote server? +-------------------------------------------------------------------- -:: +Communication with the remote server (using an ssh: repo URL) happens via an SSH +connection. This can lead to some issues that would not occur during a local backup: - Host borg.example.com - # Client kills connection after 3*30 seconds without server response: - ServerAliveInterval 30 - ServerAliveCountMax 3 +- Since Borg does not send data all the time, the connection may get closed, leading + to errors like "connection closed by remote". +- On the other hand, network issues may lead to a dysfunctional connection + that is only detected after some time by the server, leading to stale ``borg serve`` + processes and locked repositories. -You can also do the opposite and configure SSH on server side in -/etc/ssh/sshd_config, to make the server send keep-alive requests to the client: - -:: - - # Server kills connection after 3*30 seconds without client response: - ClientAliveInterval 30 - ClientAliveCountMax 3 +To fix such problems, please apply these :ref:`SSH settings ` so that +keep-alive requests are sent regularly. How can I deal with my very unstable SSH connection? ---------------------------------------------------- @@ -797,32 +791,6 @@ could try to work around: to do any more. Due to the way borg mount works, this might be less efficient than borg extract for bigger volumes of data. -Why do I get "connection closed by remote" after a while? ---------------------------------------------------------- - -When doing a backup to a remote server (using a ssh: repo URL), it sometimes -stops after a while (some minutes, hours, ... - not immediately) with -"connection closed by remote" error message. Why? - -That's a good question and we are trying to find a good answer in :issue:`636`. - -Why am I seeing idle borg serve processes on the repo server? -------------------------------------------------------------- - -Maybe the ssh connection between client and server broke down and that was not -yet noticed on the server. Try these settings: - -:: - - # /etc/ssh/sshd_config on borg repo server - kill connection to client - # after ClientAliveCountMax * ClientAliveInterval seconds with no response - ClientAliveInterval 20 - ClientAliveCountMax 3 - -If you have multiple borg create ... ; borg create ... commands in a already -serialized way in a single script, you need to give them ``--lock-wait N`` (with N -being a bit more than the time the server needs to terminate broken down -connections and release the lock). .. _disable_archive_chunks: diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 85f75742f..cab69b242 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -408,7 +408,8 @@ is installed on the remote host, in which case the following syntax is used:: $ borg init user@hostname:/path/to/repo -Note: please see the usage chapter for a full documentation of repo URLs. +Note: Please see the usage chapter for a full documentation of repo URLs. Also +see :ref:`ssh_configuration` for recommended settings to avoid disconnects and hangs. Remote operations over SSH can be automated with SSH keys. You can restrict the use of the SSH keypair by prepending a forced command to the SSH public key in diff --git a/docs/usage/serve.rst b/docs/usage/serve.rst index 96a535888..9008a143a 100644 --- a/docs/usage/serve.rst +++ b/docs/usage/serve.rst @@ -44,6 +44,8 @@ locations like ``/etc/environment`` or in the forced command itself (example bel Details about sshd usage: `sshd(8) `_ +.. _ssh_configuration: + 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``.