summaryrefslogtreecommitdiff
path: root/tutorial.md
blob: b20c84e03059adf355afa3a41e5afa0a68ceebc7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
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