Attic consists of a number of commands. Each command accepts a number of arguments and options. The following sections will describe each command in detail.
Like most UNIX commands Attic 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.
usage: attic init [-h] [-v] [-e {none,passphrase,keyfile}] REPOSITORY
Initialize an empty repository
positional arguments:
REPOSITORY repository to create
optional arguments:
-h, --help show this help message and exit
-v, --verbose verbose output
-e {none,passphrase,keyfile}, --encryption {none,passphrase,keyfile}
select encryption method
This command initializes an empty repository. A repository is a filesystem directory containing the deduplicated data from zero or more archives. Encryption can be enabled at repository init time.
# Local repository
$ attic init /data/mybackuprepo.attic
# Remote repository
$ attic init user@hostname:mybackuprepo.attic
# Encrypted remote repository
$ attic init --encryption=passphrase user@hostname:mybackuprepo.attic
usage: attic create [-h] [-v] [-s] [-e PATTERN] [--exclude-from EXCLUDEFILE]
[--exclude-caches] [-c SECONDS]
[--do-not-cross-mountpoints] [--numeric-owner]
ARCHIVE PATH [PATH ...]
Create new archive
positional arguments:
ARCHIVE archive to create
PATH paths to archive
optional arguments:
-h, --help show this help message and exit
-v, --verbose verbose output
-s, --stats print statistics for the created archive
-e PATTERN, --exclude PATTERN
exclude paths matching PATTERN
--exclude-from EXCLUDEFILE
read exclude patterns from EXCLUDEFILE, one per line
--exclude-caches exclude directories that contain a CACHEDIR.TAG file
(http://www.brynosaurus.com/cachedir/spec.html)
-c SECONDS, --checkpoint-interval SECONDS
write checkpoint every SECONDS seconds (Default: 300)
--do-not-cross-mountpoints
do not cross mount points
--numeric-owner only store numeric user and group identifiers
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.
See “attic help patterns” for more help on exclude patterns.
# 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
usage: attic extract [-h] [-v] [-n] [-e PATTERN] [--exclude-from EXCLUDEFILE]
[--numeric-owner]
ARCHIVE [PATH [PATH ...]]
Extract archive contents
positional arguments:
ARCHIVE archive to extract
PATH paths to extract
optional arguments:
-h, --help show this help message and exit
-v, --verbose verbose output
-n, --dry-run do not actually change any files
-e PATTERN, --exclude PATTERN
exclude paths matching PATTERN
--exclude-from EXCLUDEFILE
read exclude patterns from EXCLUDEFILE, one per line
--numeric-owner only obey numeric user and group identifiers
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.
See “attic help patterns” for more help on exclude patterns.
# 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'
usage: attic check [-h] [-v] [--repository-only] [--archives-only] [--repair]
REPOSITORY
Check repository consistency
positional arguments:
REPOSITORY repository to check consistency of
optional arguments:
-h, --help show this help message and exit
-v, --verbose verbose output
--repository-only only perform repository checks
--archives-only only perform archives checks
--repair attempt to repair any inconsistencies found
The check command verifies the consistency of a repository and the corresponding archives. The underlying repository data files are first checked to detect bit rot and other types of damage. After that the consistency and correctness of the archive metadata is verified.
The archive metadata checks can be time consuming and requires access to the key file and/or passphrase if encryption is enabled. These checks can be skipped using the –repository-only option.
usage: attic delete [-h] [-v] [-s] ARCHIVE
Delete an existing archive
positional arguments:
ARCHIVE archive to delete
optional arguments:
-h, --help show this help message and exit
-v, --verbose verbose output
-s, --stats print statistics for the deleted archive
This command deletes an archive from the repository. Any disk space not shared with any other existing archive is also reclaimed.
usage: attic list [-h] [-v] REPOSITORY_OR_ARCHIVE
List archive or repository contents
positional arguments:
REPOSITORY_OR_ARCHIVE
repository/archive to list contents of
optional arguments:
-h, --help show this help message and exit
-v, --verbose verbose output
This command lists the contents of a repository or an archive.
$ 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
...
usage: attic prune [-h] [-v] [-n] [-s] [--keep-within WITHIN] [-H HOURLY]
[-d DAILY] [-w WEEKLY] [-m MONTHLY] [-y YEARLY] [-p PREFIX]
REPOSITORY
Prune repository archives according to specified rules
positional arguments:
REPOSITORY repository to prune
optional arguments:
-h, --help show this help message and exit
-v, --verbose verbose output
-n, --dry-run do not change repository
-s, --stats print statistics for the deleted archive
--keep-within WITHIN keep all archives within this time interval
-H HOURLY, --keep-hourly HOURLY
number of hourly archives to keep
-d DAILY, --keep-daily DAILY
number of daily archives to keep
-w WEEKLY, --keep-weekly WEEKLY
number of weekly archives to keep
-m MONTHLY, --keep-monthly MONTHLY
number of monthly archives to keep
-y YEARLY, --keep-yearly YEARLY
number of yearly archives to keep
-p PREFIX, --prefix PREFIX
only consider archive names starting with this prefix
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.
As an example, “-d 7” means to keep the latest backup on each day for 7 days. Days without backups do not count towards the total. The rules are applied from hourly to yearly, and backups selected by previous rules do not count towards those of later rules. The time that each backup completes is used for pruning purposes. Dates and times are interpreted in the local timezone, and weeks go from Monday to Sunday. Specifying a negative number of archives to keep means that there is no limit.
The “–keep-within” option takes an argument of the form “<int><char>”, where char is “H”, “d”, “w”, “m”, “y”. For example, “–keep-within 2d” means to keep all archives that were created within the past 48 hours. “1m” is taken to mean “31d”. The archives kept with this option do not count towards the totals specified by any other options.
If a prefix is set with -p, then only archives that start with the prefix are considered for deletion and only those archives count towards the totals specified by the rules.
# Keep 7 end of day and 4 additional end of week archives:
$ attic prune /data/myrepo --keep-daily=7 --keep-weekly=4
# Same as above but only apply to archive names starting with "foo":
$ attic prune /data/myrepo --keep-daily=7 --keep-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 --keep-daily=7 --keep-weekly=4 --monthly=-1
# Keep all backups in the last 10 days, 4 additional end of week archives,
# and an end of month archive for every month:
$ attic prune /data/myrepo --keep-within=10d --keep-weekly=4 --monthly=-1
usage: attic info [-h] [-v] ARCHIVE
Show archive details such as disk space used
positional arguments:
ARCHIVE archive to display information about
optional arguments:
-h, --help show this help message and exit
-v, --verbose verbose output
This command displays some detailed information about the specified archive.
$ 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)
usage: attic mount [-h] [-v] [-f] [-o OPTIONS]
REPOSITORY_OR_ARCHIVE MOUNTPOINT
Mount archive or an entire repository as a FUSE fileystem
positional arguments:
REPOSITORY_OR_ARCHIVE
repository/archive to mount
MOUNTPOINT where to mount filesystem
optional arguments:
-h, --help show this help message and exit
-v, --verbose verbose output
-f, --foreground stay in foreground, do not daemonize
-o OPTIONS Extra mount options
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.
$ 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
usage: attic change-passphrase [-h] [-v] REPOSITORY
Change repository key file passphrase
positional arguments:
REPOSITORY
optional arguments:
-h, --help show this help message and exit
-v, --verbose verbose output
The key files used for repository encryption are optionally passphrase protected. This command can be used to change this passphrase.
# Create a key file protected repository
$ attic init --encryption=keyfile /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