mirror of
https://github.com/borgbackup/borg.git
synced 2024-09-11 12:36:12 +03:00
Docs grammar fixes
joined split infinitives, and relocated adverbs appropriately.
This commit is contained in:
parent
a85b643866
commit
253d8e8d4e
@ -8,8 +8,8 @@ Version 0.30.0 (2016-01-23)
|
||||
|
||||
Compatibility notes:
|
||||
|
||||
- you may need to use -v (or --info) more often to actually see output emitted
|
||||
at INFO log level (because it is suppressed at the default WARNING log level).
|
||||
- The new default logging level is WARNING. Previously, it was INFO, which was
|
||||
more verbose. Use -v (or --info) to show once again log level INFO messages.
|
||||
See the "general" section in the usage docs.
|
||||
- for borg create, you need --list (additionally to -v) to see the long file
|
||||
list (was needed so you can have e.g. --stats alone without the long list)
|
||||
|
@ -776,7 +776,7 @@ Other changes:
|
||||
- docs:
|
||||
|
||||
- improve description of path variables
|
||||
- document how to completely delete data, #2929
|
||||
- document how to delete data completely, #2929
|
||||
- add FAQ about Borg config dir, #4941
|
||||
- add docs about errors not printed as JSON, #4073
|
||||
- update usage_general.rst.inc
|
||||
@ -2149,7 +2149,7 @@ New features:
|
||||
- mount: added exclusion group options and paths, #2138
|
||||
|
||||
Reused some code to support similar options/paths as borg extract offers -
|
||||
making good use of these to only mount a smaller subset of dirs/files can
|
||||
making good use of these to mount only a smaller subset of dirs/files can
|
||||
speed up mounting a lot and also will consume way less memory.
|
||||
|
||||
borg mount [options] repo_or_archive mountpoint path [paths...]
|
||||
@ -3078,7 +3078,7 @@ New features:
|
||||
which includes the SHA1 and SHA2 family as well as MD5
|
||||
- borg prune:
|
||||
|
||||
- to better visualize the "thinning out", we now list all archives in
|
||||
- to visualize the "thinning out" better, we now list all archives in
|
||||
reverse time order. rephrase and reorder help text.
|
||||
- implement --keep-last N via --keep-secondly N, also --keep-minutely.
|
||||
assuming that there is not more than 1 backup archive made in 1s,
|
||||
@ -3505,8 +3505,18 @@ Security fixes:
|
||||
|
||||
CVE-2016-10099 was assigned to this vulnerability.
|
||||
- borg check: When rebuilding the manifest (which should only be needed very rarely)
|
||||
duplicate archive names would be handled on a "first come first serve" basis, allowing
|
||||
an attacker to apparently replace archives.
|
||||
duplicate archive names would be handled on a "first come first serve" basis,
|
||||
potentially opening an attack vector to replace archives.
|
||||
|
||||
Example: were there 2 archives named "foo" in a repo (which can not happen
|
||||
under normal circumstances, because borg checks if the name is already used)
|
||||
and a "borg check" recreated a (previously lost) manifest, the first of the
|
||||
archives it encountered would be in the manifest. The second archive is also
|
||||
still in the repo, but not referenced in the manifest, in this case. If the
|
||||
second archive is the "correct" one (and was previously referenced from the
|
||||
manifest), it looks like it got replaced by the first one. In the manifest,
|
||||
it actually got replaced. Both remain in the repo but the "correct" one is no
|
||||
longer accessible via normal means - the manifest.
|
||||
|
||||
CVE-2016-10100 was assigned to this vulnerability.
|
||||
|
||||
@ -4234,20 +4244,20 @@ Compatibility notes:
|
||||
changed file and in the worst case (e.g. if your files cache was lost / is
|
||||
not used) by the size of every file (minus any compression you might use).
|
||||
|
||||
in case you want to immediately see a much lower resource usage (RAM / disk)
|
||||
in case you want to see a much lower resource usage immediately (RAM / disk)
|
||||
for chunks management, it might be better to start with a new repo than
|
||||
continuing in the existing repo (with an existing repo, you'ld have to wait
|
||||
until all archives with small chunks got pruned to see a lower resource
|
||||
to continue in the existing repo (with an existing repo, you have to wait
|
||||
until all archives with small chunks get pruned to see a lower resource
|
||||
usage).
|
||||
|
||||
if you used the old --chunker-params default value (or if you did not use
|
||||
--chunker-params option at all) and you'ld like to continue using small
|
||||
--chunker-params option at all) and you'd like to continue using small
|
||||
chunks (and you accept the huge resource usage that comes with that), just
|
||||
explicitly use borg create --chunker-params=10,23,16,4095.
|
||||
use explicitly borg create --chunker-params=10,23,16,4095.
|
||||
- archive timestamps: the 'time' timestamp now refers to archive creation
|
||||
start time (was: end time), the new 'time_end' timestamp refers to archive
|
||||
creation end time. This might affect prune if your backups take rather long.
|
||||
if you give a timestamp via cli this is stored into 'time', therefore it now
|
||||
creation end time. This might affect prune if your backups take a long time.
|
||||
if you give a timestamp via cli, this is stored into 'time'. therefore it now
|
||||
needs to mean archive creation start time.
|
||||
|
||||
New features:
|
||||
@ -4289,8 +4299,8 @@ Bug fixes:
|
||||
|
||||
Other changes:
|
||||
|
||||
- it is now possible to use "pip install borgbackup[fuse]" to automatically
|
||||
install the llfuse dependency using the correct version requirement
|
||||
- it is now possible to use "pip install borgbackup[fuse]" to
|
||||
install the llfuse dependency automatically, using the correct version requirement
|
||||
for it. you still need to care about having installed the FUSE / build
|
||||
related OS package first, though, so that building llfuse can succeed.
|
||||
- Vagrant: drop Ubuntu Precise (12.04) - does not have Python >= 3.4
|
||||
|
@ -168,13 +168,13 @@ after creating the backup. Rename the file to something else (e.g. ``/etc/backup
|
||||
when you want to do something with the drive after creating backups (e.g running check).
|
||||
|
||||
Create the ``/etc/backups/backup-suspend`` file if the machine should suspend after completing
|
||||
the backup. Don't forget to physically disconnect the device before resuming,
|
||||
the backup. Don't forget to disconnect the device physically before resuming,
|
||||
otherwise you'll enter a cycle. You can also add an option to power down instead.
|
||||
|
||||
Create an empty ``/etc/backups/backup.disks`` file, you'll register your backup drives
|
||||
there.
|
||||
|
||||
The last part is to actually enable the udev rules and services:
|
||||
The last part is actually to enable the udev rules and services:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
@ -5,7 +5,7 @@
|
||||
Hosting repositories
|
||||
====================
|
||||
|
||||
This sections shows how to securely provide repository storage for users.
|
||||
This sections shows how to provide repository storage securely for users.
|
||||
Optionally, each user can have a storage quota.
|
||||
|
||||
Repositories are accessed through SSH. Each user of the service should
|
||||
|
@ -77,7 +77,7 @@ Because the partitions were zeroed in place, restoration is only one command::
|
||||
borg extract --stdout repo::hostname-disk | dd of=$DISK
|
||||
|
||||
.. note:: The "traditional" way to zero out space on a partition, especially one already
|
||||
mounted, is to simply ``dd`` from ``/dev/zero`` to a temporary file and delete
|
||||
mounted, is simply to ``dd`` from ``/dev/zero`` to a temporary file and delete
|
||||
it. This is ill-advised for the reasons mentioned in the ``zerofree`` man page:
|
||||
|
||||
- it is slow
|
||||
|
@ -161,7 +161,7 @@ Now we can run
|
||||
|
||||
borg extract /borgrepo::archive PATH
|
||||
|
||||
to partially restore whatever we like. Finally, do the clean-up:
|
||||
to restore whatever we like partially. Finally, do the clean-up:
|
||||
|
||||
::
|
||||
|
||||
@ -209,8 +209,8 @@ 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
|
||||
established that uses SSH reverse port forwarding to tunnel data
|
||||
transparently 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
|
||||
@ -277,7 +277,7 @@ forwarding can do this for us::
|
||||
|
||||
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
|
||||
When you are done, you have to remove the socket file manually, 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
|
||||
@ -417,7 +417,7 @@ Parentheses are not needed when using a dedicated bash process.
|
||||
|
||||
*ssh://borgs@borg-server/~/repo* refers to the repository *repo* within borgs's home directory on *borg-server*.
|
||||
|
||||
*StrictHostKeyChecking=no* is used to automatically add host keys to *~/.ssh/known_hosts* without user intervention.
|
||||
*StrictHostKeyChecking=no* is used to add host keys automatically to *~/.ssh/known_hosts* without user intervention.
|
||||
|
||||
``kill "${SSH_AGENT_PID}"``
|
||||
|
||||
|
14
docs/faq.rst
14
docs/faq.rst
@ -86,7 +86,7 @@ run into this by yourself by restoring an older copy of your repository.
|
||||
"attack": maybe an attacker has replaced your repo by an older copy, trying to
|
||||
trick you into AES counter reuse, trying to break your repo encryption.
|
||||
|
||||
If you'ld decide to ignore this and accept unsafe operation for this repository,
|
||||
If you decide to ignore this and accept unsafe operation for this repository,
|
||||
you could delete the manifest-timestamp and the local cache:
|
||||
|
||||
::
|
||||
@ -159,7 +159,7 @@ so that checkpoints even work while a big file is being processed.
|
||||
They are named ``<filename>.borg_part_<N>`` and all operations usually ignore
|
||||
these files, but you can make them considered by giving the option
|
||||
``--consider-part-files``. You usually only need that option if you are
|
||||
really desperate (e.g. if you have no completed backup of that file and you'ld
|
||||
really desperate (e.g. if you have no completed backup of that file and you'd
|
||||
rather get a partial file extracted than nothing). You do **not** want to give
|
||||
that option under any normal circumstances.
|
||||
|
||||
@ -342,7 +342,7 @@ That's **45** orders of magnitude more probable than the SHA-256 collision. Brie
|
||||
if you find SHA-256 collisions scary then your priorities are wrong. This example was grabbed from
|
||||
`this SO answer <https://stackoverflow.com/a/4014407/13359375>`_, it's great honestly.
|
||||
|
||||
Still, the real question is if Borg tries not to make this happen?
|
||||
Still, the real question is whether Borg tries not to make this happen?
|
||||
|
||||
Well... previously it did not check anything until there was a feature added which saves the size
|
||||
of the chunks too, so the size of the chunks is compared to the size that you got with the
|
||||
@ -467,7 +467,7 @@ Setting ``BORG_PASSPHRASE``
|
||||
user
|
||||
<https://security.stackexchange.com/questions/14000/environment-variable-accessibility-in-linux/14009#14009>`_.
|
||||
|
||||
Using ``BORG_PASSCOMMAND`` with a properly permissioned file
|
||||
Using ``BORG_PASSCOMMAND`` with a file of proper permissions
|
||||
Another option is to create a file with a password in it in your home
|
||||
directory and use permissions to keep anyone else from reading it. For
|
||||
example, first create a key::
|
||||
@ -524,7 +524,7 @@ Using ``BORG_PASSCOMMAND`` with GNOME Keyring
|
||||
|
||||
export BORG_PASSCOMMAND="secret-tool lookup borg-repository repo-name"
|
||||
|
||||
.. note:: For this to automatically unlock the keychain it must be run
|
||||
.. note:: For this to unlock the keychain automatically it must be run
|
||||
in the ``dbus`` session of an unlocked terminal; for example, running a backup
|
||||
script as a ``cron`` job might not work unless you also ``export DISPLAY=:0``
|
||||
so ``secret-tool`` can pick up your open session. `It gets even more complicated`__
|
||||
@ -573,7 +573,7 @@ C to delete all backups residing on S.
|
||||
|
||||
These are your options to protect against that:
|
||||
|
||||
- Do not allow to permanently delete data from the repo, see :ref:`append_only_mode`.
|
||||
- Do not allow to delete data permanently from the repo, see :ref:`append_only_mode`.
|
||||
- Use a pull-mode setup using ``ssh -R``, see :ref:`pull_backup` for more information.
|
||||
- Mount C's filesystem on another machine and then create a backup of it.
|
||||
- Do not give C filesystem-level access to S.
|
||||
@ -853,7 +853,7 @@ Then you do the backup and look at the log output:
|
||||
The metadata values used in this comparison are determined by the ``--files-cache`` option
|
||||
and could be e.g. size, ctime and inode number (see the ``borg create`` docs for more
|
||||
details and potential issues).
|
||||
You can use the ``stat`` command on files to manually look at fs metadata to debug if
|
||||
You can use the ``stat`` command on files to look at fs metadata manually to debug if
|
||||
there is any unexpected change triggering the ``M`` status.
|
||||
Also, the ``--debug-topic=files_cache`` option of ``borg create`` provides a lot of debug
|
||||
output helping to analyse why the files cache does not give its expected high performance.
|
||||
|
@ -134,7 +134,7 @@ fail if /tmp has not enough free space or is mounted with the ``noexec``
|
||||
option. You can change the temporary directory by setting the ``TEMP``
|
||||
environment variable before running Borg.
|
||||
|
||||
If a new version is released, you will have to manually download it and replace
|
||||
If a new version is released, you will have to download it manually and replace
|
||||
the old version using the same steps as shown above.
|
||||
|
||||
.. _pyinstaller: http://www.pyinstaller.org
|
||||
@ -331,7 +331,7 @@ optional, but recommended except for the most simple use cases.
|
||||
If you install into a virtual environment, you need to **activate** it
|
||||
first (``source borg-env/bin/activate``), before running ``borg``.
|
||||
Alternatively, symlink ``borg-env/bin/borg`` into some directory that is in
|
||||
your ``PATH`` so you can just run ``borg``.
|
||||
your ``PATH`` so you can run ``borg``.
|
||||
|
||||
This will use ``pip`` to install the latest release from PyPi::
|
||||
|
||||
|
@ -22,7 +22,7 @@ metadata, using :ref:`chunks` created by the chunker using the
|
||||
Buzhash_ algorithm ("buzhash" chunker) or a simpler fixed blocksize
|
||||
algorithm ("fixed" chunker).
|
||||
|
||||
To actually perform the repository-wide deduplication, a hash of each
|
||||
To 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.
|
||||
|
||||
|
@ -157,8 +157,8 @@ An object (the payload part of a segment file log entry) must be like:
|
||||
|
||||
- compressed data (with an optional all-zero-bytes obfuscation trailer)
|
||||
|
||||
This new, more complex repo v2 object format was implemented to be able to efficiently
|
||||
query the metadata without having to read, transfer and decrypt the (usually much bigger)
|
||||
This new, more complex repo v2 object format was implemented to be able to query the
|
||||
metadata efficiently without having to read, transfer and decrypt the (usually much bigger)
|
||||
data part.
|
||||
|
||||
The metadata is encrypted not to disclose potentially sensitive information that could be
|
||||
|
@ -546,7 +546,7 @@ Errors
|
||||
Buffer.MemoryLimitExceeded
|
||||
Requested buffer size {} is above the limit of {}.
|
||||
ExtensionModuleError
|
||||
The Borg binary extension modules do not seem to be properly installed
|
||||
The Borg binary extension modules do not seem to be installed properly
|
||||
IntegrityError
|
||||
Data integrity error: {}
|
||||
NoManifestError
|
||||
@ -638,4 +638,4 @@ Prompts
|
||||
BORG_CHECK_I_KNOW_WHAT_I_AM_DOING
|
||||
For "This is a potentially dangerous function..." (check --repair)
|
||||
BORG_DELETE_I_KNOW_WHAT_I_AM_DOING
|
||||
For "You requested to completely DELETE the repository *including* all archives it contains:"
|
||||
For "You requested to DELETE the repository completely *including* all archives it contains:"
|
||||
|
@ -277,7 +277,7 @@ SSH server -- Borg RPC does not contain *any* networking
|
||||
code. Networking is done by the SSH client running in a separate
|
||||
process, Borg only communicates over the standard pipes (stdout,
|
||||
stderr and stdin) with this process. This also means that Borg doesn't
|
||||
have to directly use a SSH client (or SSH at all). For example,
|
||||
have to use a SSH client directly (or SSH at all). For example,
|
||||
``sudo`` or ``qrexec`` could be used as an intermediary.
|
||||
|
||||
By using the system's SSH client and not implementing a
|
||||
|
@ -336,7 +336,7 @@ $ borg create \(aqdaily\-projectA\-{now:%Y\-%m\-%d}\(aq projectA
|
||||
# Use external command to determine files to archive
|
||||
# Use \-\-paths\-from\-stdin with find to back up only files less than 1MB in size
|
||||
$ find ~ \-size \-1000k | borg create \-\-paths\-from\-stdin small\-files\-only
|
||||
# Use \-\-paths\-from\-command with find to back up files only from a given user
|
||||
# Use \-\-paths\-from\-command with find to back up files from only a given user
|
||||
$ borg create \-\-paths\-from\-command joes\-files \-\- find /srv/samba/shared \-user joe
|
||||
# Use \-\-paths\-from\-stdin with \-\-paths\-delimiter (for example, for filenames with newlines in them)
|
||||
$ find ~ \-size \-1000k \-print0 | borg create \e
|
||||
|
@ -91,7 +91,7 @@ of CPU cores.
|
||||
.sp
|
||||
When the daemonized process receives a signal or crashes, it does not unmount.
|
||||
Unmounting in these cases could cause an active rsync or similar process
|
||||
to unintentionally delete data.
|
||||
to delete data unintentionally.
|
||||
.sp
|
||||
When running in the foreground ^C/SIGINT unmounts cleanly, but other
|
||||
signals or crashes do not.
|
||||
|
@ -72,7 +72,7 @@ keep the local security info when deleting a repository
|
||||
.ft C
|
||||
# delete the whole repository and the related local cache:
|
||||
$ borg rdelete
|
||||
You requested to completely DELETE the repository *including* all archives it contains:
|
||||
You requested to DELETE the repository completely *including* all archives it contains:
|
||||
repo Mon, 2016\-02\-15 19:26:54
|
||||
root\-2016\-02\-15 Mon, 2016\-02\-15 19:36:29
|
||||
newname Mon, 2016\-02\-15 19:50:19
|
||||
|
@ -59,8 +59,8 @@ There is no risk of data loss by this.
|
||||
used to have upgraded Borg 0.xx archives deduplicate with Borg 1.x archives.
|
||||
.sp
|
||||
\fBUSE WITH CAUTION.\fP
|
||||
Depending on the PATHs and patterns given, recreate can be used to permanently
|
||||
delete files from archives.
|
||||
Depending on the PATHs and patterns given, recreate can be used to
|
||||
delete files from archives permanently.
|
||||
When in doubt, use \fB\-\-dry\-run \-\-verbose \-\-list\fP to see how patterns/PATHS are
|
||||
interpreted. See \fIlist_item_flags\fP in \fBborg create\fP for details.
|
||||
.sp
|
||||
@ -163,7 +163,7 @@ manually specify the archive creation date/time (yyyy\-mm\-ddThh:mm:ss[(+|\-)HH:
|
||||
select compression algorithm, see the output of the \(dqborg help compression\(dq command for details.
|
||||
.TP
|
||||
.BI \-\-recompress \ MODE
|
||||
recompress data chunks according to \fIMODE\fP and \fB\-\-compression\fP\&. Possible modes are \fIif\-different\fP: recompress if current compression is with a different compression algorithm or different level; \fIalways\fP: recompress unconditionally; and \fInever\fP: do not recompress (use this option to explicitly prevent recompression). If no MODE is given, \fIif\-different\fP will be used. Not passing \-\-recompress is equivalent to \(dq\-\-recompress never\(dq.
|
||||
recompress data chunks according to \fIMODE\fP and \fB\-\-compression\fP\&. Possible modes are \fIif\-different\fP: recompress if current compression is with a different compression algorithm or different level; \fIalways\fP: recompress unconditionally; and \fInever\fP: do not recompress (use this option explicitly to prevent recompression). If no MODE is given, \fIif\-different\fP will be used. Not passing \-\-recompress is equivalent to \(dq\-\-recompress never\(dq.
|
||||
.TP
|
||||
.BI \-\-chunker\-params \ PARAMS
|
||||
specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or \fIdefault\fP to use the current defaults. default: buzhash,19,23,21,4095
|
||||
|
@ -43,10 +43,10 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
|
||||
.INDENT 0.0
|
||||
.TP
|
||||
.BI \-\-restrict\-to\-path \ PATH
|
||||
restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub\-directories is granted implicitly; PATH doesn\(aqt need to directly point to a repository.
|
||||
restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub\-directories is granted implicitly; PATH doesn\(aqt need to point to a repository directly.
|
||||
.TP
|
||||
.BI \-\-restrict\-to\-repository \ PATH
|
||||
restrict repository access. Only the repository located at PATH (no sub\-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike \fB\-\-restrict\-to\-path\fP sub\-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
|
||||
restrict repository access. Only the repository located at PATH (no sub\-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike \fB\-\-restrict\-to\-path\fP sub\-directories are not accessible; PATH needs to point directly at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
|
||||
.TP
|
||||
.B \-\-append\-only
|
||||
only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running \fIdelete\fP or \fIprune\fP will still be allowed. See \fIappend_only_mode\fP in Additional Notes for more details.
|
||||
@ -79,7 +79,7 @@ locations like \fB/etc/environment\fP or in the forced command itself (example b
|
||||
.sp
|
||||
.nf
|
||||
.ft C
|
||||
# Allow an SSH keypair to only run borg, and only have access to /path/to/repo.
|
||||
# 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.
|
||||
$ cat ~/.ssh/authorized_keys
|
||||
@ -100,7 +100,7 @@ The examples above use the \fBrestrict\fP directive. This does automatically
|
||||
block potential dangerous ssh features, even when they are added in a future
|
||||
update. Thus, this option should be preferred.
|
||||
.sp
|
||||
If you\(aqre using openssh\-server < 7.2, however, you have to explicitly specify
|
||||
If you\(aqre using openssh\-server < 7.2, however, you have to specify explicitly
|
||||
the ssh features to restrict and cannot simply use the restrict option as it
|
||||
has been introduced in v7.2. We recommend to use
|
||||
\fBno\-port\-forwarding,no\-X11\-forwarding,no\-pty,no\-agent\-forwarding,no\-user\-rc\fP
|
||||
|
@ -104,7 +104,7 @@ root\-2016\-02\-01 root\-2016\-02\-2015
|
||||
.INDENT 3.5
|
||||
\fBborgfs\fP will be automatically provided if you used a distribution
|
||||
package, \fBpip\fP or \fBsetup.py\fP to install Borg. Users of the
|
||||
standalone binary will have to manually create a symlink (see
|
||||
standalone binary will have to create a symlink manually (see
|
||||
\fIpyinstaller\-binary\fP).
|
||||
.UNINDENT
|
||||
.UNINDENT
|
||||
|
@ -56,8 +56,8 @@ except when noted otherwise in the changelog
|
||||
Use \fBborg upgrade \-\-tam REPO\fP to require manifest authentication
|
||||
introduced with Borg 1.0.9 to address security issues. This means
|
||||
that modifying the repository after doing this with a version prior
|
||||
to 1.0.9 will raise a validation error, so only perform this upgrade
|
||||
after updating all clients using the repository to 1.0.9 or newer.
|
||||
to 1.0.9 will raise a validation error, so perform this upgrade
|
||||
only after updating all clients using the repository to 1.0.9 or newer.
|
||||
.sp
|
||||
This upgrade should be done on each client for safety reasons.
|
||||
.sp
|
||||
|
@ -404,7 +404,7 @@ If BORG_PASSPHRASE or BORG_PASSCOMMAND are also set, they take precedence.
|
||||
When set, use the value to answer the passphrase question when a \fBnew\fP passphrase is asked for.
|
||||
This variable is checked first. If it is not set, BORG_PASSPHRASE and BORG_PASSCOMMAND will also
|
||||
be checked.
|
||||
Main usecase for this is to fully automate \fBborg change\-passphrase\fP\&.
|
||||
Main usecase for this is to automate fully \fBborg change\-passphrase\fP\&.
|
||||
.TP
|
||||
.B BORG_DISPLAY_PASSPHRASE
|
||||
When set, use the value to answer the \(dqdisplay the passphrase for verification\(dq question when defining a new passphrase for encrypted repositories.
|
||||
@ -413,7 +413,7 @@ When set, use the value to answer the \(dqdisplay the passphrase for verificatio
|
||||
Borg usually computes a host id from the FQDN plus the results of \fBuuid.getnode()\fP (which usually returns
|
||||
a unique id based on the MAC address of the network interface. Except if that MAC happens to be all\-zero \- in
|
||||
that case it returns a random value, which is not what we want (because it kills automatic stale lock removal).
|
||||
So, if you have a all\-zero MAC address or other reasons to better externally control the host id, just set this
|
||||
So, if you have a all\-zero MAC address or other reasons to control better externally the host id just set this
|
||||
environment variable to a unique value. If all your FQDNs are unique, you can just use the FQDN. If not,
|
||||
use \fI\%fqdn@uniqueid\fP\&.
|
||||
.TP
|
||||
@ -441,7 +441,7 @@ cache entries for backup sources other than the current sources.
|
||||
.TP
|
||||
.B BORG_FILES_CACHE_TTL
|
||||
When set to a numeric value, this determines the maximum \(dqtime to live\(dq for the files cache
|
||||
entries (default: 20). The files cache is used to quickly determine whether a file is unchanged.
|
||||
entries (default: 20). The files cache is used to determine quickly whether a file is unchanged.
|
||||
The FAQ explains this more detailed in: \fIalways_chunking\fP
|
||||
.TP
|
||||
.B BORG_SHOW_SYSINFO
|
||||
@ -509,7 +509,7 @@ For \(dqWarning: The repository at location ... was previously located at ...\(d
|
||||
For \(dqThis is a potentially dangerous function...\(dq (check \-\-repair)
|
||||
.TP
|
||||
.B BORG_DELETE_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
|
||||
For \(dqYou requested to completely DELETE the repository \fIincluding\fP all archives it contains:\(dq
|
||||
For \(dqYou requested to DELETE the repository completely \fIincluding\fP all archives it contains:\(dq
|
||||
.UNINDENT
|
||||
.sp
|
||||
Note: answers are case sensitive. setting an invalid answer value might either give the default
|
||||
|
@ -24,7 +24,7 @@ sudo chmod 755 /usr/local/bin/borg
|
||||
# Now check it: (possibly needs a terminal restart)
|
||||
borg -V
|
||||
|
||||
# That's it! Check out the other screencasts to see how to actually use borgbackup.
|
||||
# That's it! Now check out the other screencasts to see how to use borgbackup.
|
||||
}]
|
||||
|
||||
# wget may be slow
|
||||
|
@ -45,7 +45,7 @@ to the ratio of the different target chunk sizes.
|
||||
|
||||
Note: RAM needs were not a problem in this specific case (37GB data size).
|
||||
But just imagine, you have 37TB of such data and much less than 42GB RAM,
|
||||
then you'ld definitely want the "lg" chunker params so you only need
|
||||
then you should use the "lg" chunker params so you only need
|
||||
2.6GB RAM. Or even bigger chunks than shown for "lg" (see "xl").
|
||||
|
||||
You also see compression works better for larger chunks, as expected.
|
||||
|
@ -75,7 +75,7 @@ To avoid permissions issues (in your borg repository or borg cache), **always
|
||||
access the repository using the same user account**.
|
||||
|
||||
If you want to back up files of other users or the operating system, running
|
||||
borg as root likely will be required (otherwise you'ld get `Permission denied`
|
||||
borg as root likely will be required (otherwise you get `Permission denied`
|
||||
errors).
|
||||
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.
|
||||
@ -256,7 +256,7 @@ For more information, refer to the sudo(8) man page and ``env_keep`` in
|
||||
the sudoers(5) man page.
|
||||
|
||||
.. Tip::
|
||||
To debug what your borg process is actually seeing, find its PID
|
||||
To debug what your borg process sees, find its PID
|
||||
(``ps aux|grep borg``) and then look into ``/proc/<PID>/environ``.
|
||||
|
||||
.. passphrase_notes:
|
||||
@ -278,7 +278,7 @@ Borg is technically able to process all unicode text, but you might get into
|
||||
trouble reproducing the same encoded utf-8 bytes or with keyboard layouts,
|
||||
so better just avoid non-ASCII stuff.
|
||||
|
||||
If you want to automate, you can alternatively supply the passphrase
|
||||
Alternatively, if you want to automate, you can supply the passphrase
|
||||
directly or indirectly using some environment variables.
|
||||
|
||||
You can directly give a passphrase::
|
||||
|
@ -132,7 +132,7 @@ of CPU cores.
|
||||
|
||||
When the daemonized process receives a signal or crashes, it does not unmount.
|
||||
Unmounting in these cases could cause an active rsync or similar process
|
||||
to unintentionally delete data.
|
||||
to delete data unintentionally.
|
||||
|
||||
When running in the foreground ^C/SIGINT unmounts cleanly, but other
|
||||
signals or crashes do not.
|
@ -4,30 +4,30 @@ Examples
|
||||
~~~~~~~~
|
||||
::
|
||||
|
||||
# Back up ~/Documents into an archive named "my-documents"
|
||||
# Backup ~/Documents into an archive named "my-documents"
|
||||
$ borg create my-documents ~/Documents
|
||||
|
||||
# same, but list all files as we process them
|
||||
$ borg create --list my-documents ~/Documents
|
||||
|
||||
# Back up ~/Documents and ~/src but exclude pyc files
|
||||
# Backup ~/Documents and ~/src but exclude pyc files
|
||||
$ borg create my-files \
|
||||
~/Documents \
|
||||
~/src \
|
||||
--exclude '*.pyc'
|
||||
|
||||
# Back up home directories excluding image thumbnails (i.e. only
|
||||
# Backup home directories excluding image thumbnails (i.e. only
|
||||
# /home/<one directory>/.thumbnails is excluded, not /home/*/*/.thumbnails etc.)
|
||||
$ borg create my-files /home --exclude 'sh:home/*/.thumbnails'
|
||||
|
||||
# Back up the root filesystem into an archive named "root-YYYY-MM-DD"
|
||||
# Backup the root filesystem into an archive named "root-YYYY-MM-DD"
|
||||
# use zlib compression (good, but slow) - default is lz4 (fast, low compression ratio)
|
||||
$ borg create -C zlib,6 --one-file-system root-{now:%Y-%m-%d} /
|
||||
|
||||
# Back up into an archive name like FQDN-root-TIMESTAMP
|
||||
# Backup into an archive name like FQDN-root-TIMESTAMP
|
||||
$ borg create '{fqdn}-root-{now}' /
|
||||
|
||||
# Back up a remote host locally ("pull" style) using sshfs
|
||||
# Backup a remote host locally ("pull" style) using sshfs
|
||||
$ mkdir sshfs-mount
|
||||
$ sshfs root@example.com:/ sshfs-mount
|
||||
$ cd sshfs-mount
|
||||
@ -40,10 +40,10 @@ Examples
|
||||
# docs - same parameters as borg < 1.0):
|
||||
$ borg create --chunker-params buzhash,10,23,16,4095 small /smallstuff
|
||||
|
||||
# Back up a raw device (must not be active/in use/mounted at that time)
|
||||
# Backup a raw device (must not be active/in use/mounted at that time)
|
||||
$ borg create --read-special --chunker-params fixed,4194304 my-sdx /dev/sdX
|
||||
|
||||
# Back up a sparse disk image (must not be active/in use/mounted at that time)
|
||||
# Backup a sparse disk image (must not be active/in use/mounted at that time)
|
||||
$ borg create --sparse --chunker-params fixed,4194304 my-disk my-disk.raw
|
||||
|
||||
# No compression (none)
|
||||
@ -76,7 +76,7 @@ Examples
|
||||
# Use external command to determine files to archive
|
||||
# Use --paths-from-stdin with find to back up only files less than 1MB in size
|
||||
$ find ~ -size -1000k | borg create --paths-from-stdin small-files-only
|
||||
# Use --paths-from-command with find to back up files only from a given user
|
||||
# Use --paths-from-command with find to back up files from only a given user
|
||||
$ borg create --paths-from-command joes-files -- find /srv/samba/shared -user joe
|
||||
# Use --paths-from-stdin with --paths-delimiter (for example, for filenames with newlines in them)
|
||||
$ find ~ -size -1000k -print0 | borg create \
|
||||
|
@ -33,14 +33,14 @@ General:
|
||||
When set, use the value to answer the passphrase question when a **new** passphrase is asked for.
|
||||
This variable is checked first. If it is not set, BORG_PASSPHRASE and BORG_PASSCOMMAND will also
|
||||
be checked.
|
||||
Main usecase for this is to fully automate ``borg change-passphrase``.
|
||||
Main usecase for this is to automate fully ``borg change-passphrase``.
|
||||
BORG_DISPLAY_PASSPHRASE
|
||||
When set, use the value to answer the "display the passphrase for verification" question when defining a new passphrase for encrypted repositories.
|
||||
BORG_HOST_ID
|
||||
Borg usually computes a host id from the FQDN plus the results of ``uuid.getnode()`` (which usually returns
|
||||
a unique id based on the MAC address of the network interface. Except if that MAC happens to be all-zero - in
|
||||
that case it returns a random value, which is not what we want (because it kills automatic stale lock removal).
|
||||
So, if you have a all-zero MAC address or other reasons to better externally control the host id, just set this
|
||||
So, if you have a all-zero MAC address or other reasons to control better externally the host id, just set this
|
||||
environment variable to a unique value. If all your FQDNs are unique, you can just use the FQDN. If not,
|
||||
use fqdn@uniqueid.
|
||||
BORG_LOCK_WAIT
|
||||
@ -62,7 +62,7 @@ General:
|
||||
cache entries for backup sources other than the current sources.
|
||||
BORG_FILES_CACHE_TTL
|
||||
When set to a numeric value, this determines the maximum "time to live" for the files cache
|
||||
entries (default: 20). The files cache is used to quickly determine whether a file is unchanged.
|
||||
entries (default: 20). The files cache is used to determine quickly whether a file is unchanged.
|
||||
The FAQ explains this more detailed in: :ref:`always_chunking`
|
||||
BORG_SHOW_SYSINFO
|
||||
When set to no (default: yes), system information (like OS, Python version, ...) in
|
||||
@ -112,7 +112,7 @@ Some automatic "answerers" (if set, they automatically answer confirmation quest
|
||||
BORG_CHECK_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
|
||||
For "This is a potentially dangerous function..." (check --repair)
|
||||
BORG_DELETE_I_KNOW_WHAT_I_AM_DOING=NO (or =YES)
|
||||
For "You requested to completely DELETE the repository *including* all archives it contains:"
|
||||
For "You requested to DELETE the repository completely *including* all archives it contains:"
|
||||
|
||||
Note: answers are case sensitive. setting an invalid answer value might either give the default
|
||||
answer or ask you interactively, depending on whether retries are allowed (they by default are
|
||||
|
@ -49,5 +49,5 @@ borgfs
|
||||
|
||||
``borgfs`` will be automatically provided if you used a distribution
|
||||
package, ``pip`` or ``setup.py`` to install Borg. Users of the
|
||||
standalone binary will have to manually create a symlink (see
|
||||
standalone binary will have to create a symlink manually (see
|
||||
:ref:`pyinstaller-binary`).
|
||||
|
@ -152,7 +152,7 @@ of CPU cores.
|
||||
|
||||
When the daemonized process receives a signal or crashes, it does not unmount.
|
||||
Unmounting in these cases could cause an active rsync or similar process
|
||||
to unintentionally delete data.
|
||||
to delete data unintentionally.
|
||||
|
||||
When running in the foreground ^C/SIGINT unmounts cleanly, but other
|
||||
signals or crashes do not.
|
@ -309,8 +309,8 @@ operation on an append-only repository to catch accidental or malicious corrupti
|
||||
# run without append-only mode
|
||||
borg check --verify-data && borg compact
|
||||
|
||||
Aside from checking repository & archive integrity you may want to also manually check
|
||||
backups to ensure their content seems correct.
|
||||
Aside from checking repository & archive integrity you may also want to check
|
||||
backups manually to ensure their content seems correct.
|
||||
|
||||
Further considerations
|
||||
++++++++++++++++++++++
|
||||
|
@ -6,7 +6,7 @@ Examples
|
||||
|
||||
# delete the whole repository and the related local cache:
|
||||
$ borg rdelete
|
||||
You requested to completely DELETE the repository *including* all archives it contains:
|
||||
You requested to DELETE the repository completely *including* all archives it contains:
|
||||
repo Mon, 2016-02-15 19:26:54
|
||||
root-2016-02-15 Mon, 2016-02-15 19:36:29
|
||||
newname Mon, 2016-02-15 19:50:19
|
||||
|
@ -67,7 +67,7 @@ borg recreate
|
||||
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
|
||||
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--recompress MODE`` | recompress data chunks according to `MODE` and ``--compression``. Possible modes are `if-different`: recompress if current compression is with a different compression algorithm or different level; `always`: recompress unconditionally; and `never`: do not recompress (use this option to explicitly prevent recompression). If no MODE is given, `if-different` will be used. Not passing --recompress is equivalent to "--recompress never". |
|
||||
| | ``--recompress MODE`` | recompress data chunks according to `MODE` and ``--compression``. Possible modes are `if-different`: recompress if current compression is with a different compression algorithm or different level; `always`: recompress unconditionally; and `never`: do not recompress (use this option explicitly to prevent recompression). If no MODE is given, `if-different` will be used. Not passing --recompress is equivalent to "--recompress never". |
|
||||
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--chunker-params PARAMS`` | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. default: buzhash,19,23,21,4095 |
|
||||
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
@ -116,7 +116,7 @@ borg recreate
|
||||
--comment COMMENT add a comment text to the archive
|
||||
--timestamp TIMESTAMP manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory.
|
||||
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details.
|
||||
--recompress MODE recompress data chunks according to `MODE` and ``--compression``. Possible modes are `if-different`: recompress if current compression is with a different compression algorithm or different level; `always`: recompress unconditionally; and `never`: do not recompress (use this option to explicitly prevent recompression). If no MODE is given, `if-different` will be used. Not passing --recompress is equivalent to "--recompress never".
|
||||
--recompress MODE recompress data chunks according to `MODE` and ``--compression``. Possible modes are `if-different`: recompress if current compression is with a different compression algorithm or different level; `always`: recompress unconditionally; and `never`: do not recompress (use this option explicitly to prevent recompression). If no MODE is given, `if-different` will be used. Not passing --recompress is equivalent to "--recompress never".
|
||||
--chunker-params PARAMS specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. default: buzhash,19,23,21,4095
|
||||
|
||||
|
||||
@ -147,8 +147,8 @@ There is no risk of data loss by this.
|
||||
used to have upgraded Borg 0.xx archives deduplicate with Borg 1.x archives.
|
||||
|
||||
**USE WITH CAUTION.**
|
||||
Depending on the PATHs and patterns given, recreate can be used to permanently
|
||||
delete files from archives.
|
||||
Depending on the PATHs and patterns given, recreate can be used to
|
||||
delete files from archives permanently.
|
||||
When in doubt, use ``--dry-run --verbose --list`` to see how patterns/PATHS are
|
||||
interpreted. See :ref:`list_item_flags` in ``borg create`` for details.
|
||||
|
||||
|
@ -21,7 +21,7 @@ locations like ``/etc/environment`` or in the forced command itself (example bel
|
||||
|
||||
::
|
||||
|
||||
# Allow an SSH keypair to only run borg, and only have access to /path/to/repo.
|
||||
# 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.
|
||||
$ cat ~/.ssh/authorized_keys
|
||||
@ -36,7 +36,7 @@ locations like ``/etc/environment`` or in the forced command itself (example bel
|
||||
block potential 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
|
||||
If you're using openssh-server < 7.2, however, you have to specify explicitly
|
||||
the ssh features to restrict and cannot simply use the restrict option as it
|
||||
has been introduced in v7.2. We recommend to use
|
||||
``no-port-forwarding,no-X11-forwarding,no-pty,no-agent-forwarding,no-user-rc``
|
||||
|
@ -15,9 +15,9 @@ borg serve
|
||||
+-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| **options** |
|
||||
+-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--restrict-to-path PATH`` | restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to directly point to a repository. |
|
||||
| | ``--restrict-to-path PATH`` | restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to point directly to a repository. |
|
||||
+-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--restrict-to-repository PATH`` | restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there. |
|
||||
| | ``--restrict-to-repository PATH`` | restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to point directly at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there. |
|
||||
+-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| | ``--append-only`` | only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details. |
|
||||
+-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
@ -41,8 +41,8 @@ borg serve
|
||||
|
||||
|
||||
options
|
||||
--restrict-to-path PATH restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to directly point to a repository.
|
||||
--restrict-to-repository PATH restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
|
||||
--restrict-to-path PATH restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to point directly to a repository.
|
||||
--restrict-to-repository PATH restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to point directly at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
|
||||
--append-only only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details.
|
||||
--storage-quota QUOTA Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository is initialized, sets the storage quota on the new repository as well. Default: no quota.
|
||||
|
||||
|
@ -51,8 +51,8 @@ exe = EXE(pyz,
|
||||
console=True)
|
||||
|
||||
# Build a directory-based binary in addition to a packed
|
||||
# single file. This allows one to easily look at all included
|
||||
# files (e.g. without having to strace or halt the built binary
|
||||
# single file. This allows one to look at all included
|
||||
# files easily (e.g. without having to strace or halt the built binary
|
||||
# and introspect /tmp). Also avoids unpacking all libs when
|
||||
# running the app, which is better for app signing on various OS.
|
||||
slim_exe = EXE(pyz,
|
||||
|
@ -556,7 +556,7 @@ _borg-recreate() {
|
||||
local -a mods=(
|
||||
'if-different:recompress if current compression is with a different compression algorithm (the level is not considered)'
|
||||
'always:recompress even if current compression is with the same compression algorithm (use this to change the compression level)'
|
||||
'never:do not recompress (use this option to explicitly prevent recompression)'
|
||||
'never:do not recompress (use this option explicitly to prevent recompression)'
|
||||
)
|
||||
mods=( ${(q)mods//\\/\\\\} )
|
||||
mods=( ${mods//:/\\:} )
|
||||
|
2
setup.py
2
setup.py
@ -40,7 +40,7 @@
|
||||
# Are we building on ReadTheDocs?
|
||||
on_rtd = os.environ.get("READTHEDOCS")
|
||||
|
||||
# Extra cflags for all extensions, usually just warnings we want to explicitly enable
|
||||
# Extra cflags for all extensions, usually just warnings we want to enable explicitly
|
||||
cflags = ["-Wall", "-Wextra", "-Wpointer-arith"]
|
||||
|
||||
compress_source = "src/borg/compress.pyx"
|
||||
|
@ -105,7 +105,7 @@ def build_parser_mount_umount(self, subparsers, common_parser, mid_common_parser
|
||||
|
||||
When the daemonized process receives a signal or crashes, it does not unmount.
|
||||
Unmounting in these cases could cause an active rsync or similar process
|
||||
to unintentionally delete data.
|
||||
to delete data unintentionally.
|
||||
|
||||
When running in the foreground ^C/SIGINT unmounts cleanly, but other
|
||||
signals or crashes do not.
|
||||
|
@ -31,13 +31,13 @@ def do_rdelete(self, args, repository):
|
||||
manifest = Manifest.load(repository, Manifest.NO_OPERATION_CHECK)
|
||||
n_archives = len(manifest.archives)
|
||||
msg.append(
|
||||
f"You requested to completely DELETE the following repository "
|
||||
f"You requested to DELETE the following repository completely "
|
||||
f"*including* {n_archives} archives it contains:"
|
||||
)
|
||||
except NoManifestError:
|
||||
n_archives = None
|
||||
msg.append(
|
||||
"You requested to completely DELETE the following repository "
|
||||
"You requested to DELETE the following repository completely "
|
||||
"*including* all archives it may contain:"
|
||||
)
|
||||
|
||||
|
@ -89,8 +89,8 @@ def build_parser_recreate(self, subparsers, common_parser, mid_common_parser):
|
||||
used to have upgraded Borg 0.xx archives deduplicate with Borg 1.x archives.
|
||||
|
||||
**USE WITH CAUTION.**
|
||||
Depending on the PATHs and patterns given, recreate can be used to permanently
|
||||
delete files from archives.
|
||||
Depending on the PATHs and patterns given, recreate can be used to
|
||||
delete files from archives permanently.
|
||||
When in doubt, use ``--dry-run --verbose --list`` to see how patterns/PATHS are
|
||||
interpreted. See :ref:`list_item_flags` in ``borg create`` for details.
|
||||
|
||||
@ -199,7 +199,7 @@ def build_parser_recreate(self, subparsers, common_parser, mid_common_parser):
|
||||
"`if-different`: recompress if current compression is with a different "
|
||||
"compression algorithm or different level; "
|
||||
"`always`: recompress unconditionally; and "
|
||||
"`never`: do not recompress (use this option to explicitly prevent "
|
||||
"`never`: do not recompress (use this option explicitly to prevent "
|
||||
"recompression). "
|
||||
"If no MODE is given, `if-different` will be used. "
|
||||
'Not passing --recompress is equivalent to "--recompress never".',
|
||||
|
@ -46,7 +46,7 @@ def build_parser_serve(self, subparsers, common_parser, mid_common_parser):
|
||||
action="append",
|
||||
help="restrict repository access to PATH. "
|
||||
"Can be specified multiple times to allow the client access to several directories. "
|
||||
"Access to all sub-directories is granted implicitly; PATH doesn't need to directly point to a repository.",
|
||||
"Access to all sub-directories is granted implicitly; PATH doesn't need to point directly to a repository.",
|
||||
)
|
||||
subparser.add_argument(
|
||||
"--restrict-to-repository",
|
||||
@ -57,7 +57,7 @@ def build_parser_serve(self, subparsers, common_parser, mid_common_parser):
|
||||
"(no sub-directories are considered) is accessible. "
|
||||
"Can be specified multiple times to allow the client access to several repositories. "
|
||||
"Unlike ``--restrict-to-path`` sub-directories are not accessible; "
|
||||
"PATH needs to directly point at a repository location. "
|
||||
"PATH needs to point directly at a repository location. "
|
||||
"PATH may be an empty directory or the last element of PATH may not exist, in which case "
|
||||
"the client may initialize a repository there.",
|
||||
)
|
||||
|
@ -135,9 +135,9 @@ class ChunkerFixed:
|
||||
It optionally supports:
|
||||
|
||||
- a header block of different size
|
||||
- using a sparsemap to only read data ranges and seek over hole ranges
|
||||
- using a sparsemap to read only data ranges and seek over hole ranges
|
||||
for sparse files.
|
||||
- using an externally given filemap to only read specific ranges from
|
||||
- using an externally given filemap to read only specific ranges from
|
||||
a file.
|
||||
|
||||
Note: the last block of a data or hole range may be less than the block size,
|
||||
@ -231,7 +231,7 @@ cdef class Chunker:
|
||||
"""
|
||||
Content-Defined Chunker, variable chunk sizes.
|
||||
|
||||
This chunker does quite some effort to mostly cut the same-content chunks, even if
|
||||
This chunker makes quite some effort to cut mostly chunks of the same-content, even if
|
||||
the content moves to a different offset inside the file. It uses the buzhash
|
||||
rolling-hash algorithm to identify the chunk cutting places by looking at the
|
||||
content inside the moving window and computing the rolling hash value over the
|
||||
|
@ -261,7 +261,7 @@ def scandir_inorder(*, path, fd=None):
|
||||
|
||||
|
||||
def secure_erase(path, *, avoid_collateral_damage):
|
||||
"""Attempt to securely erase a file by writing random data over it before deleting it.
|
||||
"""Attempt to erase a file securely by writing random data over it before deleting it.
|
||||
|
||||
If avoid_collateral_damage is True, we only secure erase if the total link count is 1,
|
||||
otherwise we just do a normal "delete" (unlink) without first overwriting it with random.
|
||||
|
@ -211,7 +211,7 @@ def action_done(self):
|
||||
|
||||
def action_completed(self):
|
||||
# this must be called when the action triggered is completed,
|
||||
# to avoid that the action is repeatedly triggered.
|
||||
# to avoid repeatedly triggering the action.
|
||||
self._action_triggered = False
|
||||
self._action_done = True
|
||||
|
||||
@ -242,7 +242,7 @@ def ignore_sigint():
|
||||
|
||||
Ctrl-C will send a SIGINT to both the main process (borg) and subprocesses
|
||||
(e.g. ssh for remote ssh:// repos), but often we do not want the subprocess
|
||||
getting killed (e.g. because it is still needed to cleanly shut down borg).
|
||||
getting killed (e.g. because it is still needed to shut down borg cleanly).
|
||||
|
||||
To avoid that: Popen(..., preexec_fn=ignore_sigint)
|
||||
"""
|
||||
|
@ -328,8 +328,8 @@ def modify(self, key, op):
|
||||
def migrate_lock(self, key, old_id, new_id):
|
||||
"""migrate the lock ownership from old_id to new_id"""
|
||||
assert self.id == old_id
|
||||
# need to temporarily switch off stale lock killing as we want to
|
||||
# rather migrate than kill them (at least the one made by old_id).
|
||||
# need to switch off stale lock killing temporarily as we want to
|
||||
# migrate rather than kill them (at least the one made by old_id).
|
||||
killing, self.kill_stale_locks = self.kill_stale_locks, False
|
||||
try:
|
||||
try:
|
||||
|
@ -152,7 +152,7 @@ class Operation(enum.Enum):
|
||||
# behaviours are known when introducing new features sometimes this might not match the general descriptions
|
||||
# below.
|
||||
|
||||
# The READ operation describes which features are needed to safely list and extract the archives in the
|
||||
# The READ operation describes which features are needed to list and extract the archives safely in the
|
||||
# repository.
|
||||
READ = "read"
|
||||
# The CHECK operation is for all operations that need either to understand every detail
|
||||
|
@ -36,7 +36,7 @@ def swidth(s):
|
||||
|
||||
def process_alive(host, pid, thread):
|
||||
"""
|
||||
Check if the (host, pid, thread_id) combination corresponds to a potentially alive process.
|
||||
Check whether the (host, pid, thread_id) combination corresponds to a process potentially alive.
|
||||
|
||||
If the process is local, then this will be accurate. If the process is not local, then this
|
||||
returns always True, since there is no real way to check.
|
||||
|
@ -41,7 +41,7 @@ def getosusername():
|
||||
|
||||
def process_alive(host, pid, thread):
|
||||
"""
|
||||
Check if the (host, pid, thread_id) combination corresponds to a potentially alive process.
|
||||
Check whether the (host, pid, thread_id) combination corresponds to a process potentially alive.
|
||||
"""
|
||||
if host.split('@')[0].lower() != platform.node().lower():
|
||||
# Not running on the same node, assume running.
|
||||
|
@ -669,7 +669,7 @@ def __exit__(self, exc_type, exc_val, exc_tb):
|
||||
self.shutdown_time = time.monotonic() + 30
|
||||
self.rollback()
|
||||
finally:
|
||||
# in any case, we want to cleanly close the repo, even if the
|
||||
# in any case, we want to close the repo cleanly, even if the
|
||||
# rollback can not succeed (e.g. because the connection was
|
||||
# already closed) and raised another exception:
|
||||
logger.debug(
|
||||
|
@ -56,7 +56,7 @@ def format(
|
||||
return hdr + meta_encrypted + data_encrypted
|
||||
|
||||
def parse_meta(self, id: bytes, cdata: bytes) -> dict:
|
||||
# when calling parse_meta, enough cdata needs to be supplied to completely contain the
|
||||
# when calling parse_meta, enough cdata needs to be supplied to contain completely the
|
||||
# meta_len_hdr and the encrypted, packed metadata. it is allowed to provide more cdata.
|
||||
assert isinstance(id, bytes)
|
||||
assert isinstance(cdata, bytes)
|
||||
|
@ -328,7 +328,7 @@ def save_config(self, path, config):
|
||||
|
||||
if os.path.isfile(config_path):
|
||||
link_error_msg = (
|
||||
"Failed to securely erase old repository config file (hardlinks not supported). "
|
||||
"Failed to erase old repository config file securely (hardlinks not supported). "
|
||||
"Old repokey data, if any, might persist on physical storage."
|
||||
)
|
||||
try:
|
||||
@ -429,7 +429,7 @@ def check_transaction(self):
|
||||
# valid (committed) state of the repo which we could use.
|
||||
msg = '%s" - although likely this is "beyond repair' % self.path # dirty hack
|
||||
raise self.CheckNeeded(msg)
|
||||
# Attempt to automatically rebuild index if we crashed between commit
|
||||
# Attempt to rebuild index automatically if we crashed between commit
|
||||
# tag write and index save.
|
||||
if index_transaction_id != segments_transaction_id:
|
||||
if index_transaction_id is not None and index_transaction_id > segments_transaction_id:
|
||||
@ -719,7 +719,7 @@ def rename_tmp(file):
|
||||
self.index = None
|
||||
|
||||
def check_free_space(self):
|
||||
"""Pre-commit check for sufficient free space to actually perform the commit."""
|
||||
"""Pre-commit check for sufficient free space necessary to perform the commit."""
|
||||
# As a baseline we take four times the current (on-disk) index size.
|
||||
# At this point the index may only be updated by compaction, which won't resize it.
|
||||
# We still apply a factor of four so that a later, separate invocation can free space
|
||||
@ -734,7 +734,7 @@ def check_free_space(self):
|
||||
# 10 bytes for each segment-refcount pair, 10 bytes for each segment-space pair
|
||||
# Assume maximum of 5 bytes per integer. Segment numbers will usually be packed more densely (1-3 bytes),
|
||||
# as will refcounts and free space integers. For 5 MiB segments this estimate is good to ~20 PB repo size.
|
||||
# Add 4K to generously account for constant format overhead.
|
||||
# Add a generous 4K to account for constant format overhead.
|
||||
hints_size = len(self.segments) * 10 + len(self.compact) * 10 + 4096
|
||||
required_free_space += hints_size
|
||||
|
||||
@ -1238,7 +1238,7 @@ def scan(self, limit=None, state=None):
|
||||
# smallest valid seg is <uint32> 0, smallest valid offs is <uint32> 8
|
||||
start_segment, start_offset, end_segment = state if state is not None else (0, 0, transaction_id)
|
||||
ids, segment, offset = [], 0, 0
|
||||
# we only scan up to end_segment == transaction_id to only scan **committed** chunks,
|
||||
# we only scan up to end_segment == transaction_id to scan only **committed** chunks,
|
||||
# avoiding scanning into newly written chunks.
|
||||
for segment, filename in self.io.segment_iterator(start_segment, end_segment):
|
||||
# the start_offset we potentially got from state is only valid for the start_segment we also got
|
||||
|
@ -65,7 +65,7 @@ def exec_cmd(*args, archiver=None, fork=False, exe=None, input=b"", binary_outpu
|
||||
sys.stdin = StringIO(input.decode())
|
||||
sys.stdin.buffer = BytesIO(input)
|
||||
output = BytesIO()
|
||||
# Always use utf-8 here, to simply .decode() below
|
||||
# Always use utf-8 here, to .decode() below
|
||||
output_text = sys.stdout = sys.stderr = io.TextIOWrapper(output, encoding="utf-8")
|
||||
if archiver is None:
|
||||
archiver = Archiver()
|
||||
|
@ -113,7 +113,7 @@ def test_readonly_mount(self):
|
||||
pass
|
||||
else:
|
||||
with pytest.raises((LockFailed, RemoteRepository.RPCError)) as excinfo:
|
||||
# self.fuse_mount always assumes fork=True, so for this test we have to manually set fork=False
|
||||
# self.fuse_mount always assumes fork=True, so for this test we have to set fork=False manually
|
||||
with self.fuse_mount(self.repository_location, fork=False):
|
||||
pass
|
||||
if isinstance(excinfo.value, RemoteRepository.RPCError):
|
||||
|
@ -436,7 +436,7 @@ def test_extract_pattern_opt(self):
|
||||
def test_extract_capabilities(self):
|
||||
fchown = os.fchown
|
||||
|
||||
# We need to manually patch chown to get the behaviour Linux has, since fakeroot does not
|
||||
# We need to patch chown manually to get the behaviour Linux has, since fakeroot does not
|
||||
# accurately model the interaction of chown(2) and Linux capabilities, i.e. it does not remove them.
|
||||
def patched_fchown(fd, uid, gid):
|
||||
xattr.setxattr(fd, b"security.capability", b"", follow_symlinks=False)
|
||||
|
Loading…
Reference in New Issue
Block a user