mirror of
https://github.com/borgbackup/borg.git
synced 2025-02-21 05:37:23 +00:00
Merge pull request #10 from ThomasWaldmann/doc-misc
docs: install docs, faq improvements, other minor changes
This commit is contained in:
TW
commit
62e272b642
4 changed files with 86 additions and 53 deletions
11
docs/faq.rst
11
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 <deduplication_def>` 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 ``<archive-name>.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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
---
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue