AA_ARCH_SPEC(5)

NAME
aa_arch_spec - Archive Specification File

SYNOPSIS

<archive-specs-dir>/*.aa

DESCRIPTION

Archive specification file <#term-archive-specification-file> contains all information needed for creation of a single archive.

FILE FORMAT

Options in the .aa file <#term-.aa-file> are divided into sections. A section begins with the section name enclosed in square brackets. It contains variables which represents the options.

Variables are written in the option-name = value form, one variable per line. Boolean values are written as yes and no. For path values, tilde (~) is expanded to the user's home. Form option-name = can be used to specify a variable with undefined value.

Values of include-files and exclude-files options that contains spaces has to be enclosed in double quotes (""). They may contain standard shell wildcards.

When specifying the value it is possible to refer to other variables from the same file using the form %(variable-name)s or variables from an external file using the form @(external-name.variable-name) where external-name is reference which has to be defined in [External] section.

Lines beginning with # or ; are ignored and may be used for comments.

Three sections are valid: [External, [Archive] (optional) and [Content].

  Section [External]

This section contains definition of external references. Each reference is put on a single line. They can be specified by two forms: as a single variable or as a variable = path pair.

If single variable is specified it refers to archive specification file <#term-archive-specification-file> of the same name as the variable but without the '.aa' extension. The file is searched in the archive specifications directory <#term-archive-specifications-directory>.

The variable = path form allows to refer a file from an arbitrary location by specifying its absolute or relative path. Paths are relative to the directory of the original file. In both cases variable name is used in the reference. See Examples for the example of the .aa file <#term-.aa-file> with external references.

  Section [Archive]

This section can contain configuration options which are, when specified, overriding the ones specified in configuration files and command line.

Options valid in the [Archive] section:

•   archiver

•   compression-level

•   dest-dir

•   overwrite-at-start

•   incremental

•   restarting

•   restart-after-level

•   restart-after-age

•   full-restart-after-count

•   full-restart-after-age

•   max-restart-level-size

•   remove-obsolete-backups

•   keep-old-backups

•   number-of-old-backups

•   command-before-backup

•   command-after-backup

    See aa(1) for their description.

  Section [Content]

This section contains options specific to an archive. All options except name are required.

Options valid in the [Content] section:

•   name

    Archive name. Created backup <#term-backup> will be named according value of this variable plus appropriate extension. It is optional; default value is the name of the .aa file <#term-.aa-file> without the extension.

•   path

    Path to archive root. All paths and file names specified in the same archive specification file will be relative to this path. It will be also the root of the created archive.

•   include-files

    List of space separated file or directory names to backup. Paths here are relative to the path specified in path variable above. Starting forward slash (/) from absolute paths as well as parent directory tokens (..) will be ignored.

•   exclude-files

    List of space separated file or directory names to be excluded from the backup. Use exclude-files = to specify that no files should be excluded. Similarly to include-files these paths are relative to path.

EXAMPLES

In this example we want to configure archive <#term-archive> for "/data" directory backups <#term-backup>. There will be two locations where backups are stored. One is a large capacity NAS mounted at "/mnt/nas", the other is a smaller external disk mounted at "/mnt/backup_disk".

Below is content of two archive specification files <#term-archive-specification-file> for this use case. The first one configures archive "data-nas" for NAS storage destination. Second file configures archive "data-disk" for external disk location. It is taking all values except dest-dir from the "data-nas.aa" file via external references. Additionally it excludes "videos" directory so that backup will fit to disk.

    # ------ begin of data-nas.aa ------
    [Content]
    path = /
    include-files = data-nas
    exclude-files =
    [Archive]
    dest-dir = /mnt/nas
    # ------ end of data-nas.aa ------

    # ------ begin of data-disk.aa ------
    [External]
    data-nas
    [Content]
    path = @(data-nas.path)
    include-files = @(data-nas.include-files)
    exclude-files = @(data-nas.exclude-files) videos
    [Archive]
    dest-dir = /mnt/backup_disk
    # ------ end of data-disk.aa ------

  Specifying path to the external file

Would the "data-nas.aa" file in previous example be in a different directory than archive specifications directory <#term-archive-specifications-directory> its path had to be specified:

    # ------ begin of data-disk.aa ------
    [External]
    data-nas = /path/to/data-nas.aa
    [Content]
    # ...
    # ------ end of data-disk.aa ------

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(1), aa.conf(5)

Copyright
2003 - 2025, Robert Cernansky