1AA(1) AutoArchive AA(1)
2
3
4
6 aa - a simple backup utility
7
9 aa [options] [command] [AA_SPEC]...
10 autoarchive [options] [command] [AA_SPEC]...
11
12
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
21 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
25 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
37 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
42 List of command line options
43 Commands:
44
45 Commands for program's operations. The default operation is the
46 backup creation if no command is specified.
47
48 --list Show all configured or orphaned archives.
49
50 --purge
51 Purge stored data for an orphaned archive.
52
53 --version
54 Show program's version number and exit.
55
56 -h, --help
57 Show this help message and exit.
58
59 Archiving options:
60
61 -a ARCHIVER, --archiver=ARCHIVER
62 Specify archiver type. Supported types are: 'tar', 'targz',
63 'tarbz2', 'tarxz', 'tar_internal', 'targz_internal',
64 'tarbz2_internal' (default: targz).
65
66 -c NUM, --compression-level=NUM
67 Compression strength level. If not specified, default behav‐
68 iour of underlying compression program will be used.
69
70 -d DIR_PATH, --dest-dir=DIR_PATH
71 Directory where the backup will be created (default: <current
72 directory>).
73
74 Incremental archiving options:
75
76 -i, --incremental
77 Perform incremental backup.
78
79 -l LEVEL, --level=LEVEL
80 Specify backup level which should be created. All informa‐
81 tion about higher levels---if any exists---will be erased.
82 If not present, the next level in a row will be created.
83
84 --restarting
85 Turn on backup level restarting. See other *restart-*
86 options to configure the restarting behaviour.
87
88 --restart-after-level=LEVEL
89 Maximal backup level. If reached, it will be restarted back
90 to a lower level (which is typically level 1 but it depends
91 on --max-restart-level-size) (default: 10).
92
93 --restart-after-age=DAYS
94 Number of days after which the backup level is restarted.
95 Similarly to --restart-after-level it will be restarted to
96 level 1 or higher.
97
98 --full-restart-after-count=COUNT
99 Number of backup level restarts after which the level is
100 restarted to 0.
101
102 --full-restart-after-age=DAYS
103 Number of days after which the backup level is restarted to
104 0.
105
106 --max-restart-level-size=PERCENTAGE
107 Maximal percentage size of a backup (of level > 0) to which
108 level is allowed restart to. The size is percentage of size
109 of the level 0 backup file. If a backup of particular level
110 has its size bigger than defined percentage, restart to that
111 level will not be allowed.
112
113 --remove-obsolete-backups
114 Turn on removing backups of levels that are no longer valid
115 due to the backup level restart. All backups of the backup
116 level higher than the one currently being created will be
117 removed.
118
119 Options for keeping old backups
120
121 -k, --keep-old-backups
122 Turn on backup keeping. When a backup is about to be over‐
123 written, it is renamed instead. If --incremental is enabled
124 it applies to all corresponding increments. The new name is
125 created by inserting a keeping ID in front of backup file(s)
126 extension. The keeping ID is a string from interval 'aa',
127 'ab', ..., 'zy', 'zz' where 'aa' represents most recent kept
128 backup.
129
130 --number-of-old-backups=NUM
131 Number of old backups to keep when --keep-old-backups is
132 enabled (default: 1).
133
134 Command execution options
135
136 --command-before-all-backups=COMMAND_BEFORE_ALL
137 Arbitrary command that will be executed before backup cre‐
138 ation for the set of selected archives. The command will be
139 executed only once in a single invocation of AutoArchive.
140
141 --command-after-all-backups=COMMAND_AFTER_ALL
142 Arbitrary command that will be executed after backup creation
143 for the set of selected archives. The command will be exe‐
144 cuted only once in a single invocation of AutoArchive.
145
146 --command-before-backup=COMMAND_BEFORE
147 Arbitrary command to execute prior to each backup creation.
148
149 --command-after-backup=COMMAND_AFTER
150 Arbitrary command to execute after each backup creation.
151
152 Format of COMMAND_* arguments is:
153 command [arguments]
154
155 If arguments are specified then the whole expression should be
156 enclosed in quotes. For example:
157
158 --command-before-backup="foo arg1"
159
160 Additionally if an argument contains spaces it should be enclosed as
161 well:
162
163 --command-after-backup="foo arg1 'arg with spaces 2' arg3"
164
165 General options:
166
167 -v, --verbose
168 Turn on verbose output.
169
170 -q, --quiet
171 Turn on quiet output. Only errors will be shown. If --quiet
172 is turned on at the same level as --verbose (e. g. both are
173 specified on the command line) then --quiet has higher prior‐
174 ity than --verbose.
175
176 --all Operate on all configured archives. See also --ar‐
177 chive-specs-dir.
178
179 --overwrite-at-start
180 If enabled, backups are overwritten at the start of creation.
181 If disabled (default), backups are overwritten at the end of
182 creation. Enabling this option can be useful with big back‐
183 ups and low free space on the backup volume.
184
185 Let's say aa data command will create backup /back‐
186 ups/data.tar.gz. If a file with the same name already exists
187 in /backups then -- in case this option is enabled -- it will
188 be overwritten as soon as creation of the new backup starts.
189 If the option is not enabled the new backup will be first
190 created under a temporary name leaving the old backup
191 untouched. After the new backup is fully created it is
192 renamed to /backups/data.tar.gz overwriting the old one.
193
194 --archive-specs-dir=DIR_PATH
195 Directory where archive specification files will be searched
196 for (default: ~/.config/aa/archive_specs).
197
198 --user-config-file=FILE_PATH
199 Alternate user configuration file (default: ~/.con‐
200 fig/aa/aa.conf).
201
202 --user-config-dir=DIR_PATH
203 Alternate user configuration directory (default: ~/.con‐
204 fig/aa).
205
206 Force options:
207
208 Options to override standard options defined in archive specifica‐
209 tion files.
210
211 --force-archiver=ARCHIVER
212 Force archiver type. Supported types are: 'tar', 'targz',
213 'tarbz2', 'tarxz', 'tar_internal', 'targz_internal',
214 'tarbz2_internal'.
215
216 --force-incremental
217 Force incremental backup.
218
219 --force-restarting
220 Force backup level restarting.
221
222 --force-compression-level=NUM
223 Force compression strength level.
224
225 --force-dest-dir=DIR_PATH
226 Force the directory where the backup will be created.
227
228 --force-command-before-backup=COMMAND_BEFORE
229 Force configuration of the command to execute prior to each
230 backup creation.
231
232 --force-command-after-backup=COMMAND_AFTER
233 Force configuration of the command to execute after each
234 backup creation.
235
236 --force-overwrite-at-start
237 Force backup overwriting behavior.
238
239 Negation options:
240
241 Negative variants of standard boolean options.
242
243 --no-incremental
244 Disable incremental backup.
245
246 --no-restarting
247 Turn off backup level restarting.
248
249 --no-remove-obsolete-backups
250 Turn off obsolete backups removing.
251
252 --no-keep-old-backups
253 Turn off backup keeping.
254
255 --no-all
256 Do not operate on all configured archives.
257
258 --no-overwrite-at-start
259 Do not overwrite backup at the start of creation. Overwrite
260 after the new backup is created.
261
262 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
274 · 0: The operation finished successfully.
275
276 · 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
283 ~/.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
287 ~/.config/aa/snapshots/*.snar
288 Files that stores information about incremental backup. They
289 are created by GNU tar archiver.
290
291 ~/.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
296 /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
306 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
312 In the path variable we specify the archive root which is the the base
313 directory which content we want to backup.
314
315 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
324 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
330 Content of the "user-configs.aa" file:
331
332 # ------ 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
340 [Archive]
341 dest-dir = /mnt/backup
342 # ------ end of user-configs.aa ------
343
344 Once we configured the archive we can create the backup easily with
345 command:
346
347 aa user-configs
348
349 and in the "/mnt/backup" directory the file "user-configs.tar.gz" will
350 be created.
351
352 Given the "user-configs.aa" example file above, the command:
353
354 aa -i user-configs
355
356 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
363 In order to restart to level 0 again, thus create a fresh full backup,
364 the following command can be used:
365
366 aa -i -l 0 user-configs
367
368 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
374 Backup Keeping
375 We assume that all previously created backups were removed in order to
376 demonstrate the backup keeping.
377
378 First we create a standard backup:
379
380 aa user-configs
381
382 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
387 aa -k user-configs
388
389 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
398 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
402 aa -i -l 0 user-configs
403 aa -i user-configs
404 aa -i user-configs
405 aa -i user-configs
406
407 This will create following files:
408
409 user-configs.tar.gz
410 user-configs.1.tar.gz
411 user-configs.2.tar.gz
412 user-configs.3.tar.gz
413
414 Then we (manually) restart to level 2 while asking to keep old backups:
415
416 aa -i -l 2 -k user-configs
417
418 After this command following files will be present:
419
420 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
426 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
439 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
444 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 - 2016, Robert Cernansky
452
453
454
455
4561.3.0 November 09, 2016 AA(1)