1AA(1) AutoArchive AA(1)
2
6 aa - a simple backup utility
7
9 aa [options] [command] [AA_SPEC]...
10 autoarchive [options] [command] [AA_SPEC]...
11
14 AutoArchive is a simple utility to help create backups more easily.
15 The idea of the program is that all essential information for creating
16 a single backup---such as list of directories that should be archived,
17 the archive name, etc.---is stored in a single file -- the archive
18 specification file. It can use tar(1) for creating archives, it has a
19 command line interface and supports incremental backups.
20 Archive specification files, also called ".aa files" are normally
22 stored in a predefined location from where they are processed by the aa
23 command which results to creating of a corresponding backup for each.
24 Command autoarchive is alias for aa; these commands are equivalent.
26
28 Most of the options can be specified also in configuration files and in
29 the archive specification file (by using the long option form and leav‐
30 ing out leading dashes) -- see aa.conf(5) and aa_arch_spec(5) for com‐
31 plete list of options that can be specified there. Command line
32 options has higher priority than options in configuration files but
33 lower priority than the ones in the archive specification file.
34 --force-* options are available for the purpose of overriding some of
35 the options specified in the .aa file.
36 Boolean options can also have a negation form defined. It has the
38 "no-" prefix before the option name. For example: --incremental vs.
39 --no-incremental. The negation form has always higher priority than
40 the normal form.
41 List of command line options
43 Commands:
44 Commands for program's operations. The default operation is the
46 backup creation if no command is specified.
47 --list Show all configured or orphaned archives.
49 --purge
51 Purge stored data for an orphaned archive.
52 --version
54 Show program's version number and exit.
55 -h, --help
57 Show this help message and exit.
58 General options:
60 -v, --verbose
62 Turn on verbose output.
63 -q, --quiet
65 Turn on quiet output. Only errors will be shown. If --quiet
66 is turned on at the same level as --verbose (e. g. both are
67 specified on the command line) then --quiet has higher prior‐
68 ity than --verbose.
69 --all Operate on all configured archives. See also --ar‐
71 chive-specs-dir.
72 --archive-specs-dir=DIR_PATH
74 Directory where archive specification files will be searched
75 for (default: ~/.config/aa/archive_specs).
76 --user-config-file=FILE_PATH
78 Alternate user configuration file (default: ~/.con‐
79 fig/aa/aa.conf).
80 --user-config-dir=DIR_PATH
82 Alternate user configuration directory (default: ~/.con‐
83 fig/aa).
84 Archiving options:
86 -a ARCHIVER, --archiver=ARCHIVER
88 Specify archiver type. Supported types are: 'tar', 'targz',
89 'tarbz2', 'tarxz', 'tar_internal', 'targz_internal',
90 'tarbz2_internal' (default: targz).
91 -c NUM, --compression-level=NUM
93 Compression strength level. If not specified, default behav‐
94 iour of underlying compression program will be used.
95 -d DIR_PATH, --dest-dir=DIR_PATH
97 Directory where the backup will be created (default: <current
98 directory>).
99 --overwrite-at-start
101 If enabled, backups are overwritten at the start of creation.
102 If disabled (default), backups are overwritten at the end of
103 creation. Enabling this option can be useful with big back‐
104 ups and low free space on the backup volume.
105 Let's say aa data command will create backup /back‐
107 ups/data.tar.gz. If a file with the same name already exists
108 in /backups then -- in case this option is enabled -- it will
109 be overwritten as soon as creation of the new backup starts.
110 If the option is not enabled the new backup will be first
111 created under a temporary name leaving the old backup
112 untouched. After the new backup is fully created it is
113 renamed to /backups/data.tar.gz overwriting the old one.
114 Incremental archiving options:
116 -i, --incremental
118 Perform incremental backup.
119 -l LEVEL, --level=LEVEL
121 Specify backup level which should be created. All informa‐
122 tion about higher levels---if any exists---will be erased.
123 If not present, the next level in a row will be created.
124 --restarting
126 Turn on backup level restarting. See other *restart-*
127 options to configure the restarting behaviour.
128 --restart-after-level=LEVEL
130 Maximal backup level. If reached, it will be restarted back
131 to a lower level (which is typically level 1 but it depends
132 on --max-restart-level-size) (default: 10).
133 --restart-after-age=DAYS
135 Number of days after which the backup level is restarted.
136 Similarly to --restart-after-level it will be restarted to
137 level 1 or higher.
138 --full-restart-after-count=COUNT
140 Number of backup level restarts after which the level is
141 restarted to 0.
142 --full-restart-after-age=DAYS
144 Number of days after which the backup level is restarted to
145 0.
146 --max-restart-level-size=PERCENTAGE
148 Maximal percentage size of a backup (of level > 0) to which
149 level is allowed restart to. The size is percentage of size
150 of the level 0 backup file. If a backup of particular level
151 has its size bigger than defined percentage, restart to that
152 level will not be allowed.
153 --remove-obsolete-backups
155 Turn on removing backups of levels that are no longer valid
156 due to the backup level restart. All backups of the backup
157 level higher than the one currently being created will be
158 removed.
159 Options for keeping old backups
161 -k, --keep-old-backups
163 Turn on backup keeping. When a backup is about to be over‐
164 written, it is renamed instead. If --incremental is enabled
165 it applies to all corresponding increments. The new name is
166 created by inserting a keeping ID in front of backup file(s)
167 extension. The keeping ID is a string from interval 'aa',
168 'ab', ..., 'zy', 'zz' where 'aa' represents most recent kept
169 backup.
170 --number-of-old-backups=NUM
172 Number of old backups to keep when --keep-old-backups is
173 enabled (default: 1).
174 Command execution options
176 --command-before-all-backups=COMMAND_BEFORE_ALL
178 Arbitrary command that will be executed before backup cre‐
179 ation for the set of selected archives. The command will be
180 executed only once in a single invocation of AutoArchive.
181 --command-after-all-backups=COMMAND_AFTER_ALL
183 Arbitrary command that will be executed after backup creation
184 for the set of selected archives. The command will be exe‐
185 cuted only once in a single invocation of AutoArchive.
186 --command-before-backup=COMMAND_BEFORE
188 Arbitrary command to execute prior to each backup creation.
189 --command-after-backup=COMMAND_AFTER
191 Arbitrary command to execute after each backup creation.
192 Format of COMMAND_* arguments is:
194 command [arguments]
195 If arguments are specified then the whole expression should be
197 enclosed in quotes. For example:
198 --command-before-backup="foo arg1"
200 Additionally if an argument contains spaces it should be enclosed as
202 well:
203 --command-after-backup="foo arg1 'arg with spaces 2' arg3"
205 Force options:
207 Options to override standard options defined in archive specifica‐
209 tion files.
210 --force-archiver=ARCHIVER
212 Force archiver type. Supported types are: 'tar', 'targz',
213 'tarbz2', 'tarxz', 'tar_internal', 'targz_internal',
214 'tarbz2_internal'.
215 --force-incremental
217 Force incremental backup.
218 --force-restarting
220 Force backup level restarting.
221 --force-compression-level=NUM
223 Force compression strength level.
224 --force-dest-dir=DIR_PATH
226 Force the directory where the backup will be created.
227 --force-command-before-backup=COMMAND_BEFORE
229 Force configuration of the command to execute prior to each
230 backup creation.
231 --force-command-after-backup=COMMAND_AFTER
233 Force configuration of the command to execute after each
234 backup creation.
235 --force-overwrite-at-start
237 Force backup overwriting behavior.
238 Negation options:
240 Negative variants of standard boolean options.
242 --no-incremental
244 Disable incremental backup.
245 --no-restarting
247 Turn off backup level restarting.
248 --no-remove-obsolete-backups
250 Turn off obsolete backups removing.
251 --no-keep-old-backups
253 Turn off backup keeping.
254 --no-all
256 Do not operate on all configured archives.
257 --no-overwrite-at-start
259 Do not overwrite backup at the start of creation. Overwrite
260 after the new backup is created.
261 AA_SPEC is the archive specification file argument. It determines the
263 archive specification file that shall be processed. None, single or
264 multiple AA_SPEC arguments are allowed. If option --all or command
265 --list is specified then no AA_SPEC argument is required. Otherwise at
266 least single AA_SPEC argument is required. If it contains the ".aa"
267 extension then it is taken as the path to an archive specification
268 file. Otherwise, if specified without the extension, the corresponding
269 .aa file is searched in the archive specifications directory.
270
272 AutoArchive can return following exit codes:
273 · 0: The operation finished successfully.
275 · 1: The operation finished with minor (warnings) or major (errors)
277 issues.
278
280 ~/.config/aa/aa.conf
281 User configuration file. See aa.conf(5) for its description.
282 ~/.config/aa/archive_specs/
284 Default directory that contains archive specification files.
285 See aa_arch_spec(5) for description of the .aa file format.
286 ~/.config/aa/snapshots/*.snar
288 Files that stores information about incremental backup. They
289 are created by GNU tar archiver.
290 ~/.config/aa/storage/*.realm
292 Application internal persistent storage. It stores various data
293 needed to be preserved between program runs. For example: last
294 backup level restart, number of backup level restart, etc.
295 /etc/aa/aa.conf
297 System configuration file. See aa.conf(5) for its description.
298
300 Let's make a backup of configuration files of all users except the user
301 "foo". Let's assume that our system has unix-like style of home direc‐
302 tories (directory "/home" contains directories of all users; configura‐
303 tion files begins with dot). Name of this backup will be "user-con‐
304 figs".
305 First, we need to create the file "user-configs.aa" under the "~/.con‐
307 fig/aa/archive_specs/" directory - this is the archive specification
308 file. The file doesn't need to have the same name as the backup. If
309 it does however, the option name can be left out (in this example we
310 specified it anyway, even it is not needed).
311 In the path variable we specify the archive root which is the the base
313 directory which content we want to backup.
314 Variables include-files and exclude-files contains list of files and
316 directories that we want to be included or excluded respectively. In
317 this example we specify */.* pattern because we want to include home
318 directories of all users (such as /home/bob, /home/joe, etc.), what the
319 first * is for. And from within those user home directories we want to
320 include everything that begins with . (for example /home/bob/.bashrc),
321 what the .* pattern is for. Paths specified in these variables are
322 relative to path.
323 Although, yet we do not want to include all user home directories as we
325 specified in include-files. Those directories that should not be
326 included we put in exclude-files ("foo" in this example, which makes
327 /home/foo excluded). If we would not want to exclude any file then the
328 corresponding variable would be specified as exclude-files =.
329 Content of the "user-configs.aa" file:
331 # ------ begin of user-configs.aa ------
333 # AutoArchive's archive specification file for users configuration files
334 [Content]
335 name = user-configs
336 path = /home
337 include-files = */.*
338 exclude-files = foo
339 [Archive]
341 dest-dir = /mnt/backup
342 # ------ end of user-configs.aa ------
343 Once we configured the archive we can create the backup easily with
345 command:
346 aa user-configs
348 and in the "/mnt/backup" directory the file "user-configs.tar.gz" will
350 be created.
351 Given the "user-configs.aa" example file above, the command:
353 aa -i user-configs
355 will create level 0 incremental backup -- "user-configs.tar.gz" which
357 is essentially the same as a non-incremental backup. Another execution
358 of the same command will create level 1 backup named "user-con‐
359 figs.1.tar.gz" which contains only a differences from level 0. Each
360 subsequent call will create a next level which will contain only a dif‐
361 ferences from previous.
362 In order to restart to level 0 again, thus create a fresh full backup,
364 the following command can be used:
365 aa -i -l 0 user-configs
367 Note that you should remove all previously created "user-configs" back‐
369 ups with level higher than 0 because they are no longer valid in
370 regards to the newly created level 0 backup. You may pass
371 --remove-obsolete-backups option to the command above and they will be
372 removed automatically.
373 Backup Keeping
375 We assume that all previously created backups were removed in order to
376 demonstrate the backup keeping.
377 First we create a standard backup:
379 aa user-configs
381 This creates "user-configs.tar.gz" backup. Some days later let's say,
383 we want to create the same backup again. However we do not want to
384 overwrite the original one. The option -k can be used to keep the
385 original backup:
386 aa -k user-configs
388 This will rename the original backup to "user-configs.aa.tar.gz" and
390 create the new one "user-configs.tar.gz". If we create the same backup
391 for the third time (still using the -k) option, "user-con‐
392 figs.aa.tar.gz" will be removed, "user-configs.tar.gz" will be renamed
393 to "user-configs.aa.tar.gz" and the new "user-configs.tar.gz" will be
394 created. So AutoArchive by default keeps single old backup when -k
395 options is specified. To keep more, e.g. four backups we would specify
396 --number-of-old-backups=4 alongside with -k.
397 Incremental backups can be kept as well. Again, we assume that all
399 previously created backups were removed. Let's create a few levels of
400 incremental "user-configs" archive:
401 aa -i -l 0 user-configs
403 aa -i user-configs
404 aa -i user-configs
405 aa -i user-configs
406 This will create following files:
408 user-configs.tar.gz
410 user-configs.1.tar.gz
411 user-configs.2.tar.gz
412 user-configs.3.tar.gz
413 Then we (manually) restart to level 2 while asking to keep old backups:
415 aa -i -l 2 -k user-configs
417 After this command following files will be present:
419 user-configs.tar.gz
421 user-configs.1.tar.gz
422 user-configs.2.tar.gz
423 user-configs.2.aa.tar.gz
424 user-configs.3.aa.tar.gz
425 Let's explain what happened. The original file "user-configs.2.tar.gz"
427 was going to be overwritten therefore it was renamed to "user-con‐
428 figs.2.aa.tar.gz". As all backup levels higher than the renamed one
429 depends on it they have to be renamed as well. In this example
430 "user-configs.3.tar.gz" depends on "user-configs.2.tar.gz" therefore it
431 was renamed to "user-configs.3.aa.tar.gz". Finally the new increment
432 "user-configs.2.tar.gz" was created.
433
435 This program is free software: you can redistribute it and/or modify it
436 under the terms of the GNU General Public License version 3 as pub‐
437 lished by the Free Software Foundation.
438 This program is distributed in the hope that it will be useful, but
440 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
441 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
442 Public License for more details.
443 You should have received a copy of the GNU General Public License along
445 with this program. If not, see <http://www.gnu.org/licenses/>.
446
448 aa.conf(5), aa_arch_spec(5), tar(1), gzip(1), bzip2(1), xz(1)
449
451 2003 - 2017, Robert Cernansky
4521.4.1 Sep 22, 2017 AA(1)