diff options
author | Lars Wirzenius <liw@liw.fi> | 2014-01-31 15:54:31 +0000 |
---|---|---|
committer | Lars Wirzenius <liw@liw.fi> | 2014-01-31 15:54:31 +0000 |
commit | 91eb2c3a1faab66d578346ab9391a0bf41c9a0f4 (patch) | |
tree | e2be2815a84ed34510047a9e969553a276af754f /manual | |
parent | 67487fcc13bd770a44135647300cb5fd4e9a343e (diff) | |
download | obnam-91eb2c3a1faab66d578346ab9391a0bf41c9a0f4.tar.gz |
Add content from tutorial on website
Diffstat (limited to 'manual')
-rw-r--r-- | manual/040-installing.mdwn | 39 | ||||
-rw-r--r-- | manual/050-quick-tour.mdwn | 131 |
2 files changed, 163 insertions, 7 deletions
diff --git a/manual/040-installing.mdwn b/manual/040-installing.mdwn index 335e2c31..637fb9ed 100644 --- a/manual/040-installing.mdwn +++ b/manual/040-installing.mdwn @@ -1,8 +1,37 @@ Installing Obnam ================ -I really don't want to write this chapter, so I'll stick to just -telling people using Debian or Ubuntu how to install it with the -package manager, and how to build and install it from source. I expect -this chapter will get patches from various distros and operating -systems to explain their installation details. +This chapter explains how to install Obnam. It is not a very extensive +set of instructions, yet. In particular, itreally only caters to +Debian users. Instructions for other systems would be very much welcome. + +Debian +------ + +It is easiest to install Obnam on a Debian system. If you're running +Debian `wheezy` or a later release, Obnam is included and you can just +install it: + + apt-get install obnam + +There may be a newer version of Obnam on the author's site. The rest +of this section explains how to install from there. + +Add the following line to your `/etc/apt/sources.list` file: + + deb http://code.liw.fi/debian squeeze main + +Then run the following commands as root: + +* `apt-get update` +* `apt-get install obnam` + +The commands will complain that the PGP key used to sign the archive +is not known to apt. You can either ignore this, or add the key from +<http://code.liw.fi/apt.asc> to your key, after suitable verification. + +Other systems +------------- + +For other systems, you need to install from sources. See the `README` +file in the source tree for instructions. diff --git a/manual/050-quick-tour.mdwn b/manual/050-quick-tour.mdwn index 5be8d51d..bf5ae92f 100644 --- a/manual/050-quick-tour.mdwn +++ b/manual/050-quick-tour.mdwn @@ -1,5 +1,132 @@ A quick tour of Obnam ===================== -This chapter is an extended copy of the tutorial currently at -liw.fi/obnam/tutorial. +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 deduplication 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.) |