--- flexbackup.conf.orig	2003-09-21 22:59:58 UTC
+++ flexbackup.conf
@@ -12,29 +12,92 @@ $type = 'afio';
 
 # Configure backup "sets".
 # Not needed if you use "-dir <dir>" to backup one tree at a time.
-# Each set is a simple space-separated list of filesystems
-# Remote filesystems should denoted as 'host:dir'
-# You can use anything (other than 'all') as set names
+# Each set is a simple space-separated list of filesystems.  Remote filesystems
+# should denoted as 'host:dir'.  If the filesystem name (local or remote)
+# contains spaces, then it should be enclosed in its entirety in double quotes.
+# Multiple quoted filesystems included in a set should be space separated just
+# like unquoted filesystem.  The Perl '.' string concatenation operator can be
+# used to split excessively long lines.
 #
-# Example:
-#  $set{'set1'} = "/home /usr";
-#  $set{'set2'} = "/dir3 machine2:/dir4 machine3:/dir5";
+# You can use anything (other than 'all') as set names.
+#
+# Examples:
+#  $set{'set1'} = '/home /usr';
+#  $set{'set2'} = '/dir3 machine2:/dir4 machine3:/dir5';
+#  $set{'set3'} =
+#      '"/mnt/winmachine1/Documents and Settings" ' .
+#      '"/mnt/winmachine1/Program Files"';
 #
 # "-set all" will back up all defined sets. If you are doing a full backup
 # using tapes, each "set" will go onto a different tape and you will be
 # prompted for tape change in between.
 #
-$set{'backup'} = "/home";
+$set{'backup'} = '/home';
 
 # Subtree pruning
 # A space-separated list of directories to prune from each backup.
-# Key is a filesystem or host:dir spec as outlined above
-# regular expressions allowed (not shell-type wildcards!)
-$prune{'/'} = "tmp proc";
+# Key is a filesystem or host:dir spec as outlined above.
+# Regular expressions are allowed (not shell-type wildcards!)
+#
+# Note:  These "directories" are actually regular expressions and must
+# match "find" output relative to the path of the current backup set. This
+# means that different exclusions are needed for different backup sets.
+# This is a little tricky, so, read on.
+#
+# The regular expressions are processed by "find" but, before "find" is run,
+# FlexBackup changes into the base directory of the backup set in progress.
+# FlexBackup then runs "find" with a path of "." which means all output lines
+# start with "./".  To be helpful, FlexBackup packages each space-separated
+# prune directory as follows.  If you have a prune list like this
+#
+#     $prune{'/somedir'} = 'one two three';
+#
+# then, the constructed -regex argument to "find" looks like this
+#
+#     -regex "\./(one|two|three)"
+#
+# (with characters escaped as necessary depending on your environment).
+#
+# Another thing you need to know is that FlexBackup only uses the prune
+# terms that match the current base directory in the set you're backing
+# up.  For example, if your backup set definition looks like this
+#
+#     $set{'daily'} = '/home /root /var /usr';
+#
+# and you want to do some exclusions in "/home" and "/var" (but not the other
+# directories), you must set up a prune list for those two directories 
+# separately.  For example, to exclude bert's and ernie's home directories plus
+# /var/tmp, you would need the following:
+#
+#     $prune{'/home'} = 'bert ernie';
+#     $prune{'/var'}  = 'tmp';
+#
+# In particular, combining these *does not* work.  For example, this
+#
+#     $prune{'/'} = 'home/bert home/ernie var/tmp';
+#
+# doesn't work, unless, of course, your backup set is backing up "/", 
+# which our example is not.
+#
+# Like the $set configuration item, special handling is required for
+# directories with spaces in them.  Double quotes should surround pruning
+# targets but not the key.  Example:
+#
+#     $prune{'/mnt/winmachine1/Documents and Settings'} =
+#         '"user1/Local Settings/Temp" user2';
+#
+# Many other complex and abstruse variations are possible.  Here's one 
+# interesting corner case.  If you want to preserve a directory but none of its
+# contents, you can do it.  Picking on ernie from our previous example, preserve
+# only his home directory:
+#
+#     $prune{'/home'} = 'ernie/.*';
+#
+$prune{'/'} = 'tmp proc';
 
 # Compression
-$compress = 'gzip'; # one of false/gzip/bzip2/lzop/zip/compress/hardware
-$compr_level = '4'; # compression level (1-9) (for gzip/bzip2/lzop/zip)
+$compress = 'gzip'; # one of false/gzip/bzip2/lzop/zip/compress/hardware/lzma
+$compr_level = '4'; # compression level (1-9) (for gzip/bzip2/lzop/zip/lzma)
 
 # Buffering program - to help streaming
 $buffer = 'buffer';         # one of false/buffer/mbuffer
@@ -84,7 +147,8 @@ $staticfiles = 'false';
 # True to try and preserve file access times during backup, if the selected
 # archive program can do so. Note that if this is true, -cnewer checks (file
 # permission/status changes only, not content) are turned off when deciding
-# which files to archive on the local system.
+# which files to archive on the local system.  This is because preserving the
+# access time changes the permission/status change time in the filesystem.
 $atime_preserve = 'false';
 
 # Span across filesytems? ("dump" will ignore this option)
@@ -97,8 +161,13 @@ $traverse_fs = 'false';
 # leading directories (the filesystem specs above or the "-dir" flag).
 # Matches paths, not filenames, so put .* on the front/back as needed.
 # Comment these out to exclude nothing.
-$exclude_expr[0] = '.*/[Cc]ache/.*';
-$exclude_expr[1] = '.*~$';
+# 
+# Gentoo note:  The first example line breaks portage in a restored backup 
+# because "/usr/lib/portage/pym/cache" is not backed up.  Way too general!
+# The moral of this story is, be very careful with global excludes.  The 
+# second example is probably okay.
+# $exclude_expr[0] = '.*/[Cc]ache/.*';
+# $exclude_expr[1] = '.*~$';
 
 # If true (default), and using a tape device, level zero "set" backups
 # assume you want to erase and use a new tape for each set. If false, level
@@ -219,6 +288,8 @@ $pkgdelta_archive_changed = 'true';
 #    $path{'afio'} = 'sudo -u nonrootuser afio';
 #
 
+$path{'tar'} = '%%TAR_CMD%%';
+
 # ----------------------------------------------------------------------
 # mt operation overrides.  Set if flexbackup doesn't know the right mt
 # command(s) for your OS/device, or you want to override things.
