rsbackup(1)

📦
version 10.0 · 3 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

rsbackup(1) — General Commands Manual 🎀

okay bestie, sit down, we're learning rsbackup and honestly? it's giving organized-queen energy. let's go 💅

✨ NAME ✨

rsbackup — rsync-based backup utility 🦋

🌸 SYNOPSIS 🌸

rsbackup [OPTIONS] [--] [SELECTOR...]
rsbackup --retire [OPTIONS] [--] [SELECTOR...]
rsbackup --retire-device [OPTIONS] [--] DEVICE...

💖 DESCRIPTION 💖

So rsbackup backs up files from one or more (remote) destinations into a single backup storage directory, and it preserves their contents, layout, ownership, permissions, timestamps and hardlink structure. like, all of it. it does not play games. 👑

Incremental backups? achieved by hard-linking identical files within successive backups of the same files. that's the whole trick and it's iconic fr fr. ✨

head over to rsbackup(5) for the details of the configuration file — that's a whole other page, bestie.

💅 OPTIONS 💅

🎯 Action Options

at least one of these has to be specified, okay? and when you give multiple actions, they run in the order shown below. no queue-jumping. 🙅
  • --backup, -b — make a backup of the selected volumes. at most one backup of a given volume will be made per day — that's it, that's the limit, don't push it.
  • --retire-device — retire the named devices. and retiring a device only means deleting the records of it. the files on the device itself are not touched. not one of them. ✋

if the device is still listed in the configuration file, you'll be asked whether you really want to retire it. you can suppress this check with the --force option.

  • --retire — retire the named hosts and volumes. retiring a volume means deleting any available backups for the volume and the records of them. records corresponding to backups on unavailable devices are not removed.

if you just want to remove backup records for retired volumes but keep the backups themselves, also use the --forget-only option (peep below 👇).

since this command deletes backups, you will be prompted to confirm it. you can suppress this check with the --force option.

  • --forget-only — with --retire, this suppresses deletion of backups, and instead just drops the database records for the hosts and volumes affected. records gone, backups safe. best of both worlds honestly. 💖
  • --prune, -p — prune old backups of selected volumes. see rsbackup(5) for details on how pruning is controlled.
  • --prune-incomplete,-P — prune incomplete backups of selected volumes. any backups that failed before completion will be removed. bye bestie 👋
  • --html PATH, -H PATH — write an HTML report to PATH. the report covers all volumes, not just the selected ones. PATH can be - to write to standard output.
  • --text PATH, -T PATH — write a plain text report to PATH. again, it covers all volumes, not just selected ones. PATH can be - to write to standard output.
  • --email ADDRESS, -e ADDRESS — email a report to ADDRESS. the contents is equivalent to the output of --text and --html.
  • --check-unexpected — list unexpected files on backup devices to standard output. must not be combined with any other action option.
heads up: this option does not verify that the backups are good. it just detects unexpected files on currently-mounted backup devices. don't get it twisted. 🙈
  • --latest — prints out the path to the latest complete backup for each selected volume.
  • --dump-config — writes the parsed configuration file to standard output. must not be combined with any other action option.

with --verbose, the configuration file is annotated with descriptive comments. cute and informative. ✨

🛠️ General Options

  • --config PATH, -c PATH — the path to the configuration file. the default is /etc/rsbackup/config.
  • --store PATH, -s PATH — specify the destination directory to back up to. using this option (possibly more than once) is equivalent to removing the store directives from the configuration file and replacing them with the paths give in --store options.

this option implicitly enables the --warn-store option.

  • --unmounted-store PATH — equivalent to --store except that the store does not have to be a mount point.
  • --verbose, -v — enable verbose mode. various messages will be displayed to report progress and the rsync --quiet option is suppressed.
  • --dry-run, -n — enable dry-run mode. commands will be displayed but nothing will actually be done. it's the rehearsal, not the show. 🎭
  • --force, -f — suppress checks made when retiring devices and volumes, and overrides backup policies.
  • --null, -0 — for the --check-unexpected option, terminate filenames with a null, rather than newline.
  • --wait, -w — waits rather than giving up if another copy of rsbackup is running.
  • --database, -D PATH — override the path to the backup database.
  • --help, -h — display a usage message.
  • --version, -V — display the version number.

📢 Report Verbosity

  • --logs VERBOSITY — controls which logfiles for a given volume/device pair to include in the report. the possible values of VERBOSITY are:
    • all — includes all nonempty logfiles, even if the backup succeeded.
    • errors — includes all error logfiles.
    • recent — includes only the most recent error logfile.
    • latest — includes only the latest logfile, even if the backup succeeded.
    • failed — includes only the most recent logfile but only if that attempt failed. this is the default.

