Usage

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.

Quiet by default

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.

attic init

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

Description

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.

Examples

# 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

attic create

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

Description

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.

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

attic extract

usage: attic extract [-h] [-v] [-n] [-e PATTERN] [--exclude-from EXCLUDEFILE]
                     [--numeric-owner] [--strip-components NUMBER]
                     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
  --strip-components NUMBER
                        Remove the specified number of leading path elements.
                        Pathnames with fewer elements will be silently
                        skipped.

Description

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.

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'

attic check

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

Description

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.

attic delete

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

Description

This command deletes an archive from the repository. Any disk space not shared with any other existing archive is also reclaimed.

attic list

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

Description

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
...

attic prune

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

Description

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.

Examples

# 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 --keep-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 --keep-monthly=-1

attic info

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

Description

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)

attic mount

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

Description

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

attic change-passphrase

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

Description

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 --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