Merge branch 'master' into debian

Conflicts:
	AUTHORS
	ChangeLog
	handlers/maildir.in
	handlers/mysql.in
	handlers/rsync.in
	handlers/sys.helper.in
	handlers/sys.in
	src/backupninja.in

3 files changed, 274 insertions, 151 deletions

diff --git a/examples/example.dup b/examples/example.dup
index 830a47d..ea4d66e 100644
--- a/examples/example.dup
+++ b/examples/example.dup
@@ -1,16 +1,34 @@
+## This is an example duplicity configuration file. 
+##
+## Here you can find all the possible duplicity options, details of
+## what the options provide and possible settings. The defaults are set
+## as the commented out option, uncomment and change when
+## necessary. Options which are uncommented in this example do not have
+## defaults, and the settings provided are recommended.
+
+## passed directly to duplicity, e.g. to increase verbosity set this to:
+## options = --verbosity 8
+## when using the Amazon S3 backend to create buckets in Europe:
+## options = --s3-european-buckets --s3-use-new-style
+##
+## Default:
+# options = 
 
-# passed directly to duplicity
-#options = --verbosity 8
-
-# default is 0, but set to 19 if you want to lower the priority.
-nicelevel = 19
+## default is 0, but set to something like 19 if you want to lower the priority.
+##
+## Default:
+# nicelevel = 0
 
-# default is yes. set to no to skip the test if the remote host is alive
-#testconnect = no
+## test the connection? set to no to skip the test if the remote host is alive
+##
+## Default:
+# testconnect = yes
 
-# temporary directory used by duplicity
-# (default = /tmp or /usr/tmp, depending on the system)
-#tmpdir = /var/tmp/duplicity
+## temporary directory used by duplicity, set to some other location if your /tmp is small
+## default is either /tmp or /usr/tmp, depending on the system
+## 
+## Default:
+# tmpdir = /tmp
 
 ######################################################
 ## gpg section
@@ -35,23 +53,36 @@ nicelevel = 19
 
 [gpg]
 
-# when set to yes, encryptkey variable must be set below; if you want to use
-# two different keys for encryption and signing, you must also set the signkey
-# variable below.
-# default is no, for backwards compatibility with backupninja <= 0.5.
-sign = yes
-
-# ID of the GnuPG public key used for data encryption.
-# if not set, symmetric encryption is used, and data signing is not possible.
-encryptkey = 04D9EA79
-
-# ID of the GnuPG private key used for data signing.
-# if not set, encryptkey will be used.
-#signkey = 04D9EA79
+## when set to yes, encryptkey variable must be set below; if you want to use
+## two different keys for encryption and signing, you must also set the signkey
+## variable below.
+## default is set to no, for backwards compatibility with backupninja <= 0.5.
+##
+## Default:
+# sign = no
 
-# password
-# NB: neither quote this, nor should it contain any quotes
-password = a_very_complicated_passphrase
+## ID of the GnuPG public key used for data encryption.
+## if not set, symmetric encryption is used, and data signing is not possible.
+## an example setting would be:
+## encryptkey = 04D9EA79
+##
+## Default:
+# encryptkey = 
+
+## ID of the GnuPG private key used for data signing.
+## if not set, encryptkey will be used, an example setting would be:
+## signkey = 04D9EA79
+## 
+## Default:
+# signkey = 
+
+## password
+## NB: neither quote this, nor should it contain any quotes, 
+## an example setting would be:
+## password = a_very_complicated_passphrase
+##
+## Default:
+# password = 
 
 ######################################################
 ## source section
@@ -59,23 +90,23 @@ password = a_very_complicated_passphrase
 
 [source]
 
-# A few notes about includes and excludes:
-# 1. include, exclude and vsinclude statements support globbing with '*'
-# 2. Symlinks are not dereferenced. Moreover, an include line whose path
-#    contains, at any level, a symlink to a directory, will only have the
-#    symlink backed-up, not the target directory's content. Yes, you have to
-#    dereference yourself the symlinks, or to use 'mount --bind' instead.
-#    Example: let's say /home is a symlink to /mnt/crypt/home ; the following
-#    line will only backup a "/home" symlink ; neither /home/user nor
-#    /home/user/Mail will be backed-up :
-#      include = /home/user/Mail
-#    A workaround is to 'mount --bind /mnt/crypt/home /home' ; another one is to
-#    write :
-#      include = /mnt/crypt/home/user/Mail
-# 3. All the excludes come after all the includes. The order is not otherwise
-#    taken into account.
-
-# files to include in the backup
+## A few notes about includes and excludes:
+## 1. include, exclude and vsinclude statements support globbing with '*'
+## 2. Symlinks are not dereferenced. Moreover, an include line whose path
+##    contains, at any level, a symlink to a directory, will only have the
+##    symlink backed-up, not the target directory's content. Yes, you have to
+##    dereference yourself the symlinks, or to use 'mount --bind' instead.
+##    Example: let's say /home is a symlink to /mnt/crypt/home ; the following
+##    line will only backup a "/home" symlink ; neither /home/user nor
+##    /home/user/Mail will be backed-up :
+##      include = /home/user/Mail
+##    A workaround is to 'mount --bind /mnt/crypt/home /home' ; another one is to
+##    write :
+##      include = /mnt/crypt/home/user/Mail
+## 3. All the excludes come after all the includes. The order is not otherwise
+##    taken into account.
+
+## files to include in the backup
 include = /var/spool/cron/crontabs
 include = /var/backups
 include = /etc
