Provided by: cedar-backup3_3.2.0-2_all 
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
instructions 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://github.com/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 via GitHub issues tracker.
AUTHOR
Written and maintained by Kenneth J. Pronovici <pronovic@ieee.org> with contributions from others.
COPYRIGHT
Copyright (c) 2004-2011,2013-2017,2019 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.