documentation: more detailed information about raw targets in README.md and btrbk.conf.5; fixed outdated information in FAQ.md

README.md

@@ -268,7 +268,12 @@ Example: encrypted backup to non-btrfs target
 If your backup server does not support btrfs, you can send your
 subvolumes to a raw file.
 
-Note: this is an _experimental_ feature!
+This is an _experimental_ feature: btrbk supports "raw" targets,
+meaning that similar to the "send-receive" target the btrfs subvolume
+is being sent using `btrfs send` (mirroring filesystem level data),
+but instead of instantly being received (`btrfs receive`) by the
+target filesystem, it is being redirected to a file, optionally
+compressed and piped through GnuPG.
 
 /etc/btrbk/btrbk.conf:
 
@@ -279,16 +284,20 @@ Note: this is an _experimental_ feature!
 
     volume /mnt/btr_pool
       subvolume home
-        target raw ssh://myserver.mydomain.com/backup
+        target raw ssh://cloud.example.com/backup
           ssh_user     btrbk
-          incremental  no
+          # incremental  no
 
-This will create a GnuPG encrypted, compressed file
+This will create a GnuPG encrypted, compressed files on the target
-`/backup/home.YYYYMMDD.btrfs_<received_uuid>.xz.gpg` on the target
+host:
-host.
 
-While incremental backups are also supported for raw targets, this is
+- `/backup/home.YYYYMMDD.btrfs_<received_uuid>.xz.gpg` for
-not recommended (see [btrbk.conf(5)] for details).
+   non-incremental images,
+- `/backup/home.YYYYMMDD.btrfs_<received_uuid>@<parent_uuid>.xz.gpg`
+  for subsequent incremenal images.
+
+I you are using raw _incremental_ backups, please make sure you
+understand the implications (see [btrbk.conf(5)], TARGET TYPES).
 
 
 Setting up SSH

doc/FAQ.md

@@ -42,10 +42,10 @@ the volumes like this:
         $volume_rsh mount $volume_path
     done
 
-Note that the `btrbk config list` command accepts filters (see
+Note that the `btrbk list` command accepts filters (see [btrbk(1)],
-[btrbk(1)], FILTER STATEMENTS), which means you can e.g. add "group
+FILTER STATEMENTS), which means you can e.g. add "group automount"
-automount" tags in your configuration and dump only the volumes of
+tags in your configuration and dump only the volumes of this group:
-this group: `btrbk config dump volume automount`.
+`btrbk list volume automount`.
 
   [btrbk(1)]: http://www.digint.ch/btrbk/doc/btrbk.html
 

doc/btrbk.conf.5

@@ -57,52 +57,6 @@ Note that btrfs is very picky on file names (mainly for security
 reasons), only the characters [0-9] [a-z] [A-Z] and "._+-@" are
 allowed.
 .RE
-.SH TARGET TYPES
-.PP
-\fBsend-receive\fR
-.RS 4
-Backup to a btrfs filesystem, using "btrfs send/receive". The
-\fI<target-directory>\fR must be an absolute path and point to a btrfs
-volume (or subvolume). See btrfs-send(8), btrfs-receive(8).
-.RE
-.PP
-\fBraw\fR  \fI*experimental*\fR
-.RS 4
-Backup to a raw (filesystem independent) file from the output of
-btrfs-send(8), with optional compression and encryption.
-.PP
-Additional options for raw target:
-.PP
-.RS 4
-raw_target_compress  gzip|bzip2|xz|no
-.PD 0
-.PP
-raw_target_encrypt  gpg|no
-.PP
-gpg_keyring  <file>
-.PP
-gpg_recipient  <name>
-.RE
-.PD
-.PP
-The target file name is:
-.PP
-.RS 4
-<snapshot-name>--<received_uuid>[@<parent_uuid>].btrfs[.gz|.bz2|.xz][.gpg]
-.RE
-.PP
-It is recommended to set "incremental no" for raw backups, for the
-following reasons:
-.IP \[bu] 2
-The target preserve mechanism is disabled for raw \fIincremental\fR
-backups, since deleting of any intermediate backup would destroy the
-consistency of all subsequent backups (btrbk will never delete any
-backup in a raw incremental chain).
-.IP \[bu]
-No rotation of incremental backups: if \fIincremental\fR is set, a
-full backup must be triggered manually from time to time in order to
-be able to delete old backups.
-.RE
 .SH OPTIONS
 .PP
 \fBtransaction_log\fR  <file>
@@ -267,6 +221,60 @@ manipulated by hand (moved, deleted).
 .PP
 Lines that contain a hash character (#) in the first column are
 treated as comments.
+.SH TARGET TYPES
+.PP
+\fBsend-receive\fR
+.RS 4
+Backup to a btrfs filesystem, using "btrfs send/receive". This is the
+recommended (standard) target type. The \fI<target-directory>\fR must
+be an absolute path and point to a btrfs volume (or subvolume). See
+btrfs-send(8), btrfs-receive(8).
+.RE
+.PP
+\fBraw\fR  \fI*experimental*\fR
+.RS 4
+Backup to a raw (filesystem independent) file from the output of
+btrfs-send(8), with optional compression and encryption.
+.PP
+Note that the target preserve mechanism is currently disabled for raw
+backups (btrbk does not delete any raw files)!
+.PP
+Additional options for raw targets:
+.PP
+.RS 4
+raw_target_compress  gzip|bzip2|xz|no
+.PD 0
+.PP
+raw_target_encrypt  gpg|no
+.PP
+gpg_keyring  <file>
+.PP
+gpg_recipient  <name>
+.RE
+.PD
+.PP
+Target file name syntax:
+.PP
+.RS 4
+<snapshot-name>--<received_uuid>[@<parent_uuid>].btrfs[.gz|.bz2|.xz][.gpg]
+.RE
+.PP
+The <parent_uuid> is only set on \fIincremental\fR backups, and points
+to the <received_uuid> of the previous backup in a incremental backup
+chain. For \fIincremental\fR backups ("incremental yes"), please note
+that:
+.IP \[bu] 2
+As soon as a single \fIincremental\fR backup file is lost or
+corrupted, all later incremental backups become invalid, as there is
+no common parent for the subsequent incremental images anymore. This
+might be a good compromise for a vacation backup plan, but for the
+long term make sure that a non-incremental backup is triggered from
+time to time.
+.IP \[bu]
+There is currently no support for rotation of incremental backups: if
+\fIincremental\fR is set, a full backup must be triggered manually
+from time to time in order to be able to delete old backups.
+.RE
 .SH AVAILABILITY
 Please refer to the btrbk project page
 \fBhttp://www.digint.ch/btrbk/\fR for further