<!-- 
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
#
#              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,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, Configuration chapter.
#
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
-->

<chapter id="cedar-config">

   <title>Configuration</title>

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

   <sect1 id="cedar-config-overview">

      <title>Overview</title>

      <para>
         Configuring Cedar Backup is unfortunately
         somewhat complicated.  The good news is that once you get through the
         initial configuration process, you'll hardly ever have to change
         anything. Even better, the most typical changes (i.e. adding
         and removing directories from a backup) are easy.
      </para>

      <para>
         First, familiarize yourself with the concepts in 
         <xref linkend="cedar-basic"/>.  In particular, be sure that you understand
         the differences between a master and a client.  (If you only have one
         machine, then your machine will act as both a master and a client,
         and we'll refer to your setup as a <firstterm>pool of one</firstterm>.)
         Then, install Cedar Backup per the instructions in 
         <xref linkend="cedar-install"/>.
      </para>

      <para>
         Once everything has been installed, you are ready to begin configuring
         Cedar Backup.  Look over <xref linkend="cedar-commandline-cback3"/> (in
         <xref linkend="cedar-commandline"/>) to become familiar with the
         command line interface.  Then, look over <xref
         linkend="cedar-config-configfile"/> (below) and create a configuration
         file for each peer in your backup pool.  To start with, create a very
         simple configuration file, then expand it later.  Decide now whether
         you will store the configuration file in the standard place
         (<filename>/etc/cback3.conf</filename>) or in some other location.
      </para>

      <para>
         After you have all of the configuration files in place, configure each
         of your machines, following the instructions in the appropriate
         section below (for master, client or pool of one).  Since the master
         and client(s) must communicate over the network, you won't be able to
         fully configure the master without configuring each client and
         vice-versa.  The instructions are clear on what needs to be done.
      </para>

      <sidebar>

         <title>Which Platform?</title>

         <para>
            Cedar Backup has been designed for use on all UNIX-like systems.
            However, since it was developed on a Debian GNU/Linux system, and
            because I am a Debian developer, the packaging is prettier and the
            setup is somewhat simpler on a Debian system than on a system where
            you install from source.  
         </para>

         <para>
            The configuration instructions below have been generalized so they
            should work well regardless of what platform you are running (i.e.
            RedHat, Gentoo, FreeBSD, etc.).  If instructions vary for a
            particular platform, you will find a note related to that
            platform.
         </para>

         <para>
            I am always open to adding more platform-specific hints and notes,
            so write me if you find problems with these instructions.
         </para>

      </sidebar>
   </sect1>

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

   <sect1 id="cedar-config-configfile">
         
      <title>Configuration File Format</title>

      <para>
         Cedar Backup is configured through an XML <footnote><para>See 
         <ulink url="http://www.xml.com/pub/a/98/10/guide0.html"/>
         for a basic introduction to XML.</para></footnote> configuration file,
         usually called <filename>/etc/cback3.conf</filename>.  The configuration
         file contains the following sections: <firstterm>reference</firstterm>,
         <firstterm>options</firstterm>, <firstterm>collect</firstterm>,
         <firstterm>stage</firstterm>, <firstterm>store</firstterm>,
         <firstterm>purge</firstterm> and <firstterm>extensions</firstterm>.
      </para>

      <para>
         All configuration files must contain the two general configuration
         sections, the reference section and the options section.  Besides
         that, administrators need only configure actions they intend to use.
         For instance, on a client machine, administrators will generally only
         configure the collect and purge sections, while on a master machine
         they will have to configure all four action-related sections.
         <footnote><para>See <xref linkend="cedar-basic-process"/>, in <xref
         linkend="cedar-basic"/>.</para></footnote> The extensions section is
         always optional and can be omitted unless extensions are in use.
      </para>

      <note>
         <para>
            Even though the Mac OS X (darwin) filesystem is
            <emphasis>not</emphasis> case-sensitive, Cedar Backup configuration
            <emphasis>is</emphasis> generally case-sensitive on that platform,
            just like on all other platforms.  For instance, even though the
            files <quote>Ken</quote> and <quote>ken</quote> might be the same on the
            Mac OS X filesystem, an exclusion in Cedar Backup configuration for
            <quote>ken</quote> will only match the file if it is actually on
            the filesystem with a lower-case <quote>k</quote> as its first
            letter.  This won't surprise the typical UNIX user, but might
            surprise someone who's gotten into the <quote>Mac Mindset</quote>.
         </para>
      </note>

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

      <sect2 id="cedar-config-configfile-sample">

         <title>Sample Configuration File</title>

         <para>
            Both the Python source distribution and the Debian package come with a
            sample configuration file.  The Debian package includes its sample in
            <filename>/usr/share/doc/cedar-backup3/examples/cback3.conf.sample</filename>.
         </para>

         <para>
            This is a sample configuration file similar to the one provided in the
            source package.  Documentation below provides more information about
            each of the individual configuration sections.
         </para>

         <programlisting>
&lt;?xml version="1.0"?&gt;
&lt;cb_config&gt;
   &lt;reference&gt;
      &lt;author&gt;Kenneth J. Pronovici&lt;/author&gt;
      &lt;revision&gt;1.3&lt;/revision&gt;
      &lt;description&gt;Sample&lt;/description&gt;
   &lt;/reference&gt;
   &lt;options&gt;
      &lt;starting_day&gt;tuesday&lt;/starting_day&gt;
      &lt;working_dir&gt;/opt/backup/tmp&lt;/working_dir&gt;
      &lt;backup_user&gt;backup&lt;/backup_user&gt;
      &lt;backup_group&gt;group&lt;/backup_group&gt;
      &lt;rcp_command&gt;/usr/bin/scp -B&lt;/rcp_command&gt;
   &lt;/options&gt;
   &lt;peers&gt;
      &lt;peer&gt;
         &lt;name&gt;debian&lt;/name&gt;
         &lt;type&gt;local&lt;/type&gt;
         &lt;collect_dir&gt;/opt/backup/collect&lt;/collect_dir&gt;
      &lt;/peer&gt;
   &lt;/peers&gt;
   &lt;collect&gt;
      &lt;collect_dir&gt;/opt/backup/collect&lt;/collect_dir&gt;
      &lt;collect_mode&gt;daily&lt;/collect_mode&gt;
      &lt;archive_mode&gt;targz&lt;/archive_mode&gt;
      &lt;ignore_file&gt;.cbignore&lt;/ignore_file&gt;
      &lt;dir&gt;
         &lt;abs_path&gt;/etc&lt;/abs_path&gt;
         &lt;collect_mode&gt;incr&lt;/collect_mode&gt;
      &lt;/dir&gt;
      &lt;file&gt;
         &lt;abs_path&gt;/home/root/.profile&lt;/abs_path&gt;
         &lt;collect_mode&gt;weekly&lt;/collect_mode&gt;
      &lt;/file&gt;
   &lt;/collect&gt;
   &lt;stage&gt;
      &lt;staging_dir&gt;/opt/backup/staging&lt;/staging_dir&gt;
   &lt;/stage&gt;
   &lt;store&gt;
      &lt;source_dir&gt;/opt/backup/staging&lt;/source_dir&gt;
      &lt;media_type&gt;cdrw-74&lt;/media_type&gt;
      &lt;device_type&gt;cdwriter&lt;/device_type&gt;
      &lt;target_device&gt;/dev/cdrw&lt;/target_device&gt;
      &lt;target_scsi_id&gt;0,0,0&lt;/target_scsi_id&gt;
      &lt;drive_speed&gt;4&lt;/drive_speed&gt;
      &lt;check_data&gt;Y&lt;/check_data&gt;
      &lt;check_media&gt;Y&lt;/check_media&gt;
      &lt;warn_midnite&gt;Y&lt;/warn_midnite&gt;
   &lt;/store&gt;
   &lt;purge&gt;
      &lt;dir&gt;
         &lt;abs_path&gt;/opt/backup/stage&lt;/abs_path&gt;
         &lt;retain_days&gt;7&lt;/retain_days&gt;
      &lt;/dir&gt;
      &lt;dir&gt;
         &lt;abs_path&gt;/opt/backup/collect&lt;/abs_path&gt;
         &lt;retain_days&gt;0&lt;/retain_days&gt;
      &lt;/dir&gt;
   &lt;/purge&gt;
&lt;/cb_config&gt;
         </programlisting>

      </sect2>

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

      <sect2 id="cedar-config-configfile-reference">

         <title>Reference Configuration</title>

         <para>
            The reference configuration section contains free-text elements
            that exist only for reference..  The section itself is required,
            but the individual elements may be left blank if desired.
         </para>

         <para>
            This is an example reference configuration section:
         </para>

         <programlisting>
&lt;reference&gt;
   &lt;author&gt;Kenneth J. Pronovici&lt;/author&gt;
   &lt;revision&gt;Revision 1.3&lt;/revision&gt;
   &lt;description&gt;Sample&lt;/description&gt;
   &lt;generator&gt;Yet to be Written Config Tool (tm)&lt;/description&gt;
&lt;/reference&gt;
         </programlisting>

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

         <variablelist>

            <varlistentry>
               <term><literal>author</literal></term>
               <listitem>
                  <para>Author of the configuration file.</para>
                  <para>
                     <emphasis>Restrictions:</emphasis> None
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>revision</literal></term>
               <listitem>
                  <para>Revision of the configuration file.</para>
                  <para>
                     <emphasis>Restrictions:</emphasis> None
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>description</literal></term>
               <listitem>
                  <para>Description of the configuration file.</para>
                  <para>
                     <emphasis>Restrictions:</emphasis> None
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>generator</literal></term>
               <listitem>
                  <para>Tool that generated the configuration file, if any.</para>
                  <para>
                     <emphasis>Restrictions:</emphasis> None
                  </para>
               </listitem>
            </varlistentry>

         </variablelist>

      </sect2>

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

      <sect2 id="cedar-config-configfile-options">

         <title>Options Configuration</title>

         <para>
            The options configuration section contains configuration options
            that are not specific to any one action.  
         </para>

         <para>
            This is an example options configuration section:
         </para>

         <programlisting>
&lt;options&gt;
   &lt;starting_day&gt;tuesday&lt;/starting_day&gt;
   &lt;working_dir&gt;/opt/backup/tmp&lt;/working_dir&gt;
   &lt;backup_user&gt;backup&lt;/backup_user&gt;
   &lt;backup_group&gt;backup&lt;/backup_group&gt;
   &lt;rcp_command&gt;/usr/bin/scp -B&lt;/rcp_command&gt;
   &lt;rsh_command&gt;/usr/bin/ssh&lt;/rsh_command&gt;
   &lt;cback_command&gt;/usr/bin/cback&lt;/cback_command&gt;
   &lt;managed_actions&gt;collect, purge&lt;/managed_actions&gt;
   &lt;override&gt;
      &lt;command&gt;cdrecord&lt;/command&gt;
      &lt;abs_path&gt;/opt/local/bin/cdrecord&lt;/abs_path&gt;
   &lt;/override&gt;
   &lt;override&gt;
      &lt;command&gt;mkisofs&lt;/command&gt;
      &lt;abs_path&gt;/opt/local/bin/mkisofs&lt;/abs_path&gt;
   &lt;/override&gt;
   &lt;pre_action_hook&gt;
      &lt;action&gt;collect&lt;/action&gt;
      &lt;command&gt;echo "I AM A PRE-ACTION HOOK RELATED TO COLLECT"&lt;/command&gt;
   &lt;/pre_action_hook&gt;
   &lt;post_action_hook&gt;
      &lt;action&gt;collect&lt;/action&gt;
      &lt;command&gt;echo "I AM A POST-ACTION HOOK RELATED TO COLLECT"&lt;/command&gt;
   &lt;/post_action_hook&gt;
&lt;/options&gt;
         </programlisting>

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

         <variablelist>

            <varlistentry>
               <term><literal>starting_day</literal></term>
               <listitem>
                  <para>Day that starts the week.</para>
                  <para>
                     Cedar Backup is built around the idea of weekly backups.
                     The starting day of week is the day that media will be
                     rebuilt from scratch and that incremental backup
                     information will be cleared.
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> Must be a day of the
                     week in English, i.e. <literal>monday</literal>,
                     <literal>tuesday</literal>, etc.  The validation is
                     case-sensitive.
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>working_dir</literal></term>
               <listitem>
                  <para>Working (temporary) directory to use for backups.</para>
                  <para>
                     This directory is used for writing temporary files, such
                     as tar file or ISO filesystem images as they are being built.  It
                     is also used to store day-to-day information about
                     incremental backups.
                  </para>
                  <para>
                     The working directory should contain enough free space to
                     hold temporary tar files (on a client) or to build an ISO
                     filesystem image (on a master).
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> Must be an absolute path
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>backup_user</literal></term>
               <listitem>
                  <para>Effective user that backups should run as.</para>
                  <para>
                     This user must exist on the machine which is being
                     configured and should not be root (although that
                     restriction is not enforced).
                  </para>
                  <para>
                     This value is also used as the default remote backup user
                     for remote peers.
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> Must be non-empty
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>backup_group</literal></term>
               <listitem>
                  <para>Effective group that backups should run as.</para>
                  <para>
                     This group must exist on the machine which is being
                     configured, and should not be root or some other
                     <quote>powerful</quote> group (although that restriction
                     is not enforced).
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> Must be non-empty
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>rcp_command</literal></term>
               <listitem>
                  <para>Default rcp-compatible copy command for staging.</para>
                  <para>
                     The rcp command should be the exact command used for
                     remote copies, including any required options.  If you are
                     using <command>scp</command>, you should pass it the
                     <option>-B</option> option, so <command>scp</command> will
                     not ask for any user input (which could hang the backup).
                     A common example is something like <command>/usr/bin/scp
                     -B</command>.
                  </para>
                  <para>
                     This value is used as the default value for all remote
                     peers.  Technically, this value is not needed by clients,
                     but we require it for all config files anyway.
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> Must be non-empty
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>rsh_command</literal></term>
               <listitem>
                  <para>Default rsh-compatible command to use for remote shells.</para>
                  <para>
                     The rsh command should be the exact command used for
                     remote shells, including any required options.  
                  </para>
                  <para>
                     This value is used as the default value for all managed
                     clients.  It is optional, because it is only used when
                     executing actions on managed clients.  However, each
                     managed client must either be able to read the value from
                     options configuration or must set the value explicitly.
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> Must be non-empty
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>cback_command</literal></term>
               <listitem>
                  <para>Default cback-compatible command to use on managed remote clients.</para>
                  <para>
                     The cback command should be the exact command used for for
                     executing <command>cback</command> on a remote managed
                     client, including any required command-line options.  Do
                     <emphasis>not</emphasis> list any actions in the command
                     line, and do <emphasis>not</emphasis> include the
                     <command>--full</command> command-line option.
                  </para>
                  <para>
                     This value is used as the default value for all managed
                     clients.  It is optional, because it is only used when
                     executing actions on managed clients.  However, each
                     managed client must either be able to read the value from
                     options configuration or must set the value explicitly.
                  </para>
                  <para>
                     Note: if this command-line is complicated, it is often
                     better to create a simple shell script on the remote host
                     to encapsulate all of the options.  Then, just reference
                     the shell script in configuration.
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> Must be non-empty
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>managed_actions</literal></term>
               <listitem>
                  <para>Default set of actions that are managed on remote clients.</para>
                  <para>
                     This is a comma-separated list of actions that the master
                     will manage on behalf of remote clients.  Typically, it
                     would include only collect-like actions and purge.  
                  </para>
                  <para>
                     This value is used as the default value for all managed
                     clients.  It is optional, because it is only used when
                     executing actions on managed clients.  However, each
                     managed client must either be able to read the value from
                     options configuration or must set the value explicitly.
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> Must be non-empty.  
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>override</literal></term>
               <listitem>
                  <para>Command to override with a customized path.</para>
                  <para>
                     This is a subsection which contains a command to override
                     with a customized path.  This functionality would be used
                     if root's <literal>$PATH</literal> does not include a
                     particular required command, or if there is a need to use
                     a version of a command that is different than the one
                     listed on the <literal>$PATH</literal>.  Most users will
                     only use this section when directed to, in order to fix a
                     problem.
                  </para>
                  <para>
                     This section is optional, and can be repeated as many times
                     as necessary.
                  </para>
                  <para>
                     This subsection must contain the following two fields:
                  </para>

                  <variablelist>

                     <varlistentry>
                        <term><literal>command</literal></term>
                        <listitem>
                           <para>
                              Name of the command to be overridden, i.e.
                              <quote>cdrecord</quote>. 
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be a
                              non-empty string.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>abs_path</literal></term>
                        <listitem>
                           <para>
                              The absolute path where the overridden command 
                              can be found.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be an
                              absolute path.
                           </para>
                        </listitem>
                     </varlistentry>

                  </variablelist>

               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>pre_action_hook</literal></term>
               <listitem>
                  <para>Hook configuring a command to be executed before an action.</para>
                  <para>
                     This is a subsection which configures a command to be
                     executed immediately before a named action.  It provides a
                     way for administrators to associate their own custom
                     functionality with standard Cedar Backup actions or with
                     arbitrary extensions.
                  </para>
                  <para>
                     This section is optional, and can be repeated as many times
                     as necessary.
                  </para>
                  <para>
                     This subsection must contain the following two fields:
                  </para>

                  <variablelist>

                     <varlistentry>
                        <term><literal>action</literal></term>
                        <listitem>
                           <para>
                              Name of the Cedar Backup action that the hook is
                              associated with.   The action can be a standard
                              backup action (collect, stage, etc.) or can be an
                              extension action.  No validation is done to
                              ensure that the configured action actually
                              exists.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be a
                              non-empty string.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>command</literal></term>
                        <listitem>
                           <para>
                              Name of the command to be executed.  This item
                              can either specify the path to a shell script of
                              some sort (the recommended approach) or can include
                              a complete shell command.  
                           </para>
                           <para>
                              Note: if you choose to provide a complete shell
                              command rather than the path to a script, you
                              need to be aware of some limitations of Cedar
                              Backup's command-line parser.  You cannot use a
                              subshell (via the <literal>`command`</literal> or
                              <literal>$(command)</literal> syntaxes) or any
                              shell variable in your command line.
                              Additionally, the command-line parser only
                              recognizes the double-quote character
                              (<literal>"</literal>) to delimit groupings or
                              strings on the command-line.  The bottom line is,
                              you are probably best off writing a shell script
                              of some sort for anything more sophisticated than
                              very simple shell commands.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be a
                              non-empty string.
                           </para>
                        </listitem>
                     </varlistentry>

                  </variablelist>

               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>post_action_hook</literal></term>
               <listitem>
                  <para>Hook configuring a command to be executed after an action.</para>
                  <para>
                     This is a subsection which configures a command to be
                     executed immediately after a named action.  It provides a
                     way for administrators to associate their own custom
                     functionality with standard Cedar Backup actions or with
                     arbitrary extensions.
                  </para>
                  <para>
                     This section is optional, and can be repeated as many times
                     as necessary.
                  </para>
                  <para>
                     This subsection must contain the following two fields:
                  </para>

                  <variablelist>

                     <varlistentry>
                        <term><literal>action</literal></term>
                        <listitem>
                           <para>
                              Name of the Cedar Backup action that the hook is
                              associated with.   The action can be a standard
                              backup action (collect, stage, etc.) or can be an
                              extension action.  No validation is done to
                              ensure that the configured action actually
                              exists.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be a
                              non-empty string.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>command</literal></term>
                        <listitem>
                           <para>
                              Name of the command to be executed.  This item
                              can either specify the path to a shell script of
                              some sort (the recommended approach) or can include
                              a complete shell command.  
                           </para>
                           <para>
                              Note: if you choose to provide a complete shell
                              command rather than the path to a script, you
                              need to be aware of some limitations of Cedar
                              Backup's command-line parser.  You cannot use a
                              subshell (via the <literal>`command`</literal> or
                              <literal>$(command)</literal> syntaxes) or any
                              shell variable in your command line.
                              Additionally, the command-line parser only
                              recognizes the double-quote character
                              (<literal>"</literal>) to delimit groupings or
                              strings on the command-line.  The bottom line is,
                              you are probably best off writing a shell script
                              of some sort for anything more sophisticated than
                              very simple shell commands.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be a
                              non-empty string.
                           </para>
                        </listitem>
                     </varlistentry>

                  </variablelist>

               </listitem>
            </varlistentry>

         </variablelist>
         
      </sect2>

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

      <sect2 id="cedar-config-configfile-peers">

         <title>Peers Configuration</title>

         <para>
            The peers configuration section contains a list of the peers
            managed by a master.  This section is only required on a master.
         </para>
            
         <para>
            This is an example peers configuration section:
         </para>

         <programlisting>
&lt;peers&gt;
   &lt;peer&gt;
      &lt;name&gt;machine1&lt;/name&gt;
      &lt;type&gt;local&lt;/type&gt;
      &lt;collect_dir&gt;/opt/backup/collect&lt;/collect_dir&gt;
   &lt;/peer&gt;
   &lt;peer&gt;
      &lt;name&gt;machine2&lt;/name&gt;
      &lt;type&gt;remote&lt;/type&gt;
      &lt;backup_user&gt;backup&lt;/backup_user&gt;
      &lt;collect_dir&gt;/opt/backup/collect&lt;/collect_dir&gt;
      &lt;ignore_failures&gt;all&lt;/ignore_failures&gt;
   &lt;/peer&gt;
   &lt;peer&gt;
      &lt;name&gt;machine3&lt;/name&gt;
      &lt;type&gt;remote&lt;/type&gt;
      &lt;managed&gt;Y&lt;/managed&gt;
      &lt;backup_user&gt;backup&lt;/backup_user&gt;
      &lt;collect_dir&gt;/opt/backup/collect&lt;/collect_dir&gt;
      &lt;rcp_command&gt;/usr/bin/scp&lt;/rcp_command&gt;
      &lt;rsh_command&gt;/usr/bin/ssh&lt;/rsh_command&gt;
      &lt;cback_command&gt;/usr/bin/cback&lt;/cback_command&gt;
      &lt;managed_actions&gt;collect, purge&lt;/managed_actions&gt;
   &lt;/peer&gt;
&lt;/peers&gt;
         </programlisting>

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

         <variablelist>

            <varlistentry>
               <term><literal>peer</literal> (local version)</term>
               <listitem>
                  <para>Local client peer in a backup pool.</para>
                  <para>
                     This is a subsection which contains information about a
                     specific local client peer managed by a master.
                  </para>
                  <para>
                     This section can be repeated as many times as is
                     necessary.  At least one remote or local peer must be
                     configured.
                  </para>
                  <para>
                     The local peer subsection must contain the following fields:
                  </para>

                  <variablelist>

                     <varlistentry>
                        <term><literal>name</literal></term>
                        <listitem>
                           <para>Name of the peer, typically a valid hostname.</para>
                           <para>
                              For local peers, this value is only used for
                              reference.  However, it is good practice to list
                              the peer's hostname here, for consistency with
                              remote peers.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be non-empty,
                              and unique among all peers.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>type</literal></term>
                        <listitem>
                           <para>Type of this peer.</para>
                           <para>
                              This value identifies the type of the peer.  For
                              a local peer, it must always be <literal>local</literal>.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be <literal>local</literal>.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>collect_dir</literal></term>
                        <listitem>
                           <para>Collect directory to stage from for this peer.</para>
                           <para>
                              The master will copy all files in this directory
                              into the appropriate staging directory.  Since
                              this is a local peer, the directory is assumed to
                              be reachable via normal filesystem operations
                              (i.e. <command>cp</command>). 
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be an absolute path.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>ignore_failures</literal></term>
                        <listitem>
                           <para>Ignore failure mode for this peer</para>
                           <para>
                              The ignore failure mode indicates whether
                              <quote>not ready to be staged</quote> errors
                              should be ignored for this peer.  This option is
                              intended to be used for peers that are up only
                              intermittently, to cut down on the number of
                              error emails received by the Cedar Backup
                              administrator.
                           </para>
                           <para>
                              The "none" mode means that all errors will be
                              reported.  This is the default behavior.  The
                              "all" mode means to ignore all failures.  The
                              "weekly" mode means to ignore failures for a
                              start-of-week or full backup.  The "daily" mode
                              means to ignore failures for any backup that is
                              not either a full backup or a start-of-week
                              backup.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> If set, must
                              be one of "none", "all", "daily", or "weekly".
                           </para>
                        </listitem>
                     </varlistentry>

                  </variablelist>

               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>peer</literal> (remote version)</term>
               <listitem>
                  <para>Remote client peer in a backup pool.</para>
                  <para>
                     This is a subsection which contains information about a
                     specific remote client peer managed by a master.  A remote
                     peer is one which can be reached via an rsh-based network
                     call.
                  </para>
                  <para>
                     This section can be repeated as many times as is
                     necessary.  At least one remote or local peer must be
                     configured.
                  </para>
                  <para>
                     The remote peer subsection must contain the following fields:
                  </para>

                  <variablelist>

                     <varlistentry>
                        <term><literal>name</literal></term>
                        <listitem>
                           <para>Hostname of the peer.</para>
                           <para>
                              For remote peers, this must be a valid DNS
                              hostname or IP address which can be resolved
                              during an rsh-based network call.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be non-empty,
                              and unique among all peers.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>type</literal></term>
                        <listitem>
                           <para>Type of this peer.</para>
                           <para>
                              This value identifies the type of the peer.  For
                              a remote peer, it must always be <literal>remote</literal>.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be <literal>remote</literal>.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>managed</literal></term>
                        <listitem>
                           <para>Indicates whether this peer is managed.</para>
                           <para>
                              A managed peer (or managed client) is a peer for
                              which the master manages all of the backup
                              activites via a remote shell.
                           </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>collect_dir</literal></term>
                        <listitem>
                           <para>Collect directory to stage from for this peer.</para>
                           <para>
                              The master will copy all files in this directory
                              into the appropriate staging directory.  Since
                              this is a remote peer, the directory is assumed to
                              be reachable via rsh-based network operations
                              (i.e. <command>scp</command> or the configured
                              rcp command). 
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be an absolute path.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>ignore_failures</literal></term>
                        <listitem>
                           <para>Ignore failure mode for this peer</para>
                           <para>
                              The ignore failure mode indicates whether
                              <quote>not ready to be staged</quote> errors
                              should be ignored for this peer.  This option is
                              intended to be used for peers that are up only
                              intermittently, to cut down on the number of
                              error emails received by the Cedar Backup
                              administrator.
                           </para>
                           <para>
                              The "none" mode means that all errors will be
                              reported.  This is the default behavior.  The
                              "all" mode means to ignore all failures.  The
                              "weekly" mode means to ignore failures for a
                              start-of-week or full backup.  The "daily" mode
                              means to ignore failures for any backup that is
                              not either a full backup or a start-of-week
                              backup.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> If set, must
                              be one of "none", "all", "daily", or "weekly".
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>backup_user</literal></term>
                        <listitem>
                           <para>Name of backup user on the remote peer.</para>
                           <para>
                              This username will be used when copying files from
                              the remote peer via an rsh-based network connection.
                           </para>
                           <para>
                              This field is optional.  if it doesn't exist, the
                              backup will use the default backup user from the 
                              options section.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be non-empty.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>rcp_command</literal></term>
                        <listitem>
                           <para>The rcp-compatible copy command for this peer.</para>
                           <para>
                              The rcp command should be the exact command used for
                              remote copies, including any required options.  If you are
                              using <command>scp</command>, you should pass it the
                              <option>-B</option> option, so <command>scp</command> will
                              not ask for any user input (which could hang the backup).
                              A common example is something like <command>/usr/bin/scp
                              -B</command>.
                           </para>
                           <para>
                              This field is optional.  if it doesn't exist, the
                              backup will use the default rcp command from the
                              options section.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be non-empty.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>rsh_command</literal></term>
                        <listitem>
                           <para>The rsh-compatible command for this peer.</para>
                           <para>
                              The rsh command should be the exact command used for
                              remote shells, including any required options.  
                           </para>
                           <para>
                              This value only applies if the peer is managed.
                           </para>
                           <para>
                              This field is optional.  if it doesn't exist, the
                              backup will use the default rsh command from the
                              options section.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be non-empty
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>cback_command</literal></term>
                        <listitem>
                           <para>The cback-compatible command for this peer.</para>
                           <para>
                              The cback command should be the exact command
                              used for for executing cback on the peer as part
                              of a managed backup.  This value must include any
                              required command-line options.  Do
                              <emphasis>not</emphasis> list any actions in the
                              command line, and do <emphasis>not</emphasis>
                              include the <command>--full</command>
                              command-line option.
                           </para>
                           <para>
                              This value only applies if the peer is managed.
                           </para>
                           <para>
                              This field is optional.  if it doesn't exist, the
                              backup will use the default cback command from the
                              options section.
                           </para>
                           <para>
                              Note: if this command-line is complicated, it is often
                              better to create a simple shell script on the remote host
                              to encapsulate all of the options.  Then, just reference
                              the shell script in configuration.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be non-empty
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>managed_actions</literal></term>
                        <listitem>
                           <para>Set of actions that are managed for this peer.</para>
                           <para>
                              This is a comma-separated list of actions that
                              the master will manage on behalf this peer.
                              Typically, it would include only collect-like
                              actions and purge.  
                           </para>
                           <para>
                              This value only applies if the peer is managed.
                           </para>
                           <para>
                              This field is optional.  if it doesn't exist, the
                              backup will use the default list of managed
                              actions from the options section.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be non-empty.  
                           </para>
                        </listitem>
                     </varlistentry>

                  </variablelist>

               </listitem>
            </varlistentry>

         </variablelist>

      </sect2>

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

      <sect2 id="cedar-config-configfile-collect">

         <title>Collect Configuration</title>

         <para>
            The collect configuration section contains configuration options
            related the the collect action.  This section contains a variable
            number of elements, including an optional exclusion section and a
            repeating subsection used to specify which directories and/or files
            to collect.  You can also configure an ignore indicator file, which
            lets users mark their own directories as not backed up.
         </para>

         <sidebar>

            <title>Using a Link Farm</title>

            <para>
               Sometimes, it's not very convenient to list directories one by
               one in the Cedar Backup configuration file.  For instance, when
               backing up your home directory, you often exclude as many
               directories as you include.  The ignore file mechanism can be of
               some help, but it still isn't very convenient if there are a lot
               of directories to ignore (or if new directories pop up all of the
               time).
            </para>

            <para>
               In this situation, one option is to use a <firstterm>link
               farm</firstterm> rather than listing all of the directories in
               configuration.  A link farm is a directory that contains nothing
               but a set of soft links to other files and directories.
               Normally, Cedar Backup does not follow soft links, but you can
               override this behavior for individual directories using the
               <literal>link_depth</literal> and <literal>dereference</literal> 
               options (see below).  
            </para>

            <para>
               When using a link farm, you still have to deal with each
               backed-up directory individually, but you don't have to modify
               configuration.  Some users find that this works better for them.
            </para>
               
         </sidebar>

         <para>
            In order to actually execute the collect action, you must have
            configured at least one collect directory or one collect file.
            However, if you are only including collect configuration for use by
            an extension, then it's OK to leave out these sections.  The
            validation will take place only when the collect action is
            executed.
         </para>

         <para>
            This is an example collect configuration section:
         </para>

         <programlisting>
&lt;collect&gt;
   &lt;collect_dir&gt;/opt/backup/collect&lt;/collect_dir&gt;
   &lt;collect_mode&gt;daily&lt;/collect_mode&gt;
   &lt;archive_mode&gt;targz&lt;/archive_mode&gt;
   &lt;ignore_file&gt;.cbignore&lt;/ignore_file&gt;
   &lt;exclude&gt;
      &lt;abs_path&gt;/etc&lt;/abs_path&gt;
      &lt;pattern&gt;.*\.conf&lt;/pattern&gt;
   &lt;/exclude&gt;
   &lt;file&gt;
      &lt;abs_path&gt;/home/root/.profile&lt;/abs_path&gt;
   &lt;/file&gt;
   &lt;dir&gt;
      &lt;abs_path&gt;/etc&lt;/abs_path&gt;
   &lt;/dir&gt;
   &lt;dir&gt;
      &lt;abs_path&gt;/var/log&lt;/abs_path&gt;
      &lt;collect_mode&gt;incr&lt;/collect_mode&gt;
   &lt;/dir&gt;
   &lt;dir&gt;
      &lt;abs_path&gt;/opt&lt;/abs_path&gt;
      &lt;collect_mode&gt;weekly&lt;/collect_mode&gt;
      &lt;exclude&gt;
         &lt;abs_path&gt;/opt/large&lt;/abs_path&gt;
         &lt;rel_path&gt;backup&lt;/rel_path&gt;
         &lt;pattern&gt;.*tmp&lt;/pattern&gt;
      &lt;/exclude&gt;
   &lt;/dir&gt;
&lt;/collect&gt;
         </programlisting>

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

         <variablelist>

            <varlistentry>
               <term><literal>collect_dir</literal></term>
               <listitem>
                  <para>Directory to collect files into.</para>
                  <para>
                     On a client, this is the directory which tarfiles for
                     individual collect directories are written into.  The
                     master then stages files from this directory into its own
                     staging directory.
                  </para>
                  <para>
                     This field is always required.  It must contain enough
                     free space to collect all of the backed-up files on the
                     machine in a compressed form.
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> Must be an absolute path
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>collect_mode</literal></term>
               <listitem>
                  <para>Default collect mode.</para>
                  <para>
                     The collect mode describes how frequently a directory is
                     backed up.   See <xref
                     linkend="cedar-basic-process-collect"/> (in <xref
                     linkend="cedar-basic"/>) for more information.
                  </para>
                  <para>
                     This value is the collect mode that will be used by
                     default during the collect process.  Individual collect
                     directories (below) may override this value.  If
                     <emphasis>all</emphasis> individual 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>archive_mode</literal></term>
               <listitem>
                  <para>Default archive mode for collect files.</para>
                  <para>
                     The archive mode maps to the way that a backup file is
                     stored.  A value <literal>tar</literal> means just a
                     tarfile (<filename>file.tar</filename>); a value
                     <literal>targz</literal> means a gzipped tarfile
                     (<filename>file.tar.gz</filename>); and a value
                     <literal>tarbz2</literal> means a bzipped tarfile
                     (<filename>file.tar.bz2</filename>)
                  </para>
                  <para>
                     This value is the archive mode that will be used by
                     default during the collect process.  Individual collect
                     directories (below) may override this value.  If
                     <emphasis>all</emphasis> individual directories provide
                     their own value, then this default value may be omitted
                     from configuration.
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> Must be one of
                     <literal>tar</literal>, <literal>targz</literal> or
                     <literal>tarbz2</literal>.
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>ignore_file</literal></term>
               <listitem>
                  <para>Default ignore file name.</para>
                  <para>
                     The ignore file is an indicator file.  If it exists in a
                     given directory, then that directory will be recursively
                     excluded from the backup as if it were explicitly excluded
                     in configuration.  
                  </para>
                  <para>
                     The ignore file provides a way for individual users (who
                     might not have access to Cedar Backup configuration) to
                     control which of their own directories get backed up.  For
                     instance, users with a <filename>~/tmp</filename>
                     directory might not want it backed up.  If they create an
                     ignore file in their directory (e.g.
                     <filename>~/tmp/.cbignore</filename>), then Cedar Backup
                     will ignore it.
                  </para>
                  <para>
                     This value is the ignore file name that will be used by
                     default during the collect process.  Individual collect
                     directories (below) may override this value.  If
                     <emphasis>all</emphasis> individual directories provide
                     their own value, then this default value may be omitted
                     from configuration.
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> Must be non-empty
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>recursion_level</literal></term>
               <listitem>
                  <para>Recursion level to use when collecting directories.</para>
                  <para>
                     This is an integer value that Cedar Backup will consider
                     when generating archive files for a configured collect
                     directory.
                  </para>
                  <para>
                     Normally, Cedar Backup generates one archive file per
                     collect directory.  So, if you collect
                     <literal>/etc</literal> you get
                     <literal>etc.tar.gz</literal>.  Most of the time, this is
                     what you want.  However, you may sometimes wish to
                     generate multiple archive files for a single collect
                     directory.  
                  </para>
                  <para>
                     The most obvious example is for <literal>/home</literal>.
                     By default, Cedar Backup will generate
                     <literal>home.tar.gz</literal>. If instead, you want one
                     archive file per home directory you can set a recursion
                     level of <literal>1</literal>.  Cedar Backup will generate
                     <literal>home-user1.tar.gz</literal>,
                     <literal>home-user2.tar.gz</literal>, etc.
                  </para>
                  <para>
                     Higher recursion levels (<literal>2</literal>,
                     <literal>3</literal>, etc.) are legal, and it doesn't
                     matter if the configured recursion level is deeper than
                     the directory tree that is being collected.  You can use a
                     negative recursion level (like <literal>-1</literal>) to
                     specify an infinite level of recursion.  This will exhaust
                     the tree in the same way as if the recursion level is set
                     too high.
                  </para>
                  <para>
                     This field is optional.  if it doesn't exist, the backup
                     will use the default recursion level of zero.
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> Must be an integer.
                  </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 absolute
                     paths and patterns to be excluded across all configured
                     directories.  For a given directory, the set of absolute
                     paths and patterns to exclude is built from this list and
                     any list that exists on the directory itself.  Directories
                     <emphasis>cannot</emphasis> override or remove entries that
                     are in this list, however.
                  </para>
                  <para>
                     This section is 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>abs_path</literal></term>
                        <listitem>
                           <para>
                              An absolute path to be recursively excluded from
                              the backup.
                           </para>
                           <para>
                              If a directory is excluded, then all of its children
                              are also recursively excluded.  For instance, a value
                              <literal>/var/log/apache</literal> would exclude any
                              files within <filename>/var/log/apache</filename> as
                              well as files within other directories under
                              <filename>/var/log/apache</filename>.
                           </para>
                           <para>
                              This field can be repeated as many times as is
                              necessary.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be an absolute path.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>pattern</literal></term>
                        <listitem>
                           <para>
                              A pattern to be recursively excluded from the
                              backup.
                           </para>
                           <para>
                              The pattern must be a Python regular expression. 
                              <footnote id="cedar-config-foot-regex">
                              <para>See <ulink url="http://docs.python.org/lib/re-syntax.html"/></para></footnote>
                              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>
                              If the pattern causes a directory to be excluded,
                              then all of the children of that directory are
                              also recursively excluded.  For instance, a value
                              <literal>.*apache.*</literal> might match the
                              <filename>/var/log/apache</filename> directory.
                              This would exclude any files within
                              <filename>/var/log/apache</filename> as well as
                              files within other directories under
                              <filename>/var/log/apache</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>
                    
                  </variablelist>

               </listitem>
            </varlistentry>

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

                  <variablelist>

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

                     <varlistentry>
                        <term><literal>collect_mode</literal></term> 
                        <listitem>
                           <para>Collect mode for this file</para>
                           <para>
                              The collect mode describes how frequently a
                              file is backed up.   See <xref
                              linkend="cedar-basic-process-collect"/> (in <xref
                              linkend="cedar-basic"/>) for more information.
                           </para>
                           <para>
                              This field is optional.  If it doesn't exist, the
                              backup will use the default collect mode.  
                           </para>
                           <para>
                              Note: if your backup device does not suppport
                              multisession discs, then you should probably
                              confine yourself to 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>archive_mode</literal></term>
                        <listitem>
                           <para>Archive mode for this file.</para>
                           <para>
                              The archive mode maps to the way that a backup
                              file is stored.  A value <literal>tar</literal>
                              means just a tarfile
                              (<filename>file.tar</filename>); a value
                              <literal>targz</literal> means a gzipped tarfile
                              (<filename>file.tar.gz</filename>); and a value
                              <literal>tarbz2</literal> means a bzipped tarfile
                              (<filename>file.tar.bz2</filename>)
                           </para>
                           <para>
                              This field is optional.  if it doesn't exist, the
                              backup will use the default archive mode.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be one of
                              <literal>tar</literal>, <literal>targz</literal> or
                              <literal>tarbz2</literal>.
                           </para>
                        </listitem>
                     </varlistentry>
                  </variablelist>
               </listitem>
            </varlistentry>

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

                  <variablelist>

                     <varlistentry>
                        <term><literal>abs_path</literal></term>
                        <listitem>
                           <para>
                              Absolute path of the directory to collect.
                           </para>
                           <para>
                              The path may be either a directory, a soft link
                              to a directory, or a hard link to a directory.
                              All three are treated the same at this level.
                           </para>
                           <para>
                              The contents of the directory will be recursively
                              collected.  The backup will contain all of the
                              files in the directory, as well as the contents
                              of all of the subdirectories within the
                              directory, etc.  
                           </para>
                           <para>
                              Soft links <emphasis>within</emphasis> the
                              directory are treated as files, i.e. they are
                              copied verbatim (as a link) and their contents
                              are not backed up.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be an absolute path.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>collect_mode</literal></term> 
                        <listitem>
                           <para>Collect mode for this directory</para>
                           <para>
                              The collect mode describes how frequently a
                              directory is backed up.   See <xref
                              linkend="cedar-basic-process-collect"/> (in <xref
                              linkend="cedar-basic"/>) for more information.
                           </para>
                           <para>
                              This field is optional.  If it doesn't exist, the
                              backup will use the default collect mode.  
                           </para>
                           <para>
                              Note: if your backup device does not suppport
                              multisession discs, then you should probably
                              confine yourself to 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>archive_mode</literal></term>
                        <listitem>
                           <para>Archive mode for this directory.</para>
                           <para>
                              The archive mode maps to the way that a backup
                              file is stored.  A value <literal>tar</literal>
                              means just a tarfile
                              (<filename>file.tar</filename>); a value
                              <literal>targz</literal> means a gzipped tarfile
                              (<filename>file.tar.gz</filename>); and a value
                              <literal>tarbz2</literal> means a bzipped tarfile
                              (<filename>file.tar.bz2</filename>)
                           </para>
                           <para>
                              This field is optional.  if it doesn't exist, the
                              backup will use the default archive mode.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be one of
                              <literal>tar</literal>, <literal>targz</literal> or
                              <literal>tarbz2</literal>.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>ignore_file</literal></term>
                        <listitem>
                           <para>Ignore file name for this directory.</para>
                           <para>
                              The ignore file is an indicator file.  If it
                              exists in a given directory, then that directory
                              will be recursively excluded from the backup as
                              if it were explicitly excluded in configuration.  
                           </para>
                           <para>
                              The ignore file provides a way for individual
                              users (who might not have access to Cedar Backup
                              configuration) to control which of their own
                              directories get backed up.  For instance, users
                              with a <filename>~/tmp</filename> directory might
                              not want it backed up.  If they create an ignore
                              file in their directory (e.g.
                              <filename>~/tmp/.cbignore</filename>), then Cedar
                              Backup will ignore it.
                           </para>
                           <para>
                              This field is optional.  If it doesn't exist, the
                              backup will use the default ignore file name.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be non-empty
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>link_depth</literal></term>
                        <listitem>
                           <para>Link depth value to use for this directory.</para>
                           <para>
                              The link depth is maximum depth of the tree at
                              which soft links should be followed.  So, a depth
                              of 0 does not follow any soft links within the
                              collect directory, a depth of 1 follows only
                              links immediately within the collect directory, a
                              depth of 2 follows the links at the next level
                              down, etc.
                           </para>
                           <para>
                              This field is optional.  If it doesn't exist,
                              the backup will assume a value of zero, meaning
                              that soft links within the collect directory will
                              never be followed.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> If set, must
                              be an integer &ge; 0.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>dereference</literal></term>
                        <listitem>
                           <para>Whether to dereference soft links.</para>
                           <para>
                              If this flag is set, links that are being
                              followed will be dereferenced before being added
                              to the backup.  The link will be added (as a
                              link), and then the directory or file that the
                              link points at will be added as well.  
                           </para>
                           <para>
                              This value only applies to a directory where soft
                              links are being followed (per the
                              <literal>link_depth</literal> configuration
                              option).  It never applies to a configured
                              collect directory itself, only to other
                              directories within the collect directory.
                           </para>
                           <para>
                              This field is optional.  If it doesn't exist,
                              the backup will assume that links should never be
                              dereferenced.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be a
                              boolean (<literal>Y</literal> or
                              <literal>N</literal>).
                           </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
                              collect directory.  This list is combined with
                              the program-wide list to build a complete list
                              for the 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>abs_path</literal></term>
                                 <listitem>
                                    <para>
                                       An absolute path to be recursively
                                       excluded from the backup.
                                    </para>
                                    <para>
                                       If a directory is excluded, then all of
                                       its children are also recursively
                                       excluded.  For instance, a value
                                       <literal>/var/log/apache</literal> would
                                       exclude any files within
                                       <filename>/var/log/apache</filename> as
                                       well as files within other directories
                                       under
                                       <filename>/var/log/apache</filename>.
                                    </para>
                                    <para>
                                       This field can be repeated as many times as is
                                       necessary.
                                    </para>
                                    <para>
                                       <emphasis>Restrictions:</emphasis> Must be an absolute path.
                                    </para>
                                 </listitem>
                              </varlistentry>

                              <varlistentry>
                                 <term><literal>rel_path</literal></term>
                                 <listitem>
                                    <para>
                                       A relative path to be recursively
                                       excluded from the backup.
                                    </para>
                                    <para>
                                       The path is assumed to be relative to
                                       the collect directory itself.  For
                                       instance, if the configured directory is
                                       <filename>/opt/web</filename> a
                                       configured relative path of
                                       <filename>something/else</filename>
                                       would exclude the path
                                       <filename>/opt/web/something/else</filename>.
                                    </para>
                                    <para>
                                       If a directory is excluded, then all of
                                       its children are also recursively
                                       excluded.  For instance, a value
                                       <literal>something/else</literal> would
                                       exclude any files within
                                       <filename>something/else</filename> as
                                       well as files within other directories
                                       under <filename>something/else</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>
                                       If the pattern causes a directory to be
                                       excluded, then all of the children of
                                       that directory are also recursively
                                       excluded.  For instance, a value
                                       <literal>.*apache.*</literal> might
                                       match the <filename>/var/log/apache</filename>
                                       directory.  This would exclude any files
                                       within <filename>/var/log/apache</filename> as
                                       well as files within other directories
                                       under <filename>/var/log/apache</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>
                             
                           </variablelist>

                        </listitem>
                     </varlistentry>

                  </variablelist>

               </listitem>
            </varlistentry>

         </variablelist>

      </sect2>

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

      <sect2 id="cedar-config-configfile-stage">

         <title>Stage Configuration</title>

         <para>
            The stage configuration section contains configuration options
            related the the stage action.  The section indicates where date
            from peers can be staged to.  
         </para>
            
         <para>
            This section can also (optionally) override the list of peers so
            that not all peers are staged.  If you provide
            <emphasis>any</emphasis> peers in this section, then the list of
            peers here completely replaces the list of peers in the peers
            configuration section for the purposes of staging.
         </para>

         <para>
            This is an example stage configuration section for the simple case
            where the list of peers is taken from peers configuration:
         </para>

         <programlisting>
&lt;stage&gt;
   &lt;staging_dir&gt;/opt/backup/stage&lt;/staging_dir&gt;
&lt;/stage&gt;
         </programlisting>

         <para>
            This is an example stage configuration section that overrides the
            default list of peers:
         </para>

         <programlisting>
&lt;stage&gt;
   &lt;staging_dir&gt;/opt/backup/stage&lt;/staging_dir&gt;
   &lt;peer&gt;
      &lt;name&gt;machine1&lt;/name&gt;
      &lt;type&gt;local&lt;/type&gt;
      &lt;collect_dir&gt;/opt/backup/collect&lt;/collect_dir&gt;
   &lt;/peer&gt;
   &lt;peer&gt;
      &lt;name&gt;machine2&lt;/name&gt;
      &lt;type&gt;remote&lt;/type&gt;
      &lt;backup_user&gt;backup&lt;/backup_user&gt;
      &lt;collect_dir&gt;/opt/backup/collect&lt;/collect_dir&gt;
   &lt;/peer&gt;
&lt;/stage&gt;
         </programlisting>

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

         <variablelist>

            <varlistentry>
               <term><literal>staging_dir</literal></term>
               <listitem>
                  <para>Directory to stage files into.</para>
                  <para>
                     This is the directory into which the master stages collected
                     data from each of the clients.  Within the staging directory,
                     data is staged into date-based directories by peer name.  For
                     instance, peer <quote>daystrom</quote> backed up on 19 Feb 2005
                     would be staged into something like <filename>2005/02/19/daystrom</filename>
                     relative to the staging directory itself.
                  </para>
                  <para>
                     This field is always required.  The directory must contain
                     enough free space to stage all of the files collected from
                     all of the various machines in a backup pool.  Many
                     administrators set up purging to keep staging directories
                     around for a week or more, which requires even more space.
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> Must be an absolute path
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>peer</literal> (local version)</term>
               <listitem>
                  <para>Local client peer in a backup pool.</para>
                  <para>
                     This is a subsection which contains information about a
                     specific local client peer to be staged (backed up).  A
                     local peer is one whose collect directory can be reached
                     without requiring any rsh-based network calls.  It is
                     possible that a remote peer might be staged as a local
                     peer if its collect directory is mounted to the master via
                     NFS, AFS or some other method.
                  </para>
                  <para>
                     This section can be repeated as many times as is
                     necessary.  At least one remote or local peer must be
                     configured.
                  </para>
                  <para>
                     <emphasis>Remember</emphasis>, if you provide
                     <emphasis>any</emphasis> local or remote peer in staging
                     configuration, the global peer configuration is completely
                     replaced by the staging peer configuration.
                  </para>
                  <para>
                     The local peer subsection must contain the following fields:
                  </para>

                  <variablelist>

                     <varlistentry>
                        <term><literal>name</literal></term>
                        <listitem>
                           <para>Name of the peer, typically a valid hostname.</para>
                           <para>
                              For local peers, this value is only used for
                              reference.  However, it is good practice to list
                              the peer's hostname here, for consistency with
                              remote peers.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be non-empty,
                              and unique among all peers.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>type</literal></term>
                        <listitem>
                           <para>Type of this peer.</para>
                           <para>
                              This value identifies the type of the peer.  For
                              a local peer, it must always be <literal>local</literal>.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be <literal>local</literal>.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>collect_dir</literal></term>
                        <listitem>
                           <para>Collect directory to stage from for this peer.</para>
                           <para>
                              The master will copy all files in this directory
                              into the appropriate staging directory.  Since
                              this is a local peer, the directory is assumed to
                              be reachable via normal filesystem operations
                              (i.e. <command>cp</command>). 
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be an absolute path.
                           </para>
                        </listitem>
                     </varlistentry>

                  </variablelist>

               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>peer</literal> (remote version)</term>
               <listitem>
                  <para>Remote client peer in a backup pool.</para>
                  <para>
                     This is a subsection which contains information about a
                     specific remote client peer to be staged (backed up).  A
                     remote peer is one whose collect directory can only be
                     reached via an rsh-based network call.
                  </para>
                  <para>
                     This section can be repeated as many times as is
                     necessary.  At least one remote or local peer must be
                     configured.
                  </para>
                  <para>
                     <emphasis>Remember</emphasis>, if you provide
                     <emphasis>any</emphasis> local or remote peer in staging
                     configuration, the global peer configuration is completely
                     replaced by the staging peer configuration.
                  </para>
                  <para>
                     The remote peer subsection must contain the following fields:
                  </para>

                  <variablelist>

                     <varlistentry>
                        <term><literal>name</literal></term>
                        <listitem>
                           <para>Hostname of the peer.</para>
                           <para>
                              For remote peers, this must be a valid DNS
                              hostname or IP address which can be resolved
                              during an rsh-based network call.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be non-empty,
                              and unique among all peers.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>type</literal></term>
                        <listitem>
                           <para>Type of this peer.</para>
                           <para>
                              This value identifies the type of the peer.  For
                              a remote peer, it must always be <literal>remote</literal>.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be <literal>remote</literal>.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>collect_dir</literal></term>
                        <listitem>
                           <para>Collect directory to stage from for this peer.</para>
                           <para>
                              The master will copy all files in this directory
                              into the appropriate staging directory.  Since
                              this is a remote peer, the directory is assumed to
                              be reachable via rsh-based network operations
                              (i.e. <command>scp</command> or the configured
                              rcp command). 
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be an absolute path.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>backup_user</literal></term>
                        <listitem>
                           <para>Name of backup user on the remote peer.</para>
                           <para>
                              This username will be used when copying files from
                              the remote peer via an rsh-based network connection.
                           </para>
                           <para>
                              This field is optional.  if it doesn't exist, the
                              backup will use the default backup user from the 
                              options section.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be non-empty.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>rcp_command</literal></term>
                        <listitem>
                           <para>The rcp-compatible copy command for this peer.</para>
                           <para>
                              The rcp command should be the exact command used for
                              remote copies, including any required options.  If you are
                              using <command>scp</command>, you should pass it the
                              <option>-B</option> option, so <command>scp</command> will
                              not ask for any user input (which could hang the backup).
                              A common example is something like <command>/usr/bin/scp
                              -B</command>.
                           </para>
                           <para>
                              This field is optional.  if it doesn't exist, the
                              backup will use the default rcp command from the
                              options section.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be non-empty.
                           </para>
                        </listitem>
                     </varlistentry>

                  </variablelist>

               </listitem>
            </varlistentry>

         </variablelist>

      </sect2>

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

      <sect2 id="cedar-config-configfile-store">

         <title>Store Configuration</title>

         <para>
            The store configuration section contains configuration options
            related the the store action.  This section contains several
            optional fields.  Most fields control the way media is written
            using the writer device.
         </para> 

         <para>
            This is an example store configuration section:
         </para>

         <programlisting>
&lt;store&gt;
   &lt;source_dir&gt;/opt/backup/stage&lt;/source_dir&gt;
   &lt;media_type&gt;cdrw-74&lt;/media_type&gt;
   &lt;device_type&gt;cdwriter&lt;/device_type&gt;
   &lt;target_device&gt;/dev/cdrw&lt;/target_device&gt;
   &lt;target_scsi_id&gt;0,0,0&lt;/target_scsi_id&gt;
   &lt;drive_speed&gt;4&lt;/drive_speed&gt;
   &lt;check_data&gt;Y&lt;/check_data&gt;
   &lt;check_media&gt;Y&lt;/check_media&gt;
   &lt;warn_midnite&gt;Y&lt;/warn_midnite&gt;
   &lt;no_eject&gt;N&lt;/no_eject&gt;
   &lt;refresh_media_delay&gt;15&lt;/refresh_media_delay&gt;
   &lt;eject_delay&gt;2&lt;/eject_delay&gt;
   &lt;blank_behavior&gt;
      &lt;mode&gt;weekly&lt;/mode&gt;
      &lt;factor&gt;1.3&lt;/factor&gt;
   &lt;/blank_behavior&gt;
&lt;/store&gt;
         </programlisting>

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

         <variablelist>

            <varlistentry>
               <term><literal>source_dir</literal></term>
               <listitem>
                  <para>Directory whose contents should be written to media.</para>
                  <para>
                     This directory <emphasis>must</emphasis> be a Cedar Backup
                     staging directory, as configured in the staging configuration
                     section.  Only certain data from that directory (typically,
                     data from the current day) will be written to disc.
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> Must be an absolute path
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>device_type</literal></term>
               <listitem>
                  <para>Type of the device used to write the media.</para>
                  <para>
                     This field controls which type of writer device will be
                     used by Cedar Backup.  Currently, Cedar Backup supports CD
                     writers (<literal>cdwriter</literal>) and DVD writers
                     (<literal>dvdwriter</literal>).
                  </para>
                  <para>
                     This field is optional.  If it doesn't exist, the
                     <literal>cdwriter</literal> device type is assumed.  
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> If set, must be either <literal>cdwriter</literal>
                     or <literal>dvdwriter</literal>.
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>media_type</literal></term>
               <listitem>
                  <para>Type of the media in the device.</para>
                  <para>
                     Unless you want to throw away a backup disc every week,
                     you are probably best off using rewritable media.
                  </para>
                  <para>
                     You must choose a media type that is appropriate for the
                     device type you chose above.  For more information on
                     media types, see <xref linkend="cedar-basic-mediadevice"/>
                     (in <xref linkend="cedar-basic"/>).
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> Must be one of
                     <literal>cdr-74</literal>, <literal>cdrw-74</literal>, 
                     <literal>cdr-80</literal> or <literal>cdrw-80</literal>
                     if device type is <literal>cdwriter</literal>; or one
                     of <literal>dvd+r</literal> or <literal>dvd+rw</literal>
                     if device type is <literal>dvdwriter</literal>.
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>target_device</literal></term>
               <listitem>
                  <para>Filesystem device name for writer device.</para>
                  <para>
                     This value is required for both CD writers and DVD
                     writers.  
                  </para>
                  <para>
                     This is the UNIX device name for the writer drive, for
                     instance <filename>/dev/scd0</filename> or a symlink
                     like <filename>/dev/cdrw</filename>.   
                  </para>
                  <para>
                     In some cases, this device name is used to directly write
                     to media.  This is true all of the time for DVD writers,
                     and is true for CD writers when a SCSI id (see below) has
                     not been specified.  
                  </para>
                  <para>
                     Besides this, the device name is also needed in order to
                     do several pre-write checks (such as whether the device
                     might already be mounted) as well as the post-write
                     consistency check, if enabled.
                  </para>
                  <para>
                     Note: some users have reported intermittent problems when
                     using a symlink as the target device on Linux, especially
                     with DVD media.  If you experience problems, try using the
                     real device name rather than the symlink.
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> Must be an absolute path.
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>target_scsi_id</literal></term>
               <listitem>
                  <para>SCSI id for the writer device.</para>
                  <para>
                     This value is optional for CD writers and is ignored for
                     DVD writers.
                  </para>
                  <para>
                     If you have configured your CD writer hardware to work
                     through the normal filesystem device path, then you can
                     leave this parameter unset.  Cedar Backup will just use
                     the target device (above) when talking to
                     <command>cdrecord</command>.
                  </para>
                  <para>
                     Otherwise, if you have SCSI CD writer hardware or you have
                     configured your non-SCSI hardware to operate like a SCSI
                     device, then you need to provide Cedar Backup with a SCSI
                     id it can use when talking with
                     <command>cdrecord</command>.
                  </para>
                  <para>
                     For the purposes of Cedar Backup, a valid SCSI identifier
                     must either be in the standard SCSI identifier form
                     <literal>scsibus,target,lun</literal> or in the
                     specialized-method form
                     <literal>&lt;method&gt;:scsibus,target,lun</literal>.
                  </para>
                  <para>
                     An example of a standard SCSI identifier is
                     <literal>1,6,2</literal>. Today, the two most common examples
                     of the specialized-method form are
                     <literal>ATA:scsibus,target,lun</literal> and
                     <literal>ATAPI:scsibus,target,lun</literal>, but you may
                     occassionally see other values (like
                     <literal>OLDATAPI</literal> in some forks of
                     <command>cdrecord</command>).
                  </para>
                  <para>
                     See <xref linkend="cedar-config-writer"/> for more
                     information on writer devices and how they are configured.
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> If set, must be a valid SCSI identifier.
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>drive_speed</literal></term>
               <listitem>
                  <para>Speed of the drive, i.e. <literal>2</literal> for a 2x device.</para>
                  <para>
                     This field is optional.  If it doesn't exist, the
                     underlying device-related functionality will use the
                     default drive speed.  
                  </para>
                  <para>
                     For DVD writers, it is best to leave this value unset, so
                     <command>growisofs</command> can pick an appropriate
                     speed.  For CD writers, since media can be
                     speed-sensitive, it is probably best to set a sensible
                     value based on your specific writer and media.
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> If set, must be an integer &ge; 1.
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>check_data</literal></term>
               <listitem>
                  <para>Whether the media should be validated.</para>
                  <para>
                     This field indicates whether a resulting image on the
                     media should be validated after the write completes, by
                     running a consistency check against it.  If this check is
                     enabled, the contents of the staging directory are
                     directly compared to the media, and an error is reported
                     if there is a mismatch.
                  </para>
                  <para>
                     Practice shows that some drives can encounter an error
                     when writing a multisession disc, but not report any problems.
                     This consistency check allows us to catch the problem.
                     By default, the consistency check is disabled, but most
                     users should choose to enable it unless they have a good
                     reason not to.
                  </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>check_media</literal></term>
               <listitem>
                  <para>Whether the media should be checked before writing to it.</para>
                  <para>
                     By default, Cedar Backup does not check its media before
                     writing to it.  It will write to any media in the backup
                     device.  If you set this flag to Y, Cedar Backup will make
                     sure that the media has been initialized before writing to
                     it.  (Rewritable media is initialized using the initialize
                     action.)
                  </para>
                  <para>
                     If the configured media is not rewritable (like CD-R),
                     then this behavior is modified slightly.  For this kind of
                     media, the check passes either if the media has been
                     initialized <emphasis>or</emphasis> if the media appears
                     unused.
                  </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>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 store operation has to cross a midnite boundary in
                     order to find data to write to disc.  For instance, a
                     warning would be generated if valid store data was only
                     found in the day before or day after the current day.
                  </para>
                  <para>
                     Configuration for some users is such that the store
                     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>no_eject</literal></term>
               <listitem>
                  <para>Indicates that the writer device should not be ejected.</para>
                  <para>
                     Under some circumstances, Cedar Backup ejects (opens and
                     closes) the writer device.  This is done because some
                     writer devices need to re-load the media before noticing a
                     media state change (like a new session).
                  </para>
                  <para>
                     For most writer devices this is safe, because they have a
                     tray that can be opened and closed.  If your writer device
                     does not have a tray <emphasis>and</emphasis> Cedar Backup
                     does not properly detect this, then set this flag.  Cedar
                     Backup will not ever issue an eject command to your
                     writer.
                  </para>
                  <para>
                     Note: this could cause problems with your backup.  For
                     instance, with many writers, the check data step may fail
                     if the media is not reloaded first.  If this happens to
                     you, you may need to get a different writer device.
                  </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>refresh_media_delay</literal></term>
               <listitem>
                  <para>Number of seconds to delay after refreshing media</para>
                  <para>
                     This field is optional.  If it doesn't exist, no delay
                     will occur.
                  </para>
                  <para>
                     Some devices seem to take a little while to stablize after
                     refreshing the media (i.e. closing and opening the tray).
                     During this period, operations on the media may fail.  If
                     your device behaves like this, you can try setting a delay
                     of 10-15 seconds.
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> If set, must be an integer &ge; 1.
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>eject_delay</literal></term>
               <listitem>
                  <para>Number of seconds to delay after ejecting the tray</para>
                  <para>
                     This field is optional.  If it doesn't exist, no delay
                     will occur.
                  </para>
                  <para>
                     If your system seems to have problems opening and closing the tray,
                     one possibility is that the open/close sequence is happening too
                     quickly &mdash; either the tray isn't fully open when Cedar Backup
                     tries to close it, or it doesn't report being open.  To work around
                     that problem, set an eject delay of a few seconds.
                  </para>
                  <para>
                     <emphasis>Restrictions:</emphasis> If set, must be an integer &ge; 1.
                  </para>
               </listitem>
            </varlistentry>

            <varlistentry>
               <term><literal>blank_behavior</literal></term>
               <listitem>
                  <para>Optimized blanking strategy.</para>

                  <para>
                     For more information about Cedar Backup's optimized
                     blanking strategy, see <xref
                     linkend="cedar-config-blanking"/>.
                  </para>

                  <para>
                     This entire configuration section is optional.  However,
                     if you choose to provide it, you must configure both a
                     blanking mode and a blanking factor.
                  </para>

                  <variablelist>
                     <varlistentry>
                        <term><literal>blank_mode</literal></term>
                        <listitem>
                           <para>Blanking mode.</para>
                           <para>
                              <emphasis>Restrictions:</emphasis>Must be one of "daily" or "weekly".
                           </para>
                        </listitem>
                     </varlistentry>
                  </variablelist>

                  <variablelist>
                     <varlistentry>
                        <term><literal>blank_factor</literal></term>
                        <listitem>
                           <para>Blanking factor.</para>
                           <para>
                              <emphasis>Restrictions:</emphasis>Must be a floating point number &ge; 0.
                           </para>
                        </listitem>
                     </varlistentry>
                  </variablelist>

               </listitem>
            </varlistentry>

         </variablelist>

      </sect2>

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

      <sect2 id="cedar-config-configfile-purge">

         <title>Purge Configuration</title>

         <para>
            The purge configuration section contains configuration options
            related the the purge action.  This section contains a set of
            directories to be purged, along with information about the schedule
            at which they should be purged.
         </para>

         <para>
            Typically, Cedar Backup should be configured to purge collect
            directories daily (retain days of <literal>0</literal>).
         </para>

         <para>
            If you are tight on space, staging directories can also be purged
            daily.  However, if you have space to spare, you should consider
            purging about once per week.  That way, if your backup media is
            damaged, you will be able to recreate the week's backup using the
            rebuild action.
         </para>

         <para>
            You should also purge the working directory periodically, once
            every few weeks or once per month.  This way, if any unneeded files
            are left around, perhaps because a backup was interrupted or
            because configuration changed, they will eventually be removed.
            <emphasis>The working directory should not be purged any more
            frequently than once per week, otherwise you will risk destroying
            data used for incremental backups.</emphasis>
         </para>

         <para>
            This is an example purge configuration section:
         </para>

         <programlisting>
&lt;purge&gt;
   &lt;dir&gt;
      &lt;abs_path&gt;/opt/backup/stage&lt;/abs_path&gt;
      &lt;retain_days&gt;7&lt;/retain_days&gt;
   &lt;/dir&gt;
   &lt;dir&gt;
      &lt;abs_path&gt;/opt/backup/collect&lt;/abs_path&gt;
      &lt;retain_days&gt;0&lt;/retain_days&gt;
   &lt;/dir&gt;
&lt;/purge&gt;
         </programlisting>

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

         <variablelist>

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

                  <variablelist>

                     <varlistentry>
                        <term><literal>abs_path</literal></term>
                        <listitem>
                           <para>
                              Absolute path of the directory to purge within.
                           </para>
                           <para>
                              The contents of the directory will be purged
                              based on age.  The purge will remove any files
                              that were last modified more than <quote>retain
                              days</quote> days ago.  Empty directories will
                              also eventually be removed.  The purge directory
                              itself will never be removed.
                           </para>
                           <para>
                              The path may be either a directory, a soft link
                              to a directory, or a hard link to a directory.
                              Soft links <emphasis>within</emphasis> the
                              directory (if any) are treated as files.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be an absolute path.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>retain_days</literal></term>
                        <listitem>
                           <para>
                              Number of days to retain old files.
                           </para>
                           <para>
                              Once it has been more than this many days since a file
                              was last modified, it is a candidate for removal.
                           </para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be an integer &ge; 0.
                           </para>
                        </listitem>
                     </varlistentry>

                  </variablelist>

               </listitem>

            </varlistentry>

         </variablelist>

      </sect2>

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

      <sect2 id="cedar-config-configfile-extensions">

         <title>Extensions Configuration</title>

         <para>
            The extensions configuration section is used to configure
            third-party extensions to Cedar Backup.  If you don't intend to use
            any extensions, or don't know what extensions are, then you can
            safely leave this section out of your configuration file.  It is
            optional.
         </para>

         <para>
            Extensions configuration is used to specify <quote>extended
            actions</quote> implemented by code external to Cedar Backup.  An
            administrator can use this section to map command-line Cedar
            Backup actions to third-party extension functions.
         </para>

         <para>
            Each extended action has a name, which is mapped to a Python
            function within a particular module.  Each action also has an index
            associated with it.  This index is used to properly order execution
            when more than one action is specified on the command line.
            The standard actions have predefined indexes, and extended actions
            are interleaved into the normal order of execution using those
            indexes.  The collect action has index 100, the stage index
            has action 200, the store action has index 300 and the purge
            action has index 400.
         </para>

         <warning>
            <para>
               Extended actions should always be configured to run
               <emphasis>before</emphasis> the standard action they are
               associated with.  This is because of the way indicator files are
               used in Cedar Backup.  For instance, the staging process
               considers the collect action to be complete for a peer if the
               file <filename>cback.collect</filename> can be found in that
               peer's collect directory.  
            </para>
            
            <para>
               If you were to run the standard collect action before your other
               collect-like actions, the indicator file would be written after
               the collect action completes but <emphasis>before</emphasis> all
               of the other actions even run.  Because of this, there's a
               chance the stage process might back up the collect directory
               before the entire set of collect-like actions have completed
               &mdash; and you would get no warning about this in your email!
            </para>
         </warning>
         
         <para>
            So, imagine that a third-party developer provided a Cedar
            Backup extension to back up a certain kind of database repository,
            and you wanted to map that extension to the <quote>database</quote>
            command-line action.  You have been told that this function is
            called <quote>foo.bar()</quote>.  You think of this backup as a
            <quote>collect</quote> kind of action, so you want it to be
            performed immediately before the collect action.
         </para>

         <para>
            To configure this extension, you would list an action with a name
            <quote>database</quote>, a module <quote>foo</quote>,
            a function name <quote>bar</quote> and an index of
            <quote>99</quote>.
         </para>

         <para>
            This is how the hypothetical action would be configured:
         </para>

         <programlisting>
&lt;extensions&gt;
   &lt;action&gt;
      &lt;name&gt;database&lt;/name&gt;
      &lt;module&gt;foo&lt;/module&gt;
      &lt;function&gt;bar&lt;/function&gt;
      &lt;index&gt;99&lt;/index&gt;
   &lt;/action&gt;
&lt;/extensions&gt;
         </programlisting>

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

         <variablelist>

            <varlistentry>
               <term><literal>action</literal></term>
               <listitem>
                  <para>
                     This is a subsection that contains configuration
                     related to a single extended action.
                  </para>
                  <para>
                     This section can be repeated as many times as is
                     necessary.  
                  </para>
                  <para>
                     The action subsection contains the following fields:
                  </para>

                  <variablelist>

                     <varlistentry>
                        <term><literal>name</literal></term>
                        <listitem>
                           <para>Name of the extended action.</para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be a non-empty
                              string consisting of only lower-case letters and digits.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>module</literal></term>
                        <listitem>
                           <para>Name of the Python module associated with the extension function.</para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be a non-empty string
                              and a valid Python identifier.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>function</literal></term>
                        <listitem>
                           <para>Name of the Python extension function within the module.</para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be a non-empty string
                              and a valid Python identifier.
                           </para>
                        </listitem>
                     </varlistentry>

                     <varlistentry>
                        <term><literal>index</literal></term>
                        <listitem>
                           <para>Index of action, for execution ordering.</para>
                           <para>
                              <emphasis>Restrictions:</emphasis> Must be an integer &ge; 0.
                           </para>
                        </listitem>
                     </varlistentry>

                  </variablelist>

               </listitem>

            </varlistentry>

         </variablelist>

      </sect2>

   </sect1>

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

   <sect1 id="cedar-config-poolofone">
         
      <title>Setting up a Pool of One</title>

      <para>
         Cedar Backup has been designed primarily for situations where there is
         a single master and a set of other clients that the master interacts
         with.  However, it will just as easily work for a single machine (a
         backup pool of one).
      </para>

      <para>
         Once you complete all of these configuration steps, your backups will
         run as scheduled out of cron. Any errors that occur will be reported
         in daily emails to your root user (or the user that receives root's
         email). If you don't receive any emails, then you know your backup
         worked.
      </para>

      <para>
         Note: all of these configuration steps should be run as the root user,
         unless otherwise indicated.
      </para>

      <tip>
         <para>
            This setup procedure discusses how to set up Cedar Backup in the
            <quote>normal case</quote> for a pool of one.  If you would like to
            modify the way Cedar Backup works (for instance, by ignoring the
            store stage and just letting your backup sit in a staging
            directory), you can do that.  You'll just have to modify the
            procedure below based on information in the remainder of the
            manual.
         </para>
      </tip>

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

      <sect2>

         <title>Step 1: Decide when you will run your backup.</title>

         <para>
            There are four parts to a Cedar Backup run: collect, stage, store
            and purge. The usual way of setting off these steps is through a
            set of cron jobs.  Although you won't create your cron jobs just
            yet, you should decide now when you will run your backup so you are
            prepared for later.
         </para>

         <para>
            Backing up large directories and creating ISO filesystem images can
            be intensive operations, and could slow your computer down
            significantly. Choose a backup time that will not interfere with
            normal use of your computer.  Usually, you will want the backup to
            occur every day, but it is possible to configure cron to execute
            the backup only one day per week, three days per week, etc.
         </para>

         <warning>
            <para>
               Because of the way Cedar Backup works, you must ensure that your
               backup <emphasis>always</emphasis> runs on the first day of your
               configured week.  This is because Cedar Backup will only clear
               incremental backup information and re-initialize your media when
               running on the first day of the week.  If you skip running Cedar
               Backup on the first day of the week, your backups will likely be
               <quote>confused</quote> until the next week begins, or until you
               re-run the backup using the <option>--full</option> flag.
            </para>
         </warning>

      </sect2>

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

      <sect2>

         <title>Step 2: Make sure email works.</title>

         <para>
            Cedar Backup relies on email for problem notification.  This
            notification works through the magic of cron.  Cron will email any
            output from each job it executes to the user associated with the
            job.  Since by default Cedar Backup only writes output to the
            terminal if errors occur, this ensures that notification emails
            will only be sent out if errors occur.
         </para>
            
         <para>
            In order to receive problem notifications, you must make sure that
            email works for the user which is running the Cedar Backup cron
            jobs (typically root).  Refer to your distribution's documentation
            for information on how to configure email on your system.  Note
            that you may prefer to configure root's email to forward to some
            other user, so you do not need to check the root user's mail in
            order to see Cedar Backup errors.
         </para>
            
      </sect2>

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

      <sect2>

         <title>Step 3: Configure your writer device.</title>

         <para>
            Before using Cedar Backup, your writer device must be properly
            configured.  If you have configured your CD/DVD writer hardware to
            work through the normal filesystem device path, then you just need
            to know the path to the device on disk (something like
            <filename>/dev/cdrw</filename>).  Cedar Backup will use the this
            device path both when talking to a command like
            <command>cdrecord</command> and when doing filesystem operations
            like running media validation.
         </para>

         <para>
            Your other option is to configure your CD writer hardware like a SCSI
            device (either because it <emphasis>is</emphasis> a SCSI device or
            because you are using some sort of interface that makes it look
            like one).  In this case, Cedar Backup will use the SCSI id when
            talking to <command>cdrecord</command> and the device path when
            running filesystem operations.
         </para>

         <para>
            See <xref linkend="cedar-config-writer"/> for more information on
            writer devices and how they are configured.
         </para>

         <note>
            <para>
               There is no need to set up your CD/DVD device if you have
               decided not to execute the store action.
            </para>

            <para>
                Due to the underlying utilities that Cedar Backup uses, the
                SCSI id may only be used for CD writers,
                <emphasis>not</emphasis> DVD writers.
            </para>
         </note>

      </sect2>

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

      <sect2>

         <title>Step 4: Configure your backup user.</title>

         <para>
             Choose a user to be used for backups. Some platforms may
             come with a <quote>ready made</quote> backup user. For other
             platforms, you may have to create a user yourself. You may
             choose any id you like, but a descriptive name such as
             <literal>backup</literal> or <literal>cback</literal> is a good
             choice.  See your distribution's documentation for information on
             how to add a user.
         </para>

         <note>
            <para>
               Standard Debian systems come with a user named
               <literal>backup</literal>.  You may choose to stay with this
               user or create another one.
            </para>
         </note>

      </sect2>

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

      <sect2>

         <title>Step 5: Create your backup tree.</title>

         <para>
            Cedar Backup requires a backup directory tree on disk. This
            directory tree must be roughly three times as big as the amount of
            data that will be backed up on a nightly basis, to allow for the
            data to be collected, staged, and then placed into an ISO filesystem
            image on disk. (This is one disadvantage to using Cedar Backup in
            single-machine pools, but in this day of really large hard drives,
            it might not be an issue.) Note that if you elect not to purge the
            staging directory every night, you will need even more space.
         </para>

         <para>
            You should create a collect directory, a staging directory and a
            working (temporary) directory. One recommended layout is this:
         </para>

         <programlisting>
/opt/
     backup/
            collect/
            stage/
            tmp/
         </programlisting>

         <para>
            If you will be backing up sensitive information (i.e. password
            files), it is recommended that these directories be owned by the
            backup user (whatever you named it), with permissions
            <literal>700</literal>. 
         </para>

         <note>
            <para>
               You don't have to use <filename>/opt</filename> as the root of your
               directory structure.  Use anything you would like.  I use
               <filename>/opt</filename> because it is my <quote>dumping
               ground</quote> for filesystems that Debian does not manage.
            </para>

            <para>
               Some users have requested that the Debian packages set up a more
               <quote>standard</quote> location for backups right
               out-of-the-box.  I have resisted doing this because it's
               difficult to choose an appropriate backup location from within
               the package.  If you would prefer, you can create the backup
               directory structure within some existing Debian directory such
               as <filename>/var/backups</filename> or
               <filename>/var/tmp</filename>.
            </para>
         </note>

      </sect2>

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

      <sect2>

         <title>Step 6: Create the Cedar Backup configuration file.</title>

         <para>
            Following the instructions in <xref
            linkend="cedar-config-configfile"/> (above) create a configuration
            file for your machine.  Since you are working with a pool of one,
            you must configure all four action-specific sections: collect,
            stage, store and purge.
         </para>
            
         <para>
            The usual location for the Cedar Backup config file is
            <filename>/etc/cback3.conf</filename>.  If you change the location,
            make sure you edit your cronjobs (below) to point the
            <command>cback3</command> script at the correct config file (using
            the <option>--config</option> option).
         </para>

         <warning>
            <para>
               Configuration files should always be writable only by root
               (or by the file owner, if the owner is not root).
            </para>

            <para>
               If you intend to place confidential information into the Cedar
               Backup configuration file, make sure that you set the filesystem
               permissions on the file appropriately.  For instance, if you
               configure any extensions that require passwords or other similar
               information, you should make the file readable only to root or
               to the file owner (if the owner is not root).
            </para>
         </warning>

      </sect2>

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

      <sect2>

         <title>Step 7: Validate the Cedar Backup configuration file.</title>

         <para>
            Use the command <command>cback3 validate</command> to validate your
            configuration file. This command checks that the configuration file
            can be found and parsed, and also checks for typical configuration
            problems, such as invalid CD/DVD device entries.
         </para>

         <para>
            Note: the most common cause of configuration problems is in not
            closing XML tags properly. Any XML tag that is
            <quote>opened</quote> must be <quote>closed</quote> appropriately.
         </para>

      </sect2>

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

      <sect2>
         <title>Step 8: Test your backup.</title>

         <para>
            Place a valid CD/DVD disc in your drive, and then use the
            command <command>cback3 --full all</command>.  You should execute
            this command as root.  If the command completes with no output,
            then the backup was run successfully.
         </para>

         <para>
            Just to be sure that everything worked properly, check the logfile
            (<filename>/var/log/cback3.log</filename>) for errors and also mount
            the CD/DVD disc to be sure it can be read.
         </para>

         <para>
            <emphasis>If Cedar Backup ever completes <quote>normally</quote>
            but the disc that is created is not usable, please report this as a
            bug.
            <footnote id="cedar-config-foot-bugs"><para>
            See <ulink url="https://bitbucket.org/cedarsolutions/cedar-backup3/issues"/>.</para></footnote>
            To be safe, always enable the consistency check option in the
            store configuration section.</emphasis>
         </para>

      </sect2>

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

      <sect2>

         <title>Step 9: Modify the backup cron jobs.</title>

         <para>
            Since Cedar Backup should be run as root, one way to configure the
            cron job is to add a line like this to your
            <filename>/etc/crontab</filename> file:
         </para>

         <programlisting>
30 00 * * * root  cback3 all
         </programlisting>
                          
         <para>
            Or, you can create an executable script containing just these lines
            and place that file in the <filename>/etc/cron.daily</filename>
            directory:
         </para>

         <programlisting>
#/bin/sh
cback3 all
         </programlisting>

         <para>
            You should consider adding the <option>--output</option> or
            <option>-O</option> switch to your <command>cback3</command>
            command-line in cron.  This will result in larger logs, but could
            help diagnose problems when commands like
            <command>cdrecord</command> or <command>mkisofs</command> fail
            mysteriously.
         </para>

         <note>
            <para>
               For general information about using cron, see the manpage for
               crontab(5).
            </para>

            <para>
               On a Debian system, execution of daily backups is controlled by
               the file <filename>/etc/cron.d/cedar-backup3</filename>.  As
               installed, this file contains several different settings, all
               commented out.  Uncomment the <quote>Single machine (pool of
               one)</quote> entry in the file, and change the line so that the
               backup goes off when you want it to.
            </para>
         </note>

      </sect2>

   </sect1>

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

   <sect1 id="cedar-config-client">
         
      <title>Setting up a Client Peer Node</title>

      <para>
         Cedar Backup has been designed to backup entire <quote>pools</quote>
         of machines.  In any given pool, there is one master and some number
         of clients.  Most of the work takes place on the master, so
         configuring a client is a little simpler than configuring a master.
      </para>

      <para>
         Backups are designed to take place over an RSH or SSH connection.
         Because RSH is generally considered insecure, you are encouraged to
         use SSH rather than RSH. This document will only describe how to
         configure Cedar Backup to use SSH; if you want to use RSH, you're on
         your own. 
      </para>

      <para>
         Once you complete all of these configuration steps, your backups will
         run as scheduled out of cron. Any errors that occur will be reported
         in daily emails to your root user (or the user that receives root's
         email). If you don't receive any emails, then you know your backup
         worked.
      </para>

      <para>
         Note: all of these configuration steps should be run as the root user,
         unless otherwise indicated.
      </para>

      <note>
         <para>
            See <xref linkend="cedar-securingssh"/> for some important notes on
            how to optionally further secure password-less SSH connections to
            your clients.
         </para>
      </note>

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

      <sect2>

         <title>Step 1: Decide when you will run your backup.</title>

         <para>
            There are four parts to a Cedar Backup run: collect, stage, store
            and purge. The usual way of setting off these steps is through a
            set of cron jobs.  Although you won't create your cron jobs just
            yet, you should decide now when you will run your backup so you are
            prepared for later.
         </para>

         <para>
            Backing up large directories and creating ISO filesystem images can be
            intensive operations, and could slow your computer down
            significantly. Choose a backup time that will not interfere with
            normal use of your computer.  Usually, you will want the backup to
            occur every day, but it is possible to configure cron to execute
            the backup only one day per week, three days per week, etc.
         </para>

         <warning>
            <para>
               Because of the way Cedar Backup works, you must ensure that your
               backup <emphasis>always</emphasis> runs on the first day of your
               configured week.  This is because Cedar Backup will only clear
               incremental backup information and re-initialize your media when
               running on the first day of the week.  If you skip running Cedar
               Backup on the first day of the week, your backups will likely be
               <quote>confused</quote> until the next week begins, or until you
               re-run the backup using the <option>--full</option> flag.
            </para>
         </warning>

      </sect2>
      <!-- ################################################################# -->

      <sect2>

         <title>Step 2: Make sure email works.</title>

         <para>
            Cedar Backup relies on email for problem notification.  This
            notification works through the magic of cron.  Cron will email any
            output from each job it executes to the user associated with the
            job.  Since by default Cedar Backup only writes output to the
            terminal if errors occur, this neatly ensures that notification
            emails will only be sent out if errors occur.
         </para>
            
         <para>
            In order to receive problem notifications, you must make sure that
            email works for the user which is running the Cedar Backup cron
            jobs (typically root).  Refer to your distribution's documentation
            for information on how to configure email on your system.  Note
            that you may prefer to configure root's email to forward to some
            other user, so you do not need to check the root user's mail in
            order to see Cedar Backup errors.
         </para>
            
      </sect2>

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

      <sect2>

         <title>Step 3: Configure the master in your backup pool.</title>

         <para>
            You will not be able to complete the client configuration until at
            least step 3 of the master's configuration has been completed. In
            particular, you will need to know the master's public SSH identity
            to fully configure a client.
         </para>

         <para>
            To find the master's public SSH identity, log in as the backup
            user on the master and <command>cat</command> the public identity
            file <filename>~/.ssh/id_rsa.pub</filename>:
         </para>

         <programlisting>
user@machine> cat ~/.ssh/id_rsa.pub
ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAIEA0vOKjlfwohPg1oPRdrmwHk75l3mI9Tb/WRZfVnu2Pw69
uyphM9wBLRo6QfOC2T8vZCB8o/ZIgtAM3tkM0UgQHxKBXAZ+H36TOgg7BcI20I93iGtzpsMA/uXQy8kH
HgZooYqQ9pw+ZduXgmPcAAv2b5eTm07wRqFt/U84k6bhTzs= user@machine
         </programlisting>

      </sect2>

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

      <sect2>

         <title>Step 4: Configure your backup user.</title>

         <para>
             Choose a user to be used for backups. Some platforms may come with
             a "ready made" backup user. For other platforms, you may have to
             create a user yourself. You may choose any id you like, but a
             descriptive name such as <literal>backup</literal> or
             <literal>cback</literal> is a good choice.  See your
             distribution's documentation for information on how to add a user.
         </para>

         <note>
            <para>
               Standard Debian systems come with a user named
               <literal>backup</literal>.  You may choose to stay with this
               user or create another one.
            </para>
         </note>

         <para>
             Once you have created your backup user, you must create an SSH
             keypair for it. Log in as your backup user, and then run the
             command <command>ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa</command>:
         </para>

         <programlisting>
user@machine> ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa
Generating public/private rsa key pair.
Created directory '/home/user/.ssh'.
Your identification has been saved in /home/user/.ssh/id_rsa.
Your public key has been saved in /home/user/.ssh/id_rsa.pub.
The key fingerprint is:
11:3e:ad:72:95:fe:96:dc:1e:3b:f4:cc:2c:ff:15:9e user@machine
         </programlisting>

         <para>
            The default permissions for this directory should be fine.
            However, if the directory existed before you ran
            <command>ssh-keygen</command>, then you may need to modify the
            permissions.  Make sure that the <filename>~/.ssh</filename>
            directory is readable only by the backup user (i.e. mode
            <literal>700</literal>), that the
            <filename>~/.ssh/id_rsa</filename> file is only readable and
            writable only by the backup user (i.e. mode <literal>600</literal>)
            and that the <filename>~/.ssh/id_rsa.pub</filename> file is
            writable only by the backup user (i.e. mode <literal>600</literal>
            or mode <literal>644</literal>).
         </para>

         <para>
            Finally, take the master's public SSH identity (which you found in
            step 2) and cut-and-paste it into the file
            <filename>~/.ssh/authorized_keys</filename>.  Make sure the
            identity value is pasted into the file <emphasis>all on one
            line</emphasis>, and that the <filename>authorized_keys</filename>
            file is owned by your backup user and has permissions
            <literal>600</literal>.
         </para>
         
         <para>
            If you have other preferences or standard ways of setting up your
            users' SSH configuration (i.e. different key type, etc.), feel free
            to do things your way.  The important part is that the master must
            be able to SSH into a client <emphasis>with no password entry
            required</emphasis>.
         </para>

      </sect2>

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

      <sect2>

         <title>Step 5: Create your backup tree.</title>

         <para>
            Cedar Backup requires a backup directory tree on disk. This
            directory tree must be roughly as big as the amount of data that
            will be backed up on a nightly basis (more if you elect not to
            purge it all every night).
         </para>

         <para>
            You should create a collect directory and a working (temporary)
            directory. One recommended layout is this:
         </para>

         <programlisting>
/opt/
     backup/
            collect/
            tmp/
         </programlisting>

         <para>
            If you will be backing up sensitive information (i.e. password
            files), it is recommended that these directories be owned by the
            backup user (whatever you named it), with permissions
            <literal>700</literal>. 
         </para>

         <note>
            <para>
               You don't have to use <filename>/opt</filename> as the root of your
               directory structure.  Use anything you would like.  I use
               <filename>/opt</filename> because it is my <quote>dumping
               ground</quote> for filesystems that Debian does not manage.
            </para>

            <para>
               Some users have requested that the Debian packages set up a more
               "standard" location for backups right out-of-the-box.  I have
               resisted doing this because it's difficult to choose an
               appropriate backup location from within the package.  If you
               would prefer, you can create the backup directory structure
               within some existing Debian directory such as
               <filename>/var/backups</filename> or
               <filename>/var/tmp</filename>.
            </para>
         </note>

      </sect2>

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

      <sect2>

         <title>Step 6: Create the Cedar Backup configuration file.</title>

         <para>
            Following the instructions in <xref
            linkend="cedar-config-configfile"/> (above), create a configuration
            file for your machine.  Since you are working with a client, you
            must configure all action-specific sections for the collect and
            purge actions.
         </para>
            
         <para>
            The usual location for the Cedar Backup config file is
            <filename>/etc/cback3.conf</filename>.  If you change the location,
            make sure you edit your cronjobs (below) to point the
            <command>cback3</command> script at the correct config file (using
            the <option>--config</option> option).
         </para>

         <warning>
            <para>
               Configuration files should always be writable only by root
               (or by the file owner, if the owner is not root).
            </para>

            <para>
               If you intend to place confidental information into the Cedar
               Backup configuration file, make sure that you set the filesystem
               permissions on the file appropriately.  For instance, if you
               configure any extensions that require passwords or other similar
               information, you should make the file readable only to root or
               to the file owner (if the owner is not root).
            </para>
         </warning>

      </sect2>

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

      <sect2>

         <title>Step 7: Validate the Cedar Backup configuration file.</title>

         <para>
            Use the command <command>cback3 validate</command> to validate your
            configuration file. This command checks that the configuration file
            can be found and parsed, and also checks for typical configuration
            problems.  This command <emphasis>only</emphasis> validates
            configuration on the one client, not the master or any other
            clients in a pool.
         </para>

         <para>
            Note: the most common cause of configuration problems is in not
            closing XML tags properly. Any XML tag that is
            <quote>opened</quote> must be <quote>closed</quote> appropriately.
         </para>

      </sect2>

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

      <sect2>

         <title>Step 8: Test your backup.</title>

         <para>
            Use the command <command>cback3 --full collect purge</command>.  If the 
            command completes with no output, then the backup was run successfully.
            Just to be sure that everything worked properly, check the logfile 
            (<filename>/var/log/cback3.log</filename>) for errors.
         </para>

      </sect2>

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

      <sect2>

         <title>Step 9: Modify the backup cron jobs.</title>

         <para>
            Since Cedar Backup should be run as root, you should add a set of
            lines like this to your <filename>/etc/crontab</filename> file:
         </para>

         <programlisting>
30 00 * * * root  cback3 collect
30 06 * * * root  cback3 purge
         </programlisting>

         <para>
            You should consider adding the <option>--output</option> or
            <option>-O</option> switch to your <command>cback3</command>
            command-line in cron.  This will result in larger logs, but could
            help diagnose problems when commands like
            <command>cdrecord</command> or <command>mkisofs</command> fail
            mysteriously.
         </para>

         <para>
            You will need to coordinate the collect and purge actions on the
            client so that the collect action completes before the master
            attempts to stage, and so that the purge action does not begin
            until after the master has completed staging.  Usually, allowing an
            hour or two between steps should be sufficient.  <footnote
            id="cedar-config-foot-coordinate"><para>See <xref
            linkend="cedar-basic-coordinate"/> in <xref
            linkend="cedar-basic"/>.</para></footnote>
         </para>

         <note>
            <para>
               For general information about using cron, see the manpage for
               crontab(5).
            </para>

            <para>
               On a Debian system, execution of daily backups is controlled by
               the file <filename>/etc/cron.d/cedar-backup3</filename>.  As
               installed, this file contains several different settings, all
               commented out.  Uncomment the <quote>Client machine</quote>
               entries in the file, and change the lines so that the backup
               goes off when you want it to.
            </para>
         </note>

      </sect2>

   </sect1>

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

   <sect1 id="cedar-config-master">
         
      <title>Setting up a Master Peer Node</title>

      <para>
         Cedar Backup has been designed to backup entire <quote>pools</quote>
         of machines.  In any given pool, there is one master and some number
         of clients.  Most of the work takes place on the master, so
         configuring a master is somewhat more complicated than configuring a
         client.
      </para>

      <para>
         Backups are designed to take place over an RSH or SSH connection.
         Because RSH is generally considered insecure, you are encouraged to
         use SSH rather than RSH. This document will only describe how to
         configure Cedar Backup to use SSH; if you want to use RSH, you're on
         your own. 
      </para>

      <para>
         Once you complete all of these configuration steps, your backups will
         run as scheduled out of cron. Any errors that occur will be reported
         in daily emails to your root user (or whichever other user receives
         root's email). If you don't receive any emails, then you know your
         backup worked.
      </para>

      <para>
         Note: all of these configuration steps should be run as the root user,
         unless otherwise indicated.
      </para>

      <tip>
         <para>
            This setup procedure discusses how to set up Cedar Backup in the
            <quote>normal case</quote> for a master.  If you would like to
            modify the way Cedar Backup works (for instance, by ignoring the
            store stage and just letting your backup sit in a staging
            directory), you can do that.  You'll just have to modify the
            procedure below based on information in the remainder of the
            manual.
         </para>
      </tip>

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

      <sect2>

         <title>Step 1: Decide when you will run your backup.</title>

         <para>
            There are four parts to a Cedar Backup run: collect, stage, store
            and purge. The usual way of setting off these steps is through a
            set of cron jobs.  Although you won't create your cron jobs just
            yet, you should decide now when you will run your backup so you are
            prepared for later.
         </para>
         
         <para>
            Keep in mind that you do not necessarily have to run the collect
            action on the master.  See notes further below for more
            information.
         </para>

         <para>
            Backing up large directories and creating ISO filesystem images can be
            intensive operations, and could slow your computer down
            significantly. Choose a backup time that will not interfere with
            normal use of your computer.  Usually, you will want the backup to
            occur every day, but it is possible to configure cron to execute
            the backup only one day per week, three days per week, etc.
         </para>

         <warning>
            <para>
               Because of the way Cedar Backup works, you must ensure that your
               backup <emphasis>always</emphasis> runs on the first day of your
               configured week.  This is because Cedar Backup will only clear
               incremental backup information and re-initialize your media when
               running on the first day of the week.  If you skip running Cedar
               Backup on the first day of the week, your backups will likely be
               <quote>confused</quote> until the next week begins, or until you
               re-run the backup using the <option>--full</option> flag.
            </para>
         </warning>

      </sect2>
      <!-- ################################################################# -->

      <sect2>

         <title>Step 2: Make sure email works.</title>

         <para>
            Cedar Backup relies on email for problem notification.  This
            notification works through the magic of cron.  Cron will email any
            output from each job it executes to the user associated with the
            job.  Since by default Cedar Backup only writes output to the
            terminal if errors occur, this neatly ensures that notification
            emails will only be sent out if errors occur.
         </para>
            
         <para>
            In order to receive problem notifications, you must make sure that
            email works for the user which is running the Cedar Backup cron
            jobs (typically root).  Refer to your distribution's documentation
            for information on how to configure email on your system.  Note
            that you may prefer to configure root's email to forward to some
            other user, so you do not need to check the root user's mail in
            order to see Cedar Backup errors.
         </para>
            
      </sect2>

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

      <sect2>

         <title>Step 3: Configure your writer device.</title>

         <para>
            Before using Cedar Backup, your writer device must be properly
            configured.  If you have configured your CD/DVD writer hardware to
            work through the normal filesystem device path, then you just need
            to know the path to the device on disk (something like
            <filename>/dev/cdrw</filename>).  Cedar Backup will use the this
            device path both when talking to a command like
            <command>cdrecord</command> and when doing filesystem operations
            like running media validation.
         </para>

         <para>
            Your other option is to configure your CD writer hardware like a SCSI
            device (either because it <emphasis>is</emphasis> a SCSI device or
            because you are using some sort of interface that makes it look
            like one).  In this case, Cedar Backup will use the SCSI id when
            talking to <command>cdrecord</command> and the device path when
            running filesystem operations.
         </para>

         <para>
            See <xref linkend="cedar-config-writer"/> for more information on
            writer devices and how they are configured.
         </para>

         <note>
            <para>
               There is no need to set up your CD/DVD device if you have
               decided not to execute the store action.
            </para>

            <para>
                Due to the underlying utilities that Cedar Backup uses, the
                SCSI id may only be used for CD writers,
                <emphasis>not</emphasis> DVD writers.
            </para>
         </note>

      </sect2>

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

      <sect2>

         <title>Step 4: Configure your backup user.</title>

         <para>
             Choose a user to be used for backups. Some platforms may come with
             a <quote>ready made</quote> backup user. For other platforms, you
             may have to create a user yourself. You may choose any id you
             like, but a descriptive name such as <literal>backup</literal> or
             <literal>cback</literal> is a good choice.  See your
             distribution's documentation for information on how to add a user.
         </para>

         <note>
            <para>
               Standard Debian systems come with a user named
               <literal>backup</literal>.  You may choose to stay with this
               user or create another one.
            </para>
         </note>

         <para>
             Once you have created your backup user, you must create an SSH
             keypair for it. Log in as your backup user, and then run the
             command <command>ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa</command>:
         </para>

         <programlisting>
user@machine> ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa
Generating public/private rsa key pair.
Created directory '/home/user/.ssh'.
Your identification has been saved in /home/user/.ssh/id_rsa.
Your public key has been saved in /home/user/.ssh/id_rsa.pub.
The key fingerprint is:
11:3e:ad:72:95:fe:96:dc:1e:3b:f4:cc:2c:ff:15:9e user@machine
         </programlisting>

         <para>
            The default permissions for this directory should be fine.
            However, if the directory existed before you ran
            <command>ssh-keygen</command>, then you may need to modify the
            permissions.  Make sure that the <filename>~/.ssh</filename>
            directory is readable only by the backup user (i.e. mode
            <literal>700</literal>), that the
            <filename>~/.ssh/id_rsa</filename> file is only readable and
            writable by the backup user (i.e. mode <literal>600</literal>) and
            that the <filename>~/.ssh/id_rsa.pub</filename> file is writable
            only by the backup user (i.e. mode <literal>600</literal> or mode
            <literal>644</literal>).
         </para>
         
         <para>
            If you have other preferences or standard ways of setting up your
            users' SSH configuration (i.e. different key type, etc.), feel free
            to do things your way.  The important part is that the master must
            be able to SSH into a client <emphasis>with no password entry
            required</emphasis>.
         </para>

      </sect2>

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

      <sect2>

         <title>Step 5: Create your backup tree.</title>

         <para>
            Cedar Backup requires a backup directory tree on disk. This
            directory tree must be roughly large enough hold twice as much data
            as will be backed up from the entire pool on a given night, plus
            space for whatever is collected on the master itself. This will
            allow for all three operations - collect, stage and store - to have
            enough space to complete. Note that if you elect not to purge the
            staging directory every night, you will need even more space.
         </para>

         <para>
            You should create a collect directory, a staging directory and a
            working (temporary) directory. One recommended layout is this:
         </para>

         <programlisting>
/opt/
     backup/
            collect/
            stage/
            tmp/
         </programlisting>

         <para>
            If you will be backing up sensitive information (i.e. password
            files), it is recommended that these directories be owned by the
            backup user (whatever you named it), with permissions
            <literal>700</literal>. 
         </para>

         <note>

            <para>
               You don't have to use <filename>/opt</filename> as the root of your
               directory structure.  Use anything you would like.  I use
               <filename>/opt</filename> because it is my <quote>dumping
               ground</quote> for filesystems that Debian does not manage.
            </para>

            <para>
               Some users have requested that the Debian packages set up a more
               <quote>standard</quote> location for backups right
               out-of-the-box.  I have resisted doing this because it's
               difficult to choose an appropriate backup location from within
               the package.  If you would prefer, you can create the backup
               directory structure within some existing Debian directory such
               as <filename>/var/backups</filename> or
               <filename>/var/tmp</filename>.
            </para>
         </note>

      </sect2>

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

      <sect2>

         <title>Step 6: Create the Cedar Backup configuration file.</title>

         <para>
            Following the instructions in 
            <xref linkend="cedar-config-configfile"/> (above), create a
            configuration file for your machine.  Since you are working with a
            master machine, you would typically configure all four
            action-specific sections: collect, stage, store and purge.
         </para>

         <note>
            <para>
               Note that the master can treat itself as a <quote>client</quote>
               peer for certain actions.  As an example, if you run the collect
               action on the master, then you will stage that data by
               configuring a local peer representing the master.
            </para>

            <para>
               Something else to keep in mind is that you do not really have to
               run the collect action on the master.  For instance, you may
               prefer to just use your master machine as a <quote>consolidation
               point</quote> machine that just collects data from the other
               client machines in a backup pool.  In that case, there is no
               need to collect data on the master itself.
            </para>
         </note>
            
         <para>
            The usual location for the Cedar Backup config file is
            <filename>/etc/cback3.conf</filename>.  If you change the location,
            make sure you edit your cronjobs (below) to point the
            <command>cback3</command> script at the correct config file (using
            the <option>--config</option> option).
         </para>

         <warning>
            <para>
               Configuration files should always be writable only by root
               (or by the file owner, if the owner is not root).
            </para>

            <para>
               If you intend to place confidental information into the Cedar
               Backup configuration file, make sure that you set the filesystem
               permissions on the file appropriately.  For instance, if you
               configure any extensions that require passwords or other similar
               information, you should make the file readable only to root or
               to the file owner (if the owner is not root).
            </para>
         </warning>

      </sect2>

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

      <sect2>

         <title>Step 7: Validate the Cedar Backup configuration file.</title>

         <para>
            Use the command <command>cback3 validate</command> to validate your
            configuration file. This command checks that the configuration file
            can be found and parsed, and also checks for typical configuration
            problems, such as invalid CD/DVD device entries.  This command
            <emphasis>only</emphasis> validates configuration on the master,
            not any clients that the master might be configured to connect to.
         </para>

         <para>
            Note: the most common cause of configuration problems is in not
            closing XML tags properly. Any XML tag that is
            <quote>opened</quote> must be <quote>closed</quote> appropriately.
         </para>

      </sect2>

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

      <sect2>

         <title>Step 8: Test connectivity to client machines.</title>

         <para>
            This step must wait until after your client machines have been at
            least partially configured. Once the backup user(s) have been
            configured on the client machine(s) in a pool, attempt an SSH
            connection to each client. 
         </para>
            
         <para>
            Log in as the backup user on the master, and then use the command
            <command>ssh user@machine</command> where
            <replaceable>user</replaceable> is the name of backup user
            <emphasis>on the client machine</emphasis>, and
            <replaceable>machine</replaceable> is the name of the client
            machine.
         </para>

         <para>
            If you are able to log in successfully to each client without
            entering a password, then things have been configured properly.
            Otherwise, double-check that you followed the user setup
            instructions for the master and the clients.
         </para>

      </sect2>

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

      <sect2>
         <title>Step 9: Test your backup.</title>

         <para>
             Make sure that you have configured all of the clients in your
             backup pool. On all of the clients, execute <command>cback3 --full
             collect</command>.  (You will probably have already tested this
             command on each of the clients, so it should succeed.)
         </para>

         <para>
            When all of the client backups have completed, place a valid CD/DVD
            disc in your drive, and then use the command <command>cback3 --full
            all</command>.  You should execute this command as root.  If the
            command completes with no output, then the backup was run
            successfully. 
         </para>

         <para>
            Just to be sure that everything worked properly, check the logfile
            (<filename>/var/log/cback3.log</filename>) on the master and each of
            the clients, and also mount the CD/DVD disc on the master to
            be sure it can be read.
         </para>

         <para>
            You may also want to run <command>cback3 purge</command> on the
            master and each client once you have finished validating that
            everything worked.
         </para>

         <para>
            <emphasis>If Cedar Backup ever completes <quote>normally</quote>
            but the disc that is created is not usable, please report this as a
            bug.
            <footnoteref linkend="cedar-config-foot-bugs"/>
            To be safe, always enable the consistency check option in the
            store configuration section.</emphasis>
         </para>

      </sect2>

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

      <sect2>

         <title>Step 10: Modify the backup cron jobs.</title>

         <para>
            Since Cedar Backup should be run as root, you should add a set of
            lines like this to your <filename>/etc/crontab</filename> file:
         </para>

         <programlisting>
30 00 * * * root  cback3 collect
30 02 * * * root  cback3 stage
30 04 * * * root  cback3 store
30 06 * * * root  cback3 purge
         </programlisting>

         <para>
            You should consider adding the <option>--output</option> or
            <option>-O</option> switch to your <command>cback3</command>
            command-line in cron.  This will result in larger logs, but could
            help diagnose problems when commands like
            <command>cdrecord</command> or <command>mkisofs</command> fail
            mysteriously.
         </para>
                          
         <para>
            You will need to coordinate the collect and purge actions on
            clients so that their collect actions complete before the master
            attempts to stage, and so that their purge actions do not begin
            until after the master has completed staging.  Usually, allowing
            an hour or two between steps should be sufficient.
            <footnoteref linkend="cedar-config-foot-coordinate"/>
         </para>

         <note>
            <para>
               For general information about using cron, see the manpage for
               crontab(5).
            </para>

            <para>
               On a Debian system, execution of daily backups is controlled by
               the file <filename>/etc/cron.d/cedar-backup3</filename>.  As
               installed, this file contains several different settings, all
               commented out.  Uncomment the <quote>Master machine</quote>
               entries in the file, and change the lines so that the backup
               goes off when you want it to.
            </para>
         </note>

      </sect2>

   </sect1>

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

   <sect1 id="cedar-config-writer">
         
      <title>Configuring your Writer Device</title>

      <sect2>

         <title>Device Types</title>

         <para>
            In order to execute the store action, you need to know how to
            identify your writer device.  Cedar Backup supports two kinds of
            device types: CD writers and DVD writers.  DVD writers are always
            referenced through a filesystem device name (i.e.
            <filename>/dev/dvd</filename>).  CD writers can be referenced
            either through a SCSI id, or through a filesystem device name.
            Which you use depends on your operating system and hardware.
         </para>

      </sect2>

      <sect2>

         <title>Devices identified by by device name</title>

         <para>
            For all DVD writers, and for CD writers on certain platforms, you
            will configure your writer device using only a device name.  If
            your writer device works this way, you should just specify
            &lt;target_device&gt; in configuration.  You can either leave
            &lt;target_scsi_id&gt; blank or remove it completely.  The writer
            device will be used both to write to the device and for filesystem
            operations &mdash; for instance, when the media needs to be mounted
            to run the consistency check.
         </para>

      </sect2>

      <sect2>

         <title>Devices identified by SCSI id</title>

         <para>
            Cedar Backup can use devices identified by SCSI id only when
            configured to use the <literal>cdwriter</literal> device type.
         </para>

         <para>
            In order to use a SCSI device with Cedar Backup, you must know both the
            SCSI id &lt;target_scsi_id&gt; and the device name
            &lt;target_device&gt;.  The SCSI id will be used to write to media
            using <command>cdrecord</command>; and the device name will be used
            for other filesystem operations.
         </para>

         <para>
            A true SCSI device will always have an address
            <literal>scsibus,target,lun</literal> (i.e.
            <literal>1,6,2</literal>).  This should hold true on most UNIX-like
            systems including Linux and the various BSDs (although I do not
            have a BSD system to test with currently).  The SCSI address
            represents the location of your writer device on the one or more
            SCSI buses that you have available on your system.  
         </para>

         <para>
            On some platforms, it is possible to reference non-SCSI writer
            devices (i.e. an IDE CD writer) using an emulated SCSI id.  If you
            have configured your non-SCSI writer device to have an emulated
            SCSI id, provide the filesystem device path in
            &lt;target_device&gt; and the SCSI id in &lt;target_scsi_id&gt;,
            just like for a real SCSI device.
         </para>

         <para>
            You should note that in some cases, an emulated SCSI id takes the
            same form as a normal SCSI id, while in other cases you might see a
            method name prepended to the normal SCSI id (i.e.
            <quote>ATA:1,1,1</quote>).
         </para>

      </sect2>
      
      <sect2>

         <title>Linux Notes</title>

         <para>
            On a Linux system, IDE writer devices often have a emulated SCSI
            address, which allows SCSI-based software to access the device through
            an IDE-to-SCSI interface.  Under these circumstances, the first IDE
            writer device typically has an address <literal>0,0,0</literal>.  However,
            support for the IDE-to-SCSI interface has been deprecated and is not
            well-supported in newer kernels (kernel 2.6.x and later).
         </para> 

         <para>
            Newer Linux kernels can address <firstterm>ATA</firstterm> or
            <firstterm>ATAPI</firstterm> drives without SCSI emulation by
            prepending a <quote>method</quote> indicator to the emulated
            device address.  For instance, <literal>ATA:0,0,0</literal> or
            <literal>ATAPI:0,0,0</literal> are typical values.
         </para>

         <para>
            However, even this interface is deprecated as of late 2006, so with
            relatively new kernels you may be better off using the filesystem
            device path directly rather than relying on any SCSI emulation.
         </para>
      </sect2>

      <sect2>

         <title>Finding your Linux CD Writer</title>

         <para>
            Here are some hints about how to find your Linux CD writer
            hardware.  First, try to reference your device using the filesystem
            device path:
         </para>

         <screen>
cdrecord -prcap dev=/dev/cdrom
         </screen>

         <para>
            Running this command on my hardware gives output that looks like
            this (just the top few lines):
         </para>
         
         <screen>
Device type    : Removable CD-ROM
Version        : 0
Response Format: 2
Capabilities   : 
Vendor_info    : 'LITE-ON '
Identification : 'DVDRW SOHW-1673S'
Revision       : 'JS02'
Device seems to be: Generic mmc2 DVD-R/DVD-RW.

Drive capabilities, per MMC-3 page 2A:
         </screen>

         <para>
            If this works, and the identifying information at the top of the
            output looks like your CD writer device, you've probably found a
            working configuration.  Place the device path into
            &lt;target_device&gt; and leave &lt;target_scsi_id&gt; blank.
         </para>

         <para>
            If this doesn't work, you should try to find an ATA or ATAPI
            device:
         </para>

         <screen>
cdrecord -scanbus dev=ATA
cdrecord -scanbus dev=ATAPI
         </screen>

         <para>
            On my development system, I get a result that looks something like
            this for ATA:
         </para>

         <screen>
scsibus1:
        1,0,0   100) 'LITE-ON ' 'DVDRW SOHW-1673S' 'JS02' Removable CD-ROM
        1,1,0   101) *
        1,2,0   102) *
        1,3,0   103) *
        1,4,0   104) *
        1,5,0   105) *
        1,6,0   106) *
        1,7,0   107) *
         </screen>

         <para>
            Again, if you get a result that you recognize, you have again
            probably found a working configuraton.  Place the associated device
            path (in my case, <literal>/dev/cdrom</literal>) into
            &lt;target_device&gt; and put the emulated SCSI id
            (in this case, <literal>ATA:1,0,0</literal>) into &lt;target_scsi_id&gt;.
         </para>

         <para>
            Any further discussion of how to configure your CD writer hardware
            is outside the scope of this document.  If you have tried the hints
            above and still can't get things working, you may want to reference
            the <citetitle>Linux CDROM HOWTO</citetitle> 
            (<ulink url="http://www.tldp.org/HOWTO/CDROM-HOWTO"/>) 
            or the <citetitle>ATA RAID HOWTO</citetitle> 
            (<ulink url="http://www.tldp.org/HOWTO/ATA-RAID-HOWTO/index.html"/>) 
            for more information.
         </para>

      </sect2>

      <sect2>

         <title>Mac OS X Notes</title>

         <para>
            On a Mac OS X (darwin) system, things get strange.  Apple has
            abandoned traditional SCSI device identifiers in favor of a
            system-wide resource id.  So, on a Mac, your writer device will
            have a name something like <literal>IOCompactDiscServices</literal>
            (for a CD writer) or <literal>IODVDServices</literal> (for a DVD
            writer).  If you have multiple drives, the second drive probably
            has a number appended, i.e. <literal>IODVDServices/2</literal> for
            the second DVD writer.  You can try to figure out what the name of
            your device is by grepping through the output of the command
            <command>ioreg -l</command>.<footnote><para>Thanks to the
            file README.macosX in the cdrtools-2.01+01a01 source tree
            for this information</para></footnote>
         </para>

         <para>
            Unfortunately, even if you can figure out what device to use, I
            can't really support the store action on this platform.  In OS X,
            the <quote>automount</quote> function of the Finder interferes
            significantly with Cedar Backup's ability to mount and unmount
            media and write to the CD or DVD hardware.  The Cedar Backup writer
            and image functionality does work on this platform, but the effort
            required to fight the operating system about who owns the media and
            the device makes it nearly impossible to execute the store action
            successfully.
         </para>

      </sect2>

   </sect1>

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

   <sect1 id="cedar-config-blanking">
         
      <title>Optimized Blanking Stategy</title>

      <para>
         When the optimized blanking strategy has not been configured, Cedar
         Backup uses a simplistic approach: rewritable media is blanked at the
         beginning of every week, period.  
      </para>

      <para>
         Since rewritable media can be blanked only a finite number of times
         before becoming unusable, some users &mdash; especially users of
         rewritable DVD media with its large capacity &mdash; may prefer to
         blank the media less often.
      </para>

      <para>
         If the optimized blanking strategy is configured, Cedar Backup will
         use a blanking factor and attempt to determine whether future backups
         will fit on the current media.  If it looks like backups will fit,
         then the media will not be blanked.
      </para>

      <para>
         This feature will only be useful (assuming single disc is used for the
         whole week's backups) if the estimated total size of the weekly backup
         is considerably smaller than the capacity of the media (no more than
         50% of the total media capacity), and only if the size of the backup
         can be expected to remain fairly constant over time (no frequent rapid
         growth expected).
      </para>

      <para>
         There are two blanking modes: daily and weekly.  If the weekly
         blanking mode is set, Cedar Backup will only estimate future capacity
         (and potentially blank the disc) once per week, on the starting day of
         the week.  If the daily blanking mode is set, Cedar Backup will
         estimate future capacity (and potentially blank the disc) every time
         it is run.  <emphasis>You should only use the daily blanking mode in
         conjunction with daily collect configuration, otherwise you will risk
         losing data.</emphasis>
      </para>

      <para>
         If you are using the daily blanking mode, you can typically set the
         blanking value to 1.0.  This will cause Cedar Backup to blank the
         media whenever there is not enough space to store the current day's
         backup.
      </para>

      <para>
         If you are using the weekly blanking mode, then finding the correct
         blanking factor will require some experimentation.  Cedar Backup
         estimates future capacity based on the configured blanking factor.
         The disc will be blanked if the following relationship is true:
      </para>

      <screen>
bytes available / (1 + bytes required) &le; blanking factor
      </screen>

      <para>
         Another way to look at this is to consider the blanking factor as a
         sort of (upper) backup growth estimate:
      </para>

      <screen>
Total size of weekly backup / Full backup size at the start of the week
      </screen>

      <para>
         This ratio can be estimated using a week or two of previous backups.
         For instance, take this example, where March 10 is the start of the
         week and March 4 through March 9 represent the incremental backups
         from the previous week:
      </para>

      <screen>
/opt/backup/staging# du -s 2007/03/*
3040    2007/03/01
3044    2007/03/02
6812    2007/03/03
3044    2007/03/04
3152    2007/03/05
3056    2007/03/06
3060    2007/03/07
3056    2007/03/08
4776    2007/03/09
6812    2007/03/10
11824   2007/03/11
      </screen>

      <para>
         In this case, the ratio is approximately 4:
      </para>

      <screen>
6812 + (3044 + 3152 + 3056 + 3060 + 3056 + 4776) / 6812 = 3.9571
      </screen>

      <para>
         To be safe, you might choose to configure a factor of 5.0.  
      </para>

      <para>
         Setting a higher value reduces the risk of exceeding media capacity
         mid-week but might result in blanking the media more often than is necessary.  
      </para>
         
      <para>
         If you run out of space mid-week, then the solution is to run the
         rebuild action.  If this happens frequently, a higher blanking factor
         value should be used.
      </para>

   </sect1>

</chapter>

