obnam(1) obnam(1) NAME obnam - online backup tool SYNOPSIS obnam backup [options] directory obnam generations [options] obnam show-generations [options] generation-id obnam restore [options] generation-id [pathname] obnam forget [options] generation-id obnam write-config [options] DESCRIPTION obnam is a tool to do off-site backups over computer networks. It backs files up using the rsync algorithm, for efficiency, and encrypts the backups before sending data over the network to be stored on a remote server, for security. Backups may be stored in a directory on the local file system or re‐ motely on an SFTP server. The server location is given as a URL, of one of the the following formats: sftp://user@host:port/absolute/path or sftp://user@host:port/~/path/relative/to/home/dir. In either case, us‐ er is the username on the remote host (can be left out if same as on local host), and port is the numeric port number to connect to (again, can be left out if default SSH/SFTP port is OK). Also, if the remote home directory is used as storage, the path (in either form) can be left out. In the following examples, the remote username is ulla, the host name is example.com, and the remote directory is either /srv/backups/ulla or safe in the remote home directory. The port is always the default SSH and SFTP port. sftp://example.com/srv/backups/ulla sftp://ulla@example.com/srv/backups/ulla sftp://example.com/~/safe sftp://ulla@example.com/~/safe In the examples, the first two lines refer to the same location (assum‐ ing the local username is also ulla), and so do the last two. OPTIONS --block-size=SIZE Make blocks that are about SIZE kilobytes. -C DIR, --target=DIR Resolve filenames relative to DIR. --cache=DIR Store cached blocks in DIR. --config=FILE In addition to any other configuration files, also read FILE, after the other files have been read. --exclude=REGEXP Exclude pathnames matching REGEXP. --generation-times With the generations command, show also the start and end times of each generation (in the UTC time zone, also known as GMT). Note that this means the operation runs slower, since it needs to download more data from the store. --gpg-encrypt-to=KEYID Add KEYID to list of keys to use for encryption. --gpg-home=DIR Use DIR as the location for GnuPG keyrings and other data files. --gpg-sign-with=KEYID Sign backups with KEYID. -h, --help Show help message and exit. --host-id=ID Use ID to identify the client host. This can be any arbitrary string, but defaults to the hostname. You usually don’t need to set this, except when viewing or restoring backups for another client host. --log-file=FILE Append log messages to FILE. --log-level=LEVEL Set log level to LEVEL, one of debug, info, warning, error, critical (default is warning). --no-configs Do not read any default configuration files, only those explic‐ itly named with --config. --no-gpg Don’t use gpg at all. --object-cache-size=COUNT Set object cache maximum size to COUNT objects (default depends on block size. --odirect-pipe=DIR Use DIR as the odirect_pipe program (default is helper that avoids buffer cache). --odirect-read=PROGRAM Use PROGRAM to read contents of plain files (default is helper that avoids buffer cache). --progress Report progress of backups as they’re made. --ssh-key=FILE Read ssh private key from FILE (and public key from FILE.pub). --store=LOCATION Use LOCATION for storing the backups. LOCATION is either a di‐ rectory name on the local file system, or an SFTP url. See above in "DESCRIPTION" for an explanation. --version Print out name and version of program. CONFIGURATION FILES obnam looks for several configuration files when it starts up. The list of files depends on whether it is started by the root user, or some other user. See the FILES section for the list. Each file is read if it exists, and ignored if it does not. Each file may change the configura‐ tion variables, the effect is cumulative. The files follow the "INI" file syntax, as defined by the Python Con‐ figParser class. The following is an example, which lists all configu‐ ration variables: [backup] block-size = 1048576 cache = tmp.cache exclude = generation-times = false gpg-encrypt-to = 490C9ED1 gpg-home = sample-gpg-home gpg-sign-with = 490C9ED1 host-id = dorfl log-file = log-level = warning no-gpg = false odirect-pipe = ./odirect_pipe odirect-read = ./odirect_read ssh-key = ssh-key store = tmp.store The syntax is slightly extended from the standard syntax: you can list multiple values for one value with the += operator. For example, if you want to have multiple exclude values, write this: exclude = first exclude += second exclude += third This multi-value syntax is useful only with exclude at the moment. The variables correspond to the options of the same names. EXAMPLES The following examples assume you have configured obnam using a config‐ uration file so that it knows where to store backups, and so on. This way, the sample command lines are not burdened with unnecessary de‐ tails. To back up your home directory use the following command: obnam backup $HOME This works for the initial generation and every new generation. Each new generation is backed up as if it were a full backup, but files that existed in the previous generation are backed up using the rsync algo‐ rithm, and only the changes since the previous generation are uploaded and stored. When restoring, this distinction is, however, invisible to the user. The changes from the previous version are computed when a file with the same name exists in the previous generation, and its size, change time (mtime), owner, group, link count, or permissions have changed. To list the generations that currently exist, use one of the following commands: obnam generations obnam generations --generation-times The former is faster, and the latter shows the times when the genera‐ tions were made. The generations are shown in the order they were made, the newest one being last. Each generation is identified by a Univer‐ sally Unique IDentifier, or UUID. To see the files in a generation, use the following command: obnam show-generations GENERATION-ID Here GENERATION-ID is one of the UUIDs that the obnam generations com‐ mand showed. The file list is similar to the output of ls -l. To restore an entire generation from the, use the following command: obnam restore GENERATION-ID --target=DIR To restore just a few files (or directories, including their files) add them to the end of the command line: obnam restore GENERATION-ID --target=DIR README src/main.c Here, GENERATION-ID is again the UUID shown by obnam generations, and DIR is the directory under which the restored files will be placed. To avoid problems with overwriting files, it is best to choose a new di‐ rectory as DIR if possible. To forget (remove) a generation, use the following command: obnam forget GENERATION-ID This will remove the generation (you can give several at once, if you want). It will also remove any files in the store that are not part of any non-forgotten generations. Any parts of incremental backups (rsync file deltas) from forgotten generations that are needed to re-create remaining generations are kept even if the rest of the generations are deleted. FILES /usr/share/obnam/obnam.conf First configuration file obnam reads if it exists. /etc/obnam/obnam.conf For the root user, the second configuration file obnam reads if it exists. ~/.obnam/obnam.conf For other users, the second configuration file obnam reads if it exists. 2007-03-21 obnam(1)