Obnam tutorial

2021-12-04 07:47

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.

1 Setting up a server

For this, you’ll need:

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:

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.

2 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.

3 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:

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.

4 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.)

5 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 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. It not just explains things, but also contains acceptance criteria and tests for them. Great stuff!