cback3(1)

cback3 💅

okay bestie, sit down, hydrate, because this is the manual page for cback3 — that's section 1 of the manual, written by Kenneth J. Pronovici — and she is not a small page. Local and remote backups to CD or DVD media or Amazon S3 storage. No cap. Let's go 🎀

---

NAME ✨

cback3 — Local and remote backups to CD or DVD media or Amazon S3 storage. 🦋

---

SYNOPSIS 🌸

cback3 [switches] action(s)

---

DESCRIPTION 💖

The cback3 script is literally the command-line interface for Cedar Backup 3. And Cedar Backup 3? It's a whole software package built to manage system backups for a pool of local and remote machines. She understands how to back up filesystem data, and also MySQL and PostgreSQL databases, and Subversion repositories too. And if you want more? She can be extended pretty easily to support other kinds of data sources. Versatile queen. 👑

Cedar Backup 3 is focused around weekly backups to a single CD or DVD disc, with the expectation that the disc gets changed or overwritten at the beginning of each week. Very "new week, new me" energy. And if your hardware is new enough, Cedar Backup can write multisession discs, which means you can add incremental data to a disc on a daily basis. Slay.

Alternately — because options are everything — Cedar Backup 3 can write your backups to the Amazon S3 cloud rather than relying on physical media. Cloud girlies rise. ☁️

---

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 it's where the backup gets written to disc.
• The others, the 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. Group chat, basically. 🫶

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.
• 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. Same actions run as part of the backup process, but here's the plot twist: 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. Main character master energy fr fr. 💅

---

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. 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 — this is the good part — 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. Not me pretending it's zero effort, bestie. 😭 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. Do it at your own pace, no rush. 🐢

---

SWITCHES 🎛️

These are the flags, bestie. Every single one. Don't skip, they all matter. 💖

• -h, --help — Display usage/help listing.
• -V, --version — Display version information.
• -b, --verbose — Print verbose output to the screen as well as 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. She's chatty and she's proud. 🗣️
• -q, --quiet — Run quietly (display no output to the screen). Shy girlie. 🤫
• -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. Clean slate, periodt. ✨
• -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. ⚠️ names only, bestie, no digits.
• -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. Receipts. 🧾
• -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. It's giving unhinged journaling but make it diagnostics. 💀
• -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 propagating 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. Glow-up for your disc. 💅
• 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. Vibe check on your config. 🔍

---

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 not supported.
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.

So like, if you get a 1 through 6 back, that's your answer. No mystery, bestie. 🔥

---

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. Respectful of boundaries, we love to see it. 🫶

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/pronovic/cedar-backup3

---

okay wait, that's not even the whole page, bestie — there's more coming. don't go anywhere 💜

🐛 BUGS 🐛

okay bestie, real talk: there probably are bugs in this code. like, no software is perfect and this one is not out here pretending 💀

but here's the thing — it is in active use for my own backups, so it's not some abandoned vibe. the maintainer fixes problems as they notice them. we stay on top of it ✨

so if you find a bug, please report it. don't just suffer in silence, that's not the move 🫶

---

📮 how to report it (do this, it helps SO much)

if possible, hand over:

• the output from --diagnostics
• all of the error messages that the script printed into its log
• 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 the GitHub issues tracker.

---

👑 AUTHOR 👑

written and maintained by Kenneth J. Pronovici <pronovic@ieee.org> with contributions from others. iconic behavior honestly, the community said "we ride together" 🤝

---

🎀 COPYRIGHT 🎀

Copyright (c) 2004-2020 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. ⚠️

like, literally none. zero. ngl that's just how free software works bestie, take it as-is 💅

---

okay and that's the whole page!! 🌈 thank you for coming to my ted talk.

this is Cedar Backup 3, dated Aug 2019, and the page you're reading is cback3(1) — part of the section 1 manuals, the command-y ones 🦋

go forth and back up your stuff, bestie. your future self is obsessed with you for it 💖✨