From 1d4a502ee39c6452bea72d0a6e62f9b1aa52c339 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Merlin=20B=C3=BCge?= Date: Thu, 7 Apr 2022 02:55:46 +0200 Subject: [PATCH] documentation: fix small typos and rephrase some parts --- README.md | 17 +++++++---------- doc/FAQ.md | 6 +++--- doc/btrbk.1.asciidoc | 29 +++++++++++++++-------------- 3 files changed, 25 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 80c5ce0..5683cef 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ The source and target locations are specified in a config file, which allows to easily configure simple scenarios like "laptop with locally attached backup disks", as well as more complex ones, e.g. "server receiving backups from several hosts via ssh, with different retention -policy". +policies". Key Features: @@ -111,7 +111,7 @@ the `subvolume` declarations in the examples accordingly. Example: Local Regular Snapshots (time-machine) ----------------------------------------------- -The simpliest use case is to only create snapshots of your data. This +The simplest use case is to only create snapshots of your data. This will obviously not protect it against hardware failure, but can be useful for: @@ -167,13 +167,10 @@ If it works as expected, configure a cron job to run btrbk hourly: #!/bin/sh exec /usr/bin/btrbk -q run -Snapshots will now be created every hour, kept for 48h -(`snapshot_preserve`), then automatically removed. - -With this setup, the snapshots will be kept at least for 18 hours -(`snapshot_preserve_min`). This can be useful to create manual -snapshots by calling `sudo btrbk run` on the command line and keep -them around for a while, in addition to the regular snapshots. +Snapshots will now be created every hour. All snapshots are preserved for at +least 18 hours (`snapshot_preserve_min`), whether they are created by the cron +job or manually by calling `sudo btrbk run` on the command line. Additionally, +48 hourly snapshots are preserved (`snapshot_preserve`). Example: Backups to USB Disk @@ -249,7 +246,7 @@ Example: Host-initiated Backup on Fileserver -------------------------------------------- Let's say you have a fileserver at "myserver.mydomain.com" where you -want to create backups of your laptop disk, the config would look like +want to create backups of your laptop disk. The config could look like this: ssh_identity /etc/btrbk/ssh/id_rsa diff --git a/doc/FAQ.md b/doc/FAQ.md index 8be613d..6e95fa5 100644 --- a/doc/FAQ.md +++ b/doc/FAQ.md @@ -110,8 +110,8 @@ have to create a run-time (rw) snapshot before booting into it: How do I convert '/' (subvolid=5) into a subvolume? --------------------------------------------------- -There's several ways to achieve this, the solution described below is -that it guarantees not to create new files (extents) on disk. +There's several ways to achieve this, the solution described below +guarantees not to create new files (extents) on disk. ### Step 1: make a snapshot of your root filesystem @@ -191,7 +191,7 @@ What is the most efficient way to clone btrfs storage? ------------------------------------------------------ It is very common (and avisable!) to keep backups on a separate -location. In some situations, is is also required to transport the +location. In some situations, it is also required to transport the data physically, either to the datacenter or to your safe in the basement. diff --git a/doc/btrbk.1.asciidoc b/doc/btrbk.1.asciidoc index e52b4ca..4f5c018 100644 --- a/doc/btrbk.1.asciidoc +++ b/doc/btrbk.1.asciidoc @@ -45,26 +45,27 @@ btrbk.conf(5) for more details. === Snapshots and Backups -Snapshots as well as backup subvolumes are created in form: +Snapshots as well as backup subvolumes are created in the form: .[_N] Where '' is identical to the source subvolume name, -unless the configuration option 'snapshot_name' is set. The - is either "YYYYMMDD" or "YYYYMMDDThhmm" (dependent of the -'timestamp_format' configuration option), where "YYYY" is the year, -"MM" is the month, "DD" is the day, "hh" is the hour and "mm" is the -minute of the creation time (local time of the host running btrbk). If -multiple snapshots/backups are created on the same date/time, N will -be incremented on each snapshot, starting at 1. +unless the configuration option 'snapshot_name' is set. '' +is a timestamp describing the creation time (local time of the host +running btrbk) of the snapshot/backup. The format can be configured +using the 'timestamp_format' option, refer to btrbk.conf(5) for +details. If multiple snapshots/backups are created on the same +date/time, 'N' will be incremented on each snapshot, starting at 1. If a snapshot or backup does not match the naming scheme above -(i.e. if it has been renamed manually), btrbk will leave it untouched. +(e.g. if it has been renamed manually), btrbk will leave it untouched. -Note that 'snapshot' is a btrfs terminology for a ``read-only -subvolume'' (showing a parent-uuid, see btrfs-subvolume(8)); 'backup' -is a btrbk terminology for a ``read-only subvolume created with -send/receive'' (showing a received-uuid). +Note that in btrfs terminology, a 'snapshot' is a ``subvolume with +a given initial content of the original subvolume'' (showing a +parent-uuid, see btrfs-subvolume(8)), and they can be read-write +(default) or read-only. In btrbk terminology, 'snapshot' means +``read-only btrfs snapshot'', and 'backup' means ``read-only subvolume +created with send/receive'' (showing a received-uuid). OPTIONS @@ -104,7 +105,7 @@ OPTIONS specified in the configuration file. --wipe:: - Ignore configured snapshot retention policy, delete all but latest + Ignore configured snapshot retention policy, delete all but the latest snapshots instead. All snapshots needed for incremental backup (latest common) are also preserved. Useful if you are getting low on disk space (ENOSPC).