Provided by: cedar-backup3_3.1.6-1_all bug

NAME

       cback3 - Local and remote backups to CD or DVD media or Amazon S3 storage

SYNOPSIS

       cback3 [switches] action(s)

DESCRIPTION

       The  cback3 script provides the command-line interface for Cedar Backup 3.  Cedar Backup 3
       is a software package designed to manage system backups for a pool  of  local  and  remote
       machines.   It  understands how to back up filesystem data as well as MySQL and PostgreSQL
       databases and Subversion repositories.  It can also be easily extended  to  support  other
       kinds of data sources.

       Cedar  Backup  3  is  focused  around  weekly backups to a single CD or DVD disc, with the
       expectation that the disc will be changed or overwritten at the beginning  of  each  week.
       If your hardware is new enough, Cedar Backup can write multisession discs, allowing you to
       add incremental data to a disc on a daily basis.

       Alternately, Cedar Backup 3 can write your backups to the  Amazon  S3  cloud  rather  than
       relying on physical media.

BACKUP CONCEPTS

       There are two kinds of machines in a Cedar Backup pool.  One machine (the master) has a CD
       or DVD writer on it and is where the backup is written  to  disc.   The  others  (clients)
       collect  data  to  be  written to disc by the master.  Collectively, the master and client
       machines in a pool are all referred to as peer machines.  There are four actions that take
       place as part of the backup process: collect, stage, store and purge.  Both the master and
       the clients execute the collect and purge actions, but only the master executes the  stage
       and  store  actions.   The  configuration file /etc/cback3.conf controls the actions taken
       during the collect, stage, store and purge actions.

       Cedar Backup also supports the concept of managed clients.   Managed  clients  have  their
       entire  backup process managed by the master via a remote shell.  The same actions are run
       as part of the backup process, but the master controls when the actions  are  executed  on
       the  clients  rather  than  the  clients  controlling it for themselves.  This facility is
       intended for use in environments where a scheduler like cron is not available.

MIGRATING FROM VERSION 2 TO VERSION 3

       The main difference between Cedar Backup version 2 and  Cedar  Backup  version  3  is  the
       targeted  Python  interpreter.   Cedar  Backup  version 2 was designed for Python 2, while
       version 3 is a conversion of the original  code  to  Python  3.   Other  than  that,  both
       versions  are functionally equivalent.  The configuration format is unchanged, and you can
       mix-and-match masters and clients of different versions in the  same  backup  pool.   Both
       versions  will  be  fully  supported  until around the time of the Python 2 end-of-life in
       2020, but you should plan to migrate sooner than that if possible.

       A major design goal for version 3 was to facilitate easy migration testing for  users,  by
       making  it possible to install version 3 on the same server where version 2 was already in
       use.  A side effect of this design choice is that all of  the  executables,  configuration
       files,  and  logs  changed names in version 3.  Where version 2 used cback, version 3 uses
       cback3: cback3.conf instead of cback.conf, cback3.log instead of cback.log, etc.

       So, while migrating from version 2 to version 3 is relatively  straightforward,  you  will
       have  to make some changes manually.  You will need to create a new configuration file (or
       soft link to the old one), modify your cron jobs to use the new executable name, etc.  You
       can  migrate  one server at a time in your pool with no ill effects, or even incrementally
       migrate a single server by using version 2 and version 3 on different days of the week  or
       for different parts of the backup.

SWITCHES

       -h, --help
              Display usage/help listing.

       -V, --version
              Display version information.

       -b, --verbose
              Print verbose output to the screen as well writing to the logfile. When this option
              is enabled, most information that would normally be written  to  the  logfile  will
              also be written to the screen.

       -q, --quiet
              Run quietly (display no output to the screen).

       -c, --config
              Specify  the  path  to  an alternate configuration file.  The default configuration
              file is /etc/cback3.conf.

       -f, --full
              Perform a full backup, regardless of configuration.  For the collect  action,  this
              means  that any existing information related to incremental backups will be ignored
              and rewritten; for the store action, this means that a new disc will be started.

       -M, --managed
              Include managed clients when executing actions.  If the action  being  executed  is
              listed  as a managed action for a managed client, execute the action on that client
              after executing the action locally.

       -N, --managed-only
              Include only managed clients when executing actions.  If the action being  executed
              is  listed  as  a  managed  action for a managed client, execute the action on that
              client, but do not execute the action locally.

       -l, --logfile
              Specify  the  path  to  an  alternate  logfile.   The  default  logfile   file   is
              /var/log/cback3.log.

       -o, --owner
              Specify  the  ownership  of  the  logfile,  in  the  form  user:group.  The default
              ownership is root:adm, to match the Debian standard for most logfiles.  This  value
              will  only be used when creating a new logfile.  If the logfile already exists when
              the cback3 script is executed, it will retain  its  existing  ownership  and  mode.
              Only user and group names may be used, not numeric uid and gid values.

       -m, --mode
              Specify  the  permissions  for  the logfile, using the numeric mode as in chmod(1).
              The default mode is 640 (-rw-r-----).  This value will only be used when creating a
              new  logfile.  If the logfile already exists when the cback3 script is executed, it
              will retain its existing ownership and mode.

       -O, --output
              Record some sub-command output to the logfile. When this  option  is  enabled,  all
              output  from  system commands will be logged. This might be useful for debugging or
              just for reference.

       -d, --debug
              Write debugging information to the logfile. This option produces a high  volume  of
              output,  and  would  generally only be needed when debugging a problem. This option
              implies the --output option, as well.

       -s, --stack
              Dump a Python stack trace instead of  swallowing  exceptions.   This  forces  Cedar
              Backup  to dump the entire Python stack trace associated with an error, rather than
              just progating last message it received back up to the user interface.  Under  some
              circumstances, this is useful information to include along with a bug report.

       -D, --diagnostics
              Display  runtime diagnostic information and then exit.  This diagnostic information
              is often useful when filing a bug report.

