mirror of https://github.com/borgbackup/borg.git
update and improve docs
use the travis status image as png as svg does not show an image in firefox.
This commit is contained in:
Thomas Waldmann
parent
7b5c799440
commit
af2eaaabd4
39
README.rst
39
README.rst
|
|
@ -19,6 +19,7 @@ downloaded Borg, ``docs/installation.rst`` to get started with Borg.
|
|||
|
||||
Main features
|
||||
-------------
|
||||
|
||||
**Space efficient storage**
|
||||
Deduplication based on content-defined chunking is used to reduce the number
|
||||
of bytes stored: each file is split into a number of variable length chunks
|
||||
|
|
@ -80,24 +81,31 @@ Main features
|
|||
|
||||
Easy to use
|
||||
-----------
|
||||
|
||||
Initialize a new backup repository and create a backup archive::
|
||||
|
||||
$ borg init /mnt/backup
|
||||
$ borg create /mnt/backup::Monday ~/Documents
|
||||
$ borg create /mnt/backup::Saturday1 ~/Documents
|
||||
|
||||
Now doing another backup, just to show off the great deduplication::
|
||||
|
||||
$ borg create --stats -C zlib,6 /mnt/backup::Tuesday ~/Documents
|
||||
$ borg create -v --stats /mnt/backup::Saturday2 ~/Documents
|
||||
-----------------------------------------------------------------------------
|
||||
Archive name: Saturday2
|
||||
Archive fingerprint: 622b7c53c...
|
||||
Time (start): Sat, 2016-02-27 14:48:13
|
||||
Time (end): Sat, 2016-02-27 14:48:14
|
||||
Duration: 0.88 seconds
|
||||
Number of files: 163
|
||||
-----------------------------------------------------------------------------
|
||||
Original size Compressed size Deduplicated size
|
||||
This archive: 6.85 MB 6.85 MB 30.79 kB <-- !
|
||||
All archives: 13.69 MB 13.71 MB 6.88 MB
|
||||
|
||||
Unique chunks Total chunks
|
||||
Chunk index: 167 330
|
||||
-----------------------------------------------------------------------------
|
||||
|
||||
Archive name: Tuesday
|
||||
Archive fingerprint: 387a5e3f9b0e792e91c...
|
||||
Start time: Tue Mar 25 12:00:10 2014
|
||||
End time: Tue Mar 25 12:00:10 2014
|
||||
Duration: 0.08 seconds
|
||||
Number of files: 358
|
||||
Original size Compressed size Deduplicated size
|
||||
This archive: 57.16 MB 46.78 MB 151.67 kB <--- !
|
||||
All archives: 114.02 MB 93.46 MB 44.81 MB
|
||||
|
||||
For a graphical frontend refer to our complementary project `BorgWeb <https://borgbackup.github.io/borgweb/>`_.
|
||||
|
||||
|
|
@ -129,7 +137,7 @@ Here's a (incomplete) list of some major changes:
|
|||
|
||||
* more open, faster paced development (see `issue #1 <https://github.com/borgbackup/borg/issues/1>`_)
|
||||
* lots of attic issues fixed (see `issue #5 <https://github.com/borgbackup/borg/issues/5>`_)
|
||||
* less chunk management overhead via --chunker-params option (less memory and disk usage)
|
||||
* less chunk management overhead (less memory and disk usage for chunks index)
|
||||
* faster remote cache resync (useful when backing up multiple machines into same repo)
|
||||
* compression: no, lz4, zlib or lzma compression, adjustable compression levels
|
||||
* repokey replaces problematic passphrase mode (you can't change the passphrase nor the pbkdf2 iteration count in "passphrase" mode)
|
||||
|
|
@ -147,14 +155,13 @@ information.
|
|||
BORG IS NOT COMPATIBLE WITH ORIGINAL ATTIC (but there is a one-way conversion).
|
||||
|
||||
EXPECT THAT WE WILL BREAK COMPATIBILITY REPEATEDLY WHEN MAJOR RELEASE NUMBER
|
||||
CHANGES (like when going from 0.x.y to 1.0.0).
|
||||
CHANGES (like when going from 0.x.y to 1.0.0 or from 1.x.y to 2.0.0).
|
||||
|
||||
NOT RELEASED DEVELOPMENT VERSIONS HAVE UNKNOWN COMPATIBILITY PROPERTIES.
|
||||
|
||||
THIS IS SOFTWARE IN DEVELOPMENT, DECIDE YOURSELF WHETHER IT FITS YOUR NEEDS.
|
||||
|
||||
Borg is distributed under a 3-clause BSD license, see `License`_
|
||||
for the complete license.
|
||||
Borg is distributed under a 3-clause BSD license, see `License`_ for the complete license.
|
||||
|
||||
|doc| |build| |coverage|
|
||||
|
||||
|
|
@ -162,7 +169,7 @@ for the complete license.
|
|||
:alt: Documentation
|
||||
:target: https://borgbackup.readthedocs.org/en/stable/
|
||||
|
||||
.. |build| image:: https://travis-ci.org/borgbackup/borg.svg
|
||||
.. |build| image:: https://travis-ci.org/borgbackup/borg.png
|
||||
:alt: Build Status
|
||||
:target: https://travis-ci.org/borgbackup/borg
|
||||
|
||||
|
|
|
|||
14
docs/faq.rst
14
docs/faq.rst
|
|
@ -72,7 +72,8 @@ Which file types, attributes, etc. are *not* preserved?
|
|||
meaningless without the running process that created them and the process
|
||||
needs to recreate them in any case). So, don't panic if your backup
|
||||
misses a UDS!
|
||||
* The precise on-disk representation of the holes in a sparse file.
|
||||
* The precise on-disk (or rather: not-on-disk) representation of the holes
|
||||
in a sparse file.
|
||||
Archive creation has no special support for sparse files, holes are
|
||||
backed up as (deduplicated and compressed) runs of zero bytes.
|
||||
Archive extraction has optional support to extract all-zero chunks as
|
||||
|
|
@ -183,8 +184,8 @@ minutes) containing all the data backed-up until that point. This means
|
|||
that at most <checkpoint interval> worth of data needs to be retransmitted
|
||||
if a backup needs to be restarted.
|
||||
|
||||
Once your backup has finished successfully, you can delete all ``*.checkpoint``
|
||||
archives.
|
||||
Once your backup has finished successfully, you can delete all
|
||||
``<archive-name>.checkpoint`` archives.
|
||||
|
||||
If it crashes with a UnicodeError, what can I do?
|
||||
-------------------------------------------------
|
||||
|
|
@ -223,7 +224,7 @@ Can |project_name| verify data integrity of a backup archive?
|
|||
|
||||
Yes, if you want to detect accidental data damage (like bit rot), use the
|
||||
``check`` operation. It will notice corruption using CRCs and hashes.
|
||||
If you want to be able to detect malicious tampering also, use a encrypted
|
||||
If you want to be able to detect malicious tampering also, use an encrypted
|
||||
repo. It will then be able to check using CRCs and HMACs.
|
||||
|
||||
.. _a_status_oddity:
|
||||
|
|
@ -254,6 +255,11 @@ will often be the same and already stored in the repo (except in the above
|
|||
mentioned rare condition), it will just re-use them as usual and not store new
|
||||
data chunks.
|
||||
|
||||
If you want to avoid unnecessary chunking, just create or touch a small or
|
||||
empty file in your backup source file set (so that one has the latest mtime,
|
||||
not your 50GB VM disk image) and, if you do snapshots, do the snapshot after
|
||||
that.
|
||||
|
||||
Since only the files cache is used in the display of files status,
|
||||
those files are reported as being added when, really, chunks are
|
||||
already used.
|
||||
|
|
|
|||
|
|
@ -66,7 +66,8 @@ Standalone Binary
|
|||
|project_name| binaries (generated with `pyinstaller`_) are available
|
||||
on the releases_ page for the following platforms:
|
||||
|
||||
* **Linux**: glibc >= 2.13 (ok for most supported Linux releases)
|
||||
* **Linux**: glibc >= 2.13 (ok for most supported Linux releases). Maybe older
|
||||
glibc versions also work, if they are compatible to 2.13.
|
||||
* **Mac OS X**: 10.10 (does not work with older OS X releases)
|
||||
* **FreeBSD**: 10.2 (unknown whether it works for older releases)
|
||||
|
||||
|
|
|
|||
|
|
@ -92,7 +92,9 @@ A step by step example
|
|||
$ borg delete /mnt/backup::Monday
|
||||
|
||||
.. Note::
|
||||
Borg is quiet by default. Add the ``-v`` or ``--verbose`` option to
|
||||
Borg is quiet by default (it works on WARNING log level).
|
||||
Add the ``-v`` (or ``--verbose`` or ``--info``) option to adjust the log
|
||||
level to INFO and also use options like ``--progress`` or ``--list`` to
|
||||
get progress reporting during command execution.
|
||||
|
||||
Automating backups
|
||||
|
|
@ -130,11 +132,11 @@ Backup compression
|
|||
Default is no compression, but we support different methods with high speed
|
||||
or high compression:
|
||||
|
||||
If you have a quick repo storage and you want a little compression: ::
|
||||
If you have a fast repo storage and you want some compression: ::
|
||||
|
||||
$ borg create --compression lz4 /mnt/backup::repo ~
|
||||
|
||||
If you have a medium fast repo storage and you want a bit more compression (N=0..9,
|
||||
If you have a less fast repo storage and you want a bit more compression (N=0..9,
|
||||
0 means no compression, 9 means high compression): ::
|
||||
|
||||
$ borg create --compression zlib,N /mnt/backup::repo ~
|
||||
|
|
@ -162,7 +164,7 @@ encryption and the integrity and authenticity is verified using `HMAC-SHA256`_.
|
|||
|
||||
All data is encrypted on the client before being written to the repository. This
|
||||
means that an attacker who manages to compromise the host containing an
|
||||
encrypted archive will not be able to access any of the data, even as the backup
|
||||
encrypted archive will not be able to access any of the data, even while the backup
|
||||
is being made.
|
||||
|
||||
|project_name| supports different methods to store the AES and HMAC keys.
|
||||
|
|
@ -186,12 +188,16 @@ For automated backups the passphrase can be specified using the
|
|||
:ref:`this note about password environments <password_env>`
|
||||
for more information.
|
||||
|
||||
.. warning:: The repository data is totally inaccessible without the key:
|
||||
.. warning:: The repository data is totally inaccessible without the key
|
||||
and the key passphrase.
|
||||
|
||||
Make a backup copy of the key file (``keyfile`` mode) or repo config
|
||||
file (``repokey`` mode) and keep it at a safe place, so you still have
|
||||
the key in case it gets corrupted or lost.
|
||||
The backup that is encrypted with that key won't help you with that,
|
||||
of course.
|
||||
the key in case it gets corrupted or lost. Also keep your passphrase
|
||||
at a safe place.
|
||||
|
||||
The backup that is encrypted with that key/passphrase won't help you
|
||||
with that, of course.
|
||||
|
||||
.. _remote_repos:
|
||||
|
||||
|
|
|
|||
|
|
@ -47,7 +47,8 @@ Return codes
|
|||
did not reach its normal end, logged as ERROR)
|
||||
128+N = killed by signal N (e.g. 137 == kill -9)
|
||||
|
||||
The return code is also logged at the indicated level as the last log entry.
|
||||
If you use ``--show-rc``, the return code is also logged at the indicated
|
||||
level as the last log entry.
|
||||
|
||||
|
||||
Environment Variables
|
||||
|
|
@ -133,10 +134,9 @@ Cache files:
|
|||
single-archive chunk indexes).
|
||||
|
||||
Chunks index:
|
||||
Proportional to the amount of data chunks in your repo. Lots of small chunks
|
||||
in your repo imply a big chunks index. You may need to tweak the chunker
|
||||
params (see create options) if you have a lot of data and you want to keep
|
||||
the chunks index at some reasonable size.
|
||||
Proportional to the amount of data chunks in your repo. Lots of chunks
|
||||
in your repo imply a big chunks index.
|
||||
It is possible to tweak the chunker params (see create options).
|
||||
|
||||
Files index:
|
||||
Proportional to the amount of files in your last backup. Can be switched
|
||||
|
|
@ -169,9 +169,13 @@ using powers of two (so ``KiB`` means 1024 bytes).
|
|||
Date and Time
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
We format date and time conforming to ISO-8601, that is: YYYY-MM-DD and HH:MM:SS
|
||||
We format date and time conforming to ISO-8601, that is: YYYY-MM-DD and
|
||||
HH:MM:SS (24h clock).
|
||||
|
||||
For more information, see: https://xkcd.com/1179/
|
||||
For more information about that, see: https://xkcd.com/1179/
|
||||
|
||||
Unless otherwise noted, we display local date and time.
|
||||
Internally, we store and process date and time as UTC.
|
||||
|
||||
|
||||
.. include:: usage/init.rst.inc
|
||||
|
|
@ -180,22 +184,22 @@ Examples
|
|||
~~~~~~~~
|
||||
::
|
||||
|
||||
# Local repository
|
||||
# Local repository (default is to use encryption in repokey mode)
|
||||
$ borg init /mnt/backup
|
||||
|
||||
# Local repository (no encryption)
|
||||
$ borg init --encryption=none /mnt/backup
|
||||
|
||||
# Remote repository (accesses a remote borg via ssh)
|
||||
$ borg init user@hostname:backup
|
||||
|
||||
# Encrypted remote repository, store the key in the repo
|
||||
$ borg init --encryption=repokey user@hostname:backup
|
||||
|
||||
# Encrypted remote repository, store the key your home dir
|
||||
# Remote repository (store the key your home dir)
|
||||
$ borg init --encryption=keyfile user@hostname:backup
|
||||
|
||||
Important notes about encryption:
|
||||
|
||||
Use encryption! Repository encryption protects you e.g. against the case that
|
||||
an attacker has access to your backup repository.
|
||||
It is not recommended to disable encryption. Repository encryption protects you
|
||||
e.g. against the case that an attacker has access to your backup repository.
|
||||
|
||||
But be careful with the key / the passphrase:
|
||||
|
||||
|
|
@ -210,7 +214,7 @@ the key (and also not the passphrase).
|
|||
|
||||
Make a backup copy of the key file (``keyfile`` mode) or repo config file
|
||||
(``repokey`` mode) and keep it at a safe place, so you still have the key in
|
||||
case it gets corrupted or lost.
|
||||
case it gets corrupted or lost. Also keep the passphrase at a safe place.
|
||||
The backup that is encrypted with that key won't help you with that, of course.
|
||||
|
||||
Make sure you use a good passphrase. Not too short, not too simple. The real
|
||||
|
|
@ -218,6 +222,16 @@ encryption / decryption key is encrypted with / locked by your passphrase.
|
|||
If an attacker gets your key, he can't unlock and use it without knowing the
|
||||
passphrase.
|
||||
|
||||
Be careful with special or non-ascii characters in your passphrase:
|
||||
|
||||
- |project_name| processes the passphrase as unicode (and encodes it as utf-8),
|
||||
so it does not have problems dealing with even the strangest characters.
|
||||
- BUT: that does not necessarily apply to your OS / VM / keyboard configuration.
|
||||
|
||||
So better use a long passphrase made from simple ascii chars than one that
|
||||
includes non-ascii stuff or characters that are hard/impossible to enter on
|
||||
a different keyboard layout.
|
||||
|
||||
You can change your passphrase for existing repos at any time, it won't affect
|
||||
the encryption/decryption key or other secrets.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue