=head1 NAME

Brackup::Manual::Overview - how Brackup works, and how to use it

=head1 Quick Start Guide

=head2 Setup your config file

Run B<brackup> to initialize your config file.  You'll see:

   $ brackup
   Error:
     Your config file needs tweaking.
     I put a commented-out template at: /home/bradfitz/.brackup.conf

   brackup --from=[source_name] --to=[target_name] [--output=<backup_metafile.brackup>]
   brackup --help

Now, go edit your config file:

   $ $EDITOR ~/.brackup.conf

Tweak as appropriate.

For details on what's tweakable, see L<Brackup::Root> (a "source"), or
L<Brackup::Target> (a destination).

=head2 Do a backup

Now that you've got a source and target named, run a backup.  I like
watching it all happen with the --verbose (or -v) option:

  $ brackup --from=myhome --to=amazon -v

=head2 What just happened?

Let's look around at what just happened.

First, you'll notice a file named, by default,
"myhome-yyyymmdd.brackup" in your current directory.  Go look at it.
It describes the state of the tree (the "root", or "source") that you
just backed up.  B<You should keep this file>.  Although, if you
didn't, it was also stored on the target (in this case, Amazon), so
it's not critical, but at present you need the metafile (the .brackup
file), locally in able to do a restore with B<brackup-restore>.  (a
future version of brackup-restore will let you grab the metafile from
the target, but that's still a TODO item)

You might also notice two SQLite files at:

   $SOURCE_ROOT/.brackup-digest.db
   $HOME/.brackup-target-amazon.invdb

These are the L<Brackup::DigestCache> and
L<Brackup::InventoryDatabase> files, both of which make future
incremental backups fast.

=head1 Incremental backups

Incremental backups are essentially free, only storing new chunks,
even if you rearrange your directory tree or rename all your files.
Brackup doesn't use the I<name> of your files to decide what's new in
an incremental backup, only the contents.

For two back-to-back backups, with no data changes in-between, the
only cost of an incremental backup is that another metafile (*.brackup) is
produced, which is proportional in size to the I<number of files>
you're backing up (not the size of the files).

Another good side-effect of storing backups based on their digests is
that multiple, duplicate files on your source are only stored on the
target once.  (but yes, they're restored to all original locations)

=head1 Using encryption

Brackup supports backing up with public key encryption, using GNU
Privacy Guard (GnuPG).  One of the great advantage of using public key
encryption is that your machines doing backups only need your public
key, so you can run automated backups from hosts which are on the
public Internet and might be get compromised, without worrying about
your private key getting stolen.  (however, you'd still worry about
your machine getting compromised for lots of other reasons...)

In any case, you encrypt files I<to yourself>, and this is a property
on a backup source (see L<Brackup::Root>).  For example, in my config
file, I have:

  [SOURCE:bradhome]
  ...
  path = /home/bradfitz/
  gpg_recipient = 5E1B3EC5
  ...

Where 5E1B3EC5 corresponds to the key signature for myself as seen in:

  $ gpg --list-keys
  ...
  pub   1024D/5E1B3EC5 2006-03-20
  uid                  Brad Fitzpatrick <brad@danga.com>
  ....

While you backup automatically without a human present, a restore from
encryption requires an interactive session for you to enter your
private key's passphrase into gpg-agent.

To create a new key, run:

  $ gpg --gen-key

But really, you should go read a gpg manual first.  Notably, B<backing
up your gpg private key is very important!>.  If you lose the disk
with your files which also contain your private key, your encrypted backups on
Amazon won't do you much good, since you'll have no way to decrypt them.
I recommend burning your private key to a CD, as well as printing it out
on paper.  (Worst case you can type it back in, or use OCR.)  Export with:

  $ gpg --export-secret-keys --armor

=head1 Restores

To do a restore, you'll currently need your *.brackup file handy
(pulling the *.brackup file from the server isn't yet supported).  Then
run:

   brackup-restore --from=foo.brackup --to=<dir> --all

For more options, see:

   brackup-restore --help

=head1 SEE ALSO

L<Brackup>
