mirror of
https://github.com/borgbackup/borg.git
synced 2026-10-12 02:11:36 +00:00
docs: ssh:// repository URLs, #9765
Describe ssh:// repository URLs for current repositories (served by a remote "borg serve --rest") and for legacy borg 1.x repositories (with --from-borg1, served by a remote "borg serve") and add a change log entry. Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
Thomas Waldmann
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
93481e0fb8
commit
db0c4ac2c1
+7
-7
@@ -131,13 +131,13 @@ so the repository storage layer never sees plaintext or has any notion of files/
|
||||
- **`repository.py`** — `Repository`, a key→value object store built on top of **borgstore**
|
||||
(`borgstore.store.Store`). Keys are 32-byte object IDs; the repo doesn't know what an "archive" or
|
||||
"file" is. borgstore provides the actual storage backends and transport: local filesystem,
|
||||
`ssh://` (borgstore ssh backend, optionally reusing `BORGSTORE_RSH`), and `rest://` (borgstore REST
|
||||
server, served by `borg serve --rest`). This replaces the borg 1.x segment/journal format — read
|
||||
`ssh://` (borgstore REST backend talking HTTP over stdio over ssh to a remote `borg serve`,
|
||||
optionally reusing `BORGSTORE_RSH`), `sftp://`, `http(s)://`, `rclone:`, `s3:`/`b2:`. This replaces the borg 1.x segment/journal format — read
|
||||
`docs/internals/data-structures.rst` before touching repository/object/format code.
|
||||
- **`archiver/serve_cmd.py`** — `borg serve` provides the server side for remote repositories: the
|
||||
default mode serves a repository over stdio to a connecting borgstore ssh backend, and
|
||||
`borg serve --rest` runs the borgstore REST server. (There is no separate `remote.py` / custom RPC
|
||||
layer anymore — borgstore owns the client/server transport.)
|
||||
- **`archiver/serve_cmd.py`** — `borg serve` provides the server side for `ssh://` repositories:
|
||||
`borg serve --rest` runs the borgstore REST server on stdio for a current repository, plain
|
||||
`borg serve` serves a legacy borg 1.x repository via the legacy RPC protocol (`--from-borg1`,
|
||||
`legacy/remote.py`).
|
||||
- **`crypto/key.py`, `crypto/low_level.pyx`** — encryption/authentication (AEAD: AES-256-OCB or
|
||||
ChaCha20-Poly1305; ids via HMAC-SHA256 or BLAKE3) and key file handling (keyfile vs repokey
|
||||
storage). The `id_hash` used for deduplication depends on the key/encryption mode.
|
||||
@@ -168,7 +168,7 @@ so the repository storage layer never sees plaintext or has any notion of files/
|
||||
progress reporting, filesystem helpers); check here before writing a new utility, it may exist.
|
||||
|
||||
**Client/server split:** most `do_*` archiver commands operate against a local or remote `Repository`
|
||||
transparently — the choice of local vs. `ssh://`/`rest://` is resolved by `Location` parsing in
|
||||
transparently — the choice of local vs. `ssh://` etc. is resolved by `Location` parsing in
|
||||
`helpers/` and borgstore backend selection, and doesn't otherwise change command logic. `borg serve`
|
||||
on the remote end provides the server side.
|
||||
|
||||
|
||||
+1
-1
@@ -102,7 +102,7 @@ Main features
|
||||
**Off-site backups**
|
||||
Borg can store data on any remote host accessible via misc. protocols:
|
||||
|
||||
* ``rest://`` (REST-http-over-stdio-over-ssh) and ``http(s)://``
|
||||
* ``ssh://`` (REST-http-over-stdio-over-ssh) and ``http(s)://``
|
||||
(REST-http-over-tcp). Significant performance gains can be achieved with
|
||||
these by having a remote agent (borg must be installed on the repo server).
|
||||
* ``sftp://``
|
||||
|
||||
+4
-1
@@ -180,6 +180,9 @@ Breaking changes (you must create new repos for b25):
|
||||
the authenticated modes, #9819, #10235.
|
||||
- drop OBJ_VERSION_NO_HEADER_AAD (pack object format v1) support, #9973
|
||||
- KeyType: renumber the authenticated key types to 0x50 / 0x60
|
||||
- ssh:// repository URLs access current repositories via REST over ssh
|
||||
(served by a remote "borg serve"), #9765. With --from-borg1, they access
|
||||
legacy borg 1.x repositories via the legacy protocol (as before).
|
||||
|
||||
New features:
|
||||
|
||||
@@ -197,7 +200,7 @@ Fixes:
|
||||
|
||||
- crypto: the AEAD ciphers (AES-OCB, ChaCha20-Poly1305) feed their input to OpenSSL in
|
||||
<= 1GB chunks, to overcome the 32bit size limit of the OpenSSL API.
|
||||
- repository: raise DoesNotExist for a missing rest:// repo, #10365
|
||||
- repository: raise DoesNotExist for a missing ssh:// repo, #10365
|
||||
- compact:
|
||||
|
||||
- build the chunk index once, not three times
|
||||
|
||||
@@ -10,11 +10,10 @@ clients.
|
||||
|
||||
.. note::
|
||||
|
||||
This example predates Borg 2 and uses the legacy ``ssh://`` transport (served
|
||||
by ``borg serve``) and ``borg init``. With Borg 2, the ``ssh://`` transport is
|
||||
only used for legacy borg 1.x (v1) repositories; for current repositories use a
|
||||
``rest://`` repository instead (Borg connects via ssh and runs a borgstore REST
|
||||
server on the remote host), and use ``borg repo-create`` instead of ``borg init``.
|
||||
This example predates Borg 2 and uses ``borg init`` and ``borg serve``. With
|
||||
Borg 2, use ``borg repo-create`` instead of ``borg init``, and ``borg serve --rest``
|
||||
instead of ``borg serve`` in the forced command (for ``ssh://`` repositories,
|
||||
Borg connects via ssh and runs ``borg serve --rest`` on the remote host).
|
||||
|
||||
Machines
|
||||
--------
|
||||
|
||||
@@ -49,11 +49,11 @@ files they will be included in this set.
|
||||
|
||||
The ``command`` keyword forces execution of the specified command
|
||||
upon login. This must be ``borg serve --rest``: ``--rest`` serves a current
|
||||
repository (the server side of a ``rest://`` repository URL), while ``borg serve``
|
||||
without it serves a legacy borg 1.x repository using the legacy RPC protocol.
|
||||
The client cannot supply ``--rest`` itself - the mode is deliberately pinned by
|
||||
the forced command - so a forced command without ``--rest`` locks out all clients
|
||||
using current (``rest://``) repositories.
|
||||
repository (the server side of an ``ssh://`` repository URL), while ``borg serve``
|
||||
without it serves a legacy borg 1.x repository using the legacy RPC protocol
|
||||
(used by ``--from-borg1``). The client cannot supply ``--rest`` itself - the mode
|
||||
is deliberately pinned by the forced command - so a forced command without
|
||||
``--rest`` locks out all clients using current repositories.
|
||||
|
||||
The ``--restrict-to-repository`` option permits access to exactly **one**
|
||||
repository. It can be given multiple times to permit access to more than
|
||||
@@ -77,12 +77,12 @@ come from the forced command.
|
||||
The user therefore selects the repository through the path in the repository
|
||||
URL::
|
||||
|
||||
borg -r rest://<user>@<host>/repository repo-list
|
||||
borg -r ssh://<user>@<host>/repository repo-list
|
||||
|
||||
A path with a single leading slash is relative to the directory ssh logs into
|
||||
(the user's home directory), so with the forced command shown above,
|
||||
``rest://<user>@<host>/repository`` and
|
||||
``rest://<user>@<host>//home/<user>/repository`` address the same repository.
|
||||
``ssh://<user>@<host>/repository`` and
|
||||
``ssh://<user>@<host>//home/<user>/repository`` address the same repository.
|
||||
|
||||
Refer to the `sshd(8) <https://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man8/sshd.8>`_
|
||||
man page for more details on SSH options.
|
||||
|
||||
@@ -262,7 +262,7 @@ standard input and output available to a unix socket::
|
||||
Socat will wait until a connection is opened. Then socat will execute the
|
||||
command given, redirecting Standard Input and Output to the unix socket.
|
||||
``--rest`` and ``--backend`` are required here: ``--rest`` serves a current
|
||||
repository (talking HTTP over stdio, the server side of a ``rest://`` repository
|
||||
repository (talking HTTP over stdio, the server side of an ``ssh://`` repository
|
||||
URL), and ``--backend`` selects the repository to serve. ``--restrict-to-path``
|
||||
is not necessary but a sane default.
|
||||
|
||||
@@ -271,7 +271,7 @@ is not necessary but a sane default.
|
||||
(see ``BORG_RSH`` below) is discarded - including the ``--backend`` option the
|
||||
client would normally use to tell the server which repository it wants. The
|
||||
repository therefore is the one given by ``--backend`` in the socat command
|
||||
above, no matter which path the client uses in its ``rest://`` URL. Use the
|
||||
above, no matter which path the client uses in its ``ssh://`` URL. Use the
|
||||
same path in both places to avoid confusion.
|
||||
|
||||
.. note::
|
||||
@@ -322,7 +322,7 @@ SSH command. Those arguments can not be handled by socat. We wrap the command wi
|
||||
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 --repo rest://borg-server//path/to/repo archive /path_to_backup
|
||||
borg-client:~$ borg create --repo 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
|
||||
@@ -333,7 +333,7 @@ a backup may be the following command::
|
||||
borgc@borg-client \
|
||||
BORG_RSH="sh -c 'exec socat STDIO UNIX-CONNECT:/run/borg/reponame.sock'" \
|
||||
borg create \
|
||||
--repo rest://borg-server//path/to/repo archive /path_to_backup \
|
||||
--repo 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
|
||||
@@ -406,7 +406,7 @@ Initiating borg command execution from *borg-server* (e.g. repo-create)::
|
||||
eval $(ssh-agent) > /dev/null
|
||||
ssh-add -q ~/.ssh/borg-client_key
|
||||
echo 'your secure borg key passphrase' | \
|
||||
ssh -A -o StrictHostKeyChecking=no borgc@borg-client "BORG_PASSPHRASE=\$(cat) BORG_RSH='ssh -o StrictHostKeyChecking=no' borg repo-create --encryption aes256-ocb --key-location repokey -r rest://borgs@borg-server/repo"
|
||||
ssh -A -o StrictHostKeyChecking=no borgc@borg-client "BORG_PASSPHRASE=\$(cat) BORG_RSH='ssh -o StrictHostKeyChecking=no' borg repo-create --encryption aes256-ocb --key-location repokey -r ssh://borgs@borg-server/repo"
|
||||
kill "${SSH_AGENT_PID}"
|
||||
)
|
||||
|
||||
@@ -432,13 +432,13 @@ Parentheses are not needed when using a dedicated bash process.
|
||||
* The keys meant to be loaded into the agent must be specified explicitly, not from default locations.
|
||||
* The *borg-client*'s entry in *borgs@borg-server:~/.ssh/authorized_keys* must be as restrictive as possible.
|
||||
|
||||
``echo 'your secure borg key passphrase' | ssh -A -o StrictHostKeyChecking=no borgc@borg-client "BORG_PASSPHRASE=\$(cat) BORG_RSH='ssh -o StrictHostKeyChecking=no' borg repo-create --encryption aes256-ocb --key-location repokey -r rest://borgs@borg-server/repo"``
|
||||
``echo 'your secure borg key passphrase' | ssh -A -o StrictHostKeyChecking=no borgc@borg-client "BORG_PASSPHRASE=\$(cat) BORG_RSH='ssh -o StrictHostKeyChecking=no' borg repo-create --encryption aes256-ocb --key-location repokey -r ssh://borgs@borg-server/repo"``
|
||||
|
||||
Run the *borg repo-create* command on *borg-client*.
|
||||
|
||||
*rest://borgs@borg-server/repo* refers to the repository *repo* within borgs's home directory on *borg-server*
|
||||
*ssh://borgs@borg-server/repo* refers to the repository *repo* within borgs's home directory on *borg-server*
|
||||
(a path given with a single leading slash is relative to the directory ssh logs into; use
|
||||
*rest://borgs@borg-server//path/to/repo* for an absolute path).
|
||||
*ssh://borgs@borg-server//path/to/repo* for an absolute path).
|
||||
|
||||
Borg on *borg-client* connects via ssh (using *BORG_RSH*) and runs ``borg serve --rest`` on
|
||||
*borg-server*, which the forced command in *borgs@borg-server:~/.ssh/authorized_keys* pins down.
|
||||
@@ -490,7 +490,7 @@ using ``localhost`` instead of ``mybackup``
|
||||
|
||||
2. On machine ``myclient``
|
||||
|
||||
``borg create -v --progress --stats -r rest://backup@localhost:8022//home/backup/repos/myclient system /``
|
||||
``borg create -v --progress --stats -r ssh://backup@localhost:8022//home/backup/repos/myclient system /``
|
||||
|
||||
Make sure to use port ``8022`` and ``localhost`` for the repository as this instructs borg on ``myclient`` to use the
|
||||
remote forwarded ssh connection.
|
||||
|
||||
+4
-4
@@ -860,7 +860,7 @@ Please see the next question.
|
||||
Why does Borg disconnect or hang when backing up to a remote server?
|
||||
--------------------------------------------------------------------
|
||||
|
||||
Communication with the remote server (e.g. using a ``rest://user@host/path`` repo URL)
|
||||
Communication with the remote server (e.g. using an ``ssh://user@host/path`` repo URL)
|
||||
is tunneled through an SSH connection. This can lead to some issues that would not
|
||||
occur during a local backup:
|
||||
|
||||
@@ -1142,7 +1142,7 @@ borgstore, which Borg uses for repository access, can limit the transfer rate::
|
||||
|
||||
Pros:
|
||||
|
||||
- works for all backends (``sftp://``, ``rest://``, ``rclone:``, ``s3://``, ...).
|
||||
- works for all backends (``sftp://``, ``ssh://``, ``rclone:``, ``s3://``, ...).
|
||||
- limits both directions.
|
||||
- needs no additional software.
|
||||
|
||||
@@ -1163,7 +1163,7 @@ backend call.
|
||||
Using pv on the ssh connection
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For ``rest://`` repositories, Borg connects via ssh, so the transfer can be
|
||||
For ``ssh://`` repositories, Borg connects via ssh, so the transfer can be
|
||||
limited with pipeviewer_. Put a ``pv`` on each side of the connection using an
|
||||
ssh ``ProxyCommand`` (this needs ``nc``), e.g. in ``~/.ssh/config``::
|
||||
|
||||
@@ -1189,7 +1189,7 @@ Pros:
|
||||
|
||||
Cons:
|
||||
|
||||
- only works for ``rest://`` repositories. ``sftp://`` does not run an external
|
||||
- only works for ``ssh://`` repositories. ``sftp://`` does not run an external
|
||||
ssh command (borgstore uses paramiko and creates the connection itself) and
|
||||
a ``ProxyCommand`` in ``~/.ssh/config`` is not used there.
|
||||
- needs ``pv`` and ``nc``.
|
||||
|
||||
@@ -402,10 +402,10 @@ used:
|
||||
|
||||
Authorization and transport security come from the transport, not from borg.
|
||||
|
||||
Remote repositories over SSH: ``rest://``
|
||||
Remote repositories over SSH: ``ssh://``
|
||||
-----------------------------------------
|
||||
|
||||
For a ``rest://`` repository, borg runs ``borg serve --rest --backend FILE:<path>``
|
||||
For an ``ssh://`` repository, borg runs ``borg serve --rest --backend FILE:<path>``
|
||||
on the remote machine and speaks HTTP to it over that process' *stdin/stdout* -- not
|
||||
over a socket. If the URL contains a host, the process is started through the
|
||||
system's SSH client (honouring ``BORG_RSH`` / ``BORGSTORE_RSH`` for the ssh command
|
||||
@@ -452,7 +452,7 @@ its dependencies, so their security properties are those of the respective libra
|
||||
- ``http(s)://`` talks to a borgstore REST server over plain HTTP, authenticating
|
||||
with HTTP Basic auth taken from the URL or from ``BORGSTORE_REST_USERNAME`` /
|
||||
``BORGSTORE_REST_PASSWORD``. Basic auth sends the credentials to the server on
|
||||
every request, so use ``https`` if you use this at all. ``rest://`` over SSH needs
|
||||
every request, so use ``https`` if you use this at all. ``ssh://`` needs
|
||||
no such credentials.
|
||||
|
||||
In every case the repository never receives the borg key or the passphrase, so a
|
||||
@@ -465,11 +465,10 @@ Legacy borg 1.x RPC protocol
|
||||
|
||||
``borg serve`` *without* ``--rest`` still speaks the borg 1.x RPC protocol:
|
||||
msgpack'd messages exchanged over stdio (``borg.legacy.remote``). It exists only so
|
||||
that borg 2 can *read* a borg 1.x repository through an ``ssh://`` URL, e.g. for
|
||||
``borg transfer --from-borg1``; ``ssh://`` is rejected for current repositories, and
|
||||
this protocol cannot serve one. Its transport is the system's SSH client, so the same
|
||||
"authorization and transport security are SSH's" reasoning as for ``rest://``
|
||||
applies.
|
||||
that borg 2 can *read* a borg 1.x repository through an ``ssh://`` URL with
|
||||
``--from-borg1``, e.g. for ``borg transfer --from-borg1``; it cannot serve a current
|
||||
repository. Its transport is the system's SSH client, so the same
|
||||
"authorization and transport security are SSH's" reasoning as for REST applies.
|
||||
|
||||
Within that protocol, critical vulnerabilities such as remote code execution are
|
||||
inhibited by its design:
|
||||
@@ -526,8 +525,8 @@ while libssl implements TLS and related protocols.
|
||||
The latter historically contained most vulnerabilities, especially critical ones, and Borg's own
|
||||
extension modules do not use it: they link ``libcrypto`` only. Note that libssl can still be
|
||||
reached through Python's ``ssl`` module by the transports that do networking inside the borg
|
||||
process, i.e. ``s3:``/``b2:`` and ``http(s)://`` (see :ref:`remote_access_security`); ``rest://``
|
||||
and the legacy ``ssh://`` protocol do not need it, as they only talk to a subprocess over pipes.
|
||||
process, i.e. ``s3:``/``b2:`` and ``http(s)://`` (see :ref:`remote_access_security`); ``ssh://``
|
||||
(REST and the legacy protocol) does not need it, as it only talks to a subprocess over pipes.
|
||||
Accordingly, the binaries released by the project do include Python's ``ssl``/``_ssl`` modules
|
||||
(they are needed by pyfuse3/trio as well).
|
||||
|
||||
|
||||
@@ -78,7 +78,7 @@ ls ~/Documents
|
||||
# Backups are stored in a "repository". Let's tell borg where ours is,
|
||||
# so we do not have to repeat it in every command:
|
||||
export BORG_REPO=/media/backup/borgdemo
|
||||
# It could also live on another machine, e.g. rest://user@server/backup.
|
||||
# It could also live on another machine, e.g. ssh://user@server/backup.
|
||||
|
||||
# Creating the repository - encrypted and authenticated, with the key stored in the repo itself:
|
||||
borg repo-create --encryption=aes256-ocb --key-location=repokey
|
||||
|
||||
+13
-12
@@ -65,7 +65,7 @@ If you only back up your own files, run it as your normal user (i.e. not root).
|
||||
|
||||
For a local repository always use the same user to invoke borg.
|
||||
|
||||
For a remote repository: always use e.g., rest://borg@remote_host/path/to/repo
|
||||
For a remote repository: always use e.g., ssh://borg@remote_host/path/to/repo
|
||||
(Borg connects via ssh and runs ``borg serve --rest`` on the remote). You can use
|
||||
this from different local users; the remote user running borg and accessing the
|
||||
repo will always be `borg`.
|
||||
@@ -147,7 +147,7 @@ backed up and that the ``prune`` command keeps and deletes the correct backups.
|
||||
# Setting this, so the repo does not need to be given on the commandline.
|
||||
# One slash after the host means: relative to the remote login directory,
|
||||
# so this is ~/backup/main of the remote "username" user:
|
||||
export BORG_REPO=rest://[email protected]:2022/backup/main
|
||||
export BORG_REPO=ssh://[email protected]:2022/backup/main
|
||||
|
||||
# See the section "Passphrase notes" for more infos.
|
||||
export BORG_PASSPHRASE='XYZl0ngandsecurepa_55_phrasea&&123'
|
||||
@@ -394,21 +394,22 @@ Remote repositories
|
||||
|
||||
Borg can initialize and access repositories on remote hosts if the
|
||||
host is accessible using SSH. This is fastest and easiest when Borg
|
||||
is installed on the remote host, in which case a ``rest://`` repository URL is
|
||||
is installed on the remote host, in which case an ``ssh://`` repository URL is
|
||||
used. Borg connects via SSH and runs ``borg serve --rest`` on the remote host,
|
||||
which serves the repository talking HTTP over stdio::
|
||||
|
||||
$ borg -r rest://user@hostname:port/path/to/repo repo-create ...
|
||||
$ borg -r ssh://user@hostname:port/path/to/repo repo-create ...
|
||||
|
||||
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.
|
||||
|
||||
.. note::
|
||||
|
||||
The legacy ``ssh://`` transport, served by ``borg serve`` on the remote host,
|
||||
is now only used to access legacy borg 1.x (v1) repositories (e.g. via
|
||||
``borg transfer --from-borg1 --other-repo ssh://...``). For current
|
||||
repositories, use a ``rest://`` repository as shown above.
|
||||
An ``ssh://`` repository URL is also used to access legacy borg 1.x (v1)
|
||||
repositories on a remote host, e.g. via
|
||||
``borg transfer --from-borg1 --other-repo ssh://...``. Due to ``--from-borg1``,
|
||||
Borg then talks the legacy borg 1.x protocol to ``borg serve`` on the remote
|
||||
host, which may also be a borg 1.x ``borg serve``.
|
||||
|
||||
If it is not possible to install Borg on the remote host,
|
||||
it is still possible to use the remote host to store a repository by
|
||||
@@ -426,7 +427,7 @@ Other kinds of repositories
|
||||
---------------------------
|
||||
|
||||
Due to using the `borgstore` project, borg also supports other kinds of
|
||||
(remote) repositories besides `file:` and `rest:`:
|
||||
(remote) repositories besides `file:` and `ssh:`:
|
||||
|
||||
- sftp: the borg client will directly talk to an sftp server.
|
||||
This does not require borg being installed on the sftp server.
|
||||
@@ -572,7 +573,7 @@ Example with **borg extract**:
|
||||
Difference when using a **remote borg backup server**:
|
||||
|
||||
It is basically all the same as with the local repository, but you need to
|
||||
refer to the repo using a ``rest://`` URL (Borg connects via ssh and runs
|
||||
refer to the repo using an ``ssh://`` URL (Borg connects via ssh and runs
|
||||
``borg serve --rest`` on the remote host).
|
||||
|
||||
In the given example, ``borg`` is the user name used to log into the machine
|
||||
@@ -587,6 +588,6 @@ case if unattended, automated backups were done).
|
||||
|
||||
::
|
||||
|
||||
borg -r rest://[email protected]:2222/path/to/repo mount /mnt/borg
|
||||
borg -r ssh://[email protected]:2222/path/to/repo mount /mnt/borg
|
||||
# or
|
||||
borg -r rest://[email protected]:2222/path/to/repo extract archive
|
||||
borg -r ssh://[email protected]:2222/path/to/repo extract archive
|
||||
|
||||
@@ -8,8 +8,8 @@ Borg now uses the ``borgstore`` package to implement the key/value store it
|
||||
uses for the repository.
|
||||
|
||||
For a local repository (or a locally mounted network filesystem) it uses the
|
||||
``file:`` store (posixfs backend). For a remote repository it uses the ``rest:``
|
||||
store, talking to a ``borg serve --rest`` process on the remote side (which in
|
||||
``file:`` store (posixfs backend). For a remote ``ssh://`` repository it uses the
|
||||
REST store, talking to a ``borg serve --rest`` process on the remote side (which in
|
||||
turn uses borgstore there). Other backends (``sftp:``, ``rclone:``, ``s3:``/
|
||||
``b2:``) do not need a filesystem on the repository side at all.
|
||||
|
||||
|
||||
@@ -18,22 +18,16 @@ Note: UNC paths (``//server/share/path``, ``\\server\share\path``) are not
|
||||
supported — mount the share (on Windows: map it to a drive letter, e.g.
|
||||
``net use X: \\server\share``) and use the mounted path instead.
|
||||
|
||||
**Remote repositories** accessed via SSH user@host (REST http over stdio):
|
||||
|
||||
``rest://user@host:port//abs/path/to/repo`` — absolute path
|
||||
|
||||
``rest://user@host:port/rel/path/to/repo`` — path relative to the remote login directory
|
||||
|
||||
**Remote repositories** accessed via SSH user@host (legacy borg RPC protocol):
|
||||
**Remote repositories** accessed via SSH user@host (borg serve on the remote host):
|
||||
|
||||
``ssh://user@host:port//abs/path/to/repo`` — absolute path
|
||||
|
||||
``ssh://user@host:port/rel/path/to/repo`` — path relative to the remote login directory
|
||||
|
||||
For current (non-legacy) repositories, ``ssh://`` is rejected; use ``rest://``
|
||||
instead, which can also tunnel over ssh (see above). ``ssh://`` remains available
|
||||
only for legacy borg 1.x repositories, e.g. via
|
||||
``borg transfer --from-borg1 --other-repo ssh://...``.
|
||||
Borg talks HTTP (REST) over the ssh connection's stdio to ``borg serve --rest`` on the
|
||||
remote host. Legacy borg 1.x repositories are also accessed via ``ssh://`` URLs,
|
||||
together with ``--from-borg1`` (e.g. ``borg transfer --from-borg1 --other-repo ssh://...``):
|
||||
Borg then talks the legacy borg 1.x protocol to ``borg serve`` on the remote host.
|
||||
|
||||
**Remote repositories** accessed via SFTP:
|
||||
|
||||
@@ -41,8 +35,8 @@ only for legacy borg 1.x repositories, e.g. via
|
||||
|
||||
``sftp://user@host:port/rel/path/to/repo`` — path relative to the remote login directory
|
||||
|
||||
For REST, SSH and SFTP URLs, the ``user@`` and ``:port`` parts are optional, but the
|
||||
path is required: a URL without one, e.g. ``rest://host`` or ``rest://host/``, is
|
||||
For SSH and SFTP URLs, the ``user@`` and ``:port`` parts are optional, but the
|
||||
path is required: a URL without one, e.g. ``ssh://host`` or ``ssh://host/``, is
|
||||
rejected. Mind the difference between one and two slashes after the host: one slash
|
||||
means a path relative to the directory the remote login lands in (usually the remote
|
||||
user's home directory), two slashes mean an absolute path.
|
||||
@@ -59,7 +53,7 @@ Authentication is HTTP Basic auth: credentials come from the URL if given, other
|
||||
from the ``BORGSTORE_REST_USERNAME`` / ``BORGSTORE_REST_PASSWORD`` environment
|
||||
variables; prefer ``https://`` over ``http://`` whenever credentials are used, since
|
||||
Basic auth sends them on every request. A URL path after the host is optional and,
|
||||
unlike ``rest://``, is not a remote filesystem path — it does not follow the
|
||||
unlike ``ssh://``, is not a remote filesystem path — it does not follow the
|
||||
one-vs-two-slash rule above and is only needed to reach the server through a reverse
|
||||
proxy mounted below a sub-path.
|
||||
|
||||
@@ -82,7 +76,7 @@ If you frequently need the same repository URL, it is a good idea to set the
|
||||
|
||||
::
|
||||
|
||||
export BORG_REPO='rest://user@host:port/rel/path/to/repo'
|
||||
export BORG_REPO='ssh://user@host:port/rel/path/to/repo'
|
||||
|
||||
Then simply omit the ``--repo`` option when you want
|
||||
to use the default — it will be read from BORG_REPO.
|
||||
|
||||
@@ -19,9 +19,8 @@ options. This list currently contains:
|
||||
``--restrict-to-path`` / ``--restrict-to-repository``.
|
||||
|
||||
Notably, ``--rest`` is *not* in the allowlist, so the forced command pins the
|
||||
mode (current ``rest://`` repositories vs. legacy Borg 1.x repositories), and
|
||||
neither are ``--restrict-to-path``, ``--restrict-to-repository``, ``--umask``
|
||||
and ``--permissions``.
|
||||
mode (current repositories vs. legacy Borg 1.x repositories), and neither are
|
||||
``--restrict-to-path``, ``--restrict-to-repository``, ``--umask`` and ``--permissions``.
|
||||
|
||||
Environment variables (such as BORG_XXX) contained in the original
|
||||
command sent by the client are *not* interpreted, but ignored. If BORG_XXX environment
|
||||
@@ -33,7 +32,7 @@ locations like ``/etc/environment`` or in the forced command itself (example bel
|
||||
# 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.
|
||||
# --rest serves a current (rest://) repository; without it, a legacy Borg 1.x
|
||||
# --rest serves a current (ssh://) repository; without it, a legacy Borg 1.x
|
||||
# repository would be served. The client supplies --backend FILE:<path>,
|
||||
# which is validated against --restrict-to-path.
|
||||
$ cat ~/.ssh/authorized_keys
|
||||
|
||||
@@ -8,9 +8,9 @@ locations and passphrases first:
|
||||
|
||||
::
|
||||
|
||||
# The destination is a Borg 2 repository: use a rest:// (or local) location,
|
||||
# ssh:// is only supported for the legacy Borg 1.x source repository.
|
||||
export BORG_REPO=rest://borg2@borgbackup/tests/b20
|
||||
# The destination is a Borg 2 repository, the source is a legacy Borg 1.x repository
|
||||
# (accessed via the legacy protocol due to --from-borg1).
|
||||
export BORG_REPO=ssh://borg2@borgbackup/tests/b20
|
||||
export BORG_PASSPHRASE='your-borg2-repo-passphrase'
|
||||
export BORG_OTHER_REPO=ssh://borg2@borgbackup/./tests/b1x
|
||||
export BORG_OTHER_PASSPHRASE='your-borg1-repo-passphrase'
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
#!/usr/bin/env bash
|
||||
#
|
||||
# rest_perf_test.sh - borg2 performance harness for rest:// repositories.
|
||||
# rest_perf_test.sh - borg2 performance harness for ssh:// repositories.
|
||||
#
|
||||
# Runs a fixed workload (repo-create -> backup -> backup again -> dry-run extract
|
||||
# -> check) against a rest:// repo served over a localhost sshd, under several
|
||||
# -> check) against an ssh:// repo served over a localhost sshd, under several
|
||||
# network conditions emulated by borgstore (BORGSTORE_LATENCY / BORGSTORE_BANDWIDTH).
|
||||
# LAN and WAN use the SAME bandwidth (1 Gbit/s) and differ only in latency (0.3ms vs
|
||||
# 30ms), to isolate latency's effect; raw is a no-emulation baseline. Prints a table.
|
||||
@@ -35,8 +35,8 @@ set -euo pipefail
|
||||
# Default ~7.4GB: 20000x20KiB + 1000x5MiB + 2x1GiB. Override GROUPS_SPEC for smoke tests.
|
||||
: "${GROUPS_SPEC:=tiny:20000:20480 med:1000:5242880 big:2:1073741824}"
|
||||
|
||||
# rest://user@host//abs/path (the double slash is intentional: //tmp/REPO is absolute)
|
||||
REPO_URL="rest://${REPO_TARGET}/${REPO_PATH}"
|
||||
# ssh://user@host//abs/path (the double slash is intentional: //tmp/REPO is absolute)
|
||||
REPO_URL="ssh://${REPO_TARGET}/${REPO_PATH}"
|
||||
|
||||
# Per-profile emulation values: LATENCY in microseconds, BANDWIDTH in bits/s (0 = off).
|
||||
# lan and wan share the SAME bandwidth (1 Gbit/s); only latency differs, to isolate how
|
||||
@@ -52,7 +52,7 @@ profile_params() {
|
||||
|
||||
# Suppress borg's interactive prompts (unencrypted repo access, repo deletion) and
|
||||
# point borg at the venv borg on the *remote* side (a bare 'borg' would not resolve
|
||||
# in a non-interactive ssh session's minimal PATH). rest:// is served by 'borg serve
|
||||
# in a non-interactive ssh session's minimal PATH). ssh:// is served by 'borg serve
|
||||
# --rest', so BORG_REMOTE_PATH is the command the server runs.
|
||||
export BORG_REMOTE_PATH="$VENV/bin/borg"
|
||||
export BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=yes
|
||||
|
||||
Reference in New Issue
Block a user