mirror of https://github.com/borgbackup/borg.git
209 lines
6.3 KiB
ReStructuredText
209 lines
6.3 KiB
ReStructuredText
.. include:: global.rst.inc
|
|
.. _detailed_usage:
|
|
|
|
Usage
|
|
=====
|
|
|
|
|project_name| consists of a number of commands. Each command accepts
|
|
a number of arguments and options. The following sections will describe each
|
|
command in detail.
|
|
|
|
Quiet by default
|
|
----------------
|
|
|
|
Like most UNIX commands |project_name| is quiet by default but the ``-v`` or
|
|
``--verbose`` option can be used to get the program to output more status
|
|
messages as it is processing.
|
|
|
|
.. include:: usage/init.rst.inc
|
|
|
|
This command initializes an empty :ref:`repository <repository_def>`.
|
|
A repository is a filesystem directory
|
|
containing the deduplicated data from zero or more archives.
|
|
Encryption is enabled at repository initialization time.
|
|
|
|
Examples
|
|
~~~~~~~~
|
|
::
|
|
|
|
# Local backup repository
|
|
$ attic init /data/mybackuprepo.attic
|
|
|
|
# Remote backup repository
|
|
$ attic init user@hostname:mybackuprepo.attic
|
|
|
|
# Encrypted remote backup repository
|
|
$ attic init --encryption=passphrase user@hostname:mybackuprepo.attic
|
|
|
|
|
|
.. include:: usage/create.rst.inc
|
|
|
|
This command creates a backup archive containing all files found while
|
|
recursively traversing all paths specified. The archive will consume almost
|
|
no disk space for files or parts of files that have already been stored in
|
|
other archives.
|
|
|
|
Examples
|
|
~~~~~~~~
|
|
::
|
|
|
|
# Backup ~/Documents into an archive named "my-documents"
|
|
$ attic create /data/myrepo.attic::my-documents ~/Documents
|
|
|
|
# Backup ~/Documents and ~/src but exclude pyc files
|
|
$ attic create /data/myrepo.attic::my-files \
|
|
~/Documents \
|
|
~/src \
|
|
--exclude '*.pyc'
|
|
|
|
# Backup the root filesystem into an archive named "root-YYYY-MM-DD"
|
|
NAME="root-`date +%Y-%m-%d`"
|
|
$ attic create /data/myrepo.attic::$NAME / --do-not-cross-mountpoints
|
|
|
|
|
|
.. include:: usage/extract.rst.inc
|
|
|
|
This command extracts the contents of an archive. By default the entire
|
|
archive is extracted but a subset of files and directories can be selected
|
|
by passing a list of ``PATHs`` as arguments. The file selection can further
|
|
be restricted by using the ``--exclude`` option.
|
|
|
|
Examples
|
|
~~~~~~~~
|
|
::
|
|
|
|
# Extract entire archive
|
|
$ attic extract /data/myrepo::my-files
|
|
|
|
# Extract entire archive and list files while processing
|
|
$ attic extract -v /data/myrepo::my-files
|
|
|
|
# Extract the "src" directory
|
|
$ attic extract /data/myrepo::my-files home/USERNAME/src
|
|
|
|
# Extract the "src" directory but exclude object files
|
|
$ attic extract /data/myrepo::my-files home/USERNAME/src --exclude '*.o'
|
|
|
|
|
|
.. include:: usage/verify.rst.inc
|
|
|
|
This command is similar to :ref:`attic_extract` but instead of writing any
|
|
files to disk the command just verifies that all files are extractable and
|
|
not corrupt. |project_name| will not compare the the archived files with the
|
|
files on disk.
|
|
|
|
|
|
.. include:: usage/delete.rst.inc
|
|
|
|
This command deletes an archive from the repository. Any disk space not
|
|
shared with any other existing archive is also reclaimed.
|
|
|
|
|
|
.. include:: usage/list.rst.inc
|
|
|
|
This command lists the contents of a repository or an archive.
|
|
|
|
Examples
|
|
~~~~~~~~
|
|
::
|
|
|
|
$ attic list /data/myrepo
|
|
my-files Thu Aug 1 23:33:22 2013
|
|
my-documents Thu Aug 1 23:35:43 2013
|
|
root-2013-08-01 Thu Aug 1 23:43:55 2013
|
|
root-2013-08-02 Fri Aug 2 15:18:17 2013
|
|
...
|
|
|
|
$ attic list /data/myrepo::root-2013-08-02
|
|
drwxr-xr-x root root 0 Jun 05 12:06 .
|
|
lrwxrwxrwx root root 0 May 31 20:40 bin -> usr/bin
|
|
drwxr-xr-x root root 0 Aug 01 22:08 etc
|
|
drwxr-xr-x root root 0 Jul 15 22:07 etc/ImageMagick-6
|
|
-rw-r--r-- root root 1383 May 22 22:25 etc/ImageMagick-6/colors.xml
|
|
...
|
|
|
|
|
|
.. include:: usage/prune.rst.inc
|
|
|
|
The ``prune`` command prunes a repository by deleting archives not matching
|
|
any of the specified retention options. This command is normally
|
|
used by automated backup scripts wanting to keep a certain number of historic
|
|
backups.
|
|
|
|
Examples
|
|
~~~~~~~~
|
|
::
|
|
|
|
# Keep 7 end of day and 4 additional end of week archives
|
|
$ attic prune /data/myrepo --daily=7 --weekly=4
|
|
|
|
# Same as above but only apply to archive names starting with "foo"
|
|
$ attic prune /data/myrepo --daily=7 --weekly=4 --prefix=foo
|
|
|
|
# Keep 7 end of day, 4 additional end of week archives, and an
|
|
# end of month archive for every month:
|
|
$ attic prune /data/myrepo --daily=7 --weekly=4 --monthly=-1
|
|
|
|
|
|
.. include:: usage/info.rst.inc
|
|
|
|
This command displays some detailed information about the specified archive.
|
|
|
|
Examples
|
|
~~~~~~~~
|
|
::
|
|
|
|
$ attic info /data/myrepo::root-2013-08-02
|
|
Name: root-2013-08-02
|
|
Fingerprint: bc3902e2c79b6d25f5d769b335c5c49331e6537f324d8d3badcb9a0917536dbb
|
|
Hostname: myhostname
|
|
Username: root
|
|
Time: Fri Aug 2 15:18:17 2013
|
|
Command line: /usr/bin/attic create --stats /data/myrepo::root-2013-08-02 / --do-not-cross-mountpoints
|
|
Number of files: 147429
|
|
Original size: 5344169493 (4.98 GB)
|
|
Compressed size: 1748189642 (1.63 GB)
|
|
Unique data: 64805454 (61.80 MB)
|
|
|
|
|
|
.. include:: usage/mount.rst.inc
|
|
|
|
This command mounts an archive as a FUSE filesystem. This can be useful for
|
|
browsing an archive or restoring individual files. Unless the ``--foreground``
|
|
option is given the command will run in the background until the filesystem
|
|
is ``umounted``.
|
|
|
|
Examples
|
|
~~~~~~~~
|
|
::
|
|
|
|
$ attic mount /data/myrepo::root-2013-08-02 /tmp/mymountpoint
|
|
$ ls /tmp/mymountpoint
|
|
bin boot etc lib lib64 mnt opt root sbin srv usr var
|
|
$ fusermount -u /tmp/mymountpoint
|
|
|
|
|
|
.. include:: usage/change-passphrase.rst.inc
|
|
|
|
The key files used for repository encryption are optionally passphrase
|
|
protected. This command can be used to change this passphrase.
|
|
|
|
Examples
|
|
~~~~~~~~
|
|
::
|
|
|
|
# Create a key file protected repository
|
|
$ attic init --key-file /tmp/encrypted-repo
|
|
Initializing repository at "/tmp/encrypted-repo"
|
|
Enter passphrase (empty for no passphrase):
|
|
Enter same passphrase again:
|
|
Key file "/home/USER/.attic/keys/tmp_encrypted_repo" created.
|
|
Keep this file safe. Your data will be inaccessible without it.
|
|
|
|
# Change key file passphrase
|
|
$ attic change-passphrase /tmp/encrypted-repo
|
|
Enter passphrase for key file /home/USER/.attic/keys/tmp_encrypted_repo:
|
|
New passphrase:
|
|
Enter same passphrase again:
|
|
Key file "/home/USER/.attic/keys/tmp_encrypted_repo" updated
|