🚨 Warning Options

  • --warn-unknown — display warnings for unknown devices, hosts and volumes. (warnings will always be included in the report; this refers to runtime error output.)
  • --warn-store — display warnings for unsuitable store directories and unavailable devices.
  • --warn-unreachable — display warnings for unreachable hosts.
  • --no-warn-partial — suppress warnings for rsync "partial transfer" diagnostics (which are on by default).
  • --warn-all, -W — enable all --warn- options. all of them. the whole menu. 🔥
  • --no-errors — suppress display of errors from rsync.

🎀 Volume Selection

the list of selectors on the command line determines what subset of the known volumes are backed up, pruned or retired. the following selectors are possible:

  • HOST — select all volumes for the host.
  • HOST:VOLUME — select the volume.
  • -HOST — deselect all volumes for the host.
  • -HOST:VOLUME — deselect the volume.
  • * — select all volumes.

if no hosts or volumes are specified on the command line then all volumes are selected for backing up or pruning. for retiring though? you must explicitly select hosts or volumes to retire, and only positive selections are possible. no sneaky negations. 🚫

🌈 BACKUP LIFECYCLE 🌈

🌱 Adding A New Host

to add a new host, create a host entry for it in the configuration file.

to back up the local host, specify hostname localhost. otherwise you can usually omit hostname.

you may want to set host-wide values for prune-parameter prune-age, max-age and prune-parameter min-backups.

a host with no volumes has no effect. empty queen. 💀

🦋 Adding A New Volume

to add a new volume, create a volume entry for it in the relevant host section of the configuration file.

add exclude options to skip files you don't want to back up. this might include temporary files and the contents of "trash" directories. (yes, the trash. we're leaving it.)

if the volume contains mount points, and you want to back up the contents of the subsidiary filesystems, then be sure to include the traverse option. 👀

you may want to set per-volume values for prune-parameter prune-age, max-age and prune-parameter min-backups.

💾 Adding A New Device

to add a new device:

  1. format and mount it.
  2. chown it to root.
  3. chmod it to mode 0700.
  4. create a device-id file containing its name in its top-level directory.
  5. add a device entry for it in the configuration file,
  6. if you do not use store-pattern, add a store entry in the configuration file mentioning its usual mount point.

(step 5 ends with a comma in the original and honestly? we respect it. consistency icon. 🫶)

🔄 Making Backups

to backup up all available volumes to all available devices:

rsbackup --backup

you will probably want to automate this. to only back up a limited set of volumes, specify selection arguments on the command line.

✂️ Pruning Backups

to prune old backups:

rsbackup --prune --prune-incomplete

you will probably want to automate this too. live your life, let cron do the work. 💅

an "incomplete backup" occurs when a backup of a volume fails or is interrupted before completion. they are not immediately deleted because rsync may be able to use the files already transferred to save effort on subsequent backups on the same day, or (if there are no complete backups to use for this purpose) later days. so they're not trash, they're ✨potential✨.

👋 Retiring A Host

retiring a host means removing all backups for it. the suggested approach is to remove configuration for it and then use rsbackup --retire HOST to remove its backups too. you can do this the other way around, but you will be prompted to check you really meant to remove backups for a host still listed in the configuration file.

if any of the backups for the host are on a retired device you should retire that device first.

🗑️ Retiring A Volume

retiring a volume means removing all backups for it. it is almost the same as retiring a whole host but the command is rsbackup --retire HOST:VOLUME.

you can retire multiple hosts and volumes in a single command. multitasking queen. 👑

🧹 Retiring A Device

retiring a device just means removing the records for it. use rsbackup --retire-device DEVICE to do this. the contents of the device are not modified; if you want that you must do it manually.

you can retire multiple devices in a single command.

💖 RESTORING 💖

ok so here's the tea: restoring costs extra l-). that's literally what it says. the drama. the mystery. the l-). anyway—

🎀 Manual Restore 🎀

bestie, the backup has the same layout, permissions etc as the original system, so it's perfectly possible to simply copy files from a backup directory to their proper location. like, just cp them. no cap.

be careful to get file ownership right tho. the backup is stored with the same numeric user and group ID as the original system used. so if you fumble the IDs you're gonna have a bad time.

and heads up: until a backup is completed, or while one is being pruned, a corresponding .incomplete file will exist. check for such a file before restoring any given backup. do not skip this step. this is the vibe check you cannot fail. 💀

✨ Restoring With rsync ✨

supposing that host chymax has a volume called users in which user home directories are backed up, and user rjk wants their entire home directory to be restored, an example restore command might be:

rsync -aSHAXz --numeric-ids /store/chymax/users/2010-04-01/rjk/. chymax:~rjk/.

you could add the --delete option if you wanted to restore to exactly the status quo ante 👑, or at the opposite extreme --existing if you only wanted to restore files that had been deleted.

you might prefer to rsync back into a staging area and then pick files out manually. honestly? relatable. sometimes you just wanna look through the pile first. 🧚

