AA(1)

NAME
aa - a simple backup utility

SYNOPSIS
aa [options] [command] [AA_SPEC ...]
autoarchive [options] [command] [AA_SPEC ...]

DESCRIPTION

AutoArchive is a simple utility to help create backups more easily. The idea of the program is that all essential information for creating a single backup---such as list of directories that should be archived, the archive name, etc.---is stored in a single file -- the archive specification file <#term-archive-specification-file>. It can use tar(1) for creating archives, it has a command line interface and supports incremental backups.

Archive specification files, also called ".aa files" are normally stored in a predefined location from where they are processed by the aa command which results to creating of a corresponding backup <#term-backup> for each.

Command autoarchive is alias for aa; these commands are equivalent.

OPTIONS

Most of the options can be specified also in configuration files and in the archive specification file <#term-archive-specification-file> (by using the long option form and leaving out leading dashes) -- see aa.conf(5) and aa_arch_spec(5) for complete list of options that can be specified there. Command line options has higher priority than options in configuration files but lower priority than the ones in the archive specification file. --force-* options are available for the purpose of overriding some of the options specified in the .aa file <#term-.aa-file>.

Boolean options can also have a negation form defined. It has the "no-" prefix before the option name. For example: --incremental vs. --no-incremental. The negation form has always higher priority than the normal form.

List of command line options Arguments:

AA_SPEC
    Archive specification. It determines the archive specification file <#term-archive-specification-file> that shall be processed. None, single or multiple AA_SPEC arguments are allowed. If option --all or command --list is specified then no AA_SPEC argument is required. Otherwise at least single AA_SPEC argument is required. If it contains the ".aa" extension then it is taken as the path to an archive specification file. Otherwise, if specified without the extension, the corresponding .aa file <#term-.aa-file> is searched in the archive specifications directory <#term-archive-specifications-directory>.

    Commands:

    Commands for program's operations. The default operation is the backup <#term-backup> creation if no command is specified.

--list
    Show configured <#term-configured-archive> and orphaned archives <#term-orphaned-archive>.

--purge
    Purge stored data for an orphaned archive.

--version
    Show program's version number and exit.

-h, --help
    Show this help message and exit.

    Archiving options:

-a ARCHIVER, --archiver=ARCHIVER
    Specify archiver type. Supported types are: 'tar', 'targz', 'tarbz2', 'tarxz', 'tarzst', 'tar_internal', 'targz_internal', 'tarbz2_internal' (default: targz).

-c NUM, --compression-level=NUM
    Compression strength level. If not specified, default behaviour of underlying compression program will be used. Valid range is from 0 to 9.

-d DIR_PATH, --dest-dir=DIR_PATH
    Directory where the backup <#term-backup> will be created (default: <current directory>).

--overwrite-at-start
    If enabled, backups are overwritten at the start of creation. If disabled (default), backups are overwritten at the end of creation. Enabling this option can be useful with big backups and low free space on the backup volume.

    Let's say aa data command will create backup /backups/data.tar.gz. If a file with the same name already exists in /backups then -- in case this option is enabled -- it will be overwritten as soon as creation of the new backup starts. If the option is not enabled the new backup will be first created under a temporary name leaving the old backup untouched. After the new backup is fully created it is renamed to /backups/data.tar.gz overwriting the old one.

    Incremental archiving options:

-i, --incremental
    Perform incremental backup.

-l LEVEL, --level=LEVEL
    Specify backup level which should be created. All information about higher levels---if any exists---will be erased. If not present, the next level in a row will be created.

--restarting
    Turn on backup level restarting. See other *restart-* options to configure the restarting behaviour.

--restart-after-level=LEVEL
    Maximal backup level. If reached, it will be restarted back to a lower level (which is typically level 1 but it depends on --max-restart-level-size) (default: 10).

--restart-after-age=DAYS
    Number of days after which the backup level is restarted. Similarly to --restart-after-level it will be restarted to level 1 or higher.

--full-restart-after-count=COUNT
    Number of backup level restarts after which the level is restarted to 0.

--full-restart-after-age=DAYS
    Number of days after which the backup level is restarted to 0.

--max-restart-level-size=PERCENTAGE
    Maximal percentage size of a backup <#term-backup> (of level > 0) to which level is allowed restart to. The size is percentage of size of the level 0 backup file. If a backup of particular level has its size bigger than defined percentage, restart to that level will not be allowed.

