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, `/src/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.2.2 ``` 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 just two things: where the backup server is, and where the live data is. To tell it about that, 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. 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. So the first thing you do is 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 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 [obnam.md](obnam.md) Subplot file. It not just explains things, but also contains acceptance criteria and tests for them. Great stuff! [issue-tracker]: https://gitlab.com/larswirzenius/obnam/-/issues