diff options
Diffstat (limited to 'tutorial.md')
-rw-r--r-- | tutorial.md | 296 |
1 files changed, 296 insertions, 0 deletions
diff --git a/tutorial.md b/tutorial.md new file mode 100644 index 0000000..b20c84e --- /dev/null +++ b/tutorial.md @@ -0,0 +1,296 @@ +# Obnam tutorial + +With the help of this tutorial, you're going to set up Obnam, make your first +backup, and check that you can restore files from it. + +In Obnam, **a client** is a computer whose data is being backed up, and **a +server** is a computer that holds the backup. A single computer can serve both +roles, but don't put your backup onto the same disk as you're backing up; if +that disk breaks, the backup won't do you any good. Consider using +an USB-attached disk, or better yet, some network-attached storage. + + + +# Setting up a server + +For this, you'll need: + +* Git and Ansible installed on your local machine +* a Debian host with plenty of space to keep your backups (this can be the same, + local machine) + +On your local machine, clone the Obnam repository: + +``` +$ git clone https://gitlab.com/larswirzenius/obnam.git +$ cd obnam/ansible +``` + +The next command depends on where your Obnam server is hosted: + +- if the server is accessible from the Internet, run the following commands, + replacing `obnam.example.com` with the domain name of the host: + + ``` + $ printf '[server]\nobnam.example.com\n' > hosts + $ ansible-playbook -i hosts obnam-server.yml -e domain=obnam.example.com + ``` + + The above gets a free TLS certificate from [Let's Encrypt][]. + +- if it's a private server or just the same machine as the Obnam client, run the + following: + + + ``` + $ printf '[server]\nprivate-vm\n' > hosts + $ ansible-playbook -i hosts obnam-server.yml + ``` + + This uses a pre-created self-signed certificate from `files/server.key` and + `files/server.pem`, and is probably only good for trying out Obnam. You may + want to generate your own certificates instead, e.g. using [OpenSSL] + something like this: + + ``` + $ openssl req -x509 -newkey rsa:4096 -passout pass:hunter2 \ + -keyout key.pem -out cert.pem -days 365 -subj /CN=localhost + ``` + + Put the generated keys into `/etc/obnam` (the location can be configured + with `tls_key` and `tls_cert` keys in `/etc/obnam/server.yaml`, which we + are about to describe). + +Check that the server is installed and running: + +``` +$ sudo systemctl is-active obnam +active +``` + +Ansible created a directory, `/srv/obnam/chunks`, that will contain the +backed-up data. If you want to use a different directory, you have to stop the +service, move the existing directory to a new location, and update Obnam's +configuration: + +``` +$ sudo systemctl stop obnam +$ sudo mv /srv/obnam /the/new/location/ +$ sudoedit /etc/obnam/server.yaml +``` + +In the editor, you'll see something like this: + +``` +address: 0.0.0.0:443 +chunks: /srv/obnam/chunks +tls_key: /etc/obnam/server.key +tls_cert: /etc/obnam/server.pem +``` + +Paths to TLS files might be different if you're using Let's Encrypt. Anyway, you +have to edit `chunks` key to point at the new location. Once you're done, save +the file and start the server again: + +``` +$ sudo systemctl start obnam +$ sudo systemctl is-active obnam +active +``` + +Half the job done, another half to go! Let's set up a client now. + +[Let's Encrypt]: https://letsencrypt.org/ +[OpenSSL]: https://www.openssl.org/ + + + +# Setting up a client + +There is a Debian package built by CI from every commit. It works on Debian 10 +(buster) and later. You can run a script to install it: + +``` +$ curl -s https://gitlab.com/larswirzenius/obnam/-/raw/main/install-debian.sh | sudo bash +``` + +If you'd rather not download a script from the Internet and run it as +root (kudos!), you can do the same steps manually. Add the following +to `/etc/apt/sources.list.d/obnam.list`: + +``` +deb http://ci-prod-controller.vm.liw.fi/debian unstable-ci main +``` + +Then save the following PGP public key as `/etc/apt/trusted.gpg.d/obnam.asc`: + +``` +-----BEGIN PGP PUBLIC KEY BLOCK----- + +mQINBFrLO7kBEADdz6mHstYmKU5Dp6OSjxWtWaqTDOX1sJdmmaIK/9EKVIH0Maxp +5kvVO5G6mULLAjv/kLG0MxasHPrq8I2A/y8AqKAGVL8QelwLjQMIFZ30/VbGQPHS ++T5TZXEnoQtNce1GUhFwJ38ZyjjwHBFV9tSec7rZ2Q3YeM3nNnGPf6DacXGfEOPO +HIN4sXAN2hzNXNjKRzTIvxQseb6nr7afUh/SlZ3yhQOCrIzmYlD7tP9WJe7ofL0p +JY4pDQYw8rT6nC2BE/ioemh84kERCT1vCe+OVFlSRuMlqfEv+ZpKQ+itOmPDQ/lM +jpUm1K2hrW/lWpxT/ZxHKo/w1K36J5WshgMZxfUu5BMCL9LMqMcrXNhNjDMfxDMM +3yBPOvQ4ls6fecOZ/bsFo1p8VzMk/w/eG8vPs5yuNa5XxN95yFMXoOHGb5Xbu8D4 +6yiW+Af70LbiSNpGdmNdneiGB2fY38NxBukPw5u3S5qG8HedSmMr1RvSr5kHoAAe +UbOY+BYaaKsTAT7+1skUW1o3FJSqoRKCHAzTsMWC6zzhR8hRn7jVrrguH1hGbqq5 +TZSCFQZExuTJ7uXrTLG0WoBXIjB5wWNcSeXn8myUWYB51nJNF4tJBouZOz9JwWGl +kiAQkrHnBttLQWdW9FyjbIoTZMtpvVx+m6ObGTGdGL1cNlLAvWprMXGc+QARAQAB +tDJJY2sgQVBUIHJlcG9zaXRvcnkgc2lnbmluZyBrZXkgKDIwMTgpIDxsaXdAbGl3 +LmZpPokCTgQTAQgAOBYhBKL1uyDoXyxUH3O717Wr+TZVS6PGBQJayzu5AhsDBQsJ +CAcCBhUICQoLAgQWAgMBAh4BAheAAAoJELWr+TZVS6PGB5QQANTcikhRUHwt9N4h +dGc/Hp6CbqdshMoWlwpFskttoVDxQG5OAobuZl5XyzGcmja1lT85RGkZFfbca0IZ +LnXOLLSAu51QBkXNaj4OhjK/0uQ+ITrvL6RQSXNgHiUTR/W2XD1GIUq6nBqe2GSN +31S1baYKKVj5QIMsi7Dq8ls3BBXuPCE+xTSaNmGWjes2t9pPidcRvxsksCLY1qgw +P1GFXBeMkBQ29kBP87SUL15SIk7OiQLlEURCy5iRls5rt/YEsdEpRWIb0Tm5Nrjv +2M3VM+iBhfNXTwj0rJ34mlycF1qQmA7YcTEobT7z587GPY0VWzBpQUnEQj7rQWPM +cDYY0b+I6kQ8VKOaL4wVAtE98d7HzFIrIrwhTKufnrWrVDPYsmLZ+LPC1jiF7JBD +SR6Vftb+SdDR9xoE1yRuXbC6IfoW+5/qQNrdQ2mm9BFw5jOonBqchs18HTTf3441 +6SWwP9fY3Vi+IZphPPi0Gf85oMStgnv/Wnw6LacEL32ek39Desero/D8iGLZernK +Q2mC9mua5A/bYGVhsNWyURNFkKdbFa+/wW3NfdKYyZnsSfo+jJ2luNewrhAY7Kod +GWXTer9RxzTGA3EXFGvNr+BBOOxSj0SfWTl0Olo7J5dnxof+jLAUS1VHpceHGHps +GSJSdir7NkZidgwoCPA7BTqsb5LN +=dXB0 +-----END PGP PUBLIC KEY BLOCK----- +``` + +After that, run the following commands to install Obnam: + +``` +$ sudo apt update +$ sudo apt install obnam +``` + +Now verify that everything is installed correctly: + +``` +$ obnam --version +obnam-backup 0.3.1 +``` + +The version might be different, but at least there should **not** be any errors. + + + +# Making a backup + +To create a backup, client needs to know three things: where the backup server +is, where the live data is, and what key to use for encryption. To tell the +client about the first two, create a file `~/.config/obnam/obnam.yaml` with +contents like this: + +```yaml +server_url: https://obnam.example.com:443 +roots: + - /home/joe + - /home/ann + - /etc + - /var/spool +``` + +Adjust the server address to match what you previously configured on the server. +The `roots` key is a list of all the directories that Obnam should back up. Make +sure that the roots are accessible to the user who would be doing the backup — +the user has to be able to read their contents to back them up. + +To generate an encryption key, run `obnam init` and type a passphrase. You don't +need to remember it — it's just an additional random input to aid key +generation; Obnam will not prompt you for it ever again. The generated key will +be saved into `~/.config/obnam/passwords.yaml`, and *that's* the file you should +not lose: you can't make or restore backups without it. Consider copying it +somewhere separate from your main backup. + +With that, you're ready to make your first backup! Run the following command, +and watch Obnam go through all the files in your roots: + +``` +$ obnam backup +elapsed: 7s +files: 3422/0 +current: /home/ann/music/Beethoven/1.flac +``` + +Depending on how much data you have under the roots, this might take a while. +But once Obnam is done, it will print out a report like this: + +``` +status: OK +duration: 85 +file-count: 1223 +generation-id: 3905a0ad-9971-413c-ac81-ca8587c5f8c2 +``` + +That's how you know you've got a backup! Hold off the celebration, though; the +backups are only as good as your ability to use them, so let's check if you can +recover the files you just backed up. + + + +# Restoring a backup + +Let's imagine that your disk crapped out. In that case, you probably want to +just grab the latest backup. In other cases, you might find that a file you +thought useless and deleted long ago is actually important. To restore it, you +need to find the backup that still has it. + +The first order of business is to restore your `passwords.yaml`. If you already +have it on your current machine, great; if not, you'll have to restore it from +some *other* backup before you can use Obnam to restore everything else. It's +impossible to recover any data without knowing the key, since it's all +encrypted. + +Got the `passwords.yaml` in place? Good. Let's get a list of all your backups +with `obnam list`: + +``` +$ obnam list +6d35e3dd-3264-4269-a9d3-74fbd354c90e 2021-01-13 02:32:50.482465724 +0300 +e4387899-d1dd-4e42-bc57-f56e6097d235 2021-01-14 02:36:00.029561204 +0300 +9acde8d9-c167-4ad0-86b6-560c711713e1 2021-01-18 02:45:56.865274252 +0300 +708db71e-d863-47e6-92c3-679041e25c8e 2021-01-20 02:49:50.664349817 +0300 +0f3a63d0-d992-42ff-ab77-7e2457745a40 2021-01-22 03:00:56.902063598 +0300 +028ce888-4a5b-438c-978c-0812646165cf 2021-02-07 16:18:19.008757980 +0300 +481bb25f-5377-4e41-b824-4e60fda8f01c 2021-02-08 19:04:44.072710112 +0300 +5067e10e-2d4d-4ff4-a9a0-568ed008dd2c 2021-02-11 20:26:06.589610566 +0300 +3905a0ad-9971-413c-ac81-ca8587c5f8c2 2021-02-12 22:35:20.431081194 +0300 +``` + +That second-to-last backup, 5067e10e-2d4d-4ff4-a9a0-568ed008dd2c, looks like +it's old enough. Let's see what files it contains: + +``` +$ obnam list-files 5067e10e-2d4d-4ff4-a9a0-568ed008dd2c +``` + +You might need to `grep` the result to check for specific files. Anyway, suppose +this backup it exactly what you need. Let's restore it to a directory called +"yesterday": + +``` +$ obnam restore 5067e10e-2d4d-4ff4-a9a0-568ed008dd2c yesterday +``` + +Obnam will print out a progress bar and some stats. Once the restoration is +done, you can look under `yesterday/` to find the file you needed. Easy! + +Now you're prepared for the worst. (Unless *both* your primary and backup disks +break. Or your backup server is inaccessible. Or you lose all copies of +`passwords.yaml`. Or there is no electrical grid anymore to power your devices. +Or the zombies are trying to break in, distracting you from reading this +tutorial. Look up "disaster recovery planning"—oh right, no electricity.) + + +# Where to go from here + +Obnam is still at the alpha stage, so it's likely that the instructions above +didn't quite work for you. If so, please [open issues][issue-tracker] and help +us improve Obnam! + +If you're interested in more details, and especially in how Obnam works +internally, take a look at [the Subplot file](obnam.html). It not just explains +things, but also contains acceptance criteria and tests for them. Great stuff! + + +[issue-tracker]: https://gitlab.com/larswirzenius/obnam/-/issues |