NAME
cback - Local and remote backups to CD-R/CD-RW media
SYNOPSIS
cback [switches] action(s)
DESCRIPTION
The cback script provides the command-line interface for Cedar Backup.
Cedar Backup is a software package designed to manage system backups
for a pool of local and remote machines. Cedar Backup 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 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.
There are two kinds of machines in a Cedar Backup pool. One machine
(the master) has a CD-R or CD-RW drive 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/cback.conf controls the actions taken during
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.
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/cback.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/cback.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 cback
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 cback 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. Cedar
Backup uses system commands mostly for dealing with the CD
recorder and its media.
-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.
-s, --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
Rebuild the "this week’s" disc based on the current contents of
the staging directory. This option has been made available as a
means to recover a disc that has been "trashed" due to a
hardware or media error.
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 < 2.3.
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. The
"all" action never executes extended actions, however.
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/cback.conf - Default configuration file
/var/log/cback.log - Default log file
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 (i.e. by sending me your configuration file).
Report bugs to <support@cedar-solutions.com>.
AUTHOR
Written by Kenneth J. Pronovici <pronovic@ieee.org>.
COPYRIGHT
Copyright (c) 2004-2008 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.