TL;DR: README FIRST: A quick tour of Obnam
==========================================

You probably only need to read this chapter.

This chapter gives a quick introduction to the most important parts of
Obnam. The rest of the book is basically a verbose version of this
chapter. You should start by reading this chapter, then pretend you've
read the rest, and everyone will look at you in awe at cocktail
parties. I promise, nobody else will have read the rest of the book
either, so there's no risk of getting caught.

Configuration
-------------

Obnam does not require a configuration file, and you can configure
everything using command line options. You can, however, use a
configuration file: save it as `~/.obnam.conf` and
make it have content like this:

    [config]
    repository = sftp://your.server/home/youruser/backups/
    log = /home/liw/obnam.log

The examples below assume you have created a configuration file,
so that options do not need to be repeated every time.

You probably want to enable the `log` setting, so that if there is
a problem, you can find out all the information available to fix it
from the log file.

Initial backup
--------------

Your first backup will be pretty big, and will take a long time.
A long backup may crash, but that is not a problem: Obnam makes
a **checkpoint** every one hundred megabytes or so.

    obnam backup $HOME

Incremental backups
-------------------

When you've made your initial, full backup (possibly in stages), you can
back up any changes simply by running Obnam again:

    obnam backup $HOME

This will back up all new files, and any changed files. It will also
record which files have been deleted since the previous backup.

You can run Obnam as often as you like. Only the changes from the
previous run are backed up.

Multiple clients in one repository
----------------------------------

You can backup multiple clients to a single repository by providing the
option --client-name=<identifier> when running the program. Backup sets
will be kept separate, but data de-duplication will happen across all
the sets.

Removing old generations
------------------------

Eventually your backup repository will grow so big you'll want to
remove some old generations. The Obnam operation is called forget:

    obnam forget --keep=30d
    
This would keep one backup from each of the last thirty calendar
days, counting from the newest backup (not current time). 
If you've backed up several times during a day, only the latest
generation from that day is kept.

Any data that is part of a generation that is to be kept will
remain in the repository. Any data that exists only in those
generations that is to be forgotten gets removed.

Restoring data
--------------

You will hopefully never need this, but the whole point of having
backups is to restore data in case of a disaster.

    obnam restore --to=/var/tmp/my-recovery $HOME
    
The above command will restore your entire home directory to
`/var/tmp/my-recovery`, from the latest backup generation.
If you only need some particular directory or file, you can
specify that instead:

    obnam restore --to=/var/tmp/my-recover $HOME/Archive/receipts
    
If you can't remember the name of the file you need, use `obnam ls`:

    obnam ls > /var/tmp/my-recovery.list

This will output the contents of the backup generation, in a format
similar to `ls -lAR`. Save it into a file and browse that.
(It's a fairly slow command, so it's comfortable to save to a file.)

Using encryption
----------------

Obnam can use the GnuPG program to encrypt the backup. To enable
this, you need to have or create a PGP key, and then configure
Obnam to use it:

    [config]
    encrypt-with = CAFEBABE

Here, `CAFEBABE` is the **key identifier** for your key, 
as reported by GnuPG. You need to have `gpg-agent` or equivalent
software configured, for now, because Obnam has no way to ask for
or configure the passphrase.

After this, Obnam will automatically encrypt and decrypt data.

Note that if you encrypt your backups, you'll want to back up your GPG
key in some other way.  You can't restore any files from the obnam
backup without it, so you can't rely on the same obnam backup to back up
the GPG key itself.  Back up your passphrase-encrypted GPG key somewhere
else, and make sure you have a passphrase strong enough to stand up to
offline brute-force attacks.  Remember that if you lose access to your
GPG key, your entire backup becomes useless.

If you enable encryption after making backups, you need to start over
with a new repository. 
You can't mix encrypted and unencrypted backups in the same repository.

(There are a bunch of Obnam commands for administering encryption.
You won't need them, unless you share the same repository with several
machines. In that case, you should read the manual page.)
