Provided by: cedar-backup3_3.1.6-1_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 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.