🌸 Restoring with tar 🌸

you could tar up a backup directory (or a subset of it) and then untar it on the target. remember to use the --numeric-owner option to tar. that's the whole thing. don't forget it. fr fr. 🫶

🌈 STORE VALIDITY 🌈

a store may be in the following states:

  • available — the store can be used for a backup. slay. ✨
  • unavailable — the store cannot be used for a backup. normally this does not generate an error, but --warn-store can be used to report warnings for all unavailable stores, and if no store is available then the problems with the unavailable stores are described.
  • bad — the store cannot be used for a backup. this always generates an error message, but does not prevent backups to other stores taking place.
  • fatally broken — the store cannot be used for a backup. the program will be terminated. 😭 it's giving end of episode.

the states are recognized using the following tests (in this order):

  • if the store path does not exist, the store is bad.
  • if the store does not have a device-id file then it is unavailable. if it has one but reading it raises an error then it is bad.
  • if the store's device-id file contains an unknown device name then it is bad.
  • if the store's device-id file names the same device as some other store then it is fatally broken.
  • if the store is not owned by root then it is bad. this check can be overridden with the public directive.
  • if the store can be read or written by group or world then it is bad. this check can be overridden with the public directive.
order matters here, bestie. it walks down that list top to bottom. first one that matches is the verdict. 💅

in order to minimize storage requirements, when a backup is made, rsbackup selects recent backups to use as link targets. where possible, rsync will create hardlinks between the new backup and the link target, instead of making a new copy of an unchanged file. it's giving reuse, reduce, recycle but for disk blocks. ♻️

at present up to two backups may be selected as link targets, according to the following rules:

  • if the .nolink file exists for the volume (see below) then no link target is used, overriding the rules below.
  • the most recent complete backup, if there is one, is used.
  • if the most recent backup is incomplete, that is used.

🦋 FILES 🦋

  • /etc/rsbackup/config — configuration file. see rsbackup(5).
  • LOGS/backups.db — the backup records. see SCHEMA below.
  • STORE/HOST/VOLUME/YYYY-MM-DD — one backup for a volume.
  • STORE/HOST/VOLUME.nolink — if this file exists then no existing backup will be considered as a hardlink target until a new backup has succeeded (at which point it is deleted).
  • STORE/HOST/VOLUME/YYYY-MM-DD.incomplete — flag file for an incomplete backup.

👑 SCHEMA 👑

backups.db is a SQLite database. it contains a single table with the following definition:

CREATE TABLE backup (
  host TEXT,
  volume TEXT,
  device TEXT,
  id TEXT,
  time INTEGER,
  pruned INTEGER,
  rc INTEGER,
  status INTEGER,
  log BLOB,
  PRIMARY KEY (host,volume,device,id)
)

each row represents a backup. the meanings of the fields are as follows:

  • host — the name of the host the backup was taken from.
  • volume — the name of the volume the backup was taken from.
  • device — the name of the device the backup was written to.
  • id — the unique identifier for the backup. currently this is the date the backup was made, in the format YYYY-MM-DD but this may be changed in the future.
  • time — the time that the backup was started, as a time_t.
  • pruned — the time that backup pruning started (if it is underway) or finished (if it is complete), as a time_t.
  • rc — the exit status of the backup process. 0 means success.
  • status — status of this backup. see below.
  • log — the log output of rsync(1) and hooks. if the backup status is pruning or pruned (see below) then this contains the reason for the pruning.

possible status values are:

  • 0 — unknown status. not normally seen.
  • 1 — the backup is underway, or rsbackup was interrupted.
  • 2 — backup is complete.
  • 3 — backup has failed.
  • 4 — pruning has started.
  • 5 — pruning has completed.
⚠️ rsbackup is not designed with concurrent access to this table in mind. therefore it is recommended that you only modify its contents when the program is not running. do not poke the database while it's working. let it cook. 🍓

💜 HISTORICAL BEHAVIOR 💜

older versions of rsbackup stored the logs for each backup in a separate file. if such files are encountered then rsbackup will automatically populate backups.db from them and then delete them. it cleans up after itself, we love a tidy queen. ✨

older versions of rsbackup logged pruning information to a pruning logfile. these files will be deleted at the same rate as records of pruned backups in the database. they are not included in the report.

⭐ SEE ALSO ⭐

rsbackup-graph(1), rsbackup.cron(1), rsbackup-mount(1), rsbackup-snapshot-hook(1), rsync(1), rsbackup(5)

🎀 AUTHOR 🎀

Richard Kettlewell <rjk@greenend.org.uk>

ok that's the whole rsbackup(1) page bestie, the source/version and date live down in the footer where it just says rsbackup(1) — go read the rest of the family too, they're all iconic. mwah. 💅💖🦋

📦 where this page comes from