1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2024-12-25 17:27:31 +00:00
borg/docs/quickstart.rst

137 lines
4.5 KiB
ReStructuredText
Raw Normal View History

2013-06-29 21:56:44 +00:00
.. include:: global.rst.inc
2013-07-31 18:51:01 +00:00
.. _quickstart:
2013-06-29 21:56:44 +00:00
2013-07-31 18:51:01 +00:00
Quick Start
===========
2013-06-29 21:56:44 +00:00
2013-07-31 18:51:01 +00:00
This chapter will get you started with |project_name|. The first section
2013-08-04 20:50:34 +00:00
presents a simple step by step example that uses |project_name| to backup data.
2013-07-31 18:51:01 +00:00
The next section continues by showing how backups can be automated.
2013-06-29 21:56:44 +00:00
2013-07-31 18:51:01 +00:00
A step by step example
----------------------
1. Before a backup can be made a repository has to be initialized::
2013-06-29 21:56:44 +00:00
2013-07-08 21:38:27 +00:00
$ attic init /somewhere/my-backup.attic
2013-06-29 21:56:44 +00:00
2013-07-31 18:51:01 +00:00
2. Backup the ``~/src`` and ``~/Documents`` directories into an archive called
*first-backup*::
2013-06-29 21:56:44 +00:00
2013-07-08 21:38:27 +00:00
$ attic create -v /somwhere/my-backup.attic::first-backup ~/src ~/Documents
2013-06-29 21:56:44 +00:00
2013-07-31 18:51:01 +00:00
3. The next day create a new archive called *second-backup*::
2013-06-29 21:56:44 +00:00
2013-07-08 21:38:27 +00:00
$ attic create -v --stats /somwhere/my-backup.attic::second-backup ~/src ~/Documents
2013-06-29 21:56:44 +00:00
2013-07-31 18:51:01 +00:00
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
2013-07-31 18:51:01 +00:00
data (not shared with other archives).
4. List all archives in the repository::
2013-06-29 21:56:44 +00:00
2013-07-08 21:38:27 +00:00
$ attic list /somewhere/my-backup.attic
2013-06-29 21:56:44 +00:00
2013-07-31 18:51:01 +00:00
5. List the contents of the *first-backup* archive::
2013-06-29 21:56:44 +00:00
2013-07-08 21:38:27 +00:00
$ attic list /somewhere/my-backup.attic::first-backup
2013-06-29 21:56:44 +00:00
2013-07-31 18:51:01 +00:00
6. Restore the *first-backup* archive::
2013-06-29 21:56:44 +00:00
2013-07-08 21:38:27 +00:00
$ attic extract -v /somwhere/my-backup.attic::first-backup
2013-06-29 21:56:44 +00:00
2013-07-31 18:51:01 +00:00
7. Recover disk space by manually deleting the *first-backup* archive::
2013-06-29 21:56:44 +00:00
2013-07-08 21:38:27 +00:00
$ attic delete /somwhere/my-backup.attic::first-backup
2013-06-29 21:56:44 +00:00
2013-07-31 18:51:01 +00:00
Automating backups
------------------
The following example script backs up ``/home`` and
2013-07-31 18:51:01 +00:00
``/var/www`` to a remote server. The script also uses the
2013-08-04 20:50:34 +00:00
:ref:`attic_prune` subcommand to maintain a certain number
2013-07-31 18:51:01 +00:00
of old archives::
#!/bin/sh
REPOSITORY=username@remoteserver.com:backup.attic
# Backup all of /home and /var/www except a few
# excluded directories
attic create --stats \
$REPOSITORY::hostname-`date +%Y-%m-%d` \
/home \
/var/www \
--exclude /home/*/.cache \
--exclude /home/Ben/Music/Justin\ Bieber \
--exclude '*.pyc'
2013-07-31 18:51:01 +00:00
# Use the `prune` subcommand to maintain 7 daily, 4 weekly
# and 6 monthly archives.
attic prune -v $REPOSITORY --keep-daily=7 --keep-weekly=4 --keep-monthly=6
2013-06-29 21:56:44 +00:00
2013-07-31 18:51:01 +00:00
.. Note::
This script assumes the repository has already been initialized with
2013-07-31 18:51:01 +00:00
:ref:`attic_init`.
2013-06-29 21:56:44 +00:00
.. _encrypted_repos:
Repository encryption
---------------------
Repository encryption is enabled at repository creation time::
2013-06-29 21:56:44 +00:00
$ attic init --encryption=passphrase|keyfile PATH
2013-06-29 21:56:44 +00:00
2013-07-03 20:38:07 +00:00
When repository encryption is enabled all data is encrypted using 256-bit AES_
encryption and the integrity and authenticity is verified using `HMAC-SHA256`_.
2013-06-29 21:56:44 +00:00
|project_name| supports two different methods to derive the AES and HMAC keys.
Passphrase based encryption
This method uses a user supplied passphrase to derive the keys using the
PBKDF2_ key derivation function. This method is convenient to use and
secure as long as a *strong* passphrase is used.
2013-07-30 19:51:21 +00:00
.. Note::
For automated backups the passphrase can be specified using the
`ATTIC_PASSPHRASE` environment variable.
2013-06-29 21:56:44 +00:00
Key file based encryption
2013-07-03 20:38:07 +00:00
This method generates random keys at repository initialization time that
2013-07-08 21:38:27 +00:00
are stored in a password protected file in the ``~/.attic/keys/`` directory.
2013-06-29 21:56:44 +00:00
This method is secure and suitable for automated backups.
.. Note::
The repository data is totally inaccessible without the key file
so it must be kept **safe**.
.. _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::
2013-06-29 21:56:44 +00:00
2013-07-08 21:38:27 +00:00
$ attic init user@hostname:repository.attic
2013-06-29 21:56:44 +00:00
or::
2013-07-08 21:38:27 +00:00
$ attic init ssh://user@hostname:port/repository.attic
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/folder /tmp/mymountpoint
$ attic init /tmp/mymountpoint/repository.attic
$ fusermount -u /tmp/mymountpoint
However, be aware that sshfs doesn't fully implement POSIX locks, so
you must be sure to not have two processes trying to access the same
repository at the same time.