mirror of
https://github.com/borgbackup/borg.git
synced 2026-04-28 09:40:07 -04:00
docs: fix typos and grammar
This commit is contained in:
Thomas Waldmann
parent
404bb1ca20
commit
6602cf1679
31 changed files with 166 additions and 165 deletions
|
|
@ -5,7 +5,7 @@
|
|||
Borg documentation
|
||||
==================
|
||||
|
||||
.. when you add an element here, do not forget to add it to index.rst
|
||||
.. When you add an element here, do not forget to add it to index.rst.
|
||||
.. Note: Some things are in appendices (see latex_appendices in conf.py)
|
||||
|
||||
.. toctree::
|
||||
|
|
|
|||
|
|
@ -87,11 +87,11 @@ no matter what encryption mode they use, including "none"):
|
|||
|
||||
5. Done. Manifest and archives are TAM authenticated now.
|
||||
|
||||
Vulnerability time line:
|
||||
Vulnerability timeline:
|
||||
|
||||
* 2023-06-13: Vulnerability discovered during code review by Thomas Waldmann
|
||||
* 2023-06-13...: Work on fixing the issue, upgrade procedure, docs.
|
||||
* 2023-06-30: CVE was assigned via Github CNA
|
||||
* 2023-06-30: CVE was assigned via GitHub CNA
|
||||
* 2023-06-30 .. 2023-08-29: Fixed issue, code review, docs, testing.
|
||||
* 2023-08-30: Released fixed version 1.2.5 (broken upgrade procedure for some repos)
|
||||
* 2023-08-31: Released fixed version 1.2.6 (fixes upgrade procedure)
|
||||
|
|
@ -230,7 +230,7 @@ This attack is mitigated by:
|
|||
|
||||
We are not aware of others having discovered, disclosed or exploited this vulnerability.
|
||||
|
||||
Vulnerability time line:
|
||||
Vulnerability timeline:
|
||||
|
||||
* 2016-11-14: Vulnerability and fix discovered during review of cryptography by Marian Beermann (@enkore)
|
||||
* 2016-11-20: First patch
|
||||
|
|
|
|||
|
|
@ -14,8 +14,8 @@ systemd and udev.
|
|||
Overview
|
||||
--------
|
||||
|
||||
An udev rule is created to trigger on the addition of block devices. The rule contains a tag
|
||||
that triggers systemd to start a oneshot service. The oneshot service executes a script in
|
||||
A udev rule is created to trigger on the addition of block devices. The rule contains a tag
|
||||
that causes systemd to start a oneshot service. The oneshot service executes a script in
|
||||
the standard systemd service environment, which automatically captures stdout/stderr and
|
||||
logs it to the journal.
|
||||
|
||||
|
|
@ -36,9 +36,9 @@ Then, create ``/etc/backups/80-backup.rules`` with the following content (all on
|
|||
|
||||
ACTION=="add", SUBSYSTEM=="block", ENV{ID_PART_TABLE_UUID}=="<the PTUUID you just noted>", TAG+="systemd", ENV{SYSTEMD_WANTS}+="automatic-backup.service"
|
||||
|
||||
The "systemd" tag in conjunction with the SYSTEMD_WANTS environment variable has systemd
|
||||
launch the "automatic-backup" service, which we will create next, as the
|
||||
``/etc/backups/automatic-backup.service`` file:
|
||||
The "systemd" tag in conjunction with the SYSTEMD_WANTS environment variable causes systemd to
|
||||
launch the "automatic-backup" service, which we will create next, as the file
|
||||
``/etc/backups/automatic-backup.service``:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
|
|
@ -65,13 +65,13 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.).
|
|||
# Script configuration
|
||||
#
|
||||
|
||||
# The backup partition is mounted there
|
||||
# The backup partition is mounted here
|
||||
MOUNTPOINT=/mnt/backup
|
||||
|
||||
# This is the location of the Borg repository
|
||||
TARGET=$MOUNTPOINT/borg-backups/backup.borg
|
||||
|
||||
# Archive name schema
|
||||
# Archive name scheme
|
||||
DATE=$(date --iso-8601)-$(hostname)
|
||||
|
||||
# This is the file that will later contain UUIDs of registered backup drives
|
||||
|
|
@ -93,7 +93,7 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.).
|
|||
|
||||
echo "Disk $uuid is a backup disk"
|
||||
partition_path=/dev/disk/by-uuid/$uuid
|
||||
# Mount file system if not already done. This assumes that if something is already
|
||||
# Mount the file system if not already done. This assumes that if something is already
|
||||
# mounted at $MOUNTPOINT, it is the backup drive. It won't find the drive if
|
||||
# it was mounted somewhere else.
|
||||
findmnt $MOUNTPOINT >/dev/null || mount $partition_path $MOUNTPOINT
|
||||
|
|
@ -104,7 +104,7 @@ modify it to suit your needs (e.g. more backup sets, dumping databases etc.).
|
|||
# Create backups
|
||||
#
|
||||
|
||||
# Options for borg create
|
||||
# Options for Borg create
|
||||
BORG_OPTS="--stats --one-file-system --compression lz4 --checkpoint-interval 86400"
|
||||
|
||||
# Set BORG_PASSPHRASE or BORG_PASSCOMMAND somewhere around here, using export,
|
||||
|
|
|
|||
|
|
@ -4,20 +4,20 @@
|
|||
Central repository server with Ansible or Salt
|
||||
==============================================
|
||||
|
||||
This section will give an example how to setup a borg repository server for multiple
|
||||
This section gives an example of how to set up a Borg repository server for multiple
|
||||
clients.
|
||||
|
||||
Machines
|
||||
--------
|
||||
|
||||
There are multiple machines used in this section and will further be named by their
|
||||
respective fully qualified domain name (fqdn).
|
||||
respective fully qualified domain name (FQDN).
|
||||
|
||||
* The backup server: `backup01.srv.local`
|
||||
* The clients:
|
||||
|
||||
- John Doe's desktop: `johndoe.clnt.local`
|
||||
- Webserver 01: `web01.srv.local`
|
||||
- Web server 01: `web01.srv.local`
|
||||
- Application server 01: `app01.srv.local`
|
||||
|
||||
User and group
|
||||
|
|
@ -28,7 +28,7 @@ Recommended user and group with additional settings:
|
|||
|
||||
* User: `backup`
|
||||
* Group: `backup`
|
||||
* Shell: `/bin/bash` (or other capable to run the `borg serve` command)
|
||||
* Shell: `/bin/bash` (or another capable of running the `borg serve` command)
|
||||
* Home: `/home/backup`
|
||||
|
||||
Most clients shall initiate a backup from the root user to catch all
|
||||
|
|
@ -79,11 +79,11 @@ The options which are added to the key will perform the following:
|
|||
3. Restrict ssh and do not allow stuff which imposes a security risk
|
||||
|
||||
Due to the ``cd`` command we use, the server automatically changes the current
|
||||
working directory. Then client doesn't need to have knowledge of the absolute
|
||||
working directory. The client doesn't need to have knowledge of the absolute
|
||||
or relative remote repository path and can directly access the repositories at
|
||||
``ssh://<user>@<host>/./<repo>``.
|
||||
|
||||
.. note:: The setup above ignores all client given commandline parameters
|
||||
.. note:: The setup above ignores all client-given command-line parameters
|
||||
which are normally appended to the `borg serve` command.
|
||||
|
||||
Client
|
||||
|
|
@ -95,14 +95,14 @@ The client needs to initialize the `pictures` repository like this:
|
|||
|
||||
borg init ssh://backup@backup01.srv.local/./pictures
|
||||
|
||||
Or with the full path (should actually never be used, as only for demonstrational purposes).
|
||||
The server should automatically change the current working directory to the `<client fqdn>` folder.
|
||||
Or with the full path (should actually never be used, as only for demonstration purposes).
|
||||
The server should automatically change the current working directory to the `<client FQDN>` folder.
|
||||
|
||||
::
|
||||
|
||||
borg init ssh://backup@backup01.srv.local/home/backup/repos/johndoe.clnt.local/pictures
|
||||
|
||||
When `johndoe.clnt.local` tries to access a not restricted path the following error is raised.
|
||||
When `johndoe.clnt.local` tries to access an unrestricted path, the following error is raised.
|
||||
John Doe tries to backup into the Web 01 path:
|
||||
|
||||
::
|
||||
|
|
|
|||
|
|
@ -5,11 +5,11 @@
|
|||
Hosting repositories
|
||||
====================
|
||||
|
||||
This sections shows how to securely provide repository storage for users.
|
||||
This section shows how to securely provide repository storage for users.
|
||||
Optionally, each user can have a storage quota.
|
||||
|
||||
Repositories are accessed through SSH. Each user of the service should
|
||||
have her own login which is only able to access the user's files.
|
||||
have their own login which is only able to access the user's files.
|
||||
Technically it would be possible to have multiple users share one login,
|
||||
however, separating them is better. Separate logins increase isolation
|
||||
and are thus an additional layer of security and safety for both the
|
||||
|
|
|
|||
|
|
@ -8,9 +8,9 @@ Backing up disk images can still be efficient with Borg because its `deduplicati
|
|||
technique makes sure only the modified parts of the file are stored. Borg also has
|
||||
optional simple sparse file support for extract.
|
||||
|
||||
It is of utmost importancy to pin down the disk you want to backup.
|
||||
You need to use the SERIAL for that.
|
||||
Use:
|
||||
It is of utmost importance to pin down the disk you want to back up.
|
||||
You need to use the SERIAL for that.
|
||||
Use:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
|
@ -65,7 +65,7 @@ deduplicating. For backup, save the disk header and the contents of each partiti
|
|||
PARTNUM=$(echo $x | grep -Eo "[0-9]+$")
|
||||
ntfsclone -so - $x | borg create repo::hostname-part$PARTNUM -
|
||||
done
|
||||
# to backup non-NTFS partitions as well:
|
||||
# to back up non-NTFS partitions as well:
|
||||
echo "$PARTITIONS" | grep -v NTFS | cut -d' ' -f1 | while read x; do
|
||||
PARTNUM=$(echo $x | grep -Eo "[0-9]+$")
|
||||
borg create --read-special repo::hostname-part$PARTNUM $x
|
||||
|
|
|
|||
|
|
@ -6,29 +6,29 @@
|
|||
Backing up using a non-root user
|
||||
================================
|
||||
|
||||
This section describes how to run borg as a non-root user and still be able to
|
||||
backup every file on the system.
|
||||
This section describes how to run Borg as a non-root user and still be able to
|
||||
back up every file on the system.
|
||||
|
||||
Normally borg is run as the root user to bypass all filesystem permissions and
|
||||
be able to read all files. But in theory this also allows borg to modify or
|
||||
delete files on your system, in case of a bug for example.
|
||||
Normally Borg is run as the root user to bypass all filesystem permissions and
|
||||
be able to read all files. But in theory this also allows Borg to modify or
|
||||
delete files on your system, in case of a bug, for example.
|
||||
|
||||
To eliminate this possibility, we can run borg as a non-root user and give it read-only
|
||||
To eliminate this possibility, we can run Borg as a non-root user and give it read-only
|
||||
permissions to all files on the system.
|
||||
|
||||
|
||||
Using Linux capabilities inside a systemd service
|
||||
=================================================
|
||||
|
||||
One way to do so, is to use linux `capabilities
|
||||
One way to do so is to use Linux `capabilities
|
||||
<https://man7.org/linux/man-pages/man7/capabilities.7.html>`_ within a systemd
|
||||
service.
|
||||
|
||||
Linux capabilities allow us to give parts of the privileges the root user has to
|
||||
a non-root user. This works on a per-thread level and does not give the permission
|
||||
Linux capabilities allow us to give some of the privileges that the root user has to
|
||||
a non-root user. This works on a per-thread level and does not grant these permissions
|
||||
to the non-root user as a whole.
|
||||
|
||||
For this we need to run our backup script from a systemd service and use the `AmbientCapabilities
|
||||
For this, we need to run our backup script from a systemd service and use the `AmbientCapabilities
|
||||
<https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#AmbientCapabilities=>`_
|
||||
option added in systemd 229.
|
||||
|
||||
|
|
@ -46,7 +46,7 @@ A very basic unit file would look like this:
|
|||
|
||||
AmbientCapabilities=CAP_DAC_READ_SEARCH
|
||||
|
||||
The ``CAP_DAC_READ_SEARCH`` capability gives borg read-only access to all files and directories on the system.
|
||||
The ``CAP_DAC_READ_SEARCH`` capability gives Borg read-only access to all files and directories on the system.
|
||||
|
||||
This service can then be started manually using ``systemctl start``, a systemd timer or other methods.
|
||||
|
||||
|
|
@ -57,7 +57,7 @@ When restoring files, the root user should be used. When using the non-root user
|
|||
change all files to be owned by the non-root user. Using borg mount will not allow the non-root user
|
||||
to access files that it would not have access to on the system itself.
|
||||
|
||||
Other than that, the same restore process, that would be used when running the backup as root, can be used.
|
||||
Other than that, the same restore process that would be used when running the backup as root can be used.
|
||||
|
||||
.. warning::
|
||||
|
||||
|
|
|
|||
|
|
@ -6,20 +6,20 @@
|
|||
Backing up in pull mode
|
||||
=======================
|
||||
|
||||
Typically the borg client connects to a backup server using SSH as a transport
|
||||
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
|
||||
If, however, you 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
|
||||
A common use case for pull mode is to back up a remote server to a local personal
|
||||
computer.
|
||||
|
||||
SSHFS
|
||||
=====
|
||||
|
||||
Assuming you have a pull backup system set up with borg, where a backup server
|
||||
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
|
||||
the SSH connection must be established by the client via a remote tunnel. Other
|
||||
|
|
@ -54,7 +54,7 @@ completely in every aspect from such a backup.
|
|||
|
||||
.. warning::
|
||||
|
||||
The chroot method was chosen to get the right user and group name-id
|
||||
The chroot method was chosen to get the right user and group name-ID
|
||||
mappings, assuming they only come from files (/etc/passwd and group).
|
||||
This assumption might be wrong, e.g. if users/groups also come from
|
||||
ldap or other providers.
|
||||
|
|
@ -64,7 +64,7 @@ completely in every aspect from such a backup.
|
|||
Creating a backup
|
||||
-----------------
|
||||
|
||||
Generally, in a pull backup situation there is no direct way for borg to know
|
||||
Generally, in a pull backup situation there is no direct way for Borg to know
|
||||
the client's original UID:GID name mapping of files, because Borg would use
|
||||
``/etc/passwd`` and ``/etc/group`` of the backup server to map the names. To
|
||||
derive the right names, Borg needs to have access to the client's passwd and
|
||||
|
|
@ -72,7 +72,7 @@ group files and use them in the backup process.
|
|||
|
||||
The solution to this problem is chrooting into an sshfs mounted directory. In
|
||||
this example the whole client root file system is mounted. We use the
|
||||
stand-alone BorgBackup executable and copy it into the mounted file system to
|
||||
standalone BorgBackup executable and copy it into the mounted file system to
|
||||
make Borg available after entering chroot; this can be skipped if Borg is
|
||||
already installed on the client.
|
||||
|
||||
|
|
|
|||
|
|
@ -52,7 +52,7 @@ Borg development happens on the ``master`` branch and uses GitHub pull
|
|||
requests (if you don't have GitHub or don't want to use it you can
|
||||
send smaller patches via the borgbackup mailing list to the maintainers).
|
||||
|
||||
Stable releases are maintained on maintenance branches named ``x.y-maint``, eg.
|
||||
Stable releases are maintained on maintenance branches named ``x.y-maint``, e.g.
|
||||
the maintenance branch of the 1.4.x series is ``1.4-maint``.
|
||||
|
||||
Most PRs should be filed against the ``master`` branch. Only if an
|
||||
|
|
@ -372,6 +372,7 @@ Checklist:
|
|||
::
|
||||
|
||||
scripts/sign-binaries 201912312359
|
||||
|
||||
- Close the release milestone on GitHub.
|
||||
- `Update borgbackup.org
|
||||
<https://github.com/borgbackup/borgbackup.github.io/pull/53/files>`_ with the
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ Borg Documentation
|
|||
|
||||
.. include:: ../README.rst
|
||||
|
||||
.. when you add an element here, do not forget to add it to book.rst
|
||||
.. When you add an element here, do not forget to add it to book.rst.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
|
|
|||
|
|
@ -105,7 +105,7 @@ Standalone Binary
|
|||
.. note:: Releases are signed with an OpenPGP key, see
|
||||
:ref:`security-contact` for more instructions.
|
||||
|
||||
Borg x86-64 amd/intel compatible binaries (generated with `pyinstaller`_)
|
||||
Borg x86-64 AMD/Intel-compatible binaries (generated with `pyinstaller`_)
|
||||
are available on the releases_ page for the following platforms (for more
|
||||
details see the ``00_README.txt`` file there):
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
Internals
|
||||
=========
|
||||
|
||||
The internals chapter describes and analyses most of the inner workings
|
||||
The internals chapter describes and analyzes most of the inner workings
|
||||
of Borg.
|
||||
|
||||
Borg uses a low-level, key-value store, the :ref:`repository`, and
|
||||
|
|
@ -19,12 +19,12 @@ specified when the backup was performed.
|
|||
Deduplication is performed globally across all data in the repository
|
||||
(multiple backups and even multiple hosts), both on data and file
|
||||
metadata, using :ref:`chunks` created by the chunker using the
|
||||
Buzhash_ algorithm ("buzhash" chunker) or a simpler fixed blocksize
|
||||
Buzhash_ algorithm ("buzhash" chunker) or a simpler fixed block size
|
||||
algorithm ("fixed" chunker).
|
||||
|
||||
To actually perform the repository-wide deduplication, a hash of each
|
||||
chunk is checked against the :ref:`chunks cache <cache>`, which is a
|
||||
hash-table of all chunks that already exist.
|
||||
hash table of all chunks that already exist.
|
||||
|
||||
.. figure:: internals/structure.png
|
||||
:figwidth: 100%
|
||||
|
|
|
|||
|
|
@ -21,29 +21,29 @@ Repository
|
|||
|
||||
.. Some parts of this description were taken from the Repository docstring
|
||||
|
||||
Borg stores its data in a `Repository`, which is a file system based
|
||||
Borg stores its data in a `Repository`, which is a filesystem-based
|
||||
transactional key-value store. Thus the repository does not know about
|
||||
the concept of archives or items.
|
||||
|
||||
Each repository has the following file structure:
|
||||
|
||||
README
|
||||
simple text file telling that this is a Borg repository
|
||||
Simple text file telling that this is a Borg repository
|
||||
|
||||
config
|
||||
repository configuration
|
||||
Repository configuration
|
||||
|
||||
data/
|
||||
directory where the actual data is stored
|
||||
Directory where the actual data is stored
|
||||
|
||||
hints.%d
|
||||
hints for repository compaction
|
||||
Hints for repository compaction
|
||||
|
||||
index.%d
|
||||
repository index
|
||||
Repository index
|
||||
|
||||
lock.roster and lock.exclusive/*
|
||||
used by the locking system to manage shared and exclusive locks
|
||||
Used by the locking system to manage shared and exclusive locks
|
||||
|
||||
Transactionality is achieved by using a log (aka journal) to record changes. The log is a series of numbered files
|
||||
called segments_. Each segment is a series of log entries. The segment number together with the offset of each
|
||||
|
|
|
|||
|
|
@ -10,18 +10,18 @@ Borg does not have a public API on the Python level. That does not keep you from
|
|||
but does mean that there are no release-to-release guarantees on what you might find in that package, not
|
||||
even for point releases (1.1.x), and there is no documentation beyond the code and the internals documents.
|
||||
|
||||
Borg does on the other hand provide an API on a command-line level. In other words, a frontend should
|
||||
(for example) create a backup archive just invoke :ref:`borg_create`, give commandline parameters/options
|
||||
as needed and parse JSON output from borg.
|
||||
Borg does, on the other hand, provide an API on a command-line level. In other words, a frontend should
|
||||
(for example) create a backup archive by invoking :ref:`borg_create`, pass command-line parameters/options
|
||||
as needed, and parse JSON output from Borg.
|
||||
|
||||
Important: JSON output is expected to be UTF-8, but currently borg depends on the locale being configured
|
||||
for that (must be a UTF-8 locale and *not* "C" or "ascii"), so that Python will choose to encode to UTF-8.
|
||||
The same applies to any inputs read by borg, they are expected to be UTF-8 encoded also.
|
||||
Important: JSON output is expected to be UTF-8, but currently Borg depends on the locale being configured
|
||||
for that (must be a UTF-8 locale and not "C" or "ASCII"), so that Python will choose to encode to UTF-8.
|
||||
The same applies to any inputs read by Borg; they are expected to be UTF-8 encoded also.
|
||||
|
||||
We consider this a bug (see :issue:`2273`) and might fix it later, so borg will use UTF-8 independent of
|
||||
the locale.
|
||||
|
||||
On POSIX systems, you can usually set environment vars to choose a UTF-8 locale:
|
||||
On POSIX systems, you can usually set environment variables to choose a UTF-8 locale:
|
||||
|
||||
::
|
||||
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ Under these circumstances Borg guarantees that the attacker cannot
|
|||
|
||||
1. modify the data of any archive without the client detecting the change
|
||||
2. rename, remove or add an archive without the client detecting the change
|
||||
3. recover plain-text data
|
||||
3. recover plaintext data
|
||||
4. recover definite (heuristics based on access patterns are possible)
|
||||
structural information such as the object graph (which archives
|
||||
refer to what chunks)
|
||||
|
|
@ -144,10 +144,10 @@ Depending on the chosen mode (see :ref:`borg_init`) different primitives are use
|
|||
- The authentication primitive is either HMAC-SHA-256 or BLAKE2b-256
|
||||
in a keyed mode.
|
||||
|
||||
Both HMAC-SHA-256 and BLAKE2b have undergone extensive cryptanalysis
|
||||
Both HMAC-SHA-256 and BLAKE2b have undergone extensive cryptanalysis
|
||||
and have proven secure against known attacks. The known vulnerability
|
||||
of SHA-256 against length extension attacks does not apply to HMAC-SHA-256.
|
||||
|
||||
|
||||
The authentication primitive should be chosen based upon SHA hardware support:
|
||||
all AMD Ryzen, Intel 10th+ generation mobile and Intel 11th+ generation
|
||||
desktop processors, Apple M1+ and most current ARM64 architectures support
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
Introduction
|
||||
============
|
||||
|
||||
.. this shim is here to fix the structure in the PDF
|
||||
rendering. without this stub, the elements in the toctree of
|
||||
index.rst show up a level below the README file included
|
||||
.. This shim is here to fix the structure in the PDF
|
||||
rendering. Without this stub, the elements in the toctree of
|
||||
index.rst show up a level below the README file included there.
|
||||
|
||||
.. include:: ../README.rst
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ NOTES
|
|||
SEE ALSO
|
||||
--------
|
||||
|
||||
`borg-common(1)` for common command line options
|
||||
`borg-common(1)` for common command-line options
|
||||
|
||||
`borg-init(1)`,
|
||||
`borg-create(1)`, `borg-mount(1)`, `borg-extract(1)`,
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ Quick Start
|
|||
This chapter will get you started with Borg and covers
|
||||
various use cases.
|
||||
|
||||
A step by step example
|
||||
A step-by-step example
|
||||
----------------------
|
||||
|
||||
.. include:: quickstart_example.rst.inc
|
||||
|
|
@ -20,8 +20,8 @@ A *Borg archive* is the result of a single backup (``borg create``). An archive
|
|||
stores a snapshot of the data of the files "inside" it. One can later extract or
|
||||
mount an archive to restore from a backup.
|
||||
|
||||
*Repositories* are filesystem directories acting as self-contained stores of archives.
|
||||
Repositories can be accessed locally via path or remotely via ssh. Under the hood,
|
||||
*Repositories* are file system directories acting as self-contained stores of archives.
|
||||
Repositories can be accessed locally via path or remotely via SSH. Under the hood,
|
||||
repositories contain data blocks and a manifest tracking which blocks are in each
|
||||
archive. If some data hasn't changed from one backup to another, Borg can simply
|
||||
reference an already uploaded data chunk (deduplication).
|
||||
|
|
@ -37,7 +37,7 @@ a good amount of free space on the filesystem that has your backup repository
|
|||
repositories. See also :ref:`cache-memory-usage`.
|
||||
|
||||
Borg doesn't use space reserved for root on repository disks (even when run as root),
|
||||
on file systems which do not support this mechanism (e.g. XFS) we recommend to reserve
|
||||
on file systems which do not support this mechanism (e.g., XFS) we recommend reserving
|
||||
some space in Borg itself just to be safe by adjusting the ``additional_free_space``
|
||||
setting (a good starting point is ``2G``)::
|
||||
|
||||
|
|
@ -49,7 +49,7 @@ by deleting/pruning archives. This mechanism is not bullet-proof in some
|
|||
circumstances [1]_.
|
||||
|
||||
If you *really* run out of disk space, it can be hard or impossible to free space,
|
||||
because Borg needs free space to operate - even to delete backup
|
||||
because Borg needs free space to operate—even to delete backup
|
||||
archives.
|
||||
|
||||
You can use some monitoring process or just include the free space information
|
||||
|
|
@ -58,38 +58,38 @@ in your backup log files (you check them regularly anyway, right?).
|
|||
Also helpful:
|
||||
|
||||
- create a big file as a "space reserve", that you can delete to free space
|
||||
- if you use LVM: use a LV + a filesystem that you can resize later and have
|
||||
- if you use LVM: use an LV + a file system that you can resize later and have
|
||||
some unallocated PEs you can add to the LV.
|
||||
- consider using quotas
|
||||
- use `prune` and `compact` regularly
|
||||
|
||||
.. [1] This failsafe can fail in these circumstances:
|
||||
.. [1] This fail-safe can fail in these circumstances:
|
||||
|
||||
- The underlying file system doesn't support statvfs(2), or returns incorrect
|
||||
data, or the repository doesn't reside on a single file system
|
||||
- The underlying file system does not support statvfs(2), or returns incorrect
|
||||
data, or the repository does not reside on a single file system
|
||||
- Other tasks fill the disk simultaneously
|
||||
- Hard quotas (which may not be reflected in statvfs(2))
|
||||
|
||||
Important note about permissions
|
||||
--------------------------------
|
||||
|
||||
To avoid permissions issues (in your borg repository or borg cache), **always
|
||||
To avoid permissions issues (in your Borg repository or Borg cache), **always
|
||||
access the repository using the same user account**.
|
||||
|
||||
If you want to backup files of other users or the operating system, running
|
||||
borg as root likely will be required (otherwise you'ld get `Permission denied`
|
||||
If you want to back up files of other users or the operating system, running
|
||||
Borg as root likely will be required (otherwise you'd get `Permission denied`
|
||||
errors).
|
||||
If you only back up your own files, you neither need nor want to run borg as
|
||||
If you only back up your own files, you neither need nor want to run Borg as
|
||||
root, just run it as your normal user.
|
||||
|
||||
For a local repository just always use the same user to invoke borg.
|
||||
For a local repository just always use the same user to invoke Borg.
|
||||
|
||||
For a remote repository: always use e.g. borg@remote_host. You can use this
|
||||
from different local users, the remote user running borg and accessing the
|
||||
from different local users; the remote user running Borg and accessing the
|
||||
repo will always be `borg`.
|
||||
|
||||
If you need to access a local repository from different users, you can use the
|
||||
same method by using ssh to borg@localhost.
|
||||
same method by using SSH to borg@localhost.
|
||||
|
||||
Important note about files changing during the backup process
|
||||
-------------------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ Security
|
|||
--------
|
||||
|
||||
In case you discover a security issue, please use this contact for reporting it
|
||||
privately and please, if possible, use encrypted E-Mail:
|
||||
privately and please, if possible, use encrypted email:
|
||||
|
||||
Thomas Waldmann <tw@waldmann-edv.de>
|
||||
|
||||
|
|
@ -28,7 +28,7 @@ Verifying signed releases
|
|||
-------------------------
|
||||
|
||||
`Releases <https://github.com/borgbackup/borg/releases>`_ are signed with the
|
||||
same GPG key and a .asc file is provided for each binary.
|
||||
same GPG key and an .asc file is provided for each binary.
|
||||
|
||||
To verify a signature, the public key needs to be known to GPG. It can be
|
||||
imported into the local keystore from a keyserver with the fingerprint::
|
||||
|
|
@ -41,7 +41,7 @@ If GPG successfully imported the key, the output should include (among other thi
|
|||
gpg: Total number processed: 1
|
||||
...
|
||||
|
||||
To verify for example the signature of the borg-linux64 binary::
|
||||
To verify, for example, the signature of the borg-linux64 binary::
|
||||
|
||||
gpg --verify borg-linux64.asc
|
||||
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ Usage
|
|||
window.location.pathname = replaced;
|
||||
}
|
||||
}
|
||||
// Fixup anchored links from when usage.html contained all the commands
|
||||
// Fix up anchored links from when usage.html contained all the commands
|
||||
else if(hash.startsWith("borg-key") || hash == "borg-change-passphrase") {
|
||||
window.location.hash = "";
|
||||
window.location.pathname = window.location.pathname.replace("usage.html", "usage/key.html");
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ Examples
|
|||
# compact segments and free repo disk space
|
||||
$ borg compact /path/to/repo
|
||||
|
||||
# same as above plus clean up 17byte commit-only segments
|
||||
# same as above plus clean up 17-byte commit-only segments
|
||||
$ borg compact --cleanup-commits /path/to/repo
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ There is a ``borg debug`` command that has some subcommands which are all
|
|||
**not intended for normal use** and **potentially very dangerous** if used incorrectly.
|
||||
|
||||
For example, ``borg debug put-obj`` and ``borg debug delete-obj`` will only do
|
||||
what their name suggests: put objects into repo / delete objects from repo.
|
||||
what their name suggests: put objects into the repository or delete objects from the repository.
|
||||
|
||||
Please note:
|
||||
|
||||
|
|
@ -31,4 +31,4 @@ The ``borg debug profile-convert`` command can be used to take a Borg profile an
|
|||
it to a profile file that is compatible with the Python tools.
|
||||
|
||||
Additionally, if the filename specified for ``--debug-profile`` ends with ".pyprof" a
|
||||
Python compatible profile is generated. This is only intended for local use by developers.
|
||||
Python-compatible profile is generated. This is only intended for local use by developers.
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ Examples
|
|||
# delete all archives whose names contain "-2012-"
|
||||
$ borg delete --glob-archives '*-2012-*' /path/to/repo
|
||||
|
||||
# see what would be deleted if delete was run without --dry-run
|
||||
# see what would be deleted if delete were run without --dry-run
|
||||
$ borg delete --list --dry-run -a '*-May-*' /path/to/repo
|
||||
|
||||
# delete the whole repository and the related local cache:
|
||||
|
|
|
|||
|
|
@ -32,16 +32,16 @@ All Borg commands share these options:
|
|||
.. include:: common-options.rst.inc
|
||||
|
||||
Option ``--bypass-lock`` allows you to access the repository while bypassing
|
||||
borg's locking mechanism. This is necessary if your repository is on a read-only
|
||||
Borg's locking mechanism. This is necessary if your repository is on a read-only
|
||||
storage where you don't have write permissions or capabilities and therefore
|
||||
cannot create a lock. Examples are repositories stored on a Bluray disc or a
|
||||
read-only network storage. Avoid this option if you are able to use locks as
|
||||
cannot create a lock. Examples are repositories stored on a Blu-ray disc or a
|
||||
read-only network storage. Avoid this option if you are able to use locks, as
|
||||
that is the safer way; see the warning below.
|
||||
|
||||
.. warning::
|
||||
|
||||
If you do use ``--bypass-lock``, you are responsible to ensure that no other
|
||||
borg instances have write access to the repository. Otherwise, you might
|
||||
If you do use ``--bypass-lock``, you are responsible for ensuring that no other
|
||||
Borg instances have write access to the repository. Otherwise, you might
|
||||
experience errors and read broken data if changes to that repository are
|
||||
being made at the same time.
|
||||
|
||||
|
|
|
|||
|
|
@ -59,11 +59,11 @@ borgfs
|
|||
$ mount /tmp/myrepo
|
||||
$ mount /tmp/myarchive
|
||||
$ ls /tmp/myrepo
|
||||
root-2016-02-01 root-2016-02-2015
|
||||
root-2016-02-01 root-2016-02-15
|
||||
$ ls /tmp/myarchive
|
||||
bin boot etc home lib lib64 lost+found media mnt opt root sbin srv tmp usr var
|
||||
|
||||
.. Note::
|
||||
.. note::
|
||||
|
||||
``borgfs`` will be automatically provided if you used a distribution
|
||||
package or ``pip`` to install Borg. Users of the standalone binary will have
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
Additional Notes
|
||||
----------------
|
||||
|
||||
Here are misc. notes about topics that are maybe not covered in enough detail in the usage section.
|
||||
Here are miscellaneous notes about topics that might not be covered in enough detail in the usage section.
|
||||
|
||||
.. _chunker-params:
|
||||
|
||||
|
|
@ -24,14 +24,14 @@ deduplication and creates a much smaller amount of chunks and thus uses less
|
|||
resources. This is good for relatively big data volumes and if the machine has
|
||||
a relatively low amount of free RAM and disk space.
|
||||
|
||||
``--chunker-params=fixed,4194304`` results in fixed 4MiB sized block
|
||||
``--chunker-params=fixed,4194304`` results in fixed 4 MiB sized block
|
||||
deduplication and is more efficient than the previous example when used for
|
||||
for block devices (like disks, partitions, LVM LVs) or raw disk image files.
|
||||
block devices (like disks, partitions, LVM LVs) or raw disk image files.
|
||||
|
||||
``--chunker-params=fixed,4096,512`` results in fixed 4kiB sized blocks,
|
||||
but the first header block will only be 512B long. This might be useful to
|
||||
dedup files with 1 header + N fixed size data blocks. Be careful to not
|
||||
produce a too big amount of chunks (like using small block size for huge
|
||||
``--chunker-params=fixed,4096,512`` results in fixed 4 KiB sized blocks,
|
||||
but the first header block will only be 512 B long. This might be useful to
|
||||
deduplicate files with 1 header + N fixed-size data blocks. Be careful not to
|
||||
produce too many chunks (such as using a small block size for huge
|
||||
files).
|
||||
|
||||
If you already have made some archives in a repository and you then change
|
||||
|
|
@ -46,7 +46,7 @@ Usually, it is not that bad though:
|
|||
- usually most files are not touched, so it will just re-use the old chunks
|
||||
it already has in the repo
|
||||
- files smaller than the (both old and new) minimum chunksize result in only
|
||||
one chunk anyway, so the resulting chunks are same and deduplication will apply
|
||||
one chunk anyway, so the resulting chunks are the same and deduplication will apply
|
||||
|
||||
If you switch chunker params to save resources for an existing repo that
|
||||
already has some backup archives, you will see an increasing effect over time,
|
||||
|
|
@ -85,17 +85,17 @@ use this option also for speeding up operations.
|
|||
~~~~~~~~~~~
|
||||
|
||||
borg uses a safe default umask of 077 (that means the files borg creates have
|
||||
only permissions for owner, but no permissions for group and others) - so there
|
||||
only permissions for the owner, but no permissions for group and others) - so there
|
||||
should rarely be a need to change the default behaviour.
|
||||
|
||||
This option only affects the process to which it is given. Thus, when you run
|
||||
borg in client/server mode and you want to change the behaviour on the server
|
||||
side, you need to use ``borg serve --umask=XXX ...`` as a ssh forced command
|
||||
side, you need to use ``borg serve --umask=XXX ...`` as an SSH forced command
|
||||
in ``authorized_keys``. The ``--umask`` value given on the client side is
|
||||
**not** transferred to the server side.
|
||||
|
||||
Also, if you choose to use the ``--umask`` option, always be consistent and use
|
||||
the same umask value so you do not create a mixup of permissions in a borg
|
||||
the same umask value so you do not create a mix-up of permissions in a borg
|
||||
repository or with other files borg creates.
|
||||
|
||||
``--read-special``
|
||||
|
|
@ -120,13 +120,13 @@ You need to be careful about what you include when using ``--read-special``,
|
|||
e.g. if you include ``/dev/zero``, your backup will never terminate.
|
||||
|
||||
Restoring such files' content is currently only supported one at a time via
|
||||
``--stdout`` option (and you have to redirect stdout to where ever it shall go,
|
||||
``--stdout`` option (and you have to redirect stdout to wherever it shall go,
|
||||
maybe directly into an existing device file of your choice or indirectly via
|
||||
``dd``).
|
||||
|
||||
To some extent, mounting a backup archive with the backups of special files
|
||||
via ``borg mount`` and then loop-mounting the image files from inside the mount
|
||||
point will work. If you plan to access a lot of data in there, it likely will
|
||||
point will work. If you plan to access a lot of data in there, it will likely
|
||||
scale and perform better if you do not work via the FUSE mount.
|
||||
|
||||
Example
|
||||
|
|
@ -211,7 +211,7 @@ but borg will also reject to delete the repository completely).
|
|||
If ``borg compact`` command is used on a repo in append-only mode, there
|
||||
will be no warning or error, but no compaction will happen.
|
||||
|
||||
append-only is useful for scenarios where a backup client machine backups
|
||||
Append-only is useful for scenarios where a backup client machine backs up
|
||||
remotely to a backup server using ``borg serve``, since a hacked client machine
|
||||
cannot delete backups on the server permanently.
|
||||
|
||||
|
|
@ -233,7 +233,7 @@ in ``.ssh/authorized_keys``:
|
|||
|
||||
::
|
||||
|
||||
command="borg serve --append-only ..." ssh-rsa <key used for not-always-trustable backup clients>
|
||||
command="borg serve --append-only ..." ssh-rsa <key used for not-always-trustworthy backup clients>
|
||||
command="borg serve ..." ssh-rsa <key used for backup management>
|
||||
|
||||
Running ``borg init`` via a ``borg serve --append-only`` server will *not* create
|
||||
|
|
@ -255,7 +255,7 @@ mode. A transaction log in this situation might look like this:
|
|||
transaction 13, UTC time 2016-03-31T15:55:55.472564
|
||||
|
||||
From your security logs you conclude the attacker gained access at 15:54:00 and all
|
||||
the backups where deleted or replaced by compromised backups. From the log you know
|
||||
the backups were deleted or replaced by compromised backups. From the log you know
|
||||
that transactions 11 and later are compromised. Note that the transaction ID is the
|
||||
name of the *last* file in the transaction. For example, transaction 11 spans files 6
|
||||
to 11.
|
||||
|
|
@ -320,7 +320,7 @@ repository. Make sure that backup client machines only get to access the reposit
|
|||
``borg serve``.
|
||||
|
||||
Ensure that no remote access is possible if the repository is temporarily set to normal mode
|
||||
for e.g. regular pruning.
|
||||
for example, regular pruning.
|
||||
|
||||
Further protections can be implemented, but are outside of Borg's scope. For example,
|
||||
file system snapshots or wrapping ``borg serve`` to set special permissions or ACLs on
|
||||
|
|
|
|||
|
|
@ -3,38 +3,38 @@
|
|||
Examples
|
||||
~~~~~~~~
|
||||
|
||||
Be careful, prune is a potentially dangerous command, it will remove backup
|
||||
Be careful: prune is a potentially dangerous command; it will remove backup
|
||||
archives.
|
||||
|
||||
The default of prune is to apply to **all archives in the repository** unless
|
||||
you restrict its operation to a subset of the archives using ``--glob-archives``.
|
||||
When using ``--glob-archives``, be careful to choose a good matching pattern -
|
||||
e.g. do not use "foo*" if you do not also want to match "foobar".
|
||||
By default, prune applies to **all archives in the repository** unless you
|
||||
restrict its operation to a subset of the archives using ``--glob-archives``.
|
||||
When using ``--glob-archives``, be careful to choose a good matching pattern —
|
||||
for example, do not use "foo*" if you do not also want to match "foobar".
|
||||
|
||||
It is strongly recommended to always run ``prune -v --list --dry-run ...``
|
||||
first so you will see what it would do without it actually doing anything.
|
||||
first, so you can see what it would do without actually doing anything.
|
||||
|
||||
::
|
||||
|
||||
# Keep 7 end of day and 4 additional end of week archives.
|
||||
# Keep 7 end-of-day and 4 additional end-of-week archives.
|
||||
# Do a dry-run without actually deleting anything.
|
||||
$ borg prune -v --list --dry-run --keep-daily=7 --keep-weekly=4 /path/to/repo
|
||||
|
||||
# Same as above but only apply to archive names starting with the hostname
|
||||
# of the machine followed by a "-" character:
|
||||
$ borg prune -v --list --keep-daily=7 --keep-weekly=4 --glob-archives='{hostname}-*' /path/to/repo
|
||||
# actually free disk space:
|
||||
# Actually free disk space:
|
||||
$ borg compact /path/to/repo
|
||||
|
||||
# Keep 7 end of day, 4 additional end of week archives,
|
||||
# and an end of month archive for every month:
|
||||
# Keep 7 end-of-day, 4 additional end-of-week archives,
|
||||
# and an end-of-month archive for every month:
|
||||
$ borg prune -v --list --keep-daily=7 --keep-weekly=4 --keep-monthly=-1 /path/to/repo
|
||||
|
||||
# Keep all backups in the last 10 days, 4 additional end of week archives,
|
||||
# and an end of month archive for every month:
|
||||
# Keep all backups in the last 10 days, 4 additional end-of-week archives,
|
||||
# and an end-of-month archive for every month:
|
||||
$ borg prune -v --list --keep-within=10d --keep-weekly=4 --keep-monthly=-1 /path/to/repo
|
||||
|
||||
There is also a visualized prune example in ``docs/misc/prune-example.txt``:
|
||||
There is also a visual example of pruning in ``docs/misc/prune-example.txt``:
|
||||
|
||||
.. highlight:: none
|
||||
.. include:: ../misc/prune-example.txt
|
||||
|
|
|
|||
|
|
@ -4,22 +4,22 @@ Examples
|
|||
~~~~~~~~
|
||||
::
|
||||
|
||||
# Make old (Attic / Borg 0.xx) archives deduplicate with Borg 1.x archives.
|
||||
# Make old (Attic/Borg 0.xx) archives deduplicate with Borg 1.x archives.
|
||||
# Archives created with Borg 1.1+ and the default chunker params are skipped
|
||||
# (archive ID stays the same).
|
||||
$ borg recreate /mnt/backup --chunker-params default --progress
|
||||
|
||||
# Create a backup with little but fast compression
|
||||
# Create a backup with low but fast compression.
|
||||
$ borg create /mnt/backup::archive /some/files --compression lz4
|
||||
# Then compress it - this might take longer, but the backup has already completed,
|
||||
# Then compress it — this might take longer, but the backup has already completed,
|
||||
# so no inconsistencies from a long-running backup job.
|
||||
$ borg recreate /mnt/backup::archive --recompress --compression zlib,9
|
||||
|
||||
# Remove unwanted files from all archives in a repository.
|
||||
# Note the relative path for the --exclude option - archives only contain relative paths.
|
||||
# Note the relative path for the --exclude option — archives only contain relative paths.
|
||||
$ borg recreate /mnt/backup --exclude home/icke/Pictures/drunk_photos
|
||||
|
||||
# Change archive comment
|
||||
# Change the archive comment.
|
||||
$ borg create --comment "This is a comment" /mnt/backup::archivename ~
|
||||
$ borg info /mnt/backup::archivename
|
||||
Name: archivename
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
Examples
|
||||
~~~~~~~~
|
||||
|
||||
``borg serve`` has special support for ssh forced commands (see ``authorized_keys``
|
||||
``borg serve`` has special support for SSH forced commands (see ``authorized_keys``
|
||||
example below): if the environment variable SSH_ORIGINAL_COMMAND is set it will
|
||||
ignore some options given on the command line and use the values from the
|
||||
variable instead. This only applies to a carefully controlled allowlist of safe
|
||||
|
|
@ -15,31 +15,31 @@ options. This list currently contains:
|
|||
giving up and aborting the operation when another process is holding a lock.
|
||||
|
||||
Environment variables (such as BORG_XXX) contained in the original
|
||||
command sent by the client are *not* interpreted, but ignored. If BORG_XXX environment
|
||||
variables should be set on the ``borg serve`` side, then these must be set in system-specific
|
||||
command sent by the client are *not* interpreted; they are ignored. If BORG_XXX environment
|
||||
variables need to be set on the ``borg serve`` side, then these must be set in system-specific
|
||||
locations like ``/etc/environment`` or in the forced command itself (example below).
|
||||
|
||||
::
|
||||
|
||||
# Allow an SSH keypair to only run borg, and only have access to /path/to/repo.
|
||||
# Allow an SSH key pair to only run 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.
|
||||
# This helps secure an automated remote backup system.
|
||||
$ cat ~/.ssh/authorized_keys
|
||||
command="borg serve --restrict-to-path /path/to/repo",restrict ssh-rsa AAAAB3[...]
|
||||
|
||||
# Set a BORG_XXX environment variable on the "borg serve" side
|
||||
# Set a BORG_XXX environment variable on the ``borg serve`` side.
|
||||
$ cat ~/.ssh/authorized_keys
|
||||
command="BORG_XXX=value borg serve [...]",restrict ssh-rsa [...]
|
||||
|
||||
.. note::
|
||||
The examples above use the ``restrict`` directive and assume a POSIX
|
||||
compliant shell set as the user's login shell.
|
||||
This does automatically block potential dangerous ssh features, even when
|
||||
The examples above use the ``restrict`` directive and assume a POSIX-compliant
|
||||
shell set as the user's login shell.
|
||||
This automatically blocks potentially dangerous SSH features, even when
|
||||
they are added in a future update. Thus, this option should be preferred.
|
||||
|
||||
If you're using openssh-server < 7.2, however, you have to explicitly specify
|
||||
the ssh features to restrict and cannot simply use the restrict option as it
|
||||
has been introduced in v7.2. We recommend to use
|
||||
If you're using OpenSSH server < 7.2, however, you have to explicitly specify
|
||||
the SSH features to restrict and cannot simply use the ``restrict`` option as it
|
||||
was introduced in v7.2. We recommend using
|
||||
``no-port-forwarding,no-X11-forwarding,no-pty,no-agent-forwarding,no-user-rc``
|
||||
in this case.
|
||||
|
||||
|
|
@ -60,9 +60,9 @@ Either in the client side's ``~/.ssh/config`` file, or in the client's ``/etc/ss
|
|||
ServerAliveInterval 10
|
||||
ServerAliveCountMax 30
|
||||
|
||||
Replacing ``backupserver`` with the hostname, FQDN or IP address of the borg server.
|
||||
Replace ``backupserver`` with the hostname, FQDN, or IP address of the Borg server.
|
||||
|
||||
This will cause the client to send a keepalive to the server every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the ssh client process will be terminated, causing the borg process to terminate gracefully.
|
||||
This will cause the client to send a keepalive to the server every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the SSH client process will be terminated, causing the Borg process to terminate gracefully.
|
||||
|
||||
On the server side's ``sshd`` configuration file (typically ``/etc/ssh/sshd_config``):
|
||||
::
|
||||
|
|
@ -70,8 +70,8 @@ On the server side's ``sshd`` configuration file (typically ``/etc/ssh/sshd_conf
|
|||
ClientAliveInterval 10
|
||||
ClientAliveCountMax 30
|
||||
|
||||
This will cause the server to send a keep alive to the client every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the server's sshd process will be terminated, causing the ``borg serve`` process to terminate gracefully and release the lock on the repository.
|
||||
This will cause the server to send a keepalive to the client every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the server's sshd process will be terminated, causing the ``borg serve`` process to terminate gracefully and release the lock on the repository.
|
||||
|
||||
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.
|
||||
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 following 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.
|
||||
|
|
|
|||
|
|
@ -6,18 +6,18 @@ Examples
|
|||
~~~~~~~~
|
||||
::
|
||||
|
||||
# export as uncompressed tar
|
||||
# Export as an uncompressed tar.
|
||||
$ borg export-tar /path/to/repo::Monday Monday.tar
|
||||
|
||||
# exclude some types, compress using gzip
|
||||
# Exclude some types; compress using gzip.
|
||||
$ borg export-tar /path/to/repo::Monday Monday.tar.gz --exclude '*.so'
|
||||
|
||||
# use higher compression level with gzip
|
||||
# Use a higher compression level with gzip.
|
||||
$ borg export-tar --tar-filter="gzip -9" testrepo::linux Monday.tar.gz
|
||||
|
||||
# export a tar, but instead of storing it on disk,
|
||||
# Export a tar, but instead of storing it on disk,
|
||||
# upload it to a remote site using curl.
|
||||
$ borg export-tar /path/to/repo::Monday - | curl --data-binary @- https://somewhere/to/POST
|
||||
|
||||
# remote extraction via "tarpipe"
|
||||
# Remote extraction via "tarpipe".
|
||||
$ borg export-tar /path/to/repo::Monday - | ssh somewhere "cd extracted; tar x"
|
||||
|
|
|
|||
|
|
@ -16,14 +16,14 @@ Examples
|
|||
|
||||
.. _borg_key_migrate-to-repokey:
|
||||
|
||||
Upgrading a passphrase encrypted attic repo
|
||||
Upgrading a passphrase-encrypted Attic repo
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
attic offered a "passphrase" encryption mode, but this was removed in borg 1.0
|
||||
Attic offered a "passphrase" encryption mode, but this was removed in Borg 1.0
|
||||
and replaced by the "repokey" mode (which stores the passphrase-protected
|
||||
encryption key into the repository config).
|
||||
encryption key in the repository config).
|
||||
|
||||
Thus, to upgrade a "passphrase" attic repo to a "repokey" borg repo, 2 steps
|
||||
Thus, to upgrade a "passphrase" Attic repo to a "repokey" Borg repo, two steps
|
||||
are needed, in this order:
|
||||
|
||||
- borg upgrade repo
|
||||
|
|
|
|||
Loading…
Reference in a new issue