From f30d05fcd41da13c434efc39d7f97fb53bb47798 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Thu, 14 May 2015 20:47:08 +0200 Subject: [PATCH] docs: install docs, faq improvements, other minor changes --- docs/faq.rst | 11 ++++- docs/index.rst | 18 +++++--- docs/installation.rst | 97 +++++++++++++++++++++++++------------------ docs/quickstart.rst | 13 +++--- 4 files changed, 86 insertions(+), 53 deletions(-) diff --git a/docs/faq.rst b/docs/faq.rst index 1721d9531..54bd47c1e 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -7,10 +7,13 @@ Frequently asked questions Which platforms are supported? Currently Linux, FreeBSD and MacOS X are supported. + You can try your luck on other POSIX-like systems, like Cygwin, + other BSDs, etc. but they are not officially supported. Can I backup VM disk images? Yes, the :ref:`deduplication ` technique used by |project_name| makes sure only the modified parts of the file are stored. + Also, we have optional simple sparse file support for extract. Can I backup from multiple servers into a single repository? Yes, but in order for the deduplication used by Borg to work, it @@ -62,7 +65,13 @@ How can I specify the encryption passphrase programmatically? When backing up to remote servers, is data encrypted before leaving the local machine, or do I have to trust that the remote server isn't malicious? Yes, everything is encrypted before leaving the local machine. -If a backup stops mid-way, does the already-backed-up data stay there? I.e. does Borg resume backups? +If a backup stops mid-way, does the already-backed-up data stay there? I.e. does |project_name| resume backups? Yes, during a backup a special checkpoint archive named ``.checkpoint`` is saved every 5 minutes containing all the data backed-up until that point. This means that at most 5 minutes worth of data needs to be retransmitted if a backup needs to be restarted. + +If it crashes with a UnicodeError, what can I do? + Check if your encoding is set correctly. For most POSIX-like systems, try:: + + export LANG=en_US.UTF-8 # or similar, important is correct charset + diff --git a/docs/index.rst b/docs/index.rst index 723ad3d7f..cca367317 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,10 +2,16 @@ Welcome to Borg ================ -|project_name| is a deduplicating backup program written in Python. +|project_name| is a deduplicating and compressing backup program. +Optionally, it also supports authenticated encryption. + The main goal of |project_name| is to provide an efficient and secure way to backup data. The data deduplication technique used makes |project_name| -suitable for daily backups since only the changes are stored. +suitable for daily backups since only the changes are stored. The authenticated +encryption makes it suitable for backups to not fully trusted targets. + +|project_name| is written in Python (with a little bit of Cython and C for +the speed critical parts). Easy to use @@ -52,9 +58,11 @@ User's Guide Getting help ============ -If you've found a bug or have a concrete feature request, you can add your bug -report or feature request directly to the project's `issue tracker`_. For more -general questions or discussions, a post to the mailing list is preferred. +If you've found a bug or have a concrete feature request, please create a new +ticket on the project's `issue tracker`_ (after checking whether someone else +already has reported the same thing). + +For more general questions or discussions, IRC or mailing list are preferred. IRC --- diff --git a/docs/installation.rst b/docs/installation.rst index c42c99473..ec47fe3ae 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -4,62 +4,79 @@ Installation ============ -|project_name| requires Python_ 3.2 or above to work. Even though Python 3 is -not the default Python version on most Linux distributions, it is usually -available as an optional install. +|project_name| requires: -Other dependencies: - -* `msgpack-python`_ >= 0.1.10 +* Python_ >= 3.2 * OpenSSL_ >= 1.0.0 * libacl_ +* some python dependencies, see install_requires in setup.py -The OpenSSL version bundled with Mac OS X and FreeBSD is most likey too old. -Newer versions are available from homebrew_ on OS X and from FreeBSD ports. +General notes +------------- +Even though Python 3 is not the default Python version on many systems, it is +usually available as an optional install. + +Virtualenv_ can be used to build and install |project_name| without affecting +the system Python or requiring root access. The llfuse_ python package is also required if you wish to mount an -archive as a FUSE filesystem. +archive as a FUSE filesystem. Only FUSE >= 2.8.0 can support llfuse. -Virtualenv_ can be used to build and install |project_name| -without affecting the system Python or requiring root access. +You only need Cython to compile the .pyx files to the respective .c files +when using |project_name| code from git. For |project_name| releases, the .c +files will be bundled. -Common compilation pre-requisites ---------------------------------- +Platform notes +-------------- +FreeBSD: You may need to get a recent enough OpenSSL version from FreeBSD ports. -The following Debian packages are generally necessary to compile -|project_name|, either through pip, the tarball or git:: +Mac OS X: You may need to get a recent enough OpenSSL version from homebrew_. - $ sudo apt-get install python3 python3-dev python3-msgpack python3-sphinx libssl-dev libacl1-dev +Mac OS X: A recent enough FUSE implementation might be unavailable. -Installing from PyPI using pip ------------------------------- -To install |project_name| system-wide:: +Debian / Ubuntu installation (from git) +--------------------------------------- +Note: this uses latest, unreleased development code from git. +While we try not to break master, there are no guarantees on anything. - $ sudo pip3 install borgbackup +Some of the steps detailled below might be useful also for non-git installs. -To install it in a user-specific account:: - - $ pip3 install --user borgbackup - -Then add ``$HOME/.library/bin`` to your ``$PATH``. - -Installing from source tarballs -------------------------------- .. parsed-literal:: - $ curl -O :targz_url:`Borg` - $ tar -xvzf |package_filename| - $ cd |package_dirname| - $ sudo python3 setup.py install + # Python 3.x (>= 3.2) + Headers, Py Package Installer + apt-get install python3 python3-dev python3-pip -Installing from git -------------------- -.. parsed-literal:: + # we need OpenSSL + Headers for Crypto + apt-get install libssl-dev openssl - $ git clone |git_url| - $ cd borg - $ sudo python3 setup.py install + # ACL support Headers + Library + apt-get install libacl1-dev libacl1 + + # if you do not have gcc / make / etc. yet + apt-get install build-essential + + # optional: lowlevel FUSE py binding - to mount backup archives + apt-get install python3-llfuse fuse + + # optional: for unit testing + apt-get install fakeroot + + # install virtualenv tool, create and activate a virtual env + apt-get install python-virtualenv + virtualenv --python=python3 borg-env + source borg-env/bin/activate # always do this before using! + + # install some dependencies into virtual env + pip install cython # to compile .pyx -> .c + pip install tox # optional, for running unit tests + pip install sphinx # optional, to build the docs + + # get |project_name| from github, install it + git clone |git_url| + cd borg + pip install -e . # in-place editable mode + + # optional: run all the tests, on all supported Python versions + fakeroot -u tox -Please note that when installing from git, Cython_ is required to generate some files that -are normally bundled with the release tarball. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 366f3aacb..b4273167c 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -68,18 +68,17 @@ A step by step example Automating backups ------------------ -The following example script backs up ``/home`` and -``/var/www`` to a remote server. The script also uses the -:ref:`borg_prune` subcommand to maintain a certain number -of old archives:: +The following example script backs up ``/home`` and ``/var/www`` to a remote +server. The script also uses the :ref:`borg_prune` subcommand to maintain a +certain number of old archives:: #!/bin/sh REPOSITORY=username@remoteserver.com:backup # Backup all of /home and /var/www except a few # excluded directories - borg create --stats \ - $REPOSITORY::hostname-`date +%Y-%m-%d` \ + borg create --stats \ + $REPOSITORY::`hostname`-`date +%Y-%m-%d` \ /home \ /var/www \ --exclude /home/*/.cache \ @@ -103,7 +102,7 @@ When repository encryption is enabled all data is encrypted using 256-bit AES_ encryption and the integrity and authenticity is verified using `HMAC-SHA256`_. All data is encrypted before being written to the repository. This means that -an attacker that manages to compromise the host containing an encrypted +an attacker who manages to compromise the host containing an encrypted archive will not be able to access any of the data. |project_name| supports two different methods to derive the AES and HMAC keys.