mirror
/
borg
mirror of https://github.com/borgbackup/borg.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Merge pull request #568 from ypid/docs-fixes 

Docs fixes.
This commit is contained in:
TW 2016-01-18 11:02:13 +01:00
parent 1878e223d6 32900c8679
commit f2f2810b5a
9 changed files with 45 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.rst
View File

@ -165,7 +165,7 @@ for the complete license.
.. |doc| image:: https://readthedocs.org/projects/borgbackup/badge/?version=stable
:alt: Documentation
:target: http://borgbackup.readthedocs.org/en/stable/
:target: https://borgbackup.readthedocs.org/en/stable/
.. |build| image:: https://travis-ci.org/borgbackup/borg.svg
:alt: Build Status

2
borg/archiver.py
View File

@ -470,7 +470,7 @@ class Archiver:
manifest, key = Manifest.load(repository)
archives = manifest.list_archive_infos(sort_by='ts', reverse=True) # just a ArchiveInfo list
if args.hourly + args.daily + args.weekly + args.monthly + args.yearly == 0 and args.within is None:
self.print_error('At least one of the "within", "keep-hourly", "keep-daily", "keep-weekly", '
self.print_error('At least one of the "keep-within", "keep-hourly", "keep-daily", "keep-weekly", '
'"keep-monthly" or "keep-yearly" settings must be specified')
return self.exit_code
if args.prefix:

2
borg/testsuite/archiver.py
View File

@ -769,7 +769,7 @@ class ArchiverTestCase(ArchiverTestCaseBase):
output = self.cmd('create', '-v', '--list', self.repository_location + '::test1', 'input')
self.assert_in("U input/file1", output)
# this is expected, although surprising, for why, see:
# http://borgbackup.readthedocs.org/en/latest/faq.html#i-am-seeing-a-added-status-for-a-unchanged-file
# https://borgbackup.readthedocs.org/en/latest/faq.html#i-am-seeing-a-added-status-for-a-unchanged-file
self.assert_in("A input/file2", output)
def test_create_topical(self):

8
docs/deployment.rst
View File

@ -73,8 +73,10 @@ The options which are added to the key will perform the following:
3. Run ``borg serve`` restricted at the client base path
4. 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 so the client will not need to append the hostname to the remote URI.
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
or relative remote repository path and can directly access the repositories at
``<user>@<host>:<repo>``.
.. note:: The setup above ignores all client given commandline parameters
which are normally appended to the `borg serve` command.
@ -161,4 +163,4 @@ See also
--------
* `SSH Daemon manpage <http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man8/sshd.8>`_
* `Ansible <http://docs.ansible.com>`_
* `Ansible <https://docs.ansible.com>`_

8
docs/faq.rst
View File

@ -67,14 +67,14 @@ adjust the level or algorithm).
|project_name| offers a lot of different compression algorithms and
levels. Which of them is the best for you pretty much depends on your
use case, your data, your hardware - so you need to do an informed
use case, your data, your hardware -- so you need to do an informed
decision about whether you want to use compression, which algorithm
and which level you want to use. This is why compression defaults to
none.
How can I specify the encryption passphrase programmatically?
-------------------------------------------------------------
The encryption passphrase can be specified programmatically using the
`BORG_PASSPHRASE` environment variable. This is convenient when setting up
automated encrypted backups. Another option is to use
@ -89,11 +89,11 @@ key file based encryption with a blank passphrase. See
``export`` in a shell script file should be safe, however, as
the environment of a process is `accessible only to that
user
<http://security.stackexchange.com/questions/14000/environment-variable-accessibility-in-linux/14009#14009>`_.
<https://security.stackexchange.com/questions/14000/environment-variable-accessibility-in-linux/14009#14009>`_.
When backing up to remote encrypted repos, is encryption done locally?
----------------------------------------------------------------------
Yes, file and directory metadata and data is locally encrypted, before
leaving the local machine. We do not mean the transport layer encryption
by that, but the data/metadata itself. Transport layer encryption (e.g.

10
docs/global.rst.inc
View File

@ -8,17 +8,17 @@
.. _issue tracker: https://github.com/borgbackup/borg/issues
.. _deduplication: https://en.wikipedia.org/wiki/Data_deduplication
.. _AES: https://en.wikipedia.org/wiki/Advanced_Encryption_Standard
.. _HMAC-SHA256: http://en.wikipedia.org/wiki/HMAC
.. _HMAC-SHA256: https://en.wikipedia.org/wiki/HMAC
.. _SHA256: https://en.wikipedia.org/wiki/SHA-256
.. _PBKDF2: https://en.wikipedia.org/wiki/PBKDF2
.. _ACL: https://en.wikipedia.org/wiki/Access_control_list
.. _libacl: http://savannah.nongnu.org/projects/acl/
.. _libattr: http://savannah.nongnu.org/projects/attr/
.. _libacl: https://savannah.nongnu.org/projects/acl/
.. _libattr: https://savannah.nongnu.org/projects/attr/
.. _liblz4: https://github.com/Cyan4973/lz4
.. _OpenSSL: https://www.openssl.org/
.. _`Python 3`: http://www.python.org/
.. _`Python 3`: https://www.python.org/
.. _Buzhash: https://en.wikipedia.org/wiki/Buzhash
.. _msgpack: http://msgpack.org/
.. _msgpack: https://msgpack.org/
.. _`msgpack-python`: https://pypi.python.org/pypi/msgpack-python/
.. _llfuse: https://pypi.python.org/pypi/llfuse/
.. _homebrew: http://brew.sh/

21
docs/internals.rst
View File

@ -207,7 +207,7 @@ The |project_name| chunker uses a rolling hash computed by the Buzhash_ algorith
It triggers (chunks) when the last HASH_MASK_BITS bits of the hash are zero,
producing chunks of 2^HASH_MASK_BITS Bytes on average.
create --chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE
``borg create --chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE``
can be used to tune the chunker parameters, the default is:
- CHUNK_MIN_EXP = 10 (minimum chunk size = 2^10 B = 1 kiB)
@ -220,7 +220,7 @@ for the archive, and stored encrypted in the keyfile. This is to prevent chunk
size based fingerprinting attacks on your encrypted repo contents (to guess
what files you have based on a specific set of chunk sizes).
For some more general usage hints see also `--chunker-params`.
For some more general usage hints see also ``--chunker-params``.
Indexes / Caches
@ -311,28 +311,27 @@ more chunks than estimated above, because 1 file is at least 1 chunk).
If a remote repository is used the repo index will be allocated on the remote side.
E.g. backing up a total count of 1Mi files with a total size of 1TiB.
E.g. backing up a total count of 1 Mi (IEC binary prefix e.g. 2^20) files with a total size of 1TiB.
a) with create --chunker-params 10,23,16,4095 (default):
a) with create ``--chunker-params 10,23,16,4095`` (default):
mem_usage = 2.8GiB
b) with create --chunker-params 10,23,20,4095 (custom):
b) with create ``--chunker-params 10,23,20,4095`` (custom):
mem_usage = 0.4GiB
Note: there is also the --no-files-cache option to switch off the files cache.
You'll save some memory, but it will need to read / chunk all the files then as
it can not skip unmodified files then.
.. note:: There is also the ``--no-files-cache`` option to switch off the files cache.
You'll save some memory, but it will need to read / chunk all the files as
it can not skip unmodified files then.
Encryption
----------
AES_ is used in CTR mode (so no need for padding). A 64bit initialization
AES_-256 is used in CTR mode (so no need for padding). A 64bit initialization
vector is used, a `HMAC-SHA256`_ is computed on the encrypted chunk with a
random 64bit nonce and both are stored in the chunk.
The header of each chunk is : ``TYPE(1)`` + ``HMAC(32)`` + ``NONCE(8)`` + ``CIPHERTEXT``.
The header of each chunk is: ``TYPE(1)`` + ``HMAC(32)`` + ``NONCE(8)`` + ``CIPHERTEXT``.
Encryption and HMAC use two different keys.
In AES CTR mode you can think of the IV as the start value for the counter.