@@ -86,20 +117,20 @@ include = /usr/local/sbin
 include = /var/lib/dpkg/status
 include = /var/lib/dpkg/status-old
 
-# If vservers = yes in /etc/backupninja.conf then the following variables can
-# be used:
-# vsnames = all | <vserver1> <vserver2> ... (default = all)
-# vsinclude = <path>
-# vsinclude = <path>
-# ...
-# Any path specified in vsinclude is added to the include list for each vserver
-# listed in vsnames (or all if vsnames = all, which is the default).
-#
-# For example, vsinclude = /home will backup the /home directory in every
-# vserver listed in vsnames. If you have 'vsnames = foo bar baz', this
-# vsinclude will add to the include list /vservers/foo/home, /vservers/bar/home
-# and /vservers/baz/home.
-# Vservers paths are derived from $VROOTDIR.
+## If vservers = yes in /etc/backupninja.conf then the following variables can
+## be used:
+## vsnames = all | <vserver1> <vserver2> ... (default = all)
+## vsinclude = <path>
+## vsinclude = <path>
+## ...
+## Any path specified in vsinclude is added to the include list for each vserver
+## listed in vsnames (or all if vsnames = all, which is the default).
+##
+## For example, vsinclude = /home will backup the /home directory in every
+## vserver listed in vsnames. If you have 'vsnames = foo bar baz', this
+## vsinclude will add to the include list /vservers/foo/home, /vservers/bar/home
+## and /vservers/baz/home.
+## Vservers paths are derived from $VROOTDIR.
 
 # files to exclude from the backup
 exclude = /home/*/.gnupg
@@ -110,38 +141,77 @@ exclude = /home/*/.gnupg
 
 [dest]
 
-# perform an incremental backup? (default = yes)
-# if incremental = no, perform a full backup in order to start a new backup set
-#incremental = yes
-
-# how many days of data to keep ; default is 60 days.
-# (you can also use the time format of duplicity)
-# 'keep = yes' means : do not delete old data, the remote host will take care of this
-#keep = 60
-#keep = yes
-
-# full destination URL, in duplicity format; if set, desturl overrides
-# sshoptions, destdir, desthost and destuser; it also disables testconnect and
-# bandwithlimit. For details, see duplicity manpage, section "URL FORMAT".
-#desturl = file:///usr/local/backup
-#desturl = rsync://user@other.host//var/backup/bla
-
-# bandwith limit, in kbit/s ; default is 0, i.e. no limit
-#bandwidthlimit = 128
+## perform an incremental backup? (default = yes)
+## if incremental = no, perform a full backup in order to start a new backup set
+##
+## Default: 
+# incremental = yes
 
-# passed directly to ssh, scp (and sftp in duplicity >=0.4.2)
-# warning: sftp does not support all scp options, especially -i; as
-# a workaround, you can use "-o <SSHOPTION>"
-sshoptions = -o IdentityFile=/root/.ssh/id_dsa_duplicity
+## how many days of data to keep ; default is 60 days.
+## (you can also use the time format of duplicity)
+## 'keep = yes' means : do not delete old data, the remote host will take care of this
+##
+## Default:
+# keep = 60
+
+## full destination URL, in duplicity format; if set, desturl overrides
+## sshoptions, destdir, desthost and destuser; it also disables testconnect and
+## bandwithlimit. For details, see duplicity manpage, section "URL FORMAT", some
+## examples include:
+## desturl = file:///usr/local/backup
+## desturl = rsync://user@other.host//var/backup/bla
+## desturl = s3+http://
+## the default value of this configuration option is not set:
+##
+## Default:
+# desturl = 
 
-# put the backups under this directory
-destdir = /backups
+## Amazon Web Services Access Key ID and Secret Access Key, needed for backups
+## to S3 buckets.
+## awsaccesskeyid = YOUR_AWS_ACCESS_KEY_ID
+## awssecretaccesskey = YOUR_AWS_SECRET_KEY
+##
+## Default:
+# awsaccesskeyid = 
+# awssecretaccesskey = 
 
