path: root/obnam.1

.TH OBNAM 1
.SH NAME
obnam \- make, restore, and manipulate backups
.SH SYNOPSIS
.B obnam
.RI [ options ]
.I command
.RI [ args ]...
.SH DESCRIPTION
.B obnam
makes, restores, manipulates, and otherwise deals with backups.
It can store backups on a local disk or to a server via sftp.
Every backup generation looks like a fresh snapshot,
but is really incremental:
the user does not need to worry whether it's a full backup or not.
Only changed data is backed up,
and if a chunk of data is already backed up in another file,
that data is re-used.
.PP
The place where backed up data is placed is called the
backup store, or
.I store
for short.
A store may be, for example, a directory on an sftp server,
or a directory on a USB hard disk.
A single store may contain backups from several hosts.
Their data will intermingle as if they were using separate stores,
but if one host backs up a file, the others may re-use the data.
.PP
.B obnam 
command line syntax consists of a 
.I command
possibly followed by arguments.
The commands are:
.BR backup ,
.BR restore ,
.BR hosts ,
.BR generations ,
.BR ls ,
.BR verify ,
.BR forget ,
and
.BR fsck .
.IP \(bu
.B backup
makes a new backup.
The first time it is run, it makes a full backup,
after that an incremental one.
.IP \(bu
.B restore
is the opposite of a backup.
It copies backed up data from the backup store to a target directory.
.IP \(bu
.B hosts
lists the hosts that are backed up to the store.
.IP \(bu
.B generations
lists every backup generation for a given host.
.IP \(bu
.B ls
lists the contents of a given generation, similar to 
.BR ls -lAR .
.IP \(bu
.B verify
compares data in the backup with actual user data,
and makes sures they are identical.
It is most useful to run immediately after a backup,
to check that it actually worked.
It can be run at any time,
but if the user data has changed,
verification fails even though the backup is OK.
.IP \(bu
.B forget
removes backup generations that are no longer wanted,
so that they don't use disk space.
Note that after a backup generation is removed
the data can't be restored anymore.
You can either specify the generations to remove by listing them
on the command line,
or use the
.B --keep
option to specify a policy for what to keep (everything else will
be removed).
.IP \(bu
.B fsck
checks the internal consistency of the backup store.
It verifies that all hosts, generations, directories, files, and
all file contents still exists in the backup store.
It may take quite a long time to run.
.SS "Verifying backups"
What good is a backup system you cannot rely on?
How can you rely on something you cannot test?
The
.B "obnam verify"
command checks that data in the backup store matches actual user data.
It retrieves one or more files from the store and compares them to
the user data.
This is essentialy the same as doing a restore,
then comparing restored files with the original files using 
.BR cmp (1),
but easier to use.
.PP
By default verification happens on all files.
You can also specify the files to be verified by listing them on the
command line.
.PP
The output lists files that fail verification for some reason.
If you verify everything, it is likely that some files (e.g.,
parent directories of backup root) may have changed without it
being a problem.
Note that you will need to specify the whole path to the files
or directories to be verified, not relative to the backup root.
You still need to specify at least one of the backup roots via
the
.B --root
option so that obnam will find the filesystem, in case it is
a remote one.
.SS "URL syntax"
Whenever obnam accepts a URL, it can be either a local pathname,
or an 
.B sftp
URL.
An sftp URL has the following form:
.IP
.BI sftp:// domain\fR[\fB:\fIport\fR] / path
.PP
where 
.I domain
is a normal Internetl domain name,
.I port
is an optional port number,
and
.I path
is a pathname on the server side.
Like
.BR bzr (1),
but unlike the sftp URL standard,
the pathname is absolute,
unless it starts with
.B /~/
in which case it is relative to the user's home directory on the server.
.PP
See the EXAMPLES section for examples of URLs.
.SS "Generation specifications"
When not using the latest generation,
you will need to specify which one you need.
This will be done with the
.B --generation
option,
which takes a generation specification as its argument.
The specification is either the word
.IR latest ,
meaning the latest generation (also the default),
or a number.
See the
.B generations
command to see what generations are available,
and what their numbers are.
.SS "Policy for keeping and removing backup generations"
The
.B forget
command can follow a policy to automatically keep some and remove
other backup generations.
The policy is set with the
.BR --keep =\fIPOLICY
option.
.PP
.I POLICY
is comma-separated list of rules.
Each rule consists of a count and a time period.
The time periods are 
.BR h ,
.BR d ,
.BR w ,
.BR m ,
and
.BR y ,
for hour, day, week, month, and year.
.PP
A policy of
.I 30d
means to keep the latest backup for each day, for thirty days.
Any backups in between will be removed,
as will any backups older than thirty days.
.PP
As an example, assume backups are taken every hour, on the hour:
at 00:00, 01:00, 02:00, and so on, until 23:00.
If the
.B forget
command is run at 23:15, with the above policy,
it will keep the backup taken at 23:00 on each day,
and remove every other backup that day.
It will also remove backups older than 30 days.
.PP
Note that obnam will only inspect timestamps in the backup store,
and does not care what the actual current time is.
This means that if you stop making new backups,
the existing ones won't be removed automatically.
In essence, obnam pretends the current time is just after the
latest backup when 
.B forget
is run.
.PP
The rules can be given in any order,
but will be sorted to ascending order of time period before applied.
(It is an error to give two rules for the same period.)
A backup generation is kept if it matches any rule.
.PP
For example, assume the same backup frequence as above,
but a policy of
.IR 30d,52w .
This will keep the newest daily backup for each day for thirty days,
.I and
the newest weekly backup for 52 weeks.
Because the hourly backups will be removed daily,
before they have a chance to get saved by a weekly rule,
the effect is that the 23:00 o'clock backup for each day is
saved for a month,
and the 23:00 backup on Sundays is saved for a year.
.PP
If no policy is given,
.B forget
will keep everything.
.PP
A typical policy might be
.IR 72h,7d,5w,12m ,
to keep hourly backups for three days,
daily backups for a week,
weekly backups for a month,
and monthly backups for a year.
.SH OPTIONS
.TP
.BR -h ", " --help
Show a summary of options.
.TP
.BR --log =\fIFILE
Log debug and other messages to
.IR FILE .
.TP
.BR --store =\fIURL
Store backups in
.IR URL ,
which may be either a pathname or an 
.B sftp
URL.
See above for a description of URL syntax.
.TP
.BR --hostname =\fIHOSTNAME
Set name of host to use.
Default is the hostname of the machine where obnam runs.
This is used to determine which part of the backup store to put backups in.
.TP
.BR --to =\fIDIR
Restore files to
.IR DIR .
This is only used with the
.B restore
command.
.TP
.BR --generation =\fIGENSPEC
Use generation specified by
.IR GENSPEC .
See above for ways to specify a generation.
Default is
.IR latest .
.TP
.BR --quiet
Do not report progress when running.
This is helpful when running obnam non-interactively,
for example from 
.BR cron (8).
.TP
.BR --root =\fDIR
Back up 
.IR DIR .
This is only relevant with the
.B backup
command.
.TP
.BR --keep =\fIPOLICY
Specify which generations the
.B forget
command will keep.
Everything else will be removed.
See above for a description of
.IR POLICY .
.TP
.BR --pretend ", " --no-act ", " --dry-run
Pretend to do things, but don't actually do them, if they change anything.
Report what would have been done.
Currently only applies to the
.B forget
command,
which will list the generations that would be removed.
.SH "EXIT STATUS"
.B obnam
will exit with zero if everything went well,
and non-zero otherwise.
.SH ENVIRONMENT
.B obnam
will pass on the environment it gets from its parent,
without modification.
It does not obey any unusual environment variables,
but it does obey the usual ones when running external programs,
creating temporary variables, etc.
.SH FILES
There will some day be a configuration file, which will be documented here.
.SH EXAMPLE
To back up your home directory to a server:
.IP
.nf
obnam backup --store sftp://your.server/~/backups $HOME
.PP
To restore your latest backup from the server:
.IP
.nf
obnam restore --store sftp://your.server/~/backups \\
--to /var/tmp/my.home.dir
.PP
To check that the backup worked:
.IP
.nf
obnam verify --store sftp://your.server/~/backups /path/to/file
.PP
To remove old backups, keeping the newest backup for each day for
ten years:
.IP
.nf
obnam forget --store sftp://your.server/~/backups --keep 3650d
.PP
To verify that the backup store is OK:
.IP
.nf
obnam fsck --store sftp://your.server/~/backups