2
docs/quickstart.rst
View File

@ -17,7 +17,7 @@ a good amount of free space on the filesystem that has your backup repository
If you run out of disk space, it can be hard or impossible to free space,
because |project_name| needs free space to operate - even to delete backup
archives. There is a `--save-space` option for some commands, but even with
archives. There is a ``--save-space`` option for some commands, but even with
that |project_name| will need free space to operate.
You can use some monitoring process or just include the free space information

33
docs/usage.rst
View File

@ -18,9 +18,9 @@ The log level of the builtin logging configuration defaults to WARNING.
This is because we want |project_name| to be mostly silent and only output
warnings (plus errors and critical messages).
Use --verbose or --info to set INFO (you will get informative output then
Use ``--verbose`` or ``--info`` to set INFO (you will get informative output then
additionally to warnings, errors, critical messages).
Use --debug to set DEBUG to get output made for debugging.
Use ``--debug`` to set DEBUG to get output made for debugging.
All log messages created with at least the set level will be output.
@ -29,9 +29,9 @@ Log levels: DEBUG < INFO < WARNING < ERROR < CRITICAL
While you can set misc. log levels, do not expect that every command will
give different output on different log levels - it's just a possibility.
..warning:: While some options (like --stats or --list) will emit more
.. warning:: While some options (like ``--stats`` or ``--list``) will emit more
informational messages, you have to use INFO (or lower) log level to make
them show up in log output. Use `-v` or a logging configuration.
them show up in log output. Use ``-v`` or a logging configuration.
Return codes
~~~~~~~~~~~~
@ -75,7 +75,7 @@ Some "yes" sayers (if set, they automatically confirm that you really want to do
BORG_RELOCATED_REPO_ACCESS_IS_OK
For "Warning: The repository at location ... was previously located at ..."
BORG_CHECK_I_KNOW_WHAT_I_AM_DOING
For "Warning: 'check --repair' is an experimental feature that might result in data loss."
For "Warning: '``check --repair``' is an experimental feature that might result in data loss."
BORG_DELETE_I_KNOW_WHAT_I_AM_DOING
For "You requested to completely DELETE the repository *including* all archives it contains: "
@ -334,11 +334,11 @@ Be careful, prune is 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 `--prefix`.
When using --prefix, be careful to choose a good prefix - e.g. do not use a
you restrict its operation to a subset of the archives using ``--prefix``.
When using ``--prefix``, be careful to choose a good prefix - e.g. do not use a
prefix "foo" if you do not also want to match "foobar".
It is strongly recommended to always run `prune --dry-run ...` first so you
It is strongly recommended to always run ``prune --dry-run ...`` first so you
will see what it would do without it actually doing anything.
::
@ -457,17 +457,17 @@ Here are misc. notes about topics that are maybe not covered in enough detail in
Item flags
~~~~~~~~~~
`borg create -v --list` outputs a verbose list of all files, directories and other
``borg create -v --list`` outputs a verbose list of all files, directories and other
file system items it considered (no matter whether they had content changes
or not). For each item, it prefixes a single-letter flag that indicates type
and/or status of the item.
If you are interested only in a subset of that output, you can give e.g.
`--filter=AME` and it will only show regular files with A, M or E status (see
``--filter=AME`` and it will only show regular files with A, M or E status (see
below).
A uppercase character represents the status of a regular file relative to the
"files" cache (not relative to the repo - this is an issue if the files cache
"files" cache (not relative to the repo -- this is an issue if the files cache
is not used). Metadata is stored in any case and for 'A' and 'M' also new data
chunks are stored. For 'U' all data chunks refer to already existing chunks.
@ -501,12 +501,12 @@ resource usage (RAM and disk space) as the amount of resources needed is
(also) determined by the total amount of chunks in the repository (see
`Indexes / Caches memory usage` for details).
`--chunker-params=10,23,16,4095 (default)` results in a fine-grained deduplication
``--chunker-params=10,23,16,4095 (default)`` results in a fine-grained deduplication
and creates a big amount of chunks and thus uses a lot of resources to manage them.
This is good for relatively small data volumes and if the machine has a good
amount of free RAM and disk space.
`--chunker-params=19,23,21,4095` results in a coarse-grained deduplication and
``--chunker-params=19,23,21,4095`` results in a coarse-grained 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.
@ -519,10 +519,11 @@ In the worst case (all files are big and were touched in between backups), this
will store all content into the repository again.
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
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 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,
@ -556,7 +557,7 @@ You need to be careful with what you give as filename when using ``--read-specia
e.g. if you give ``/dev/zero``, your backup will never terminate.
The given files' metadata is saved as it would be saved without
``--read-special`` (e.g. its name, its size [might be 0], its mode, etc.) - but
``--read-special`` (e.g. its name, its size [might be 0], its mode, etc.) -- but
additionally, also the content read from it will be saved for it.
Restoring such files' content is currently only supported one at a time via