ACTIONS

       all    Take all normal actions (collect, stage, store, purge), in that order.

       collect
              Take the collect action, creating tarfiles for  each  directory  specified  in  the
              collect section of the configuration file.

       stage  Take  the  stage  action, copying tarfiles from each peer in the backup pool to the
              daily staging directory, based on the stage section of the configuration file.

       store  Take the store action, writing the daily staging directory to  disc  based  on  the
              store section of the configuration file.

       purge  Take  the  purge  action, removing old and outdated files as specified in the purge
              section of the configuration file.

       rebuild
              The rebuild action attempts to  rebuild  "this  week's"  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.

       validate
              Ensure  that  configuration  is valid, but take no other action.  Validation checks
              that the configuration file can be found and can be parsed,  and  also  checks  for
              typical  configuration  problems,  such  as  directories  that  are not writable or
              problems with the target SCSI device.

RETURN VALUES

       Cedar Backup returns 0 (zero) upon normal completion, and six other error codes related to
       particular errors.

       1      The Python interpreter version is < 3.4.

       2      Error processing command-line arguments.

       3      Error configuring logging.

       4      Error parsing indicated configuration file.

       5      Backup was interrupted with a CTRL-C or similar.

       6      Error executing specified backup actions.

NOTES

       The  script  is  designed to run as root, since otherwise it's difficult to back up system
       directories or write the CD or DVD device.  However, pains are taken to switch to a backup
       user (specified in configuration) when appropriate.

       To  use  the  script,  you must specify at least one action to take.  More than one of the
       "collect", "stage", "store" or "purge" actions may be specified, in any  arbitrary  order.
       The  "all",  "rebuild"  or  "validate" actions may not be combined with other actions.  If
       more than one action is specified,  then  actions  will  be  taken  in  a  sensible  order
       (generally collect, followed by stage, followed by store, followed by purge).

       If you have configured any Cedar Backup extensions, then the actions associated with those
       extensions may also be specified on the command line. If you  specify  any  other  actions
       along  with  an  extended  action,  the  actions  will be executed in a sensible order per
       configuration. However, the "all" action never executes extended actions.

       Note that there is no facility for restoring backups.  It is assumed  that  the  user  can
       deal  with  copying  tarfiles  off disc and using them to restore missing files as needed.
       The user manual provides detailed intructions in Appendix C.

       Finally, you should be aware that backups to CD or DVD can probably be read  by  any  user
       which  has  permissions  to  mount the CD or DVD drive.  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.  You might also want to investigate the encrypt extension.

FILES

       /etc/cback3.conf - Default configuration file

       /var/log/cback3.log - Default log file

URLS

       The project homepage is: https://bitbucket.org/cedarsolutions/cedar-backup3

BUGS

       There  probably  are  bugs in this code.  However, it is in active use for my own backups,
       and I fix problems as I notice them.  If you find a bug, please report it.

       If possible, give me the output from --diagnostics, all of the  error  messages  that  the
       script  printed  into its log, and also any stack-traces (exceptions) that Python printed.
       It would be even better if you could tell me how to reproduce the problem, for instance by
       sending me your configuration file.

       Report bugs to <support@cedar-solutions.com> or by using the BitBucket issue tracker.

AUTHOR

       Written and maintained by Kenneth J. Pronovici <pronovic@ieee.org> with contributions from
       others.

COPYRIGHT

       Copyright (c) 2004-2011,2013-2015 Kenneth J. Pronovici.

       This is free software; see the source for copying conditions.  There is NO  warranty;  not
       even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.