mirror of
https://github.com/borgbackup/borg.git
synced 2024-12-24 16:55:36 +00:00
c8c0495724
move the note about free space after the step by step example. it is unlikely that users will hit out of space conditions on their first run, and at the end of the example, they will see the not anyways. this is to make the documentation less scary for new users and easier to use.
287 lines
11 KiB
ReStructuredText
287 lines
11 KiB
ReStructuredText
.. include:: global.rst.inc
|
|
.. highlight:: bash
|
|
.. _quickstart:
|
|
|
|
Quick Start
|
|
===========
|
|
|
|
This chapter will get you started with |project_name| and covers
|
|
various use cases.
|
|
|
|
A step by step example
|
|
----------------------
|
|
|
|
1. Before a backup can be made a repository has to be initialized::
|
|
|
|
$ borg init /path/to/repo
|
|
|
|
2. Backup the ``~/src`` and ``~/Documents`` directories into an archive called
|
|
*Monday*::
|
|
|
|
$ borg create /path/to/repo::Monday ~/src ~/Documents
|
|
|
|
3. The next day create a new archive called *Tuesday*::
|
|
|
|
$ borg create --stats /path/to/repo::Tuesday ~/src ~/Documents
|
|
|
|
This backup will be a lot quicker and a lot smaller since only new never
|
|
before seen data is stored. The ``--stats`` option causes |project_name| to
|
|
output statistics about the newly created archive such as the amount of unique
|
|
data (not shared with other archives)::
|
|
|
|
------------------------------------------------------------------------------
|
|
Archive name: Tuesday
|
|
Archive fingerprint: bd31004d58f51ea06ff735d2e5ac49376901b21d58035f8fb05dbf866566e3c2
|
|
Time (start): Tue, 2016-02-16 18:15:11
|
|
Time (end): Tue, 2016-02-16 18:15:11
|
|
|
|
Duration: 0.19 seconds
|
|
Number of files: 127
|
|
------------------------------------------------------------------------------
|
|
Original size Compressed size Deduplicated size
|
|
This archive: 4.16 MB 4.17 MB 26.78 kB
|
|
All archives: 8.33 MB 8.34 MB 4.19 MB
|
|
|
|
Unique chunks Total chunks
|
|
Chunk index: 132 261
|
|
------------------------------------------------------------------------------
|
|
|
|
4. List all archives in the repository::
|
|
|
|
$ borg list /path/to/repo
|
|
Monday Mon, 2016-02-15 19:14:44
|
|
Tuesday Tue, 2016-02-16 19:15:11
|
|
|
|
5. List the contents of the *Monday* archive::
|
|
|
|
$ borg list /path/to/repo::Monday
|
|
drwxr-xr-x user group 0 Mon, 2016-02-15 18:22:30 home/user/Documents
|
|
-rw-r--r-- user group 7961 Mon, 2016-02-15 18:22:30 home/user/Documents/Important.doc
|
|
...
|
|
|
|
6. Restore the *Monday* archive::
|
|
|
|
$ borg extract /path/to/repo::Monday
|
|
|
|
7. Recover disk space by manually deleting the *Monday* archive::
|
|
|
|
$ borg delete /path/to/repo::Monday
|
|
|
|
.. Note::
|
|
Borg is quiet by default (it works on WARNING log level).
|
|
You can use options like ``--progress`` or ``--list`` to get specific
|
|
reports during command execution. You can also add the ``-v`` (or
|
|
``--verbose`` or ``--info``) option to adjust the log level to INFO to
|
|
get other informational messages.
|
|
|
|
Important note about free space
|
|
-------------------------------
|
|
|
|
Before you start creating backups, please make sure that there is *always*
|
|
a good amount of free space on the filesystem that has your backup repository
|
|
(and also on ~/.cache). A few GB should suffice for most hard-drive sized
|
|
repositories. See also :ref:`cache-memory-usage`.
|
|
|
|
Borg doesn't use space reserved for root on repository disks (even when run as root),
|
|
on file systems which do not support this mechanism (e.g. XFS) we recommend to
|
|
reserve some space in Borg itself just to be safe by adjusting the
|
|
``additional_free_space`` setting in the ``[repository]`` section of a repositories
|
|
``config`` file. A good starting point is ``2G``.
|
|
|
|
If |project_name| runs out of disk space, it tries to free as much space as it
|
|
can while aborting the current operation safely, which allows to free more space
|
|
by deleting/pruning archives. This mechanism is not bullet-proof in some
|
|
circumstances [1]_.
|
|
|
|
If you *really* 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.
|
|
|
|
You can use some monitoring process or just include the free space information
|
|
in your backup log files (you check them regularly anyway, right?).
|
|
|
|
Also helpful:
|
|
|
|
- create a big file as a "space reserve", that you can delete to free space
|
|
- if you use LVM: use a LV + a filesystem that you can resize later and have
|
|
some unallocated PEs you can add to the LV.
|
|
- consider using quotas
|
|
- use `prune` regularly
|
|
|
|
.. [1] This failsafe can fail in these circumstances:
|
|
|
|
- The underlying file system doesn't support statvfs(2), or returns incorrect
|
|
data, or the repository doesn't reside on a single file system
|
|
- Other tasks fill the disk simultaneously
|
|
- Hard quotas (which may not be reflected in statvfs(2))
|
|
|
|
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:
|
|
|
|
::
|
|
|
|
#!/bin/sh
|
|
# setting this, so the repo does not need to be given on the commandline:
|
|
export BORG_REPO=username@remoteserver.com:backup
|
|
|
|
# setting this, so you won't be asked for your passphrase - make sure the
|
|
# script has appropriate owner/group and mode, e.g. root.root 600:
|
|
export BORG_PASSPHRASE=mysecret
|
|
|
|
# Backup most important stuff:
|
|
borg create --stats -C lz4 ::'{hostname}-{now:%Y-%m-%d}' \
|
|
/etc \
|
|
/home \
|
|
/var \
|
|
--exclude '/home/*/.cache' \
|
|
--exclude '*.pyc'
|
|
|
|
# Use the `prune` subcommand to maintain 7 daily, 4 weekly and 6 monthly
|
|
# archives of THIS machine. The '{hostname}-' prefix is very important to
|
|
# limit prune's operation to this machine's archives and not apply to
|
|
# other machine's archives also.
|
|
borg prune -v --prefix '{hostname}-' \
|
|
--keep-daily=7 --keep-weekly=4 --keep-monthly=6
|
|
|
|
Pitfalls with shell variables and environment variables
|
|
-------------------------------------------------------
|
|
|
|
This applies to all environment variables you want borg to see, not just
|
|
``BORG_PASSPHRASE``. The short explanation is: always ``export`` your variable,
|
|
and use single quotes if you're unsure of the details of your shell's expansion
|
|
behavior. E.g.::
|
|
|
|
export BORG_PASSPHRASE='complicated & long'
|
|
|
|
This is because ``export`` exposes variables to subprocesses, which borg may be
|
|
one of. More on ``export`` can be found in the "ENVIRONMENT" section of the
|
|
bash(1) man page.
|
|
|
|
Beware of how ``sudo`` interacts with environment variables. For example, you
|
|
may be surprised that the following ``export`` has no effect on your command::
|
|
|
|
export BORG_PASSPHRASE='complicated & long'
|
|
sudo ./yourborgwrapper.sh # still prompts for password
|
|
|
|
For more information, see sudo(8) man page. Hint: see ``env_keep`` in
|
|
sudoers(5), or try ``sudo BORG_PASSPHRASE='yourphrase' borg`` syntax.
|
|
|
|
.. Tip::
|
|
To debug what your borg process is actually seeing, find its PID
|
|
(``ps aux|grep borg``) and then look into ``/proc/<PID>/environ``.
|
|
|
|
.. backup_compression:
|
|
|
|
Backup compression
|
|
------------------
|
|
|
|
Default is no compression, but we support different methods with high speed
|
|
or high compression:
|
|
|
|
If you have a fast repo storage and you want some compression: ::
|
|
|
|
$ borg create --compression lz4 /path/to/repo::arch ~
|
|
|
|
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 /path/to/repo::arch ~
|
|
|
|
If you have a very slow repo storage and you want high compression (N=0..9, 0 means
|
|
low compression, 9 means high compression): ::
|
|
|
|
$ borg create --compression lzma,N /path/to/repo::arch ~
|
|
|
|
You'll need to experiment a bit to find the best compression for your use case.
|
|
Keep an eye on CPU load and throughput.
|
|
|
|
.. _encrypted_repos:
|
|
|
|
Repository encryption
|
|
---------------------
|
|
|
|
Repository encryption can be enabled or disabled at repository creation time
|
|
(the default is enabled, with `repokey` method)::
|
|
|
|
$ borg init --encryption=none|repokey|keyfile PATH
|
|
|
|
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 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 while the backup
|
|
is being made.
|
|
|
|
|project_name| supports different methods to store the AES and HMAC keys.
|
|
|
|
``repokey`` mode
|
|
The key is stored inside the repository (in its "config" file).
|
|
Use this mode if you trust in your good passphrase giving you enough
|
|
protection. The repository server never sees the plaintext key.
|
|
|
|
``keyfile`` mode
|
|
The key is stored on your local disk (in ``~/.config/borg/keys/``).
|
|
Use this mode if you want "passphrase and having-the-key" security.
|
|
|
|
In both modes, the key is stored in encrypted form and can be only decrypted
|
|
by providing the correct passphrase.
|
|
|
|
For automated backups the passphrase can be specified using the
|
|
`BORG_PASSPHRASE` environment variable.
|
|
|
|
.. note:: Be careful about how you set that environment, see
|
|
:ref:`this note about password environments <password_env>`
|
|
for more information.
|
|
|
|
.. 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. Also keep your passphrase
|
|
at a safe place.
|
|
|
|
You can make backups using :ref:`borg_key_export` subcommand.
|
|
|
|
If you want to print a backup of your key to paper use the ``--paper``
|
|
option of this command and print the result.
|
|
|
|
A backup inside of the backup that is encrypted with that key/passphrase
|
|
won't help you with that, of course.
|
|
|
|
.. _remote_repos:
|
|
|
|
Remote repositories
|
|
-------------------
|
|
|
|
|project_name| can initialize and access repositories on remote hosts if the
|
|
host is accessible using SSH. This is fastest and easiest when |project_name|
|
|
is installed on the remote host, in which case the following syntax is used::
|
|
|
|
$ borg init user@hostname:/path/to/repo
|
|
|
|
Note: please see the usage chapter for a full documentation of repo URLs.
|
|
|
|
Remote operations over SSH can be automated with SSH keys. You can restrict the
|
|
use of the SSH keypair by prepending a forced command to the SSH public key in
|
|
the remote server's `authorized_keys` file. This example will start |project_name|
|
|
in server mode and limit it to a specific filesystem path::
|
|
|
|
command="borg serve --restrict-to-path /path/to/repo",no-pty,no-agent-forwarding,no-port-forwarding,no-X11-forwarding,no-user-rc ssh-rsa AAAAB3[...]
|
|
|
|
If it is not possible to install |project_name| on the remote host,
|
|
it is still possible to use the remote host to store a repository by
|
|
mounting the remote filesystem, for example, using sshfs::
|
|
|
|
$ sshfs user@hostname:/path/to /path/to
|
|
$ borg init /path/to/repo
|
|
$ fusermount -u /path/to
|
|
|
|
You can also use other remote filesystems in a similar way. Just be careful,
|
|
not all filesystems out there are really stable and working good enough to
|
|
be acceptable for backup usage.
|