1OBNAM(1) General Commands Manual OBNAM(1)
2
6 obnam - make, restore, and manipulate backups
7
9 obnam [--always-restore-setuid] [--no-always-restore-setuid]
10 [--checkpoint=SIZE] [--checksum-algorithm=CHECKSUM]
11 [--chunk-bag-size=SIZE] [--chunk-cache-size=SIZE] [--chunk-size=SIZE]
12 [--chunkids-per-group=NUM] [--client-name=CLIENT-NAME]
13 [--compress-with=PROGRAM] [--config=FILE] [--dump-config]
14 [--dump-setting-names] [--generate-manpage=TEMPLATE] [-h] [--help]
15 [--help-all] [--list-config-files] [--version] [--no-default-configs]
16 [--crash-limit=COUNTER] [--critical-age=AGE] [--deduplicate=MODE]
17 [--dir-bag-size=SIZE] [--dir-cache-size=SIZE]
18 [--dump-memory-profile=METHOD] [--dump-repo-file-metadata]
19 [--no-dump-repo-file-metadata] [--encrypt-with=ENCRYPT-WITH]
20 [--exclude=EXCLUDE] [--exclude-caches] [--no-exclude-caches]
21 [--exclude-from=FILE] [--fsck-fix] [--no-fsck-fix]
22 [--fsck-ignore-chunks] [--no-fsck-ignore-chunks]
23 [--fsck-ignore-client=NAME] [--fsck-last-generation-only]
24 [--no-fsck-last-generation-only] [--fsck-rm-unused]
25 [--no-fsck-rm-unused] [--fsck-skip-checksums]
26 [--no-fsck-skip-checksums] [--fsck-skip-dirs] [--no-fsck-skip-dirs]
27 [--fsck-skip-files] [--no-fsck-skip-files] [--fsck-skip-generations]
28 [--no-fsck-skip-generations] [--fsck-skip-per-client-b-trees]
29 [--no-fsck-skip-per-client-b-trees] [--fsck-skip-shared-b-trees]
30 [--no-fsck-skip-shared-b-trees] [--fuse-opt=FUSE]
31 [--generation=GENERATION] [--gnupghome=HOMEDIR]
32 [--idpath-bits=IDPATH-BITS] [--idpath-depth=IDPATH-DEPTH]
33 [--idpath-skip=IDPATH-SKIP] [--include=INCLUDE] [--keep=KEEP]
34 [--key-details] [--no-key-details] [--keyid=KEYID]
35 [--leave-checkpoints] [--no-leave-checkpoints] [--lock-timeout=TIMEOUT]
36 [--log=FILE] [--log-keep=N] [--log-level=LEVEL] [--log-max=SIZE]
37 [--log-mode=MODE] [--lru-size=SIZE] [--memory-dump-interval=SECONDS]
38 [--node-size=SIZE] [--one-file-system] [--no-one-file-system]
39 [--output=FILE] [--pretend] [--dry-run] [--no-act] [--no-pretend]
40 [--no-dry-run] [--no-no-act] [--pretend-time=TIMESTAMP]
41 [--pure-paramiko] [--no-pure-paramiko] [--quiet] [--silent]
42 [--no-quiet] [--no-silent] [-rURL] [--repository=URL]
43 [--repository-format=FORMAT] [--root=URL] [--sftp-delay=SFTP-DELAY]
44 [--small-files-in-btree] [--no-small-files-in-btree]
45 [--ssh-command=EXECUTABLE] [--ssh-host-keys-check=VALUE]
46 [--ssh-key=FILENAME] [--ssh-known-hosts=FILENAME]
47 [--strict-ssh-host-keys] [--no-strict-ssh-host-keys]
48 [--symmetric-key-bits=BITS] [--testing-fail-matching=REGEXP] [--to=TO]
49 [--trace=TRACE] [--upload-queue-size=SIZE] [--verbose] [--no-verbose]
50 [--verify-randomly=N] [--warn-age=AGE] [--weak-random]
51 [--no-weak-random]
52 obnam [options] _lock
54 obnam [options] add-key [CLIENT-NAME]...
55 obnam [options] backup [DIRECTORY|URL]...
56 obnam [options] client-keys
57 obnam [options] clients
58 obnam [options] diff [GENERATION1]GENERATION2
59 obnam [options] dump-repo
60 obnam [options] force-lock
61 obnam [options] forget [GENERATION]...
62 obnam [options] fsck
63 obnam [options] generations
64 obnam [options] genids
65 obnam [options] help
66 obnam [options] help-all
67 obnam [options] kdirstat [FILE]...
68 obnam [options] list-errors
69 obnam [options] list-formats
70 obnam [options] list-keys
71 obnam [options] list-toplevels
72 obnam [options] ls [FILE]...
73 obnam [options] mount [ROOT]
74 obnam [options] nagios-last-backup-age
75 obnam [options] remove-client [CLIENT-NAME]...
76 obnam [options] remove-key [CLIENT-NAME]...
77 obnam [options] restore [DIRECTORY]...
78 obnam [options] verify [DIRECTORY]...
79
81 obnam makes, restores, manipulates, and otherwise deals with backups.
82 It can store backups on a local disk or to a server via sftp. Every
83 backup generation looks like a fresh snapshot, but is really incremen‐
84 tal: the user does not need to worry whether it's a full backup or not.
85 Only changed data is backed up, and if a chunk of data is already
86 backed up in another file, that data is re-used.
87 The place where backed up data is placed is called the backup reposito‐
89 ry. A repository may be, for example, a directory on an sftp server,
90 or a directory on a USB hard disk. A single repository may contain
91 backups from several clients. Their data will intermingle as if they
92 were using separate repositories, but if one client backs up a file,
93 the others may re-use the data.
94 obnam command line syntax consists of a command possibly followed by
96 arguments. The commands are list below.
97 · backup makes a new backup. The first time it is run, it makes a
99 full backup, after that an incremental one.
100 · restore is the opposite of a backup. It copies backed up data
102 from the backup repository to a target directory. You can re‐
103 store everything in a generation, or just selected files.
104 · clients lists the clients that are backed up to the repository.
106 · generations lists every backup generation for a given client,
108 plus some metadata about the generation.
109 · genids lists the identifier for every backup generation for a
111 given client. No other information is shown. This can be use‐
112 ful for scripting.
113 · ls lists the contents of a given generation, similar to ls -lAR.
115 · kdirstat lists the contents of a given generation, in a format
117 which is compatible with the kdirstat cache file format, which
118 can then be used to visualise the contents of a backup.
119 · verify compares data in the backup with actual user data, and
121 makes sure they are identical. It is most useful to run immedi‐
122 ately after a backup, to check that it actually worked. It can
123 be run at any time, but if the user data has changed, verifica‐
124 tion fails even though the backup is OK.
125 · forget removes backup generations that are no longer wanted, so
127 that they don't use disk space. Note that after a backup gener‐
128 ation is removed the data can't be restored anymore. You can
129 either specify the generations to remove by listing them on the
130 command line, or use the --keep option to specify a policy for
131 what to keep (everything else will be removed).
132 · fsck checks the internal consistency of the backup repository.
134 It verifies that all clients, generations, directories, files,
135 and all file contents still exists in the backup repository. It
136 may take quite a long time to run.
137 · force-lock removes lock files for aall clients in the reposito‐
139 ry. You should only force a lock if you are sure no client is
140 accessing the repository. A dangling lock might happen, for ex‐
141 ample, if "obnam backup" loses its network connection to the
142 backup repository.
143 · client-keys lists the encryption key associated with each
145 client.
146 · list-keys lists the keys that can access the repository, and
148 which toplevel directories each key can access. Some of the
149 toplevel directories are shared between clients, others are spe‐
150 cific to a client.
151 · list-toplevels is like list-keys, but lists toplevels and which
153 keys can access them.
154 · add-key adds an encryption key to the repository. By default,
156 the key is added only to the shared toplevel directories, but it
157 can also be added to specific clients: list the names of the
158 clients on the command line. They key is given with the --keyid
159 option. Whoever has access to the secret key corresponding to
160 the key id can access the backup repository (the shared
161 toplevels plus specified clients).
162 · remove-key removes a key from the shared toplevel directories,
164 plus any clients specified on the command line.
165 · nagios-last-backup-age is a check that exits with non-zero re‐
167 turn if a backup age exceeds a certain threshold. It is suit‐
168 able for use as a check plugin for nagios. Thresholds can be
169 given the --warn-age and --critical-age options.
170 · diff compares two generations and lists files differing between
172 them. Every output line will be prefixed either by a plus sign
173 (+) for files that were added, a minus sign (-) for files that
174 have been removed or an asterisk (*) for files that have
175 changed. If only one generation ID is specified on the command
176 line that generation will be compared with its direct predeces‐
177 sor. If two IDs have been specified, all changes between those
178 two generations will be listed.
179 · mount makes the backup repository available via a read-only FUSE
181 filesystem. Each backup generation is visible as a subdirecto‐
182 ry, named after the generation id. This means you can look at
183 backed up data using normal tools, such as your GUI file manag‐
184 er, or command line tools such as ls(1), diff(1), and cp(1).
185 You can't make new backups with the mount subcommand, but you
186 can restore data easily.
187 You need to have the FUSE utilities and have permission to use
189 FUSE for this to work. The details will vary between operating
190 systems; in Debian, install the package fuse and add yourself to
191 the fuse group (you may need to log out and back in again).
192 Making backups
194 When you run a backup, obnam uploads data into the backup repository.
195 The data is divided into chunks, and if a chunk already exists in the
196 backup repository, it is not uploaded again. This allows obnam to deal
197 with files that have been changed or renamed since the previous backup
198 run. It also allows several backup clients to avoid uploading the same
199 data. If, for example, everyone in the office has a copy of the same
200 sales brochures, only one copy needs to be stored in the backup reposi‐
201 tory.
202 Every backup run is a generation. In addition, obnam will make check‐
204 point generations every now and then. These are exactly like normal
205 generations, but are not guaranteed to be a complete snapshot of the
206 live data. If the backup run needs to be aborted in the middle, the
207 next backup run can continue from the latest checkpoint, avoiding the
208 need to start over from scratch.
209 If one backup run drops a backup root directory, the older generations
211 will still keep it: nothing changes in the old generations just because
212 there is a new one. If the root was dropped by mistake, it can be
213 added back and the next backup run will re-use the existing data in the
214 backup repository, and will only back up the file metadata (filenames,
215 permissions, etc).
216 Verifying backups
218 What good is a backup system you cannot rely on? How can you rely on
219 something you cannot test? The obnam verify command checks that data
220 in the backup repository matches actual user data. It retrieves one or
221 more files from the repository and compares them to the user data.
222 This is essentially the same as doing a restore, then comparing re‐
223 stored files with the original files using cmp(1), but easier to use.
224 By default, verification happens on all files. You can also specify
226 the files to be verified by listing them on the command line. You
227 should specify the full paths to the files, not relative to the current
228 directory.
229 The output lists files that fail verification for some reason. If you
231 verify everything, it is likely that some files (e.g., parent directo‐
232 ries of backup root) may have changed without it being a problem. Note
233 that you will need to specify the whole path to the files or directo‐
234 ries to be verified, not relative to the backup root. You still need
235 to specify at least one of the backup roots on the command line or via
236 the --root option so that obnam will find the filesystem, in case it is
237 a remote one.
238 URL syntax
240 Whenever obnam accepts a URL, it can be either a local pathname, or an
241 sftp URL. An sftp URL has the following form:
242 sftp://[user@]domain[:port]/path
244 where domain is a normal Internet domain name for a server, user is
246 your username on that server, port is an optional port number, and path
247 is a pathname on the server side. Like bzr(1), but unlike the sftp URL
248 standard, the pathname is absolute, unless it starts with /~/ in which
249 case it is relative to the user's home directory on the server.
250 See the EXAMPLE section for examples of URLs.
252 You can use sftp URLs for the repository, or the live data (root), but
254 note that due to limitations in the protocol, and its implementation in
255 the paramiko library, some things will not work very well for accessing
256 live data over sftp. Most importantly, the handling of of hardlinks is
257 rather suboptimal. For live data access, you should not end the URL
258 with /~/ and should append a dot at the end in this special case.
259 Generation specifications
261 When not using the latest generation, you will need to specify which
262 one you need. This will be done with the --generation option, which
263 takes a generation specification as its argument. The specification is
264 either the word latest, meaning the latest generation (also the de‐
265 fault), or a number. See the generations command to see what genera‐
266 tions are available, and what their numbers are.
267 Policy for keeping and removing backup generations
269 The forget command can follow a policy to automatically keep some and
270 remove other backup generations. The policy is set with the
271 --keep=POLICY option.
272 POLICY is comma-separated list of rules. Each rule consists of a count
274 and a time period. The time periods are h, d, w, m, and y, for hour,
275 day, week, month, and year.
276 A policy of 30d means to keep the latest backup for each day when a
278 backup was made, and keep the last 30 such backups. Any backup matched
279 by any policy rule is kept, and any backups in between will be removed,
280 as will any backups older than the oldest kept backup.
281 As an example, assume backups are taken every hour, on the hour: at
283 00:00, 01:00, 02:00, and so on, until 23:00. If the forget command is
284 run at 23:15, with the above policy, it will keep the backup taken at
285 23:00 on each day, and remove every other backup that day. It will al‐
286 so remove backups older than 30 days.
287 If backups are made every other day, at noon, forget would keep the 30
289 last backups, or 60 days worth of backups, with the above policy.
290 Note that obnam will only inspect timestamps in the backup repository,
292 and does not care what the actual current time is. This means that if
293 you stop making new backups, the existing ones won't be removed auto‐
294 matically. In essence, obnam pretends the current time is just after
295 the latest backup when forget is run.
296 The rules can be given in any order, but will be sorted to ascending
298 order of time period before applied. (It is an error to give two rules
299 for the same period.) A backup generation is kept if it matches any
300 rule.
301 For example, assume the same backup frequency as above, but a policy of
303 30d,52w. This will keep the newest daily backup for each day for thir‐
304 ty days, and the newest weekly backup for 52 weeks. Because the hourly
305 backups will be removed daily, before they have a chance to get saved
306 by a weekly rule, the effect is that the 23:00 o'clock backup for each
307 day is saved for a month, and the 23:00 backup on Sundays is saved for
308 a year.
309 If, instead, you use a policy of 72h,30d,52w, obnam would keep the last
311 72 hourly backups, and the last backup of each calendar day for 30
312 days, and the last backup of each calendar week for 52 weeks. If the
313 backup frequency was once per day, obnam would keep the backup of each
314 calendar hour for which a backup was made, for 72 such backups. In
315 other words, it would effectively keep the last 72 daily backups.
316 Sound confusing? Just think how confused the developer was when writ‐
318 ing the code.
319 If no policy is given, forget will keep everything.
321 A typical policy might be 72h,7d,5w,12m, which means: keep the last 72
323 hourly backups, the last 7 daily backups, the last 5 weekly backups and
324 the last 12 monthly backups. If the backups are systematically run on
325 an hourly basis, this will mean keeping hourly backups for three days,
326 daily backups for a week, weekly backups for a month, and monthly back‐
327 ups for a year.
328 The way the policy works is a bit complicated. Run forget with the
330 --pretend option to make sure you're removing the right ones.
331 Using encryption
333 obnam can encrypt all the data it writes to the backup repository. It
334 uses gpg(1) to do the encryption. You need to create a key pair using
335 gpg --gen-key (or use an existing one), and then tell obnam about it
336 using the --encrypt-with option. You may optionally use a separate
337 home directory using the --gnupghome option. By default, the default
338 directory for gpg(1) will be used.
339 Configuration files
341 obnam will look for configuration files in a number of locations. See
342 the FILES section for a list. All these files together are treated as
343 one big file with the contents of all files concatenated.
344 The files are in INI format, and only the [config] section is used (any
346 other sections are ignored).
347 The long names of options are used as keys for configuration variables.
349 Any setting that can be set from the command line can be set in a con‐
350 figuration file, in the [config] section.
351 For example, the options in the following command line:
353 obnam --repository=/backup --exclude='.wav$' backup
355 could be replaced with the following configuration file:
357 [config]
359 repository: /backup
360 exclude: .wav$
361 (You can use either foo=value or foo: value syntax in the files.)
363 The only unusual thing about the files is the way options that can be
365 used many times are expressed. All values are put in a single logical
366 line, separated by commas (and optionally spaces as well). For exam‐
367 ple:
368 [config]
370 exclude = foo, bar, \.mp3$
371 The above has three values for the exclude option: any files that con‐
373 tain the words foo or bar anywhere in the fully qualified pathname, or
374 files with names ending with a period and mp3 (because the exclusions
375 are regular expressions).
376 A long logical line can be broken into several physical ones, by start‐
378 ing a new line at white space, and indenting the continuation lines:
379 [config]
381 exclude = foo,
382 bar,
383 \.mp3$
384 The above example adds three exclusion patterns.
386 Multiple clients and locking
388 obnam supports sharing a repository between multiple clients. The
389 clients can share the file contents (chunks), so that if client A backs
390 up a large file, and client B has the same file, then B does not need
391 to upload the large file to the repository a second time. For this to
392 work without confusion, the clients use a simple locking protocol that
393 allows only one client at a time to modify the shared data structures.
394 Locks do not prevent read-only access at the same time: this allows you
395 to restore while someone else is backing up.
396 Sometimes a read-only operation happens to access a data structure at
398 the same time as it is being modified. This can result in a crash. It
399 will not result in corrupt data, or incorrect restores. However, you
400 may need to restart the read-only operation after a crash.
401
403 --always-restore-setuid
404 restore setuid/setgid bits in restored files, even if not root
405 or backed up file had different owner than user running restore
406 --no-always-restore-setuid
408 opposite of --always-restore-setuid
409 --checksum-algorithm=CHECKSUM
411 use CHECKSUM for checksum algorithm (not for repository format
412 6); one of: sha512, sha224, sha256, sha384
413 --client-name=CLIENT-NAME
415 name of client (defaults to hostname)
416 --compress-with=PROGRAM
418 use PROGRAM to compress repository with (one of none, deflate)
419 --critical-age=AGE
421 for nagios-last-backup-age: maximum age (by default in hours)
422 for the most recent backup before statis is critical. Accepts
423 one char unit specifier (s,m,h,d for seconds, minutes, hours,
424 and days.
425 --dump-repo-file-metadata
427 dump metadata about files?
428 --no-dump-repo-file-metadata
430 opposite of --dump-repo-file-metadata
431 --generate-manpage=TEMPLATE
433 fill in manual page TEMPLATE
434 --generation=GENERATION
436 which generation to restore
437 -h, --help
439 show this help message and exit
440 --keep=KEEP
442 policy for what generations to keep when forgetting
443 --lock-timeout=TIMEOUT
445 when locking in the backup repository, wait TIMEOUT seconds for
446 an existing lock to go away before giving up
447 --output=FILE
449 write output to FILE, instead of standard output
450 --pretend, --dry-run, --no-act
452 do not actually change anything (works with backup, forget and
453 restore only, and may only simulate approximately real behavior)
454 --no-pretend, --no-dry-run, --no-no-act
456 opposite of --pretend
457 --quiet, --silent
459 be silent: show only error messages, no progress updates
460 --no-quiet, --no-silent
462 opposite of --quiet
463 -r, --repository=URL
465 name of backup repository (can be pathname or supported URL)
466 --repository-format=FORMAT
468 use FORMAT for new repositories; one of "6", "green-alba‐
469 tross-20160813"
470 --to=TO
472 where to restore or FUSE mount; for restores, must be empty or
473 must not exist
474 --verbose
476 be verbose: tell the user more of what is going on and generally
477 make sure the user is aware of what is happening or at least
478 that something is happening and also make sure their screen is
479 getting updates frequently and that there is changes happening
480 all the time so they do not get bored and that they in fact get
481 frustrated by getting distracted by so many updates that they
482 will move into the Gobi desert to live under a rock
483 --no-verbose
485 opposite of --verbose
486 --verify-randomly=N
488 verify N files randomly from the backup (default is zero, mean‐
489 ing everything)
490 --version
492 show program's version number and exit
493 --warn-age=AGE
495 for nagios-last-backup-age: maximum age (by default in hours)
496 for the most recent backup before status is warning. Accepts one
497 char unit specifier (s,m,h,d for seconds, minutes, hours, and
498 days.
499 Backing up
501 --checkpoint=SIZE
502 make a checkpoint after a given SIZE
503 --deduplicate=MODE
505 find duplicate data in backed up data and store it only once;
506 three modes are available: never de-duplicate, verify that no
507 hash collisions happen, or (the default) fatalistically accept
508 the risk of collisions
509 --exclude=EXCLUDE
511 regular expression for pathnames to exclude from backup (can be
512 used multiple times)
513 --exclude-caches
515 exclude directories (and their subdirs) that contain a
516 CACHEDIR.TAG file (see
517 http://www.brynosaurus.com/cachedir/spec.html for what it needs
518 to contain, and http://liw.fi/cachedir/ for a helper tool)
519 --no-exclude-caches
521 opposite of --exclude-caches
522 --exclude-from=FILE
524 read exclude patterns from FILE
525 --include=INCLUDE
527 regular expression for pathnames to include from backup even if
528 it matches an exclude rule (can be used multiple times)
529 --leave-checkpoints
531 leave checkpoint generations at the end of a successful backup
532 run
533 --no-leave-checkpoints
535 opposite of --leave-checkpoints
536 --one-file-system
538 exclude directories (and their subdirs) that are in a different
539 filesystem
540 --no-one-file-system
542 opposite of --one-file-system
543 --root=URL
545 what to backup
546 --small-files-in-btree
548 this is available only for backwards compatibility; do not use
549 it, and remove it from your configuration
550 --no-small-files-in-btree
552 opposite of --small-files-in-btree
553 Configuration files and settings
555 --config=FILE
556 add FILE to config files
557 --dump-config
559 write out the entire current configuration
560 --dump-setting-names
562 write out all names of settings and quit
563 --help-all
565 show all options
566 --list-config-files
568 list all possible config files
569 --no-default-configs
571 clear list of configuration files to read
572 Development of Obnam itself
574 --crash-limit=COUNTER
575 artificially crash the program after COUNTER files written to
576 the repository; this is useful for crash testing the applica‐
577 tion, and should not be enabled for real use; set to 0 to dis‐
578 able (disabled by default)
579 --pretend-time=TIMESTAMP
581 pretend it is TIMESTAMP (YYYY-MM-DD HH:MM:SS); this is only use‐
582 ful for testing purposes
583 --sftp-delay=SFTP-DELAY
585 add an artificial delay (in milliseconds) to all SFTP transfers
586 --testing-fail-matching=REGEXP
588 development testing helper: simulate failures during backup for
589 files that match the given regular expressions
590 --trace=TRACE
592 add to filename patters for which trace debugging logging hap‐
593 pens
594 Encryption
596 --encrypt-with=ENCRYPT-WITH
597 PGP key with which to encrypt data in the backup repository
598 --gnupghome=HOMEDIR
600 home directory for GPG
601 --key-details
603 show additional user IDs for all keys
604 --no-key-details
606 opposite of --key-details
607 --keyid=KEYID
609 PGP key id to add to/remove from the backup repository
610 --symmetric-key-bits=BITS
612 size of symmetric key, in bits
613 --weak-random
615 use /dev/urandom instead of /dev/random to generate symmetric
616 keys
617 --no-weak-random
619 opposite of --weak-random
620 Integrity checking (fsck)
622 --fsck-fix
623 should fsck try to fix problems? Implies --fsck-rm-unused
624 --no-fsck-fix
626 opposite of --fsck-fix
627 --fsck-ignore-chunks
629 ignore chunks when checking repository integrity (assume all
630 chunks exist and are correct)
631 --no-fsck-ignore-chunks
633 opposite of --fsck-ignore-chunks
634 --fsck-ignore-client=NAME
636 do not check repository data for client NAME
637 --fsck-last-generation-only
639 check only the last generation for each client
640 --no-fsck-last-generation-only
642 opposite of --fsck-last-generation-only
643 --fsck-rm-unused
645 should fsck remove unused chunks?
646 --no-fsck-rm-unused
648 opposite of --fsck-rm-unused
649 --fsck-skip-checksums
651 do not check checksums of files
652 --no-fsck-skip-checksums
654 opposite of --fsck-skip-checksums
655 --fsck-skip-dirs
657 do not check anything about directories and their files
658 --no-fsck-skip-dirs
660 opposite of --fsck-skip-dirs
661 --fsck-skip-files
663 do not check anything about files
664 --no-fsck-skip-files
666 opposite of --fsck-skip-files
667 --fsck-skip-generations
669 do not check any generations
670 --no-fsck-skip-generations
672 opposite of --fsck-skip-generations
673 --fsck-skip-per-client-b-trees
675 do not check per-client B-trees
676 --no-fsck-skip-per-client-b-trees
678 opposite of --fsck-skip-per-client-b-trees
679 --fsck-skip-shared-b-trees
681 do not check shared B-trees
682 --no-fsck-skip-shared-b-trees
684 opposite of --fsck-skip-shared-b-trees
685 Logging
687 --log=FILE
688 write log entries to FILE (default is to not write log files at
689 all); use "syslog" to log to system log, "stderr" to log to the
690 standard error output, or "none" to disable logging
691 --log-keep=N
693 keep last N logs (10)
694 --log-level=LEVEL
696 log at LEVEL, one of debug, info, warning, error, critical, fa‐
697 tal (default: info)
698 --log-max=SIZE
700 rotate logs larger than SIZE, zero for never (default: 0)
701 --log-mode=MODE
703 set permissions of new log files to MODE (octal; default 0600)
704 Mounting with FUSE
706 --fuse-opt=FUSE
707 options to pass directly to Fuse
708 Peformance
710 --dump-memory-profile=METHOD
711 make memory profiling dumps using METHOD, which is one of: none,
712 simple, or meliae (default: simple)
713 --memory-dump-interval=SECONDS
715 make memory profiling dumps at least SECONDS apart
716 Performance tweaking
718 --chunk-size=SIZE
719 size of chunks of file data backed up
720 --chunkids-per-group=NUM
722 encode NUM chunk ids per group
723 --idpath-bits=IDPATH-BITS
725 chunk id level size
726 --idpath-depth=IDPATH-DEPTH
728 depth of chunk id mapping
729 --idpath-skip=IDPATH-SKIP
731 chunk id mapping lowest bits skip
732 --lru-size=SIZE
734 size of LRU cache for B-tree nodes
735 --node-size=SIZE
737 size of B-tree nodes on disk; only affects new B-trees so you
738 may need to delete a client or repository to change this for ex‐
739 isting repositories
740 --upload-queue-size=SIZE
742 length of upload queue for B-tree nodes
743 Repository format green-albatross
745 --chunk-bag-size=SIZE
746 approximate maximum size of bag combining many chunk objects
747 --chunk-cache-size=SIZE
749 size of in-memory cache for file data chunk objects
750 --dir-bag-size=SIZE
752 approximate maximum size of bags combining many DIR objects
753 --dir-cache-size=SIZE
755 size of in-memory cache for DIR objects
756 SSH/SFTP
758 --pure-paramiko
759 do not use openssh even if available, use paramiko only instead
760 --no-pure-paramiko
762 opposite of --pure-paramiko
763 --ssh-command=EXECUTABLE
765 alternative executable to be used instead of "ssh" (full path is
766 allowed, no arguments may be added)
767 --ssh-host-keys-check=VALUE
769 If "yes", require that the ssh host key must be known and cor‐
770 rect to be accepted. If "no", do not require that. If "ask", the
771 user is interactively asked to accept new hosts. The default
772 ("ssh-config") is to rely on the settings of the underlying SSH
773 client
774 --ssh-key=FILENAME
776 use FILENAME as the ssh RSA private key for sftp access (default
777 is using keys known to ssh-agent)
778 --ssh-known-hosts=FILENAME
780 filename of the user's known hosts file
781 --strict-ssh-host-keys
783 DEPRECATED, use --ssh-host-keys-check instead
784 --no-strict-ssh-host-keys
786 opposite of --strict-ssh-host-keys
787 Option values
789 The SIZE value in options mentioned above specifies a size in bytes,
790 with optional suffixes to indicate kilobytes (k), kibibytes (Ki),
791 megabytes (M), mebibyts (Mi), gigabytes (G), gibibytes (Gi), terabytes
792 (T), tibibytes (Ti). The suffixes are case-insensitive.
793
795 obnam will exit with zero if everything went well, and non-zero other‐
796 wise.
797
799 obnam will pass on the environment it gets from its parent, without
800 modification. It does not obey any unusual environment variables, but
801 it does obey the usual ones when running external programs, creating
802 temporary files, etc.
803
805 /etc/obnam.conf
806 /etc/obnam/*.conf
807 ~/.obnam.conf
808 ~/.config/obnam/*.conf
809 Configuration files for obnam. It is not an error for any or
810 all of the files to not exist.
811
813 To back up your home directory to a server:
814 obnam backup --repository sftp://your.server/~/backups $HOME
816 To restore your latest backup from the server:
818 obnam restore --repository sftp://your.server/~/backups \
820 --to /var/tmp/my.home.dir
821 To restore just one file or directory:
823 obnam restore --repository sftp://your.server/~/backups \
825 --to /var/tmp/my.home.dir $HOME/myfile.txt
826 Alternatively, mount the backup repository using the FUSE filesystem
828 (note that the --to option is necessary):
829 mkdir my-repo
831 obnam mount --repository sftp://your.server/~/backups \
832 --to my-repo
833 cp my-repo/latest/$HOME/myfile.txt
834 fusermount -u my-repo
835 To check that the backup worked:
837 obnam verify --repository sftp://your.server/~/backups \
839 /path/to/file
840 To remove old backups, keeping the newest backup for each day for
842 ten years:
843 obnam forget --repository sftp://your.server/~/backups \
845 --keep 3650d
846 To verify that the backup repository is OK:
848 obnam fsck --repository sftp://your.server/~/backups
850 To view the backed up files in the backup repository using FUSE:
852 obnam mount --to my-fuse
854 ls -lh my-fuse
855 fusermount -u my-fuse
856
858 obnam comes with a manual in HTML and PDF forms. See
859 /usr/share/doc/obnam if you have Obnam installed system-wide, or in the
860 subdirectory manual in the source tree.
861 cliapp(5)
863 OBNAM(1)