From 2d6cde78095be1760648f93713c976ed33d319bc Mon Sep 17 00:00:00 2001 From: Alexander Batischev Date: Fri, 12 Feb 2021 23:42:09 +0300 Subject: doc(tutorial.md): add a rudimentary tutorial --- README.md | 51 +---------- tutorial.md | 279 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 282 insertions(+), 48 deletions(-) create mode 100644 tutorial.md diff --git a/README.md b/README.md index cba9db8..97c4484 100644 --- a/README.md +++ b/README.md @@ -2,54 +2,9 @@ Obnam2 is a project to develop a backup system. -You probably want to read the [obnam.md](obnam.md) subplot file. - -## Client installation - -See instructions at for installing the -client. It's not duplicated here to avoid having to keep the -information in sync in two places. - -## Server installation - -To install the Obnam server component, you need a Debian host with -sufficient disk space, and Ansible installed locally. Run the -following commands in the Obnam source tree, replacing -`obnam.example.com` with the domain name of your server: - -```sh -$ cd ansible -$ 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][], but only -works if the server is accessible from the public Internet. For a -private host use the following instead: - -```sh -$ cd ansible -$ 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. - -To create a self-signed certificate, something like the following -command might work, using [OpenSSL]: - -```sh -$ openssl req -x509 -newkey rsa:4096 -passout pass:hunter2 \ - -keyout key.pem -out cert.pem -days 365 -subj /CN=localhost -``` - - -[Let's Encrypt]: https://letsencrypt.org/ -[OpenSSL]: https://www.openssl.org/ - +For installation instructions and a quick start guide, see +[tutorial.md](tutorial.md). For more details on goals, requirements, and +implementation details, see the [obnam.md](obnam.md) subplot file. ## Legalese diff --git a/tutorial.md b/tutorial.md new file mode 100644 index 0000000..4f84380 --- /dev/null +++ b/tutorial.md @@ -0,0 +1,279 @@ +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 -- cgit v1.2.1