From a92f27e40bf5298a5d193fae077e2e5496af52b1 Mon Sep 17 00:00:00 2001 From: Alexander Batischev Date: Sat, 5 Jun 2021 23:32:37 +0300 Subject: doc(tutorial.md): describe `obnam init` I did not describe `--insecure-passphrase` because it's probably meant for scripting, not interactive use. Fixes #120. --- tutorial.md | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/tutorial.md b/tutorial.md index ce5df2e..4eed072 100644 --- a/tutorial.md +++ b/tutorial.md @@ -169,7 +169,7 @@ Now verify that everything is installed correctly: ``` $ obnam --version -obnam-backup 0.2.2 +obnam-backup 0.3.1 ``` The version might be different, but at least there should **not** be any errors. @@ -178,8 +178,8 @@ 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 +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. Create a file `~/.config/obnam/obnam.yaml` with contents like this: ```yaml @@ -196,6 +196,12 @@ 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. The key +will be derived from that, and saved into `~/.config/obnam/passwords.yaml`. TK +do I need to remember the passphrase for anything else? `backup` and `restore` +don't need it. Should we advise users to keep a separate backup of +passwords.yaml, since it's impossible to restore backups without it? + 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: @@ -227,8 +233,16 @@ recover the files you just backed up. 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`: +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 -- cgit v1.2.1 From b4969148e29fa2f2579e932dae87ae8940192b88 Mon Sep 17 00:00:00 2001 From: Alexander Batischev Date: Sat, 5 Jun 2021 23:37:42 +0300 Subject: doc(tutorial.md): point to compiled Subplot file When the tutorial is deployed to doc.obnam.org, it's better for it to point at the HTML version of the Subplot file rather than the Markdown version which doesn't exist on doc.obnam.org. --- tutorial.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/tutorial.md b/tutorial.md index 4eed072..a95cdc3 100644 --- a/tutorial.md +++ b/tutorial.md @@ -289,9 +289,8 @@ 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! +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 -- cgit v1.2.1 From c0006040165cf389c114f34362f95f388ee069bd Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sun, 6 Jun 2021 11:53:30 +0300 Subject: docs: drop questions from tutorial.md I want the rest included in the release that's about to happen. If this was the wrong thing, we will fix it promptly. Sponsored-by: author --- tutorial.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/tutorial.md b/tutorial.md index a95cdc3..26e5875 100644 --- a/tutorial.md +++ b/tutorial.md @@ -197,10 +197,8 @@ 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. The key -will be derived from that, and saved into `~/.config/obnam/passwords.yaml`. TK -do I need to remember the passphrase for anything else? `backup` and `restore` -don't need it. Should we advise users to keep a separate backup of -passwords.yaml, since it's impossible to restore backups without it? +will be derived from that, and saved into +`~/.config/obnam/passwords.yaml`. 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: -- cgit v1.2.1