--remove-obsolete-backups
    Turn on removing backups of levels that are no longer valid due to the backup level restart. All backups of the backup level higher than the one currently being created will be removed.

    Options for keeping old backups

-k, --keep-old-backups
    Turn on backup keeping. When a backup <#term-backup> is about to be overwritten, it is renamed instead. If --incremental is enabled it applies to all corresponding increments <#term-increment>. The new name is created by inserting a keeping ID <#term-keeping-ID> in front of backup file(s) extension. The keeping ID is a string from interval 'aa', 'ab', ..., 'zy', 'zz' where 'aa' represents most recent kept backup.

--number-of-old-backups=NUM
    Number of old backups to keep when --keep-old-backups is enabled (default: 1).

    Command execution options

--command-before-all-backups=COMMAND_BEFORE_ALL
    Arbitrary command that will be executed before backup creation for the set of selected archives. The command will be executed only once in a single invocation of AutoArchive.

--command-after-all-backups=COMMAND_AFTER_ALL
    Arbitrary command that will be executed after backup creation for the set of selected archives. The command will be executed only once in a single invocation of AutoArchive.

--command-before-backup=COMMAND_BEFORE
    Arbitrary command to execute prior to each backup creation.

--command-after-backup=COMMAND_AFTER
    Arbitrary command to execute after each backup creation.

    Format of COMMAND_* arguments is: command [arguments]

    If arguments are specified then the whole expression should be enclosed in quotes. For example:

        --command-before-backup="foo arg1"

    Additionally if an argument contains spaces it should be enclosed as well:

        --command-after-backup="foo arg1 'arg with spaces 2' arg3"

    General options:

-v, --verbose
    Turn on verbose output.

-q, --quiet
    Turn on quiet output. Only errors will be shown. If --quiet is turned on at the same level as --verbose (e. g. both are specified on the command line) then --quiet has higher priority than --verbose.

--all
    Operate on all configured archives <#term-configured-archive> (additional to those specified as AA_SPEC arguments). Default for --list if no AA_SPEC is specified. See also --archive-specs-dir.

--archive-specs-dir=DIR_PATH
    Directory where archive specification files <#term-archive-specification-file> will be searched for (default: <user-config-dir>/archive_specs).

--user-config-file=FILE_PATH
    User configuration file (default: <user-config-dir>/aa.conf).

--user-config-dir=DIR_PATH
    User configuration directory (default: ~/.config/aa).

    Force options:

    Options to override standard options defined in archive specification files.

--force-archiver=ARCHIVER
    Force archiver type. See --archiver option for supported types.

--force-incremental
    Force incremental backup.

--force-restarting
    Force backup level restarting.

--force-compression-level=NUM
    Force compression strength level.

--force-dest-dir=DIR_PATH
    Force the directory where the backup will be created.

--force-command-before-backup=COMMAND_BEFORE
    Force configuration of the command to execute prior to each backup creation.

--force-command-after-backup=COMMAND_AFTER
    Force configuration of the command to execute after each backup creation.

--force-overwrite-at-start
    Force backup overwriting behavior.

    Negation options:

    Negative variants of standard boolean options.

--no-incremental
    Disable incremental backup.

--no-restarting
    Turn off backup level restarting.

--no-remove-obsolete-backups
    Turn off obsolete backups removing.

--no-keep-old-backups
    Turn off backup keeping.

--no-all
    Do not operate on all configured archives <#term-configured-archive>.

--no-overwrite-at-start
    Do not overwrite backup at the start of creation. Overwrite after the new backup is created.

EXIT CODES

AutoArchive can return following exit codes:

•   0: The operation finished successfully.

•   1: The operation finished with minor (warnings) or major (errors) issues.

FILES

<user-config-dir>/aa.conf
    User configuration file. See aa.conf(5) for its description.

