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

<chapter id="cedar-basic">

   <title>Basic Concepts</title>

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

   <sect1 id="cedar-basic-general">

      <title>General Architecture</title>

      <para>
         Cedar Backup is architected as a Python package (library) and a single
         executable (a Python script).  The Python package provides both
         application-specific code and general utilities that can be used by
         programs other than Cedar Backup.  It also includes modules that can
         be used by third parties to extend Cedar Backup or provide related
         functionality.
      </para>

      <para>
         The <command>cback3</command> script is designed to run as root, since
         otherwise it's difficult to back up system directories or write to the
         CD/DVD device.  However, pains are taken to use the backup user's
         effective user id (specified in configuration) when appropriate.
         Note: this does not mean that <command>cback3</command> runs
         <firstterm>setuid</firstterm><footnote><para>See <ulink
         url="http://en.wikipedia.org/wiki/Setuid"/></para></footnote> or
         <firstterm>setgid</firstterm>.  However, all files on disk will be
         owned by the backup user, and and all rsh-based network connections
         will take place as the backup user.
      </para>

      <para>
         The <command>cback3</command> script is configured via command-line
         options and an XML configuration file on disk.  The configuration file
         is normally stored in <filename>/etc/cback3.conf</filename>, but this
         path can be overridden at runtime.   See <xref linkend="cedar-config"/>
         for more information on how Cedar Backup is configured.
      </para>

      <warning>
         <para>
            You should be aware that backups to CD/DVD media can probably be read
            by any user which has permissions to mount the CD/DVD writer.  If you
            intend to leave the backup disc in the drive at all times, you may
            want to consider this when setting up device permissions on your
            machine.  See also <xref linkend="cedar-extensions-encrypt"/>.
         </para>
      </warning>

   </sect1>


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

   <sect1 id="cedar-basic-datarecovery">

      <title>Data Recovery</title>

      <para>
         Cedar Backup does not include any facility to restore backups.
         Instead, it assumes that the administrator (using the procedures
         and references in <xref linkend="cedar-recovering"/>) can handle the task of
         restoring their own system, using the standard system tools at hand.
      </para>

      <para>
         If I were to maintain recovery code in Cedar Backup, I would almost
         certainly end up in one of two situations.  Either Cedar Backup would
         only support simple recovery tasks, and those via an interface a lot
         like that of the underlying system tools; or Cedar Backup would have
         to include a hugely complicated interface to support more specialized
         (and hence useful) recovery tasks like restoring individual files as
         of a certain point in time.  In either case, I would end up trying to
         maintain critical functionality that would be rarely used, and hence
         would also be rarely tested by end-users.  I am uncomfortable asking
         anyone to rely on functionality that falls into this category.
      </para>

      <para>
         My primary goal is to keep the Cedar Backup codebase as simple and
         focused as possible.  I hope you can understand how the choice of
         providing documentation, but not code, seems to strike the best
         balance between managing code complexity and providing the
         functionality that end-users need.  
      </para>
         
   </sect1>


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

   <sect1 id="cedar-basic-pools">

      <title>Cedar Backup Pools</title>

      <para>
         There are two kinds of machines in a Cedar Backup pool.  One machine
         (the <firstterm>master</firstterm>) has a CD or DVD writer on it
         and writes the backup to disc.  The others
         (<firstterm>clients</firstterm>) collect data to be written to disc by
         the master.  Collectively, the master and client machines in a pool
         are called <firstterm>peer machines</firstterm>. 
      </para>

      <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) and in fact more users seem to use it like this
         than any other way.
      </para>

   </sect1>

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

   <sect1 id="cedar-basic-process">

      <title>The Backup Process</title>

      <para>
         The Cedar Backup backup process is structured in terms of a set of
         decoupled actions which execute independently (based on a schedule in
         <command>cron</command>) rather than through some highly coordinated
         flow of control.  
      </para>
         
      <para>
         This design decision has both positive and negative consequences.  On
         the one hand, the code is much simpler and can choose to simply abort
         or log an error if its expectations are not met.  On the other hand,
         the administrator must coordinate the various actions during initial
         set-up.  See <xref linkend="cedar-basic-coordinate"/> (later in this
         chapter) for more information on this subject.
      </para>

      <para>
         A standard backup run consists of four steps (actions), some of which
         execute on the master machine, and some of which execute on one or
         more client machines.  These actions are:
         <firstterm>collect</firstterm>, <firstterm>stage</firstterm>,
         <firstterm>store</firstterm> and <firstterm>purge</firstterm>.
      </para>

      <para>
         In general, more than one action may be specified on the command-line.
         If more than one action is specified, then actions will be taken in a
         sensible order (generally collect, stage, store, purge).   A special
         <firstterm>all</firstterm> action is also allowed, which implies all
         of the standard actions in the same sensible order.
      </para>

      <para>
         The <command>cback3</command> command also supports several actions
         that are not part of the standard backup run and cannot be executed
         along with any other actions.  These actions are
         <firstterm>validate</firstterm>, <firstterm>initialize</firstterm> and
         <firstterm>rebuild</firstterm>.  All of the various actions are
         discussed further below.
      </para>

      <para>
         See <xref linkend="cedar-config"/> for more information on how a
         backup run is configured.
      </para>

      <sidebar>

         <title>Flexibility</title>

         <para>
            Cedar Backup was designed to be flexible.  It allows you to decide
            for yourself which backup steps you care about executing (and when
            you execute them), based on your own situation and your own
            priorities.
         </para>
            
         <para>
            As an example, I always back up every machine I own.  I typically
            keep 7-10 days of staging directories around, but switch CD/DVD media
            mostly every week.  That way, I can periodically take a disc
            off-site in case the machine gets stolen or damaged.  
         </para>
            
         <para>
            If you're not worried about these risks, then there's no need to
            write to disc.  In fact, some users prefer to use their master
            machine as a simple <quote>consolidation point</quote>.  They don't
            back up any data on the master, and don't write to disc at all.
            They just use Cedar Backup to handle the mechanics of moving
            backed-up data to a central location.  This isn't quite what Cedar
            Backup was written to do, but it is flexible enough to meet their
            needs.
         </para>

      </sidebar>

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

      <sect2 id="cedar-basic-process-collect">
         
         <title>The Collect Action</title>

         <para>
            The collect action is the first action in a standard backup run.
            It executes on both master and client nodes.  Based on configuration,
            this action traverses the peer's filesystem and gathers files to be
            backed up.  Each configured high-level directory is collected up
            into its own <command>tar</command> file in the <firstterm>collect
            directory</firstterm>.   The tarfiles can either be uncompressed
            (<filename>.tar</filename>) or compressed with either
            <command>gzip</command> (<filename>.tar.gz</filename>) or
            <command>bzip2</command> (<filename>.tar.bz2</filename>).
         </para>

         <para>
            There are three supported collect modes:
            <firstterm>daily</firstterm>, <firstterm>weekly</firstterm> and
            <firstterm>incremental</firstterm>.  Directories configured for
            daily backups are backed up every day.  Directories configured for
            weekly backups are backed up on the first day of the week.
            Directories configured for incremental backups are traversed every
            day, but only the files which have changed (based on a saved-off
            <firstterm>SHA hash</firstterm>) are actually backed up.
         </para>
            
         <para>
            Collect configuration also allows for a variety of ways to filter
            files and directories out of the backup.  For instance,
            administrators can configure an <firstterm>ignore indicator
            file</firstterm> 
            <footnote><para>Analagous to <filename>.cvsignore</filename> in CVS</para></footnote> 
            or specify absolute paths or filename patterns 
            <footnote><para>In terms of Python regular expressions</para></footnote>
            to be excluded.  You can even configure a backup <quote>link
            farm</quote> rather than explicitly listing files and directories
            in configuration.
         </para>
            
         <para>
            This action is optional on the master.  You only need to configure
            and execute the collect action on the master if you have data to
            back up on that machine.  If you plan to use the master only as a
            <quote>consolidation point</quote> to collect data from other
            machines, then there is no need to execute the collect action
            there.  If you run the collect action on the master, it behaves the
            same there as anywhere else, and you have to stage the master's
            collected data just like any other client (typically by configuring
            a local peer in the stage action).
         </para>

      </sect2>

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

      <sect2 id="cedar-basic-process-stage">
         
         <title>The Stage Action</title>

         <para>
            The stage action is the second action in a standard backup run.  It
            executes on the master peer node.  The master works down the list of
            peers in its backup pool and stages (copies) the collected backup
            files from each of them into a daily staging directory by peer
            name.
         </para>

         <para>
            For the purposes of this action, the master node can be configured
            to treat itself as a client node.  If you intend to back up data on
            the master, configure the master as a local peer.  Otherwise, just
            configure each of the clients as a remote peer.
         </para>

         <para> 
            Local and remote client peers are treated differently.  Local peer
            collect directories are assumed to be accessible via normal copy
            commands (i.e. on a mounted filesystem) while remote peer collect
            directories are accessed via an <firstterm>RSH-compatible</firstterm>
            command such as <command>ssh</command>.
         </para>

         <para>
            If a given peer is not ready to be staged, the stage process will
            log an error, abort the backup for that peer, and then move on to
            its other peers.  This way, one broken peer cannot break a backup
            for other peers which are up and running.
         </para>

         <para>
            Keep in mind that Cedar Backup is flexible about what actions must
            be executed as part of a backup.  If you would prefer, you can stop
            the backup process at this step, and skip the store step.  In this
            case, the staged directories will represent your backup rather than
            a disc.
         </para>

         <note>
            <para>
               Directories <quote>collected</quote> by another process can be
               staged by Cedar Backup.  If the file
               <filename>cback.collect</filename> exists in a collect directory
               when the stage action is taken, then that directory will be
               staged.
            </para>
         </note>

      </sect2>

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

      <sect2 id="cedar-basic-process-store">
         
         <title>The Store Action</title>

         <para>
            The store action is the third action in a standard backup run.  It
            executes on the master peer node.  The master machine determines the
            location of the current staging directory, and then writes the
            contents of that staging directory to disc.  After the contents of
            the directory have been written to disc, an optional validation
            step ensures that the write was successful.
         </para>

         <para>
            If the backup is running on the first day of the week, if the drive
            does not support multisession discs, or if the
            <option>--full</option> option is passed to the
            <command>cback3</command> command, the disc will be rebuilt from
            scratch.   Otherwise, a new ISO session will be added to the disc
            each day the backup runs.  
         </para>

         <para>
            This action is entirely optional.  If you would prefer to just
            stage backup data from a set of peers to a master machine, and have
            the staged directories represent your backup rather than a disc,
            this is fine. 
         </para>

         <warning>
            <para>
               The store action is not supported on the Mac OS X (darwin)
               platform.  On that platform, 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 works 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>
         </warning>

         <sidebar>
            <title>Current Staging Directory</title>

            <para>
               The store action tries to be smart about finding the current
               staging directory.  It first checks the current day's staging
               directory.  If that directory exists, and it has not yet been
               written to disc (i.e. there is no store indicator), then it will
               be used.  Otherwise, the store action will look for an unused
               staging directory for either the previous day or the next day,
               in that order.  A warning will be written to the log under 
               these circumstances (controlled by the &lt;warn_midnite&gt;
               configuration value).
            </para>

            <para>
               This behavior varies slightly when the <option>--full</option>
               option is in effect.  Under these circumstances, any existing
               store indicator will be ignored.  Also, the store action will
               always attempt to use the current day's staging directory,
               ignoring any staging directories for the previous day or the
               next day.  This way, running a full store action more than once
               concurrently will always produce the same results.  (You might
               imagine a use case where a person wants to make several copies
               of the same full backup.)
            </para>
         </sidebar>
         
      </sect2>

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

      <sect2 id="cedar-basic-process-purge">
         
         <title>The Purge Action</title>

         <para>
            The purge action is the fourth and final action in a standard
            backup run.  It executes both on the master and client peer nodes.
            Configuration specifies how long to retain files in certain
            directories, and older files and empty directories are purged.
         </para>

         <para>
            Typically, collect directories are purged daily, and stage
            directories are purged weekly or slightly less often (if a disc
            gets corrupted, older backups may still be available on the
            master).  Some users also choose to purge the configured working
            directory (which is used for temporary files) to eliminate any
            leftover files which might have resulted from changes to
            configuration.
         </para>

      </sect2>

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

      <sect2 id="cedar-basic-process-all">
         
         <title>The All Action</title>

         <para>
            The all action is a pseudo-action which causes all of the actions
            in a standard backup run to be executed together in order.  It
            cannot be combined with any other actions on the command line.
         </para>

         <para>
            Extensions <emphasis>cannot</emphasis> be executed as part of the
            all action.  If you need to execute an extended action, you must
            specify the other actions you want to run individually on the
            command line.  <footnote><para>Some users find this surprising,
            because extensions are configured with sequence numbers.  I did it
            this way because I felt that running extensions as part of the all
            action would sometimes result in surprising behavior.  I am not
            planning to change the way this works.</para></footnote>
         </para>

         <para>
            The all action does not have its own configuration.  Instead, it
            relies on the individual configuration sections for all of the
            other actions.  
         </para>

      </sect2>

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

      <sect2 id="cedar-basic-process-validate">
         
         <title>The Validate Action</title>

         <para>
            The validate action is used to validate configuration
            on a particular peer node, either master or client.   It cannot be
            combined with any other actions on the command line.
         </para>

         <para>
            The validate action checks that the configuration file can be
            found, that the configuration file is valid, and that certain
            portions of the configuration file make sense (for instance, making
            sure that specified users exist, directories are readable and
            writable as necessary, etc.).
         </para>

      </sect2>

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

      <sect2 id="cedar-basic-process-initialize">
         
         <title>The Initialize Action</title>

         <para>
            The initialize action is used to initialize media for use with
            Cedar Backup.  This is an optional step.  By default, Cedar Backup
            does not need to use initialized media and will write to whatever
            media exists in the writer device.  
         </para>
            
         <para>
            However, if the <quote>check media</quote> store configuration
            option is set to true, Cedar Backup will check the media before
            writing to it and will error out if the media has not been
            initialized. 
         </para>

         <para>
            Initializing the media consists of writing a mostly-empty image
            using a known media label (the media label will begin with
            <quote>CEDAR BACKUP</quote>).
         </para>

         <para>
            Note that only rewritable media (CD-RW, DVD+RW) can be initialized.
            It doesn't make any sense to initialize media that cannot be
            rewritten (CD-R, DVD+R), since Cedar Backup would then not be able
            to use that media for a backup.  You can still configure Cedar
            Backup to check non-rewritable media; in this case, the check will
            also pass if the media is apparently unused (i.e. has no media
            label).
         </para>

      </sect2>

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

      <sect2 id="cedar-basic-process-rebuild">
         
         <title>The Rebuild Action</title>

         <para>
            The rebuild action is an exception-handling action that is executed
            independent of a standard backup run.  It cannot be combined with
            any other actions on the command line.
         </para>

         <para>
            The rebuild action attempts to rebuild <quote>this week's</quote>
            disc from any remaining unpurged staging directories.  Typically,
            it is used to make a copy of a backup, replace lost or damaged
            media, or to switch to new media mid-week for some other reason.
         </para>

         <para>
            To decide what data to write to disc again, the rebuild action
            looks back and finds the first day of the current week.  Then, it finds
            any remaining staging directories between that date and the current
            date.  If any staging directories are found, they are all written
            to disc in one big ISO session.
         </para>

         <para>
            The rebuild action does not have its own configuration.  It relies
            on configuration for other other actions, especially the store
            action.
         </para>

      </sect2>

   </sect1>

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

   <sect1 id="cedar-basic-coordinate">

      <title>Coordination between Master and Clients</title>

      <para>
         Unless you are using Cedar Backup to manage a <quote>pool of
         one</quote>, you will need to set up some coordination between your
         clients and master to make everything work properly.  This
         coordination isn't difficult &mdash; it mostly consists of making sure
         that operations happen in the right order &mdash; but some users are
         suprised that it is required and want to know why Cedar Backup can't
         just <quote>take care of it for me</quote>.
      </para>
       
      <para>
         Essentially, each client must finish collecting all of its data before
         the master begins staging it, and the master must finish staging data
         from a client before that client purges its collected data.
         Administrators may need to experiment with the time between the
         collect and purge entries so that the master has enough time to stage
         data before it is purged.
      </para>

   </sect1>

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

   <sect1 id="cedar-basic-managedbackups">

      <title>Managed Backups</title>

      <para>
         Cedar Backup also supports an optional feature called the
         <quote>managed backup</quote>.  This feature is intended for use with
         remote clients where cron is not available.
      </para>

      <para>
         When managed backups are enabled, managed clients must still be
         configured as usual.  However, rather than using a cron job on the
         client to execute the collect and purge actions, the master executes
         these actions on the client via a remote shell.  
      </para>

      <para>
         To make this happen, first set up one or more managed clients in Cedar
         Backup configuration.  Then, invoke Cedar Backup with the
         <command>--managed</command> command-line option.  Whenever Cedar
         Backup invokes an action locally, it will invoke the same action on
         each of the managed clients.
      </para>

      <para>
         Technically, this feature works for any client, not just clients that
         don't have cron available.  Used this way, it can simplify the setup
         process, because cron only has to be configured on the master.  For
         some users, that may be motivation enough to use this feature all of
         the time.
      </para>

      <para>
         However, please keep in mind that this feature depends on a stable
         network.  If your network connection drops, your backup will be
         interrupted and will not be complete.  It is even possible that some
         of the Cedar Backup metadata (like incremental backup state) will be
         corrupted.  The risk is not high, but it is something you need to be
         aware of if you choose to use this optional feature.
      </para>

   </sect1>


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

   <sect1 id="cedar-basic-mediadevice">

      <title>Media and Device Types</title>

      <para>
         Cedar Backup is focused around writing backups to CD or DVD media
         using a standard SCSI or IDE writer.  In Cedar Backup terms, the
         disc itself is referred to as the <firstterm>media</firstterm>, and
         the CD/DVD drive is referred to as the <firstterm>device</firstterm> 
         or sometimes the <firstterm>backup device</firstterm>.
         <footnote><para>My original backup device was an old
         Sony CRX140E 4X CD-RW drive.  It has since died, and I currently
         develop using a Lite-On 1673S DVD&plusmn;RW drive.</para> </footnote>
      </para>

      <para>
         When using a new enough backup device, a new
         <quote>multisession</quote> ISO image <footnote><para>An
         <firstterm>ISO image</firstterm> is the standard way of creating a
         filesystem to be copied to a CD or DVD.  It is essentially a
         <quote>filesystem-within-a-file</quote> and many UNIX operating
         systems can actually mount ISO image files just like hard drives,
         floppy disks or actual CDs.  See Wikipedia for more information:
         <ulink url="http://en.wikipedia.org/wiki/ISO_image"/>.</para></footnote> 
         is written to the media on the first day of the week, and then
         additional multisession images are added to the media each day that
         Cedar Backup runs.  This way, the media is complete and usable at the
         end of every backup run, but a single disc can be used all week long.
         If your backup device does not support multisession images &mdash; which is
         really unusual today &mdash; then a new ISO image will be written to the
         media each time Cedar Backup runs (and you should probably confine
         yourself to the <quote>daily</quote> backup mode to avoid losing
         data).
      </para>

      <para>
         Cedar Backup currently supports four different kinds of CD media:
      </para>

      <variablelist>

         <varlistentry>
            <term>cdr-74</term>
            <listitem>
               <para>74-minute non-rewritable CD media</para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term>cdrw-74</term>
            <listitem>
               <para>74-minute rewritable CD media</para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term>cdr-80</term>
            <listitem>
               <para>80-minute non-rewritable CD media</para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term>cdrw-80</term>
            <listitem>
               <para>80-minute rewritable CD media</para>
            </listitem>
         </varlistentry>

      </variablelist>

      <para>
         I have chosen to support just these four types of CD media because
         they seem to be the most <quote>standard</quote> of the various types
         commonly sold in the U.S. as of this writing (early 2005).  If you
         regularly use an unsupported media type and would like Cedar Backup to
         support it, send me information about the capacity of the media in
         megabytes (MB) and whether it is rewritable.  
      </para>

      <para>
         Cedar Backup also supports two kinds of DVD media:
      </para>

      <variablelist>

         <varlistentry>
            <term>dvd+r</term>
            <listitem>
               <para>Single-layer non-rewritable DVD+R media</para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <term>dvd+rw</term>
            <listitem>
               <para>Single-layer rewritable DVD+RW media</para>
            </listitem>
         </varlistentry>

      </variablelist>

      <para>
         The underlying <command>growisofs</command> utility does support other
         kinds of media (including DVD-R, DVD-RW and BlueRay) which work
         somewhat differently than standard DVD+R and DVD+RW media.  I don't
         support these other kinds of media because I haven't had any
         opportunity to work with them.  The same goes for dual-layer media of
         any type.
      </para>

   </sect1>

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

   <sect1 id="cedar-basic-incremental">

      <title>Incremental Backups</title>

      <para>
         Cedar Backup supports three different kinds of backups for individual
         collect directories.  These are <firstterm>daily</firstterm>,
         <firstterm>weekly</firstterm> and <firstterm>incremental</firstterm>
         backups.  Directories using the daily mode are backed up every day.
         Directories using the weekly mode are only backed up on the first day
         of the week, or when the <option>--full</option> option is used.
         Directories using the incremental mode are always backed up on the
         first day of the week (like a weekly backup), but after that only the
         files which have changed are actually backed up on a daily basis.
      </para>

      <para>
         In Cedar Backup, incremental backups are not based on date, but are
         instead based on saved checksums, one for each backed-up file.
         When a full backup is run, Cedar Backup gathers a checksum value
         <footnote><para>The checksum is actually an <firstterm>SHA
         cryptographic hash</firstterm>.  See Wikipedia for more information:
         <ulink url="http://en.wikipedia.org/wiki/SHA-1"/>.</para></footnote> 
         for each backed-up file.  The next time an incremental backup is run,
         Cedar Backup checks its list of file/checksum pairs for each file that
         might be backed up.  If the file's checksum value does not
         match the saved value, or if the file does not appear in the list
         of file/checksum pairs, then it will be backed up and a new checksum
         value will be placed into the list.  Otherwise, the file will be
         ignored and the checksum value will be left unchanged.
      </para>

      <para>
         Cedar Backup stores the file/checksum pairs in
         <filename>.sha</filename> files in its working directory, one file per
         configured collect directory.  The mappings in these files are reset
         at the start of the week or when the <option>--full</option> option is
         used.  Because these files are used for an entire week, you should
         never purge the working directory more frequently than once per week.
      </para>

   </sect1>

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

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

      <title>Extensions</title>

      <para>
         Imagine that there is a third party developer who understands how to
         back up a certain kind of database repository.  This third party
         might want to integrate his or her specialized backup into the Cedar
         Backup process, perhaps thinking of the database backup as a sort of
         <quote>collect</quote> step.
      </para>

      <para>
         Prior to Cedar Backup version 2, any such integration would have been
         completely independent of Cedar Backup itself.  The
         <quote>external</quote> backup functionality would have had to
         maintain its own configuration and would not have had access to any
         Cedar Backup configuration.
      </para>

      <para>
         Starting with version 2, Cedar Backup allows
         <firstterm>extensions</firstterm> to the backup process.   An
         extension is an action that isn't part of the standard backup process
         (i.e. not collect, stage, store or purge), but can be executed by Cedar
         Backup when properly configured.
      </para>

      <para>
         Extension authors implement an <quote>action process</quote> function
         with a certain interface, and are allowed to add their own sections to
         the Cedar Backup configuration file, so that all backup configuration
         can be centralized.  Then, the action process function is associated
         with an action name which can be executed from the
         <command>cback3</command> command line like any other action.
      </para>

      <para>
         Hopefully, as the Cedar Backup user community grows, users will
         contribute their own extensions back to the community.  Well-written
         general-purpose extensions will be accepted into the official
         codebase.
      </para>

      <note>
         <para>
            Users should see <xref linkend="cedar-config"/> for more
            information on how extensions are configured, and <xref
            linkend="cedar-extensions"/> for details on all of the
            officially-supported extensions.  
         </para>
            
         <para>
            Developers may be interested in <xref linkend="cedar-extenspec"/>.
         </para>
      </note>

   </sect1>

</chapter>

