<!-- 
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
#
#              C E D A R
#          S O L U T I O N S       "Software done right."
#           S O F T W A R E
#
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
#
# Copyright (c) 2005-2008,2010,2014,2015 Kenneth J. Pronovici.
# All rights reserved.
#
# This work is free; you can redistribute it and/or modify it
# under the terms of the GNU General Public License, Version 2,
# as published by the Free Software Foundation.
#
# This work is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
#
# Copies of the GNU General Public License are available from
# the Free Software Foundation website, http://www.gnu.org/.
#
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
#
# Author   : Kenneth J. Pronovici <pronovic@ieee.org>
# Language : O'Reilly DocBook Lite XML DTD
# Project  : Cedar Backup, release 3
# Purpose  : Cedar Backup software manual, Official Extensions chapter.
#
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
-->

<chapter id="cedar-extensions">

   <title>Official Extensions</title>

   <!-- ################################################################# -->

   <sect1 id="cedar-extensions-sysinfo">

      <title>System Information Extension</title>

      <para>
         The System Information Extension is a simple Cedar Backup extension
         used to save off important system recovery information that might be
         useful when reconstructing a <quote>broken</quote> system.  It is
         intended to be run either immediately before or immediately after the
         standard collect action.
      </para>

      <para>
         This extension saves off the following information to the configured
         Cedar Backup collect directory.  Saved off data is always compressed
         using <command>bzip2</command>.
      </para>

      <itemizedlist>
         <listitem><para>Currently-installed Debian packages via <command>dpkg --get-selections</command></para></listitem>
         <listitem><para>Disk partition information via <command>fdisk -l</command></para></listitem>
         <listitem><para>System-wide mounted filesystem contents, via <command>ls -laR</command></para></listitem>
      </itemizedlist>

      <para>
         The Debian-specific information is only collected on systems where
         <filename>/usr/bin/dpkg</filename> exists.
      </para>

      <para>
         To enable this extension, add the following section to the Cedar Backup
         configuration file:
      </para>
      
      <programlisting>
&lt;extensions&gt;
   &lt;action&gt;
      &lt;name&gt;sysinfo&lt;/name&gt;
      &lt;module&gt;CedarBackup3.extend.sysinfo&lt;/module&gt;
      &lt;function&gt;executeAction&lt;/function&gt;
      &lt;index&gt;99&lt;/index&gt;
   &lt;/action&gt;
&lt;/extensions&gt;
      </programlisting>

      <para>
         This extension relies on the options and collect configuration
         sections in the standard Cedar Backup configuration file, but
         requires no new configuration of its own.  
      </para>

   </sect1>

   <!-- ################################################################# -->

   <sect1 id="cedar-extensions-amazons3">

      <title>Amazon S3 Extension</title>

      <para>
         The Amazon S3 extension writes data to Amazon S3 cloud storage rather
         than to physical media.  It is intended to replace the store action,
         but you can also use it alongside the store action if you'd prefer to
         backup your data in more than one place.  This extension must be run
         after the stage action.
      </para>

      <para>
         The underlying functionality relies on the 
         <ulink url="http://aws.amazon.com/documentation/cli/">AWS CLI</ulink> toolset.
         Before you use this extension, you need to set up your Amazon S3
         account and configure AWS CLI as detailed in Amazons's 
         <ulink url="http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-set-up.html">setup guide</ulink>.
         The extension assumes that the backup is being executed as root, and
         switches over to the configured backup user to run the
         <command>aws</command> program.  So, make sure you configure the AWS
         CLI tools as the backup user and not root.  (This is different than
         the amazons3 sync tool extension, which executes AWS CLI command as
         the same user that is running the tool.)
      </para>

      <para>
         You can use whichever Amazon-supported authentication mechanism you
         would like when setting up connectivity for the AWS CLI.  It's best
         to set up a separate user in the 
         <ulink url="https://console.aws.amazon.com/iam/home">IAM Console</ulink>
         rather than using your main administrative user.
      </para>

      <para>
         You probably want to lock down this user so that it can only take
         backup related actions in the AWS infrastructure.  One option is to
         apply the <command>AmazonS3FullAccess</command> policy, which grants
         full access to the S3 infrastructure.  If you would like to lock down
         the user even further, this appears to be the minimum set of
         permissions required for Cedar Backup, written as a JSON policy
         statement:
      </para>

      <programlisting>
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:ListObjects",
                "s3:PutObject",
                "s3:PutObjectAcl",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::my-bucket",
                "arn:aws:s3:::my-bucket/*"
            ]
        }
    ]
}
      </programlisting>

      <para>
         In the <literal>Resource</literal> section, be sure to list the name
         of your S3 bucket instead of <literal>my-bucket</literal>.
      </para>

      <para>
         When using physical media via the standard store action, there is an
         implicit limit to the size of a backup, since a backup must fit on a
         single disc.  Since there is no physical media, no such limit exists
         for Amazon S3 backups.  This leaves open the possibility that Cedar
         Backup might construct an unexpectedly-large backup that the
         administrator is not aware of.  Over time, this might become
         expensive, either in terms of network bandwidth or in terms of Amazon
         S3 storage and I/O charges.  To mitigate this risk, set a reasonable
         maximum size using the configuration elements shown below.  If the
         backup fails, you have a chance to review what made the backup larger
         than you expected, and you can either correct the problem (i.e. remove
         a large temporary directory that got inadvertently included in the
         backup) or change configuration to take into account the new "normal"
         maximum size.
      </para>

      <para>
         You can optionally configure Cedar Backup to encrypt data before
         sending it to S3.  To do that, provide a complete command line using
         the <literal>${input}</literal> and <literal>${output}</literal>
         variables to represent the original input file and the encrypted
         output file.  This command will be executed as the backup user.
      </para>

      <para>
         For instance, you can use something like this with GPG:
      </para>

      <programlisting>
/usr/bin/gpg -c --no-use-agent --batch --yes --passphrase-file /home/backup/.passphrase -o ${output} ${input}
      </programlisting>

      <para>
         The GPG mechanism depends on a strong passphrase for security.  One way to
         generate a strong passphrase is using your system random number generator, i.e.:
      </para>

      <programlisting>
dd if=/dev/urandom count=20 bs=1 | xxd -ps
      </programlisting>

      <para>
         (See <ulink url="http://security.stackexchange.com/questions/14867/gpg-encryption-security">StackExchange</ulink>
         for more details about that advice.) If you decide to use encryption, make sure you
         save off the passphrase in a safe place, so you can get at your backup data
         later if you need to.  And obviously, make sure to set permissions on the
         passphrase file so it can only be read by the backup user.
      </para>

      <para>
         To enable this extension, add the following section to the Cedar Backup
         configuration file:
      </para>
      
      <programlisting>
&lt;extensions&gt;
   &lt;action&gt;
      &lt;name&gt;amazons3&lt;/name&gt;
      &lt;module&gt;CedarBackup3.extend.amazons3&lt;/module&gt;
      &lt;function&gt;executeAction&lt;/function&gt;
      &lt;index&gt;201&lt;/index&gt; &lt;!-- just after stage --&gt;
   &lt;/action&gt;
