diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/usage.rst | 78 |
1 files changed, 67 insertions, 11 deletions
diff --git a/docs/usage.rst b/docs/usage.rst index da6d93f11..3a933d42c 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -214,12 +214,6 @@ Examples # Even slower, even higher compression (N = 0..9) $ borg create --compression lzma,N /mnt/backup::repo ~ - # Backup some LV snapshots (you have to create the snapshots before this - # and remove them afterwards). We also backup the output of lvdisplay so - # we can see the LV sizes at restore time. See also "borg extract" examples. - $ lvdisplay > lvdisplay.txt - $ borg create --read-special /mnt/backup::repo lvdisplay.txt /dev/vg0/*-snapshot - .. include:: usage/extract.rst.inc Examples @@ -238,11 +232,6 @@ Examples # Extract the "src" directory but exclude object files $ borg extract /mnt/backup::my-files home/USERNAME/src --exclude '*.o' - # Restore LV snapshots (the target LVs /dev/vg0/* of correct size have - # to be already available and will be overwritten by this command!) - $ borg extract --stdout /mnt/backup::repo dev/vg0/root-snapshot > /dev/vg0/root - $ borg extract --stdout /mnt/backup::repo dev/vg0/home-snapshot > /dev/vg0/home - Note: currently, extract always writes into the current working directory ("."), so make sure you ``cd`` to the right place before calling ``borg extract``. @@ -357,3 +346,70 @@ Examples $ cat ~/.ssh/authorized_keys command="borg serve --restrict-to-path /mnt/backup" ssh-rsa AAAAB3[...] + +Additional Notes +================ + +Here are misc. notes about topics that are maybe not covered in enough detail in the usage section. + +--read-special +-------------- + +The option --read-special is not intended for normal, filesystem-level (full or +partly-recursive) backups. You only give this option if you want to do something +rather ... special - and if you have hand-picked some files that you want to treat +that way. + +`borg create --read-special` will open all files without doing any special treatment +according to the file type (the only exception here are directories: they will be +recursed into). Just imagine what happens if you do `cat filename` - the content +you will see there is what borg will backup for that filename. + +So, for example, symlinks will be followed, block device content will be read, +named pipes / UNIX domain sockets will be read. + +You need to be careful with what you give as filename when using --read-special, +e.g. if you give /dev/zero, your backup will never terminate. + +The given files' metadata is saved as it would be saved without --read-special +(e.g. its name, its size [might be 0], its mode, etc.) - but additionally, also +the content read from it will be saved for it. + +Restoring such files' content is currently only supported one at a time via --stdout +option (and you have to redirect stdout to where ever it shall go, maybe directly +into an existing device file of your choice or indirectly via dd). + +Example +~~~~~~~ + +Imagine you have made some snapshots of logical volumes (LVs) you want to backup. + +Note: For some scenarios, this is a good method to get "crash-like" consistency +(I call it crash-like because it is the same as you would get if you just hit the +reset button or your machine would abrubtly and completely crash). +This is better than no consistency at all and a good method for some use cases, +but likely not good enough if you have databases running. + +Then you create a backup archive of all these snapshots. The backup process will +see a "frozen" state of the logical volumes, while the processes working in the +original volumes continue changing the data stored there. + +You also add the output of `lvdisplay` to your backup, so you can see the LV sizes +in case you ever need to recreate and restore them. + +After the backup has completed, you remove the snapshots again. + +:: + $ # create snapshots here + $ lvdisplay > lvdisplay.txt + $ borg create --read-special /mnt/backup::repo lvdisplay.txt /dev/vg0/*-snapshot + $ # remove snapshots here + +Now, let's see how to restore some LVs from such a backup. + + $ borg extract /mnt/backup::repo lvdisplay.txt + $ # create empty LVs with correct sizes here (look into lvdisplay.txt). + $ # we assume that you created an empty root and home LV and overwrite it now: + $ borg extract --stdout /mnt/backup::repo dev/vg0/root-snapshot > /dev/vg0/root + $ borg extract --stdout /mnt/backup::repo dev/vg0/home-snapshot > /dev/vg0/home + |