mirror of
https://github.com/borgbackup/borg.git
synced 2026-09-01 14:13:19 +02:00
f4a24bb05eAdd the missing http(s):// section (borgstore REST server, HTTP Basic auth via URL or BORGSTORE_REST_USERNAME/PASSWORD, URL path only for reverse-proxy prefixes - unlike rest:// it is not a filesystem path). Qualify file:// as absolute-paths-only and state explicitly that ssh:// works only for legacy borg 1.x repositories. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
88 lines
3.9 KiB
PHP
88 lines
3.9 KiB
PHP
Repository URLs
|
|
~~~~~~~~~~~~~~~
|
|
|
|
**Local filesystem** (or locally mounted network filesystem):
|
|
|
|
``/path/to/repo`` — filesystem path to the repository directory (absolute path)
|
|
|
|
``path/to/repo`` — filesystem path to the repository directory (relative path)
|
|
|
|
Also, paths like ``~/path/to/repo`` or ``~other/path/to/repo`` work (this is
|
|
expanded by your shell).
|
|
|
|
Note: You may also prepend ``file://`` to an absolute filesystem path to use URL
|
|
style, e.g. ``file:///abs/path/to/repo``. This only works for absolute paths —
|
|
``file://rel/path`` is rejected; use a plain relative path (see above) instead.
|
|
|
|
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):
|
|
|
|
``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://...``.
|
|
|
|
**Remote repositories** accessed via SFTP:
|
|
|
|
``sftp://user@host:port//abs/path/to/repo`` — absolute path
|
|
|
|
``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
|
|
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.
|
|
|
|
**Remote repositories** accessed directly via HTTP(S), talking to a borgstore REST
|
|
server:
|
|
|
|
``http://host:port`` — plain HTTP
|
|
|
|
``https://user:password@host:port`` — HTTPS, optionally with credentials embedded in the URL
|
|
|
|
For ``http://`` and ``https://`` URLs, ``user:password@`` and ``:port`` are optional.
|
|
Authentication is HTTP Basic auth: credentials come from the URL if given, otherwise
|
|
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
|
|
one-vs-two-slash rule above and is only needed to reach the server through a reverse
|
|
proxy mounted below a sub-path.
|
|
|
|
**Remote repositories** accessed via rclone:
|
|
|
|
``rclone:remote:path`` — see the rclone docs for more details about ``remote:path``.
|
|
|
|
**Remote repositories** accessed via S3:
|
|
|
|
``(s3|b2):[(profile|(access_key_id:access_key_secret))@][scheme://hostname[:port]]/bucket/path`` — see the boto3 docs for more details about credentials.
|
|
|
|
If you are connecting to AWS S3, ``[schema://hostname[:port]]`` is optional, but ``bucket`` and ``path`` are always required.
|
|
`scheme` is usually `https` here, hostname and optional port refer to your S3/B2 server, if that is not Amazon's.
|
|
|
|
Note: There is a known issue with some S3-compatible services, e.g., Backblaze B2. If you encounter problems, try using ``b2:`` instead of ``s3:`` in the URL.
|
|
|
|
|
|
If you frequently need the same repository URL, it is a good idea to set the
|
|
``BORG_REPO`` environment variable to set a default repository URL:
|
|
|
|
::
|
|
|
|
export BORG_REPO='rest://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.
|