documentation: added "target raw" and "timestamp short|long" documentation to btrbk.conf(5), as well as an example for raw targets in README.md

README.md

@@ -78,10 +78,10 @@ btrbk is in AUR: https://aur.archlinux.org/packages/btrbk/
 Synopsis
 ========
 
-Please consult the [btrbk(1) man-page] provided with this package for a
+Please consult the [btrbk(1)] man-page provided with this package for a
 full description of the command line options.
 
-  [btrbk(1) man-page]: http://www.digint.ch/btrbk/doc/btrbk.html
+  [btrbk(1)]: http://www.digint.ch/btrbk/doc/btrbk.html
 
 
 Configuration File
@@ -90,7 +90,7 @@ Configuration File
 Before running `btrbk`, you will need to create a configuration
 file. You might want to take a look at `btrbk.conf.example` provided
 with this package. For a detailed description, please consult the
-[btrbk.conf(5) man-page].
+[btrbk.conf(5)] man-page.
 
 When playing around with config-files, it is highly recommended to
 check the output using the `dryrun` command before executing the
@@ -102,7 +102,7 @@ This will read all btrfs information on the source/target filesystems
 and show what actions would be performed (without writing anything to
 the disks).
 
-  [btrbk.conf(5) man-page]: http://www.digint.ch/btrbk/doc/btrbk.conf.html
+  [btrbk.conf(5)]: http://www.digint.ch/btrbk/doc/btrbk.conf.html
 
 
 Example: laptop with usb-disk for backups
@@ -262,6 +262,35 @@ from 192.168.0.42. The source filesystem is never altered because of
 `snapshot_preserve_daily all`.
 
 
+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!
+
+/etc/btrbk/btrbk.conf:
+
+    raw_target_compress  xz
+    raw_target_encrypt   gpg
+    gpg_keyring          /etc/btrbk/gpg/pubring.gpg
+    gpg_recipient        btrbk@mydomain.com
+
+    volume /mnt/btr_pool
+      subvolume home
+        target raw ssh://myserver.mydomain.com/backup
+          ssh_user     btrbk
+          incremental  no
+
+This will create a GnuPG encrypted, compressed file
+`/backup/home.YYYYMMDD.btrfs_<received_uuid>.xz.gpg` on the target
+host.
+
+While incremental backups are also supported for raw targets, this is
+not recommended (see [btrbk.conf(5)] for details).
+
+
 Setting up SSH
 ==============
 

doc/btrbk.1

@@ -1,4 +1,4 @@
-.TH "btrbk" "1" "2015-09-02" "btrbk v0.20.0" ""
+.TH "btrbk" "1" "2015-09-29" "btrbk v0.21.0-dev" ""
 .\" disable hyphenation
 .nh
 .\" disable justification (adjust text to left margin only)
@@ -21,12 +21,17 @@ from one source to multiple destinations.
 Snapshots as well as backup subvolume names are created in form:
 .PP
 .RS 4
-<source_name>.YYYYMMDD[_N]
+<snapshot_name>.<timestamp>[_N]
 .RE
 .PP
-Where YYYY is the year, MM is the month, and DD is the day of
+Where <snapshot_name> is identical to the source subvolume name,
-creation, and, if multiple backups are created on the same day, N will
+unless the configuration option \fIsnapshot_name\fR is set. The
-be incremented on each backup, starting at 1.
+<timestamp> is either "YYYYMMDD" or "YYYYMMDDThhmm" (dependent of the
+\fItimestamp_format\fR 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 backup, starting at 1.
 .SH OPTIONS
 .PP
 \-h, \-\-help

doc/btrbk.conf.5

@@ -1,4 +1,4 @@
-.TH "btrbk.conf" "5" "2015-09-02" "btrbk v0.20.0" ""
+.TH "btrbk.conf" "5" "2015-09-29" "btrbk v0.21.0-dev" ""
 .\" disable hyphenation
 .nh
 .\" disable justification (adjust text to left margin only)
@@ -19,8 +19,7 @@ defined either globally or within a section.
 The options specified always apply to the last section encountered,
 superseding the values set in upper-level sections. This means that
 global options must be set before any sections are defined.
-.PP
+.SH SECTIONS
-The sections are:
 .PP
 \fBvolume\fR  <volume-directory>|<url>
 .RS 4
@@ -33,17 +32,19 @@ filesystem mounted with the \fIsubvolid=0\fR option.
 \fBsubvolume\fR  <subvolume-name>
 .RS 4
 Subvolume to be backed up, relative to the \fI<volume-directory>\fR
-specified in the \fIvolume\fR section.
+specified in the \fIvolume\fR section. Multiple \fIsubvolume\fR
+sections are allowed within \fIvolume\fR sections.
 .RE
 .PP
-\fBtarget\fR  <type> <volume-directory>|<url>
+\fBtarget\fR  <type> <target-directory>|<url>
 .RS 4
 Target type and directory where the backup subvolumes are to be
-created. \fI<volume-directory>\fR must be an absolute path and point
+created. See the TARGET TYPES section for supported
-to a btrfs volume (or subvolume). Currently the the only valid
+\fI<type>\fR. Multiple \fItarget\fR sections are allowed within
-\fI<type>\fR is \[lq]send\-receive\[rq].
+\fIsubvolume\fR sections.
+.RE
 .PP
-For the \fIvolume\fR and \fItarget\fR sections, you can also specify a
+For the \fIvolume\fR and \fItarget\fR sections, you can specify a
 ssh-url instead of a local directory. The syntax for \fI<url>\fR is:
 .PP
 .RS 4
@@ -56,8 +57,67 @@ 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
-The configuration options are:
+\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
+\fBtimestamp_format\fR  short|long
+.RS 4
+Timestamp format used as postfix for new snapshot subvolume names.
+defaults to \[lq]short\[rq].
+.IP \[bu] 2
+\fIshort\fR: YYYYMMDD[_N] (e.g. "20150825", "20150825_1")
+.IP \[bu]
+\fIlong\fR:  YYYYMMDD<T>hhmm[_N] (e.g. "20150825T1531")
+.PP
+Note that a postfix "_N" is only appended to the timestamp if a
+snapshot/backup already exists with the timestamp of current
+date/time.
+.RE
 .PP
 \fBsnapshot_dir\fR  <directory>
 .RS 4