mirror of https://github.com/borgbackup/borg.git
[DOCS] Add socat pull mode (#5150)
docs: describe socat pull mode, fixes #900 also: fix sphinx deprecation warning borg/docs/conf.py:114: RemovedInSphinx40Warning: The app.add_stylesheet() is deprecated. Please use app.add_css_file() instead.
This commit is contained in:
Benedikt Seidl
GitHub
parent
e351eedd87
commit
6a1f31bf29
|
|
@ -111,7 +111,7 @@ def set_rst_settings(app):
|
|||
|
||||
|
||||
def setup(app):
|
||||
app.add_stylesheet('css/borg.css')
|
||||
app.add_css_file('css/borg.css')
|
||||
app.connect('builder-inited', set_rst_settings)
|
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme
|
||||
|
|
|
|||
|
|
@ -1,9 +1,23 @@
|
|||
.. include:: ../global.rst.inc
|
||||
.. highlight:: none
|
||||
|
||||
=======================
|
||||
Backing up in pull mode
|
||||
=======================
|
||||
|
||||
Typically the borg client connects to a backup server using SSH as a transport
|
||||
when initiating a backup. This is referred to as push mode.
|
||||
|
||||
If you however require the backup server to initiate the connection or prefer
|
||||
it to initiate the backup run, one of the following workarounds is required to
|
||||
allow such a pull mode setup.
|
||||
|
||||
A common use case for pull mode is to backup a remote server to a local personal
|
||||
computer.
|
||||
|
||||
SSHFS
|
||||
=====
|
||||
|
||||
Assuming you have a pull backup system set up with borg, where a backup server
|
||||
pulls the data from the target via SSHFS. In this mode, the backup client's file
|
||||
system is mounted remotely on the backup server. Pull mode is even possible if
|
||||
|
|
@ -174,3 +188,116 @@ directly extract it without the need of mounting with SSHFS:
|
|||
Note that in this scenario the tar format is the limiting factor – it cannot
|
||||
restore all the advanced features that BorgBackup supports. See
|
||||
:ref:`borg_export-tar` for limitations.
|
||||
|
||||
socat
|
||||
=====
|
||||
|
||||
In this setup a SSH connection from the backup server to the client is
|
||||
established that uses SSH reverse port forwarding to transparently
|
||||
tunnel data between UNIX domain sockets on the client and server and the socat
|
||||
tool to connect these with the borg client and server processes, respectively.
|
||||
|
||||
The program socat has to be available on the backup server and on the client
|
||||
to be backed up.
|
||||
|
||||
When **pushing** a backup the borg client (holding the data to be backed up)
|
||||
connects to the backup server via ssh, starts ``borg serve`` on the backup
|
||||
server and communicates via standard input and output (transported via SSH)
|
||||
with the process on the backup server.
|
||||
|
||||
With the help of socat this process can be reversed. The backup server will
|
||||
create a connection to the client (holding the data to be backed up) and will
|
||||
**pull** the data.
|
||||
|
||||
In the following example *borg-server* connects to *borg-client* to pull a backup.
|
||||
|
||||
To provide a secure setup sockets should be stored in ``/run/borg``, only
|
||||
accessible to the users that run the backup process. So on both systems,
|
||||
*borg-server* and *borg-client* the folder ``/run/borg`` has to be created::
|
||||
|
||||
sudo mkdir -m 0700 /run/borg
|
||||
|
||||
On *borg-server* the socket file is opened by the user running the ``borg
|
||||
serve`` process writing to the repository
|
||||
so the user has to have read and write permissions on ``/run/borg``::
|
||||
|
||||
borg-server:~$ sudo chown borgs /run/borg
|
||||
|
||||
On *borg-client* the socket file is created by ssh, so the user used to connect
|
||||
to *borg-client* has to have read and write permissions on ``/run/borg``::
|
||||
|
||||
borg-client:~$ sudo chown borgc /run/borg
|
||||
|
||||
On *borg-server*, we have to start the command ``borg serve`` and make its
|
||||
standard input and output available to a unix socket::
|
||||
|
||||
borg-server:~$ socat UNIX-LISTEN:/run/borg/reponame.sock,fork EXEC:"borg serve --append-only --restrict-to-path /path/to/repo"
|
||||
|
||||
Socat will wait until a connection is opened. Then socat will execute the
|
||||
command given, redirecting Standard Input and Output to the unix socket. The
|
||||
optional arguments for ``borg serve`` are not necessary but a sane default.
|
||||
|
||||
.. note::
|
||||
When used in production you may also use systemd socket-based activation
|
||||
instead of socat on the server side. You would wrap the ``borg serve`` command
|
||||
in a `service unit`_ and configure a matching `socket unit`_
|
||||
to start the service whenever a client connects to the socket.
|
||||
|
||||
.. _service unit: https://www.freedesktop.org/software/systemd/man/systemd.service.html
|
||||
.. _socket unit: https://www.freedesktop.org/software/systemd/man/systemd.socket.html
|
||||
|
||||
Now we need a way to access the unix socket on *borg-client* (holding the
|
||||
data to be backed up), as we created the unix socket on *borg-server*
|
||||
Opening a SSH connection from the *borg-server* to the *borg-client* with reverse port
|
||||
forwarding can do this for us::
|
||||
|
||||
borg-server:~$ ssh -R /run/borg/reponame.sock:/run/borg/reponame.sock borgc@borg-client
|
||||
|
||||
.. note::
|
||||
|
||||
As the default value of OpenSSH for ``StreamLocalBindUnlink`` is ``no``, the
|
||||
socket file created by sshd is not removed. Trying to connect a second time,
|
||||
will print a short warning, and the forwarding does **not** take place::
|
||||
|
||||
Warning: remote port forwarding failed for listen path /run/borg/reponame.sock
|
||||
|
||||
When you are done, you have to manually remove the socket file, otherwise
|
||||
you may see an error like this when trying to execute borg commands::
|
||||
|
||||
Remote: YYYY/MM/DD HH:MM:SS socat[XXX] E connect(5, AF=1 "/run/borg/reponame.sock", 13): Connection refused
|
||||
Connection closed by remote host. Is borg working on the server?
|
||||
|
||||
|
||||
When a process opens the socket on *borg-client*, SSH will forward all
|
||||
data to the socket on *borg-server*.
|
||||
|
||||
The next step is to tell borg on *borg-client* to use the unix socket to communicate with the
|
||||
``borg serve`` command on *borg-server* via the socat socket instead of SSH::
|
||||
|
||||
borg-client:~$ export BORG_RSH="sh -c 'exec socat STDIO UNIX-CONNECT:/run/borg/reponame.sock'"
|
||||
|
||||
The default value for ``BORG_RSH`` is ``ssh``. By default Borg uses SSH to create
|
||||
the connection to the backup server. Therefore Borg parses the repo URL
|
||||
and adds the server name (and other arguments) to the SSH command. Those
|
||||
arguments can not be handled by socat. We wrap the command with ``sh`` to
|
||||
ignore all arguments intended for the SSH command.
|
||||
|
||||
All Borg commands can now be executed on *borg-client*. For example to create a
|
||||
backup execute the ``borg create`` command::
|
||||
|
||||
borg-client:~$ borg create ssh://borg-server/path/to/repo::archive /path_to_backup
|
||||
|
||||
When automating backup creation, the
|
||||
interactive ssh session may seem inappropriate. An alternative way of creating
|
||||
a backup may be the following command::
|
||||
|
||||
borg-server:~$ ssh \
|
||||
-R /run/borg/reponame.sock:/run/borg/reponame.sock \
|
||||
borgc@borg-client \
|
||||
borg create \
|
||||
--rsh "sh -c 'exec socat STDIO UNIX-CONNECT:/run/borg/reponame.sock'" \
|
||||
ssh://borg-server/path/to/repo::archive /path_to_backup \
|
||||
';' rm /run/borg/reponame.sock
|
||||
|
||||
This command also automatically removes the socket file after the ``borg
|
||||
create`` command is done.
|
||||
|
|
|
|||
Loading…
Reference in New Issue