-# the machine which will receive the backups
-desthost = backuphost
+## bandwith limit, in kbit/s ; default is 0, i.e. no limit an example
+## setting would be:
+## bandwidthlimit = 128
+##
+## Default:
+# bandwidthlimit = 0
+
+## passed directly to ssh, scp (and sftp in duplicity >=0.4.2)
+## warning: sftp does not support all scp options, especially -i; as
+## a workaround, you can use "-o <SSHOPTION>"
+## an example setting would be:
+## sshoptions = -o IdentityFile=/root/.ssh/id_dsa_duplicity
+##
+## Default:
+# sshoptions = 
+
+## put the backups under this directory, this must be set!
+## an example setting would be:
+## destdir = /backups
+## 
+## Default:
+# destdir = 
+
+## the machine which will receive the backups, this must be set!
+## an example setting would be:
+## desthost = backuphost
+## 
+## Default: 
+# desthost = 
+
+## make the files owned by this user
+## note: you must be able to ssh backupuser@backhost
+## without specifying a password (if type = remote).
+## an example setting would be:
+## destuser = backupuser
+##
+## Default:
+# destuser =
 
-# make the files owned by this user
-# note: you must be able to ssh backupuser@backhost
-# without specifying a password (if type = remote).
-destuser = backupuser
 
diff --git a/examples/example.maildir b/examples/example.maildir
index 8898a78..eba5429 100644
--- a/examples/example.maildir
+++ b/examples/example.maildir
@@ -50,6 +50,16 @@ desthost = kakapo-pn
 # arbitrary bash commands on the desthost.
 destuser = backer
 
+# For alternate ports from the default 22, specify here
+destport = 4444
+
+# If you need to specify an alternate ssh public key authentication file 
+# do that here. Default: /root/.ssh/id_rsa
+destid_file = /home/backupkeys/.ssh/maildirbackup_id_rsa
+
+# If you need to specify other ssh configuration options, do that here
+sshoptions = "-C -6"
+
 # remove any maildirs from backup which might have been deleted
 remove = yes
 
diff --git a/examples/example.rdiff b/examples/example.rdiff
index 3767f9b..08e8869 100644
--- a/examples/example.rdiff
+++ b/examples/example.rdiff
@@ -1,16 +1,33 @@
 ##
 ## This is an example rdiff-backup configuration file.
-## The defaults are useful in most cases, just make sure
-## to configure the destination host and user.
+##
+## Here you can find all the possible rdiff-backup options, details of
+## what the options provide and possible settings. The defaults are set
+## as the commented out option, uncomment and change when
+## necessary. Options which are uncommented in this example do not have
+## defaults, and the settings provided are recommended.
+## 
+## The defaults are useful in most cases, just make sure to configure the 
+## destination host and user.
 ##
 
 ## passed directly to rdiff-backup
-# options = --force
+## an example setting would be:
+## options = --force
+## 
+## Default:
+# options = 
 
 ## default is 0, but set to 19 if you want to lower the priority.
-# nicelevel = 19
+## an example setting would be:
+## nicelevel = 19
+##
+## Default
+# nicelevel = 0
 
 ## default is yes. set to no to skip the test if the remote host is alive
+##
+## Default:
 # testconnect = no
 
 ## default is not to limit bandwidth. 
@@ -18,7 +35,11 @@
 ## number to set a limit that will never be exceeded, or a positive number 
 ## to set a target average bandwidth use. cstream is required. See cstream's 
 ## -t option for more information. 62500 bytes = 500 Kb (.5 Mb)
-# bwlimit = 62500
+## an example setting would be:
+## bwlimit = 62500
+##
+## Default:
+# bwlimit = 0
 
 ## should backupninja ignore the version differences between source and remote
 ## rdiff-backup? (default: no)
@@ -28,6 +49,8 @@
 ## An example usage could be the remote side has its authorized_keys configured
 ## with command="rdiff-backup --server" to allow for restricted yet automated 
 ## password-less backups
+## 
+## Default:
 # ignore_version = no
 
 ######################################################
@@ -36,39 +59,42 @@
 
 [source]
 
-# an optional subdirectory below 'directory' (see [dest])
+## an optional subdirectory below 'directory' (see [dest])
 label = thishostname
 
-# type can be "local" or "remote"
+## type can be "local" or "remote"
 type = local
 