<archive-specs-dir>/*.aa
    Archive specification files <#term-archive-specification-file>. See aa_arch_spec(5) for description of the .aa file <#term-.aa-file> format.

<user-config-dir>/snapshots/*.snar
    Files that stores information about incremental backup. They are created by GNU tar archiver.

<user-config-dir>/storage/*.realm
    Application internal persistent storage. It stores various data needed to be preserved between program runs. For example: last backup level restart, number of backup level restart, etc.

/etc/aa/aa.conf
    System configuration file. See aa.conf(5) for its description.

EXAMPLES

Let's make a backup <#term-backup> of configuration files of all users except the user "foo". Let's assume that our system has unix-like style of home directories (directory "/home" contains directories of all users; configuration files begins with dot). Name of this backup will be "user-configs".

First, we need to create the file "user-configs.aa" under the "~/.config/aa/archive_specs/" directory - this is the archive specification file <#term-archive-specification-file>. The file doesn't need to have the same name as the backup <#term-backup>. If it does however, the option name can be left out (in this example we specified it anyway, even it is not needed).

In the path variable we specify the archive root which is the the base directory which content we want to backup.

Variables include-files and exclude-files contains list of files and directories that we want to be included or excluded respectively. In this example we specify */.* pattern because we want to include home directories of all users (such as /home/bob, /home/joe, etc.), what the first * is for. And from within those user home directories we want to include everything that begins with . (for example /home/bob/.bashrc), what the .* pattern is for. Paths specified in these variables are relative to path.

Although, yet we do not want to include all user home directories as we specified in include-files. Those directories that should not be included we put in exclude-files ("foo" in this example, which makes /home/foo excluded). If we would not want to exclude any file then the corresponding variable would be specified as exclude-files =.

Content of the "user-configs.aa" file:

    # ------ begin of user-configs.aa ------
    # AutoArchive's archive specification file for users configuration files
    [Content]
    name = user-configs
    path = /home
    include-files = */.*
    exclude-files = foo
    [Archive]
    dest-dir = /mnt/backup
    # ------ end of user-configs.aa ------

Once we configured the archive <#term-archive> we can create the backup <#term-backup> easily with command:

    aa user-configs

and in the "/mnt/backup" directory the file "user-configs.tar.gz" will be created.

Given the "user-configs.aa" example file above, the command:

    aa -i user-configs

will create level 0 incremental backup -- "user-configs.tar.gz" which is essentially the same as a non-incremental backup. Another execution of the same command will create level 1 backup named "user-configs.1.tar.gz" which contains only a differences from level 0. Each subsequent call will create a next level which will contain only a differences from previous.

In order to restart to level 0 again, thus create a fresh full backup, the following command can be used:

    aa -i -l 0 user-configs

Note that you should remove all previously created "user-configs" backups with level <#term-level> higher than 0 because they are no longer valid in regards to the newly created level 0 backup. You may pass --remove-obsolete-backups option to the command above and they will be removed automatically.

  Backup Keeping

We assume that all previously created backups were removed in order to demonstrate the backup keeping.

First we create a standard backup:

    aa user-configs

This creates "user-configs.tar.gz" backup. Some days later let's say, we want to create the same backup again. However we do not want to overwrite the original one. The option -k can be used to keep the original backup:

    aa -k user-configs

This will rename the original backup to "user-configs.aa.tar.gz" and create the new one "user-configs.tar.gz". If we create the same backup for the third time (still using the -k) option, "user-configs.aa.tar.gz" will be removed, "user-configs.tar.gz" will be renamed to "user-configs.aa.tar.gz" and the new "user-configs.tar.gz" will be created. So AutoArchive by default keeps single old backup when -k options is specified. To keep more, e.g. four backups we would specify --number-of-old-backups=4 alongside with -k.

Incremental backups can be kept as well. Again, we assume that all previously created backups were removed. Let's create a few levels of incremental "user-configs" archive:

    aa -i -l 0 user-configs
    aa -i user-configs
    aa -i user-configs
    aa -i user-configs

This will create following files:

    user-configs.tar.gz
    user-configs.1.tar.gz
    user-configs.2.tar.gz
    user-configs.3.tar.gz

Then we (manually) restart to level 2 while asking to keep old backups:

    aa -i -l 2 -k user-configs

After this command following files will be present:

    user-configs.tar.gz
    user-configs.1.tar.gz
    user-configs.2.tar.gz
    user-configs.2.aa.tar.gz
    user-configs.3.aa.tar.gz

Let's explain what happened. The original file "user-configs.2.tar.gz" was going to be overwritten therefore it was renamed to "user-configs.2.aa.tar.gz". As all backup levels higher than the renamed one depends on it they have to be renamed as well. In this example "user-configs.3.tar.gz" depends on "user-configs.2.tar.gz" therefore it was renamed to "user-configs.3.aa.tar.gz". Finally the new increment <#term-increment> "user-configs.2.tar.gz" was created.

LICENSE

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <<http://www.gnu.org/licenses/>>.

SEE ALSO

aa.conf(5), aa_arch_spec(5), tar(1), gzip(1), bzip2(1), xz(1), zstd(1)

Copyright
2003 - 2025, Robert Cernansky