&lt;/extensions&gt;
      </programlisting>
      
      <para>
         This extension relies on the options and staging configuration sections
         in the standard Cedar Backup configuration file, and then also
         requires its own <literal>amazons3</literal> configuration section.
         This is an example configuration section with encryption disabled:
      </para> 

      <programlisting>
&lt;amazons3&gt;
      &lt;s3_bucket&gt;example.com-backup/staging&lt;/s3_bucket&gt;
&lt;/amazons3&gt;
      </programlisting>

      <para>
         The following elements are part of the Amazon S3 configuration section:
      </para>

      <variablelist>

         <varlistentry>
            <term><literal>warn_midnite</literal></term>
            <listitem>
               <para>Whether to generate warnings for crossing midnite.</para>
               <para>
                  This field indicates whether warnings should be generated
                  if the Amazon S3 operation has to cross a midnite boundary in
                  order to find data to write to the cloud.  For instance, a
                  warning would be generated if valid data was only
                  found in the day before or day after the current day.
               </para>
               <para>
                  Configuration for some users is such that the amazons3
                  operation will always cross a midnite boundary, so they
                  will not care about this warning.  Other users will expect
                  to never cross a boundary, and want to be notified that
                  something <quote>strange</quote> might have happened.
               </para>
               <para>
                  This field is optional.  If it doesn't exist, then
                  <literal>N</literal> will be assumed.
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> Must be a boolean (<literal>Y</literal> or <literal>N</literal>).
               </para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term><literal>s3_bucket</literal></term>
            <listitem>
               <para>The name of the Amazon S3 bucket that data will be written to.</para>
               <para>
                  This field configures the S3 bucket that your data will be
                  written to.  In S3, buckets are named globally.  For
                  uniqueness, you would typically use the name of your domain
                  followed by some suffix, such as <literal>example.com-backup</literal>.  
                  If you want, you can specify a subdirectory within the bucket,
                  such as <literal>example.com-backup/staging</literal>.
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> Must be non-empty.
               </para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term><literal>encrypt</literal></term>
            <listitem>
               <para>Command used to encrypt backup data before upload to S3</para>
               <para>
                  If this field is provided, then data will be encrypted before
                  it is uploaded to Amazon S3.  You must provide the entire
                  command used to encrypt a file, including the
                  <literal>${input}</literal> and <literal>${output}</literal>
                  variables.  An example GPG command is shown above, but you
                  can use any mechanism you choose.  The command will be run as
                  the configured backup user.
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> If provided, must be non-empty.
               </para>
            </listitem>
         </varlistentry>
         
         <varlistentry>
            <term><literal>full_size_limit</literal></term>
            <listitem>
               <para>Maximum size of a full backup</para>
               <para>
                  If this field is provided, then a size limit will be applied
                  to full backups.  If the total size of the selected staging
                  directory is greater than the limit, then the backup will
                  fail.  
               </para>
               <para>
                  You can enter this value in two different forms.  It can
                  either be a simple number, in which case the value is assumed
                  to be in bytes; or it can be a number followed by a unit
                  (KB, MB, GB).  
               </para>
               <para>
                  Valid examples are <quote>10240</quote>, <quote>250
                  MB</quote> or <quote>1.1 GB</quote>.
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> Must be a value as described above, greater than zero.
               </para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term><literal>incr_size_limit</literal></term>
            <listitem>
               <para>Maximum size of an incremental backup</para>
               <para>
                  If this field is provided, then a size limit will be applied
                  to incremental backups.  If the total size of the selected
                  staging directory is greater than the limit, then the backup
                  will fail.  
               </para>
               <para>
                  You can enter this value in two different forms.  It can
                  either be a simple number, in which case the value is assumed
                  to be in bytes; or it can be a number followed by a unit
                  (KB, MB, GB).  
               </para>
               <para>
                  Valid examples are <quote>10240</quote>, <quote>250
                  MB</quote> or <quote>1.1 GB</quote>.
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> Must be a value as described above, greater than zero.
               </para>
            </listitem>
         </varlistentry>

      </variablelist>


   </sect1>

   <!-- ################################################################# -->

   <sect1 id="cedar-extensions-subversion">

      <title>Subversion Extension</title>

      <para>
         The Subversion Extension is a Cedar Backup extension
         used to back up Subversion 
         <footnote><para>See <ulink url="http://subversion.org"/></para></footnote>
         version control repositories via the Cedar Backup command line.
         It is intended to be run either immediately before or immediately
         after the standard collect action.
      </para>

      <para>
         Each configured Subversion repository can be backed using the same
         collect modes allowed for filesystems in the standard Cedar Backup
         collect action (weekly, daily, incremental) and the output can be
         compressed using either <command>gzip</command> or
         <command>bzip2</command>.
      </para>

      <para>
         There are two different kinds of Subversion repositories at this
         writing: BDB (Berkeley Database) and FSFS (a "filesystem within a
         filesystem").  This extension backs up both kinds of repositories in
         the same way, using <command>svnadmin dump</command> in an incremental
         mode.  
      </para>
         
      <para>
         It turns out that FSFS repositories can also be backed up just like
         any other filesystem directory.  If you would rather do the backup
         that way, then use the normal collect action rather than this
         extension.  If you decide to do that, be sure to consult the
         Subversion documentation and make sure you understand the limitations
         of this kind of backup. 
      </para>

      <para>
         To enable this extension, add the following section to the Cedar Backup
         configuration file:
      </para>
      
      <programlisting>
&lt;extensions&gt;
   &lt;action&gt;
      &lt;name&gt;subversion&lt;/name&gt;
      &lt;module&gt;CedarBackup3.extend.subversion&lt;/module&gt;
      &lt;function&gt;executeAction&lt;/function&gt;
      &lt;index&gt;99&lt;/index&gt;
   &lt;/action&gt;
&lt;/extensions&gt;
      </programlisting>
      
      <para>
         This extension relies on the options and collect configuration
         sections in the standard Cedar Backup configuration file, and then
         also requires its own <literal>subversion</literal> configuration
         section.  This is an example Subversion configuration section:
      </para> 

      <programlisting>
&lt;subversion&gt;
   &lt;collect_mode&gt;incr&lt;/collect_mode&gt;
   &lt;compress_mode&gt;bzip2&lt;/compress_mode&gt;
   &lt;repository&gt;
      &lt;abs_path&gt;/opt/public/svn/docs&lt;/abs_path&gt;
   &lt;/repository&gt;
   &lt;repository&gt;
      &lt;abs_path&gt;/opt/public/svn/web&lt;/abs_path&gt;
      &lt;compress_mode&gt;gzip&lt;/compress_mode&gt;
   &lt;/repository&gt;
   &lt;repository_dir&gt;
      &lt;abs_path&gt;/opt/private/svn&lt;/abs_path&gt;
      &lt;collect_mode&gt;daily&lt;/collect_mode&gt;
   &lt;/repository_dir&gt;
&lt;/subversion&gt;
      </programlisting>

      <para>
         The following elements are part of the Subversion configuration section:
      </para>

      <variablelist>

         <varlistentry>
            <term><literal>collect_mode</literal></term>
            <listitem>
               <para>Default collect mode.</para>
               <para>
                  The collect mode describes how frequently a Subversion
                  repository is backed up.  The Subversion extension
                  recognizes the same collect modes as the standard Cedar
                  Backup collect action (see <xref linkend="cedar-basic"/>).
               </para>
               <para>
                  This value is the collect mode that will be used by
                  default during the backup process.  Individual
                  repositories (below) may override this value.  If
                  <emphasis>all</emphasis> individual repositories provide
                  their own value, then this default value may be omitted
                  from configuration.
               </para>
               <para>
                  Note: if your backup device does not suppport multisession
                  discs, then you should probably use the
                  <literal>daily</literal> collect mode to avoid losing
                  data.
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> Must be one of
                  <literal>daily</literal>, <literal>weekly</literal> or
                  <literal>incr</literal>.
               </para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term><literal>compress_mode</literal></term>
            <listitem>
               <para>Default compress mode.</para>
               <para>
                  Subversion repositories backups are just
                  specially-formatted text files, and often compress quite
                  well using <command>gzip</command> or
                  <command>bzip2</command>.  The compress mode describes how
                  the backed-up data will be compressed, if at all.  
               </para>
               <para>
                  This value is the compress mode that will be used by
                  default during the backup process.  Individual
                  repositories (below) may override this value.  If
                  <emphasis>all</emphasis> individual repositories provide
                  their own value, then this default value may be omitted
                  from configuration.
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> Must be one of
                  <literal>none</literal>, <literal>gzip</literal> or
                  <literal>bzip2</literal>.
               </para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term><literal>repository</literal></term>
            <listitem>
               <para>A Subversion repository be collected.</para>
               <para>
                  This is a subsection which contains information about
                  a specific Subversion repository to be backed up.
               </para>
               <para>
                  This section can be repeated as many times as is necessary.
                  At least one repository or repository directory must be
                  configured.
               </para>
               <para>
                  The <literal>repository</literal> subsection contains the
                  following fields:
               </para>

               <variablelist>

                  <varlistentry>
                     <term><literal>collect_mode</literal></term>
                     <listitem>
                        <para>Collect mode for this repository.</para>
                        <para>
                           This field is optional.  If it doesn't exist, the backup
                           will use the default collect mode.
                        </para>
                        <para>
                           <emphasis>Restrictions:</emphasis> Must be one of
                           <literal>daily</literal>, <literal>weekly</literal> or
                           <literal>incr</literal>.
                        </para>
                     </listitem>
                  </varlistentry>

                  <varlistentry>
                     <term><literal>compress_mode</literal></term>
                     <listitem>
                        <para>Compress mode for this repository.</para>
                        <para>
                           This field is optional.  If it doesn't exist, the backup
                           will use the default compress mode.
                        </para>
                        <para>
                           <emphasis>Restrictions:</emphasis> Must be one of
                           <literal>none</literal>, <literal>gzip</literal> or
                           <literal>bzip2</literal>.
                        </para>
                     </listitem>
                  </varlistentry>

                  <varlistentry>
                     <term><literal>abs_path</literal></term>
                     <listitem>
                        <para>
                           Absolute path of the Subversion repository to
                           back up.
                        </para>
                        <para>
                           <emphasis>Restrictions:</emphasis> Must be an absolute path.
                        </para>
                     </listitem>
                  </varlistentry>
               </variablelist>

            </listitem>

         </varlistentry>

         <varlistentry>
            <term><literal>repository_dir</literal></term>
            <listitem>
               <para>A Subversion parent repository directory be collected.</para>
               <para>
                  This is a subsection which contains information about a
                  Subversion parent repository directory to be backed up.  Any
                  subdirectory immediately within this directory is assumed to
                  be a Subversion repository, and will be backed up.
               </para>
               <para>
                  This section can be repeated as many times as is necessary.
                  At least one repository or repository directory must be
                  configured.
               </para>
               <para>
                  The <literal>repository_dir</literal> subsection contains the
                  following fields:
               </para>

               <variablelist>

                  <varlistentry>
                     <term><literal>collect_mode</literal></term>
                     <listitem>
                        <para>Collect mode for this repository.</para>
                        <para>
                           This field is optional.  If it doesn't exist, the backup
                           will use the default collect mode.
                        </para>
                        <para>
                           <emphasis>Restrictions:</emphasis> Must be one of
                           <literal>daily</literal>, <literal>weekly</literal> or
                           <literal>incr</literal>.
                        </para>
                     </listitem>
                  </varlistentry>

                  <varlistentry>
                     <term><literal>compress_mode</literal></term>
                     <listitem>
                        <para>Compress mode for this repository.</para>
                        <para>
                           This field is optional.  If it doesn't exist, the backup
                           will use the default compress mode.
                        </para>
                        <para>
                           <emphasis>Restrictions:</emphasis> Must be one of
                           <literal>none</literal>, <literal>gzip</literal> or
                           <literal>bzip2</literal>.
                        </para>
                     </listitem>
                  </varlistentry>

                  <varlistentry>
                     <term><literal>abs_path</literal></term>
                     <listitem>
                        <para>
                           Absolute path of the Subversion repository to
                           back up.
                        </para>
                        <para>
                           <emphasis>Restrictions:</emphasis> Must be an absolute path.
                        </para>
                     </listitem>
                  </varlistentry>

                  <varlistentry>
                     <term><literal>exclude</literal></term>
                     <listitem>
                        <para>List of paths or patterns to exclude from the backup.</para>
                        <para>
                           This is a subsection which contains a set of paths
                           and patterns to be excluded within this subversion
                           parent directory.
                        </para>
                        <para>
                           This section is entirely optional, and if it exists
                           can also be empty.  
                        </para>
                        <para>
                           The exclude subsection can contain one or more of each of
                           the following fields:
                        </para>

                        <variablelist>

                           <varlistentry>
                              <term><literal>rel_path</literal></term>
                              <listitem>
                                 <para>
                                    A relative path to be excluded from the
                                    backup.
                                 </para>
                                 <para>
                                    The path is assumed to be relative to the
                                    subversion parent directory itself.  For instance, if
                                    the configured subversion parent directory is
                                    <filename>/opt/svn</filename> a
                                    configured relative path of
                                    <filename>software</filename> would exclude the
                                    path <filename>/opt/svn/software</filename>.
                                 </para>
                                 <para>
                                    This field can be repeated as many times as
                                    is necessary.
                                 </para>
                                 <para>
                                    <emphasis>Restrictions:</emphasis> Must be non-empty.
                                 </para>
                              </listitem>
                           </varlistentry>

                           <varlistentry>
                              <term><literal>pattern</literal></term>
                              <listitem>
                                 <para>
                                    A pattern to be excluded from the backup.
                                 </para>
                                 <para>
                                    The pattern must be a Python regular
                                    expression.  <footnoteref linkend="cedar-config-foot-regex"/> 
                                    It is assumed to be bounded at front and
                                    back by the beginning and end of the
                                    string (i.e. it is treated as if it
                                    begins with <literal>^</literal> and
                                    ends with <literal>$</literal>).
                                 </para>
                                 <para>
                                    This field can be repeated as many times as
                                    is necessary.
                                 </para>
                                 <para>
                                    <emphasis>Restrictions:</emphasis> Must be non-empty
                                 </para>
                              </listitem>
                           </varlistentry>
                          
                        </variablelist>

                     </listitem>
                  </varlistentry>
               </variablelist>

            </listitem>

         </varlistentry>

      </variablelist>

   </sect1>

   <!-- ################################################################# -->

   <sect1 id="cedar-extensions-mysql">

      <title>MySQL Extension</title>

      <para>
         The MySQL Extension is a Cedar Backup extension used to back up MySQL
         <footnote><para>See <ulink url="http://www.mysql.com"/></para></footnote> 
         databases via the Cedar Backup command line.  It is intended to be run
         either immediately before or immediately after the standard collect
         action.
      </para>

      <note>
         <para>
            This extension always produces a full backup.  There is currently
            no facility for making incremental backups.  If/when someone has a
            need for this and can describe how to do it, I will update this
            extension or provide another.
         </para>
      </note>

      <para>
         The backup is done via the <command>mysqldump</command> command
         included with the MySQL product.  Output can be compressed using
         <command>gzip</command> or <command>bzip2</command>.  Administrators
         can configure the extension either to back up all databases or to back
         up only specific databases.  
      </para>

      <para>
         The extension assumes that all configured databases can be backed up
         by a single user.  Often, the <quote>root</quote> database user will
         be used.  An alternative is to create a separate MySQL
         <quote>backup</quote> user and grant that user rights to read (but not
         write) various databases as needed.  This second option is probably
         your best choice.
      </para>

      <warning>
         <para>
            The extension accepts a username and password in configuration.
            However, you probably do not want to list those values in Cedar
            Backup configuration.  This is because Cedar Backup will provide these
            values to <command>mysqldump</command> via the command-line
            <option>--user</option> and <option>--password</option> switches,
            which will be visible to other users in the process listing.
         </para>

         <para>
            Instead, you should configure the username and password in one of MySQL's
            configuration files.  Typically, that would be done by putting a stanza like
            this in <filename>/root/.my.cnf</filename>:
         </para>

         <programlisting>
[mysqldump]
user     = root
password = &lt;secret&gt;
         </programlisting>

         <para>
            Of course, if you are executing the backup as a user other than root, then
            you would create the file in that user's home directory instead.
         </para>

         <para>
            As a side note, it is also possible to configure <filename>.my.cnf</filename>
            such that Cedar Backup can back up a remote database server:
         </para>

         <programlisting>
[mysqldump]
host = remote.host
         </programlisting>

         <para>
            For this to work, you will also need to grant privileges properly
            for the user which is executing the backup.  See your MySQL documentation 
            for more information about how this can be done.
         </para>

         <para>
            Regardless of whether you are using <filename>~/.my.cnf</filename> or
            <filename>/etc/cback3.conf</filename> to store database login and
            password information, you should be careful about who is allowed to
            view that information.  Typically, this means locking down permissions
            so that only the file owner can read the file contents (i.e. use mode
            <literal>0600</literal>).
         </para>

      </warning>

      <para>
         To enable this extension, add the following section to the Cedar Backup
         configuration file:
      </para>
      
      <programlisting>
&lt;extensions&gt;
   &lt;action&gt;
      &lt;name&gt;mysql&lt;/name&gt;
      &lt;module&gt;CedarBackup3.extend.mysql&lt;/module&gt;
      &lt;function&gt;executeAction&lt;/function&gt;
      &lt;index&gt;99&lt;/index&gt;
   &lt;/action&gt;
&lt;/extensions&gt;
      </programlisting>
      
      <para>
         This extension relies on the options and collect configuration
         sections in the standard Cedar Backup configuration file, and then
         also requires its own <literal>mysql</literal> configuration section.
         This is an example MySQL configuration section:
      </para> 

      <programlisting>
&lt;mysql&gt;
   &lt;compress_mode&gt;bzip2&lt;/compress_mode&gt;
   &lt;all&gt;Y&lt;/all&gt;
&lt;/mysql&gt;
      </programlisting>

      <para>
         If you have decided to configure login information in Cedar Backup
         rather than using MySQL configuration, then you would add the username
         and password fields to configuration:
      </para>

      <programlisting>
&lt;mysql&gt;
   &lt;user&gt;root&lt;/user&gt;
   &lt;password&gt;password&lt;/password&gt;
   &lt;compress_mode&gt;bzip2&lt;/compress_mode&gt;
   &lt;all&gt;Y&lt;/all&gt;
&lt;/mysql&gt;
      </programlisting>

      <para>
         The following elements are part of the MySQL configuration section:
      </para>

      <variablelist>

         <varlistentry>
            <term><literal>user</literal></term>
            <listitem>
               <para>Database user.</para>
               <para>
                  The database user that the backup should be executed as.
                  Even if you list more than one database (below) all backups
                  must be done as the same user.  Typically, this would be
                  <literal>root</literal> (i.e. the database root user, not the
                  system root user).
               </para>
               <para>
                  This value is optional.  You should probably configure the
                  username and password in MySQL configuration instead, as
                  discussed above.
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> If provided, must be
                  non-empty.
               </para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term><literal>password</literal></term>
            <listitem>
               <para>Password associated with the database user.</para>
               <para>
                  This value is optional.  You should probably configure the
                  username and password in MySQL configuration instead, as
                  discussed above.
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> If provided, must be
                  non-empty.
               </para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term><literal>compress_mode</literal></term>
            <listitem>
               <para>Compress mode.</para>
               <para>
                  MySQL databases dumps are just
                  specially-formatted text files, and often compress quite
                  well using <command>gzip</command> or
                  <command>bzip2</command>.  The compress mode describes how
                  the backed-up data will be compressed, if at all.  
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> Must be one of
                  <literal>none</literal>, <literal>gzip</literal> or
                  <literal>bzip2</literal>.
               </para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term><literal>all</literal></term>
            <listitem>
               <para>Indicates whether to back up all databases.</para>
               <para>
                  If this value is <literal>Y</literal>, then all MySQL
                  databases will be backed up.  If this value is
                  <literal>N</literal>, then one or more specific databases
                  must be specified (see below).
               </para>
               <para>
                  If you choose this option, the entire database backup will go
                  into one big dump file.  
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> Must be a boolean
                  (<literal>Y</literal> or <literal>N</literal>).
               </para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term><literal>database</literal></term>
            <listitem>
               <para>Named database to be backed up.</para>
               <para>
                  If you choose to specify individual databases rather than all
                  databases, then each database will be backed up into its own
                  dump file.
               </para>
               <para>
                  This field can be repeated as many times as is necessary.  At
                  least one database must be configured if the all option
                  (above) is set to <literal>N</literal>.  You may not
                  configure any individual databases if the all option is set
                  to <literal>Y</literal>.
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> Must be non-empty.
               </para>
            </listitem>
         </varlistentry>

      </variablelist>

   </sect1>

   <!-- ################################################################# -->

   <sect1 id="cedar-extensions-postgresql">

      <title>PostgreSQL Extension</title>

      <sidebar>
         <title>Community-contributed Extension</title>
         <para>
            This is a community-contributed extension provided by Antoine
            Beaupre ("The Anarcat").  I have added regression tests around
            the configuration parsing code and I will maintain this section
            in the user manual based on his source code documentation.
         </para>
         <para>
            Unfortunately, I don't have any PostgreSQL databases with which to
            test the functional code.  While I have code-reviewed the code and
            it looks both sensible and safe, I have to rely on the author to
            ensure that it works properly.
         </para>
      </sidebar>

      <para>
         The PostgreSQL Extension is a Cedar Backup extension used to back up
         PostgreSQL <footnote><para>See <ulink
         url="http://www.postgresql.org/"/></para></footnote> databases via the
         Cedar Backup command line.  It is intended to be run either
         immediately before or immediately after the standard collect action. 
      </para>

      <para>
         The backup is done via the <command>pg_dump</command> or
         <command>pg_dumpall</command> commands included with the PostgreSQL
         product.  Output can be compressed using <command>gzip</command> or
         <command>bzip2</command>.  Administrators can configure the extension
         either to back up all databases or to back up only specific databases.  
      </para>

      <para>
         The extension assumes that the current user has passwordless access to
         the database since there is no easy way to pass a password to the
         <command>pg_dump</command> client. This can be accomplished using
         appropriate configuration in the <command>pg_hda.conf</command> file.
      </para>

      <para>
         This extension always produces a full backup.  There is currently
         no facility for making incremental backups.
      </para>

      <warning>
         <para>
            Once you place PostgreSQL configuration into the Cedar Backup
            configuration file, you should be careful about who is allowed to
            see that information.  This is because PostgreSQL configuration
            will contain information about available PostgreSQL databases and
            usernames.  Typically, you might want to lock down permissions so
            that only the file owner can read the file contents (i.e. use mode
            <literal>0600</literal>).
         </para>
      </warning>

      <para>
         To enable this extension, add the following section to the Cedar Backup
         configuration file:
      </para>
      
      <programlisting>
&lt;extensions&gt;
   &lt;action&gt;
      &lt;name&gt;postgresql&lt;/name&gt;
      &lt;module&gt;CedarBackup3.extend.postgresql&lt;/module&gt;
      &lt;function&gt;executeAction&lt;/function&gt;
      &lt;index&gt;99&lt;/index&gt;
   &lt;/action&gt;
&lt;/extensions&gt;
      </programlisting>
      
      <para>
         This extension relies on the options and collect configuration
         sections in the standard Cedar Backup configuration file, and then
         also requires its own <literal>postgresql</literal> configuration
         section.  This is an example PostgreSQL configuration section:
      </para> 

      <programlisting>
&lt;postgresql&gt;
   &lt;compress_mode&gt;bzip2&lt;/compress_mode&gt;
   &lt;user&gt;username&lt;/user&gt;
   &lt;all&gt;Y&lt;/all&gt;
&lt;/postgresql&gt;
      </programlisting>

      <para>
         If you decide to back up specific databases, then you would list them
         individually, like this:
      </para>

      <programlisting>
&lt;postgresql&gt;
   &lt;compress_mode&gt;bzip2&lt;/compress_mode&gt;
   &lt;user&gt;username&lt;/user&gt;
   &lt;all&gt;N&lt;/all&gt;
   &lt;database&gt;db1&lt;/database&gt;
   &lt;database&gt;db2&lt;/database&gt;
&lt;/postgresql&gt;
      </programlisting>

      <para>
         The following elements are part of the PostgreSQL configuration section:
      </para>

      <variablelist>

         <varlistentry>
            <term><literal>user</literal></term>
            <listitem>
               <para>Database user.</para>
               <para>
                  The database user that the backup should be executed as.
                  Even if you list more than one database (below) all backups
                  must be done as the same user.
               </para>
               <para>
                  This value is optional.
               </para>
               <para>
                  Consult your PostgreSQL documentation for information on how
                  to configure a default database user outside of Cedar Backup,
                  and for information on how to specify a database password
                  when you configure a user within Cedar Backup.  You will
                  probably want to modify <command>pg_hda.conf</command>.
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> If provided, must be
                  non-empty.
               </para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term><literal>compress_mode</literal></term>
            <listitem>
               <para>Compress mode.</para>
               <para>
                  PostgreSQL databases dumps are just
                  specially-formatted text files, and often compress quite
                  well using <command>gzip</command> or
                  <command>bzip2</command>.  The compress mode describes how
                  the backed-up data will be compressed, if at all.  
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> Must be one of
                  <literal>none</literal>, <literal>gzip</literal> or
                  <literal>bzip2</literal>.
               </para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term><literal>all</literal></term>
            <listitem>
               <para>Indicates whether to back up all databases.</para>
               <para>
                  If this value is <literal>Y</literal>, then all PostgreSQL
                  databases will be backed up.  If this value is
                  <literal>N</literal>, then one or more specific databases
                  must be specified (see below).
               </para>
               <para>
                  If you choose this option, the entire database backup will go
                  into one big dump file.  
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> Must be a boolean
                  (<literal>Y</literal> or <literal>N</literal>).
               </para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term><literal>database</literal></term>
            <listitem>
               <para>Named database to be backed up.</para>
               <para>
                  If you choose to specify individual databases rather than all
                  databases, then each database will be backed up into its own
                  dump file.
               </para>
               <para>
                  This field can be repeated as many times as is necessary.  At
                  least one database must be configured if the all option
                  (above) is set to <literal>N</literal>.  You may not
                  configure any individual databases if the all option is set
                  to <literal>Y</literal>.
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> Must be non-empty.
               </para>
            </listitem>
         </varlistentry>

      </variablelist>

   </sect1>

   <!-- ################################################################# -->

   <sect1 id="cedar-extensions-mbox">

      <title>Mbox Extension</title>

      <para>
         The Mbox Extension is a Cedar Backup extension used to incrementally
         back up UNIX-style <quote>mbox</quote> mail folders via the Cedar
         Backup command line.  It is intended to be run either immediately
         before or immediately after the standard collect action.
      </para>

      <para>
         Mbox mail folders are not well-suited to being backed up by the normal
         Cedar Backup incremental backup process.  This is because active
         folders are typically appended to on a daily basis.  This forces the
         incremental backup process to back them up every day in order to avoid
         losing data.  This can result in quite a bit of wasted space when
         backing up large mail folders.
      </para>

      <para>
         What the mbox extension does is leverage the
         <command>grepmail</command> utility to back up only email messages
         which have been received since the last incremental backup.  This way,
         even if a folder is added to every day, only the recently-added
         messages are backed up.  This can potentially save a lot of space.
      </para>

      <para>
         Each configured mbox file or directory can be backed using the same
         collect modes allowed for filesystems in the standard Cedar Backup
         collect action (weekly, daily, incremental) and the output can be
         compressed using either <command>gzip</command> or
         <command>bzip2</command>.
      </para>

      <para>
         To enable this extension, add the following section to the Cedar Backup
         configuration file:
      </para>
      
      <programlisting>
&lt;extensions&gt;
   &lt;action&gt;
      &lt;name&gt;mbox&lt;/name&gt;
      &lt;module&gt;CedarBackup3.extend.mbox&lt;/module&gt;
      &lt;function&gt;executeAction&lt;/function&gt;
      &lt;index&gt;99&lt;/index&gt;
   &lt;/action&gt;
&lt;/extensions&gt;
      </programlisting>
      
      <para>
         This extension relies on the options and collect configuration
         sections in the standard Cedar Backup configuration file, and then
         also requires its own <literal>mbox</literal> configuration
         section.  This is an example mbox configuration section:
      </para> 

      <programlisting>
&lt;mbox&gt;
   &lt;collect_mode&gt;incr&lt;/collect_mode&gt;
   &lt;compress_mode&gt;gzip&lt;/compress_mode&gt;
   &lt;file&gt;
      &lt;abs_path&gt;/home/user1/mail/greylist&lt;/abs_path&gt;
      &lt;collect_mode&gt;daily&lt;/collect_mode&gt;
   &lt;/file&gt;
   &lt;dir&gt;
      &lt;abs_path&gt;/home/user2/mail&lt;/abs_path&gt;
   &lt;/dir&gt;
   &lt;dir&gt;
      &lt;abs_path&gt;/home/user3/mail&lt;/abs_path&gt;
      &lt;exclude&gt;
         &lt;rel_path&gt;spam&lt;/rel_path&gt;
         &lt;pattern&gt;.*debian.*&lt;/pattern&gt;
      &lt;/exclude&gt;
   &lt;/dir&gt;
&lt;/mbox&gt;
      </programlisting>

      <para>
         Configuration is much like the standard collect action.  Differences
         come from the fact that mbox directories are <emphasis>not</emphasis>
         collected recursively.
      </para>

      <para>
         Unlike collect configuration, exclusion information can only be
         configured at the mbox directory level (there are no global
         exclusions).  Another difference is that no absolute exclusion
         paths are allowed &mdash; only relative path exclusions and patterns.
      </para>

      <para>
         The following elements are part of the mbox configuration section:
      </para>

      <variablelist>

         <varlistentry>
            <term><literal>collect_mode</literal></term>
            <listitem>
               <para>Default collect mode.</para>
               <para>
                  The collect mode describes how frequently an mbox file
                  or directory is backed up.  The mbox extension
                  recognizes the same collect modes as the standard Cedar
                  Backup collect action (see <xref linkend="cedar-basic"/>).
               </para>
               <para>
                  This value is the collect mode that will be used by default
                  during the backup process.  Individual files or directories
                  (below) may override this value.  If <emphasis>all</emphasis>
                  individual files or directories provide their own value, then
                  this default value may be omitted from configuration.
               </para>
               <para>
                  Note: if your backup device does not suppport multisession
                  discs, then you should probably use the
                  <literal>daily</literal> collect mode to avoid losing
                  data.
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> Must be one of
                  <literal>daily</literal>, <literal>weekly</literal> or
                  <literal>incr</literal>.
               </para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term><literal>compress_mode</literal></term>
            <listitem>
               <para>Default compress mode.</para>
               <para>
                  Mbox file or directory backups are just text, and often compress
                  quite well using <command>gzip</command> or
                  <command>bzip2</command>.  The compress mode describes how
                  the backed-up data will be compressed, if at all.  
               </para>
               <para>
                  This value is the compress mode that will be used by default
                  during the backup process.  Individual files or directories
                  (below) may override this value.  If <emphasis>all</emphasis>
                  individual files or directories provide their own value, then
                  this default value may be omitted from configuration.
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> Must be one of
                  <literal>none</literal>, <literal>gzip</literal> or
                  <literal>bzip2</literal>.
               </para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term><literal>file</literal></term>
            <listitem>
               <para>An individual mbox file to be collected.</para>
               <para>
                  This is a subsection which contains information about
                  an individual mbox file to be backed up.
               </para>
               <para>
                  This section can be repeated as many times as is necessary.
                  At least one mbox file or directory must be configured.
               </para>
               <para>
                  The file subsection contains the following fields:
               </para>

               <variablelist>

                  <varlistentry>
                     <term><literal>collect_mode</literal></term>
                     <listitem>
                        <para>Collect mode for this file.</para>
                        <para>
                           This field is optional.  If it doesn't exist, the backup
                           will use the default collect mode.
                        </para>
                        <para>
                           <emphasis>Restrictions:</emphasis> Must be one of
                           <literal>daily</literal>, <literal>weekly</literal> or
                           <literal>incr</literal>.
                        </para>
                     </listitem>
                  </varlistentry>

                  <varlistentry>
                     <term><literal>compress_mode</literal></term>
                     <listitem>
                        <para>Compress mode for this file.</para>
                        <para>
                           This field is optional.  If it doesn't exist, the backup
                           will use the default compress mode.
                        </para>
                        <para>
                           <emphasis>Restrictions:</emphasis> Must be one of
                           <literal>none</literal>, <literal>gzip</literal> or
                           <literal>bzip2</literal>.
                        </para>
                     </listitem>
                  </varlistentry>

                  <varlistentry>
                     <term><literal>abs_path</literal></term>
                     <listitem>
                        <para>
                           Absolute path of the mbox file to back up.
                        </para>
                        <para>
                           <emphasis>Restrictions:</emphasis> Must be an absolute path.
                        </para>
                     </listitem>
                  </varlistentry>
               </variablelist>

            </listitem>

         </varlistentry>

         <varlistentry>
            <term><literal>dir</literal></term>
            <listitem>
               <para>An mbox directory to be collected.</para>
               <para>
                  This is a subsection which contains information about an mbox
                  directory to be backed up.  An mbox directory is a directory
                  containing mbox files.  Every file in an mbox directory is
                  assumed to be an mbox file.  Mbox directories are
                  <emphasis>not</emphasis> collected recursively.  Only the
                  files immediately within the configured directory will be
                  backed-up and any subdirectories will be ignored.
               </para>
               <para>
                  This section can be repeated as many times as is necessary.
                  At least one mbox file or directory must be configured.
               </para>
               <para>
                  The dir subsection contains the following fields:
               </para>

               <variablelist>

                  <varlistentry>
                     <term><literal>collect_mode</literal></term>
                     <listitem>
                        <para>Collect mode for this file.</para>
                        <para>
                           This field is optional.  If it doesn't exist, the backup
                           will use the default collect mode.
                        </para>
                        <para>
                           <emphasis>Restrictions:</emphasis> Must be one of
                           <literal>daily</literal>, <literal>weekly</literal> or
                           <literal>incr</literal>.
                        </para>
                     </listitem>
                  </varlistentry>

                  <varlistentry>
                     <term><literal>compress_mode</literal></term>
                     <listitem>
                        <para>Compress mode for this file.</para>
                        <para>
                           This field is optional.  If it doesn't exist, the backup
                           will use the default compress mode.
                        </para>
                        <para>
                           <emphasis>Restrictions:</emphasis> Must be one of
                           <literal>none</literal>, <literal>gzip</literal> or
                           <literal>bzip2</literal>.
                        </para>
                     </listitem>
                  </varlistentry>

                  <varlistentry>
                     <term><literal>abs_path</literal></term>
                     <listitem>
                        <para>
                           Absolute path of the mbox directory to back up.
                        </para>
                        <para>
                           <emphasis>Restrictions:</emphasis> Must be an absolute path.
                        </para>
                     </listitem>
                  </varlistentry>

                  <varlistentry>
                     <term><literal>exclude</literal></term>
                     <listitem>
                        <para>List of paths or patterns to exclude from the backup.</para>
                        <para>
                           This is a subsection which contains a set of paths
                           and patterns to be excluded within this mbox
                           directory.
                        </para>
                        <para>
                           This section is entirely optional, and if it exists can
                           also be empty.  
                        </para>
                        <para>
                           The exclude subsection can contain one or more of each of
                           the following fields:
                        </para>

                        <variablelist>

                           <varlistentry>
                              <term><literal>rel_path</literal></term>
                              <listitem>
                                 <para>
                                    A relative path to be excluded from the
                                    backup.
                                 </para>
                                 <para>
                                    The path is assumed to be relative to the
                                    mbox directory itself.  For instance, if
                                    the configured mbox directory is
                                    <filename>/home/user2/mail</filename> a
                                    configured relative path of
                                    <filename>SPAM</filename> would exclude the
                                    path <filename>/home/user2/mail/SPAM</filename>.
                                 </para>
                                 <para>
                                    This field can be repeated as many times as
                                    is necessary.
                                 </para>
                                 <para>
                                    <emphasis>Restrictions:</emphasis> Must be non-empty.
                                 </para>
                              </listitem>
                           </varlistentry>

                           <varlistentry>
                              <term><literal>pattern</literal></term>
                              <listitem>
                                 <para>
                                    A pattern to be excluded from the backup.
                                 </para>
                                 <para>
                                    The pattern must be a Python regular
                                    expression.  <footnoteref linkend="cedar-config-foot-regex"/> 
                                    It is assumed to be bounded at front and
                                    back by the beginning and end of the
                                    string (i.e. it is treated as if it
                                    begins with <literal>^</literal> and
                                    ends with <literal>$</literal>).
                                 </para>
                                 <para>
                                    This field can be repeated as many times as
                                    is necessary.
                                 </para>
                                 <para>
                                    <emphasis>Restrictions:</emphasis> Must be non-empty
                                 </para>
                              </listitem>
                           </varlistentry>
                          
                        </variablelist>

                     </listitem>
                  </varlistentry>

               </variablelist>

            </listitem>

         </varlistentry>

      </variablelist>

   </sect1>

   <!-- ################################################################# -->

   <sect1 id="cedar-extensions-encrypt">

      <title>Encrypt Extension</title>

      <para>
         The Encrypt Extension is a Cedar Backup extension used to encrypt
         backups.  It does this by encrypting the contents of a master's
         staging directory each day after the stage action is run.  This way,
         backed-up data is encrypted both when sitting on the master and when
         written to disc.  This extension must be run before the standard store
         action, otherwise unencrypted data will be written to disc.
      </para>

      <para>
         There are several differents ways encryption could have been built in
         to or layered on to Cedar Backup.  I asked the mailing list for
         opinions on the subject in January 2007 and did not get a lot of
         feedback, so I chose the option that was simplest to understand and
         simplest to implement.  If other encryption use cases make themselves
         known in the future, this extension can be enhanced or replaced.
      </para>

      <para>
         Currently, this extension supports only GPG.  However, it would be
         straightforward to support other public-key encryption mechanisms,
         such as OpenSSL.
      </para>

      <warning>
         <para>
            If you decide to encrypt your backups, be <emphasis>absolutely
            sure</emphasis> that you have your GPG secret key saved off
            someplace safe &mdash; someplace other than on your backup disc.
            If you lose your secret key, your backup will be useless.
         </para>

         <para>
            I suggest that before you rely on this extension, you should
            execute a dry run and make sure you can successfully decrypt the
            backup that is written to disc.
         </para>
      </warning>

      <para>
         Before configuring the Encrypt extension, you must configure GPG.
         Either create a new keypair or use an existing one.  Determine which
         user will execute your backup (typically root) and have that user
         import <emphasis>and lsign</emphasis> the public half of the keypair.
         Then, save off the secret half of the keypair someplace safe, apart
         from your backup (i.e. on a floppy disk or USB drive).  Make sure you
         know the recipient name associated with the public key because you'll
         need it to configure Cedar Backup.  (If you can run 
         <command>gpg -e -r "Recipient Name" file.txt</command> 
         and it executes cleanly with no user interaction required, you should
         be OK.)
      </para>

      <para>
         An encrypted backup has the same file structure as a normal backup, so
         all of the instructions in <xref linkend="cedar-recovering"/> apply.
         The only difference is that encrypted files will have an additional
         <filename>.gpg</filename> extension (so
         for instance <filename>file.tar.gz</filename> becomes
         <filename>file.tar.gz.gpg</filename>).  To recover decrypted data, simply
         log on as a user which has access to the secret key and decrypt the
         <filename>.gpg</filename> file that you are interested in.  Then, recover
         the data as usual.
      </para>

      <para>
         Note: I am being intentionally vague about how to configure and use GPG,
         because I do not want to encourage neophytes to blindly use this
         extension.  If you do not already understand GPG well enough to follow
         the two paragraphs above, <emphasis>do not use this
         extension</emphasis>.  Instead, before encrypting your backups, check
         out the excellent GNU Privacy Handbook at 
         <ulink url="http://www.gnupg.org/gph/en/manual.html"/> 
         and gain an understanding of how encryption can help you or hurt you.
      </para>

      <para>
         To enable this extension, add the following section to the Cedar Backup
         configuration file:
      </para>
      
      <programlisting>
&lt;extensions&gt;
   &lt;action&gt;
      &lt;name&gt;encrypt&lt;/name&gt;
      &lt;module&gt;CedarBackup3.extend.encrypt&lt;/module&gt;
      &lt;function&gt;executeAction&lt;/function&gt;
      &lt;index&gt;301&lt;/index&gt;
   &lt;/action&gt;
&lt;/extensions&gt;
      </programlisting>
      
      <para>
         This extension relies on the options and staging configuration
         sections in the standard Cedar Backup configuration file, and then
         also requires its own <literal>encrypt</literal> configuration
         section.  This is an example Encrypt configuration section:
      </para> 

      <programlisting>
&lt;encrypt&gt;
   &lt;encrypt_mode&gt;gpg&lt;/encrypt_mode&gt;
   &lt;encrypt_target&gt;Backup User&lt;/encrypt_target&gt;
&lt;/encrypt&gt;
      </programlisting>

      <para>
         The following elements are part of the Encrypt configuration section:
      </para>

      <variablelist>

         <varlistentry>
            <term><literal>encrypt_mode</literal></term>
            <listitem>
               <para>Encryption mode.</para>
               <para>
                  This value specifies which encryption mechanism will be used
                  by the extension.
               </para>
               <para>
                  Currently, only the GPG public-key encryption mechanism is
                  supported.
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> Must be <literal>gpg</literal>.
               </para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term><literal>encrypt_target</literal></term>
            <listitem>
               <para>Encryption target.</para>
               <para>
                  The value in this field is dependent on the encryption mode.
                  For the <literal>gpg</literal> mode, this is the name of the
                  recipient whose public key will be used to encrypt the backup
                  data, i.e. the value accepted by <command>gpg -r</command>.
               </para>
            </listitem>
         </varlistentry>

      </variablelist>

   </sect1>

   <!-- ################################################################# -->

   <sect1 id="cedar-extensions-split">

      <title>Split Extension</title>

      <para>
         The Split Extension is a Cedar Backup extension used to split up
         large files within staging directories.  It is probably only useful
         in combination with the <command>cback3-span</command> command, which
         requires individual files within staging directories to each be
         smaller than a single disc.
      </para>

      <para>
         You would normally run this action immediately after the standard
         stage action, but you could also choose to run it by hand immediately
         before running <command>cback3-span</command>.
      </para>

      <para>
         The split extension uses the standard UNIX <command>split</command>
         tool to split the large files up.  This tool simply splits the files
         on bite-size boundaries.  It has no knowledge of file formats.  
      </para>
         
      <para>
         <emphasis>Note: this means that in order to recover the data in your
         original large file, you must have every file that the original file
         was split into.</emphasis>  Think carefully about whether this is what
         you want.  It doesn't sound like a huge limitation.  However,
         <command>cback3-span</command> might put an indivdual file on
         <emphasis>any</emphasis> disc in a set &mdash; the files split from
         one larger file will not necessarily be together.  That means you will
         probably need every disc in your backup set in order to recover any
         data from the backup set.
      </para>

      <para>
         To enable this extension, add the following section to the Cedar Backup
         configuration file:
      </para>
      
      <programlisting>
&lt;extensions&gt; 
   &lt;action&gt;
      &lt;name&gt;split&lt;/name&gt;
      &lt;module&gt;CedarBackup3.extend.split&lt;/module&gt;
      &lt;function&gt;executeAction&lt;/function&gt;
      &lt;index&gt;299&lt;/index&gt;
   &lt;/action&gt;
&lt;/extensions&gt;
      </programlisting>
      
      <para>
         This extension relies on the options and staging configuration
         sections in the standard Cedar Backup configuration file, and then
         also requires its own <literal>split</literal> configuration
         section.  This is an example Split configuration section:
      </para> 

      <programlisting>
&lt;split&gt;
   &lt;size_limit&gt;250 MB&lt;/size_limit&gt;
   &lt;split_size&gt;100 MB&lt;/split_size&gt;
&lt;/split&gt;
      </programlisting>

      <para>
         The following elements are part of the Split configuration section:
      </para>

      <variablelist>

         <varlistentry>
            <term><literal>size_limit</literal></term>
            <listitem>
               <para>Size limit.</para>
               <para>
                  Files with a size strictly larger than this limit will
                  be split by the extension.
               </para>
               <para>
                  You can enter this value in two different forms.  It can
                  either be a simple number, in which case the value is assumed
                  to be in bytes; or it can be a number followed by a unit
                  (KB, MB, GB).  
               </para>
               <para>
                  Valid examples are <quote>10240</quote>, <quote>250
                  MB</quote> or <quote>1.1 GB</quote>.
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> Must be a size as described above.
               </para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term><literal>split_size</literal></term>
            <listitem>
               <para>Split size.</para>
               <para>
                  This is the size of the chunks that a large file will be split into.
                  The final chunk may be smaller if the split size doesn't divide
                  evenly into the file size.
               </para>
               <para>
                  You can enter this value in two different forms.  It can
                  either be a simple number, in which case the value is assumed
                  to be in bytes; or it can be a number followed by a unit
                  (KB, MB, GB).  
               </para>
               <para>
                  Valid examples are <quote>10240</quote>, <quote>250
                  MB</quote> or <quote>1.1 GB</quote>.
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> Must be a size as described above.
               </para>
            </listitem>
         </varlistentry>

      </variablelist>

   </sect1>

   <!-- ################################################################# -->

   <sect1 id="cedar-extensions-capacity">

      <title>Capacity Extension</title>

      <para>
         The capacity extension checks the current capacity of the media in the
         writer and prints a warning if the media exceeds an indicated
         capacity.  The capacity is indicated either by a maximum percentage
         utilized or by a minimum number of bytes that must remain unused.
      </para>

      <para>
         This action can be run at any time, but is probably best run as the
         last action on any given day, so you get as much notice as possible
         that your media is full and needs to be replaced.
      </para>

      <para>
         To enable this extension, add the following section to the Cedar Backup
         configuration file:
      </para>
      
      <programlisting>
&lt;extensions&gt; &lt;action&gt;
      &lt;name&gt;capacity&lt;/name&gt;
      &lt;module&gt;CedarBackup3.extend.capacity&lt;/module&gt;
      &lt;function&gt;executeAction&lt;/function&gt;
      &lt;index&gt;299&lt;/index&gt;
   &lt;/action&gt;
&lt;/extensions&gt;
      </programlisting>
      
      <para>
         This extension relies on the options and store configuration sections
         in the standard Cedar Backup configuration file, and then also
         requires its own <literal>capacity</literal> configuration section.
         This is an example Capacity configuration section that configures the
         extension to warn if the media is more than 95.5% full:
      </para> 

      <programlisting>
&lt;capacity&gt;
   &lt;max_percentage&gt;95.5&lt;/max_percentage&gt;
&lt;/capacity&gt;
      </programlisting>

      <para>
         This example configures the extension to warn if the media has fewer
         than 16 MB free:
      </para>

      <programlisting>
&lt;capacity&gt;
   &lt;min_bytes&gt;16 MB&lt;/min_bytes&gt;
&lt;/capacity&gt;
      </programlisting>

      <para>
         The following elements are part of the Capacity configuration section:
      </para>

      <variablelist>

         <varlistentry>
            <term><literal>max_percentage</literal></term>
            <listitem>
               <para>Maximum percentage of the media that may be utilized.</para>
               <para>
                  You must provide either this value <emphasis>or</emphasis> the
                  <literal>min_bytes</literal> value.
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> Must be a floating point
                  number between 0.0 and 100.0
               </para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term><literal>min_bytes</literal></term>
            <listitem>
               <para>Minimum number of free bytes that must be available.</para>
               <para>
                  You can enter this value in two different forms.  It can
                  either be a simple number, in which case the value is assumed
                  to be in bytes; or it can be a number followed by a unit
                  (KB, MB, GB).  
               </para>
               <para>
                  Valid examples are <quote>10240</quote>, <quote>250
                  MB</quote> or <quote>1.1 GB</quote>.
               </para>
               <para>
                  You must provide either this value <emphasis>or</emphasis> the
                  <literal>max_percentage</literal> value.
               </para>
               <para>
                  <emphasis>Restrictions:</emphasis> Must be a byte quantity as
                  described above.
               </para>
            </listitem>
         </varlistentry>

      </variablelist>

   </sect1>

</chapter>