-# only use if '[source] type = remote'
-#host = srchost
-#user = srcuser
-
-# how many days of data to keep
-# (you can also use the time format of rdiff-backup, e.g. 6D5h)
-# (to keep everything, set this to yes)
-#keep = yes
-keep = 60
-
-# A few notes about includes and excludes:
-# 1. include, exclude and vsinclude statements support globbing with '*'
-# 2. Symlinks are not dereferenced. Moreover, an include line whose path
-#    contains, at any level, a symlink to a directory, will only have the
-#    symlink backed-up, not the target directory's content. Yes, you have to
-#    dereference yourself the symlinks, or to use 'mount --bind' instead.
-#    Example: let's say /home is a symlink to /mnt/crypt/home ; the following
-#    line will only backup a "/home" symlink ; neither /home/user nor
-#    /home/user/Mail will be backed-up :
-#      include = /home/user/Mail
-#    A workaround is to 'mount --bind /mnt/crypt/home /home' ; another one is to
-#    write :
-#      include = /mnt/crypt/home/user/Mail
-# 3. All the excludes come after all the includes. The order is not otherwise
-#    taken into account.
-
-# files to include in the backup
+## only use if '[source] type = remote'
+# host = srchost
+# user = srcuser
+
+## how many days of data to keep
+## (you can also use the time format of rdiff-backup, e.g. 6D5h)
+## (to keep everything, set this to yes)
+## an example setting would be:
+##keep = yes
+##
+## Default:
+# keep = 60
+
+## A few notes about includes and excludes:
+## 1. include, exclude and vsinclude statements support globbing with '*'
+## 2. Symlinks are not dereferenced. Moreover, an include line whose path
+##    contains, at any level, a symlink to a directory, will only have the
+##    symlink backed-up, not the target directory's content. Yes, you have to
+##    dereference yourself the symlinks, or to use 'mount --bind' instead.
+##    Example: let's say /home is a symlink to /mnt/crypt/home ; the following
+##    line will only backup a "/home" symlink ; neither /home/user nor
+##    /home/user/Mail will be backed-up :
+##      include = /home/user/Mail
+##    A workaround is to 'mount --bind /mnt/crypt/home /home' ; another one is to
+##    write :
+##      include = /mnt/crypt/home/user/Mail
+## 3. All the excludes come after all the includes. The order is not otherwise
+##    taken into account.
+
+## files to include in the backup
 include = /var/spool/cron/crontabs
 include = /var/backups
 include = /etc
@@ -79,23 +105,23 @@ include = /usr/local/sbin
 include = /var/lib/dpkg/status
 include = /var/lib/dpkg/status-old
 
-# If vservers = yes in /etc/backupninja.conf then the following variables can
-# be used:
-# vsnames = all | <vserver1> <vserver2> ... (default = all)
-# vsinclude = <path>
-# vsinclude = <path>
-# ...
-# Any path specified in vsinclude is added to the include list for each vserver
-# listed in vsnames (or all if vsnames = all, which is the default).
-#
-# For example, vsinclude = /home will backup the /home directory in every
-# vserver listed in vsnames. If you have 'vsnames = foo bar baz', this
-# vsinclude will add to the include list /vservers/foo/home, /vservers/bar/home
-# and /vservers/baz/home.
-# Vservers paths are derived from $VROOTDIR.
-
-# files to exclude from the backup
-#exclude = /home/*/.gnupg
+## If vservers = yes in /etc/backupninja.conf then the following variables can
+## be used:
+## vsnames = all | <vserver1> <vserver2> ... (default = all)
+## vsinclude = <path>
+## vsinclude = <path>
+## ...
+## Any path specified in vsinclude is added to the include list for each vserver
+## listed in vsnames (or all if vsnames = all, which is the default).
+##
+## For example, vsinclude = /home will backup the /home directory in every
+## vserver listed in vsnames. If you have 'vsnames = foo bar baz', this
+## vsinclude will add to the include list /vservers/foo/home, /vservers/bar/home
+## and /vservers/baz/home.
+## Vservers paths are derived from $VROOTDIR.
+
+## files to exclude from the backup
+exclude = /home/*/.gnupg
 
 ######################################################
 ## destination section
@@ -103,18 +129,35 @@ include = /var/lib/dpkg/status-old
 
 [dest]
 
-# type can be "local" or "remote"
-type = remote
-
-# put the backups under this directory
-directory = /backups
-
-# the machine which will receive the backups.
-# only use if "[dest] type = remote"
-host = backuphost
+## type can be "local" or "remote", this must be set!
+## an example configuration would be:
+## type = remote
+##
+## Default:
+# type =
+
+## put the backups under this directory, this must be set!
+## an example setting would be:
+## directory = /backups
+## 
+## Default:
+# directory =
+
+## the machine which will receive the backups.
+## only use if "[dest] type = remote"
+## an example setting would be:
+## host = backuphost
+##
+## Default
+# host =
+
+## make the files owned by this user. you must be able to
+## `su -c "ssh backupuser@backhost"` without specifying a password.
+## only use if "[dest] type = remote"
+## an example setting would be:
+## user = backupuser
+##
+## Default:
+# user =
 
-# make the files owned by this user. you must be able to
-# `su -c "ssh backupuser@backhost"` without specifying a password.
-# only use if "[dest] type = remote"
-user = backupuser