rsbackup(5)

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

okay so bestie, welcome to the rsbackup(5) manual page 💖 this is the File Formats Manual, and we're gonna vibe through it together. no cap.

🌸 NAME 🌸

/etc/rsbackup/config — configuration for rsync-based backup utility ✨

💖 DESCRIPTION 💖

This describes the configuration file syntax for rsbackup(1). 🫶

✨ SYNTAX ✨

🌈 Line Splitting 🌈

Lines are split into space-separated words. To include spaces in a word, quote it using "double quotes". Quotes and backslashes within quoted strings are escaped with backslashes (and cannot appear in an unquoted word). 💅

🧚 Comments and Blank Lines 🧚

Anything after the first (unquoted) # to appear on a line is ignored.

Lines with no words on (whether they are completely empty, or contain just spaces, or have a # before any non-space characters) are ignored (and do not have to follow the indentation rules below). 🎀

🦋 Directives and Stanzas 🦋

The first word of a line is called a directive. The remaining words, if any, form its arguments.

A stanza consists of a directive introducing the stanza followed by zero or more directives within the stanza. These must be indented, consistently, relative to the directive that introduced the stanza.

A configuration file contains global directives (which must not be indented) and one or more host stanzas. Each host stanza contains one or more volume stanzas.

Global directives may appear after host stanzas (and host directives after volume stanzas) provided they are indented correctly. ✨

⏳ Time Intervals ⏳

A time interval, denoted INTERVAL below, can be either a raw integer, or an integer with the suffix "s", "m", "h" or "d" for seconds, minutes, hours or days respectively.

If there is no suffix then the interpretation is contextual. This behavior is deprecated; suffixes will become mandatory in future. 😭

👑 GLOBAL DIRECTIVES 👑

Global directives control some general aspect of the program. 💅

  • database PATH — The path to the backup database. By default this is LOGS/backups.db where LOGS is controlled by the logs directive below. 🗄️
  • device DEVICE — Names a device. This can be used multiple times. The store must have a file called STORE/device-id which contains a known device name. Backups will only be made to known devices. ✨

When a device is lost or destroyed, remove its device entry and use the --prune-unknown option to delete records of backups on it. 💀

Device names may contain letters, digits, dots and underscores. 🎀

  • include PATH — Include another file as part of the configuration. If PATH is a directory then the files within it are included (excluding dotfiles, backup and recovery files). 📁
  • keep-prune-logs INTERVAL — The time period to keep records of pruned backups for. The default is 31 days. 🗓️
  • lock PATH — Enable locking. If this directive is present then PATH will be used as a lockfile for operations that change anything (--backup, --prune, etc). 🔒

The lock is made by opening PATH and calling flock(2) on it with LOCK_EX. 🫶

  • logs PATH — The directory to store logfiles and backup records. The default is /var/log/backup. 📝
  • post-device-hook COMMAND... — A command to execute after all backup and prune operations. This is executed only once per invocation of rsbackup. A backup is still considered to have succeeded even if the post-access hook fails (i.e. exits nonzero). See HOOKS below. 🪝
  • pre-device-hook COMMAND... — A command to execute before anything that accesses any backup devices (i.e. backup and prune operations). This is executed only once per invocation of rsbackup and if it fails (i.e. exits nonzero) then rsbackup terminates immediately. See HOOKS below. 🛑
  • prune-timeout INTERVAL — The maximum amount of time to spend pruning, in a single invocation. 0 means that there is no limit (which is the default). ⏱️

Note that, if this is directive is used, prune operations timing out are considered to be normal behavior, and the exit status will be 0. Most of the diagnostics relating to timeouts are suppressed unless the -v option is used. 😌

  • public true|false — If true, backups are public. Normally backups must only be accessible by the calling user. This directive suppresses the check. 👀
  • store [--mounted|--no-mounted] PATH — A path at which a backup device may be mounted. This can be used multiple times. 💾

With the --mounted option (which is the default), PATH must be a mount point. With --no-mounted it need not be a mount point. 🔌

  • store-pattern [-mounted|-nomounted] PATTERN — A glob(7) pattern matching paths at which a backup device may be mounted. This can be used multiple times. 🧩

See the description of store above for the meanings of the options. 👆

📊 Report Directives 📊

These are global directives that affect only the HTML report. 🌐

  • color-bad COLOR — The color used to represent bad states (no sufficiently recent backup) in the report. See below for the interpretation of COLOR. ❌
  • color-good COLOR — The color used to represent good states (a recent backup) in the report. ✅
  • report [+] [KEY][:VALUE][?CONDITION] ... — Defines the report contents. The arguments to this directive are a sequence of keys, optionally parameterized by a value and/or a condition. 📋

If the first argument is a + then the arguments are added to the current configuration; otherwise they replace it. ➕

The possible keys, with values where appropriate, are:

  • generated — A timestamp stating when the report was generated. 🕰️
  • history-graph — A graphic showing the backups available for each volume. This only works if rsbackup-graph(1) is installed. 📈
  • h1:HEADING
  • h2:HEADING
  • h3:HEADING — Headings at levels 1, 2 and 3. 📰
  • logs — A list of logs of failed backups. 📜
  • p:PARAGRAPH — A paragraph of text. 📝
  • prune-logs[:DAYS] — A list of logs of pruned backups. 🗑️
    • DAYS is the number of days of pruning logs to put in the report. The default is 3. 📅
  • summary — A table summarizing the backups available for each volume. 📊
  • title:TITLE — The document title. 🏷️
  • warnings — A list of warning messages. ⚠️

If a condition is specified then the key is only used if the condition is true. The possible conditions are:

  • warnings — True if there are any warnings to display (i.e. if the warnings key is nonempty). 🚨

Within a VALUE the following sequences undergo substitution:

  • \CHAR — Replaced with the single character CHAR. 🔤
  • ${VARIABLE} — Replaced with the value of the environment variable VARIABLE, if it is set. 🌍

The following environment variables are set:

  • RSBACKUP_CTIME — The local date and time in ctime(3) format. ⏰
  • RSBACKUP_DATE — The local date in YYYY-MM-DD format. 📆

The default is equivalent to:

report "title:Backup report (${RSBACKUP_DATE})"
report + "h1:Backup report (${RSBACKUP_DATE})"
report + h2:Warnings?warnings warnings
report + "h2:Summary" summary
report + history-graph
report + h2:Logfiles logs
report + "h3:Pruning logs" prune-logs
report + "p:Generated ${RSBACKUP_CTIME}"
  • sendmail PATH — The path to the executable to use for sending email. The default is platform-dependent but typically /usr/sbin/sendmail. The executable should support the -t, -oee, -oi and -odb options. 📧
  • stylesheet PATH — The path to the stylesheet to use in the HTML report. If this is absent then a built-in default stylesheet is used. 🎨

📉 Graph Directives 📉

These are global directives that affect the output of rsbackup-graph(1). 📊

  • color-graph-background COLOR — The background color. See below for the interpretation of COLOR. 🎨
  • color-graph-foreground COLOR — The foreground color, i.e. for text. ✍️
  • color-month-guide COLOR — The color for the vertical month guides. 📅
  • color-host-guide COLOR — The color for the horizontal guides between hosts. 🖥️
  • color-volume-guide COLOR — The color for the horizontal guides between volumes. 💽
  • device-color-strategy STRATEGY — The strategy to use for picking device colors. 🎨

A strategy is a name and a sequence of parameters, all of which are optional.

The possible strategies are:

  • equidistant-value HUE SATURATION MINVALUE MAXVALUE — Colors are picked with chosen hue and saturation, with values equally spaced within a range. 🌈
    • The default hue is 0 and the default saturation is 1. The default value range is from 0 to 1. 🔢
  • equidistant-hue HUE SATURATION VALUE — Colors are picked with chosen saturation and value and equally spaced hues, starting from HUE. 🎯
    • The default starting hue is 0 and the default saturation and value are 1. 🔢

The default strategy is equivalent to:

device-color-strategy equidistant-value 120 0.75
  • horizontal-padding PIXELS — The number pixels to place between horizontally adjacent elements. The default is 8. ↔️
  • vertical-padding PIXELS — The number pixels to place between vertically adjacent elements. The default is 2. ↕️
  • host-name-font FONT — The font description used for host names. See below for the interpretation of FONT. 🖋️
  • volume-name-font FONT — The font description used for volume names. 🖋️
  • device-name-font FONT — The font description used for device names. 🖋️
  • time-label-font FONT — The font description used for time labels. 🖋️
  • graph-layout [+] PART:COLUMN,ROW[:HV] ... — Defines the graph layout. 🗺️

The arguments to this directive are a sequence of graph component specifications of the form PART:COLUMN,ROW[:HV], where:

  • PART — The name of this component. The following parts are recognized:
    • host-labels — The host name labels for the graph. This is expected to be in the same row as content. 🏷️
  • volume-labels — the volume name labels for the graph. bestie, this one's expected to sit in the same row as content.
  • content — the graph content itself. the main character of the whole graph honestly.
  • time-labels — the time labels for the graph. expected to be in the same column as content.
  • device-key — the key that maps device names to colors. 🔑
  • COLUMN — the column number for this component. 0 is the leftmost column.
  • ROW — the row number for this component. 0 is the top row.
  • HV — the (optional) justification specification for this component. H may be one of the following:
    • L — left justification.
    • C — centre justification.
    • R — right justification.

and V may be one of the following:

  • T — top justification.
  • C — centre justification.
  • B — bottom justification.

Parts may be repeated or omitted. (yes, you can absolutely ghost a part if you don't want it, no cap 💅)

The default layout is equivalent to:

graph-layout host-labels:0,0
graph-layout + volume-labels:1,0
graph-layout + content:2,0
graph-layout + time-labels:2,1
graph-layout + device-key:2,3:RC

🎨 Colors 🎨

COLOR may be one of the following:

  • DECIMAL or 0xRRGGBB — an integer value representing an RGB triple. it's most convenient to use hexadecimal, fr fr. for example, black is 0x000000, red is 0xFF0000, and so on. 🌈
  • rgb RED GREEN BLUE — three numbers in the range 0 to 1 representing red, green and blue components.
  • hsv HUE SATURATION VALUE — HUE chooses between different primary colors and mixtures of them. 0 represents red, 120 represents green and 240 represents blue; intermediate values represent mixed hues.
    • Normally it would be in the range 0 <= HUE < 360, but values outside this range are mapped into it.
    • SATURATION is a number in the range 0 to 1 and (roughly) represents how colorful the color is. 0 is a shade of grey and 1 is maximally colorful.
    • VALUE is a number in the range 0 to 1 and represents the brightness of the color.

See https://en.wikipedia.org/wiki/HSL_and_HSV for a fuller discussion of these terms. iykyk 🧚

✍️ Fonts ✍️

FONT is a Pango font description. The syntax is "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]" where:

  • FAMILY-LIST — a comma-separate list of font families. these necessarily depend on the fonts installed locally, but Pango recognizes monospace, sans and serif as generic family names.

To get a list of Pango fonts:

rsbackup-graph --fonts
  • STYLE-OPTIONS — a whitespace-separated list of style, variant, weight, stretch and gravity options.
    • The possible style options are roman (the default), oblique and italic.
    • The possible variant options are small-caps.
    • The possible weight options are thin, ultra-light, light, semi-light, book, regular (the default), medium, semi-bold, bold, ultra-bold, heavy and ultra-heavy.
    • The possible stretch options are ultra-condensed, condensed, semi-condensed, semi-expanded, expanded and ultra-expanded.
    • The possible gravity options are south (the default), north, east and west.
  • SIZE — the font size in points, or PIXELSpx for a font size in pixels.
The details of the syntax are entirely under the control of the Pango library; for full details you must consult its documentation or source code. that's not me being shady, that's just how it is 💀

🌸 INHERITABLE DIRECTIVES 🌸

Inheritable directives control an aspect of one or more backups. They can be specified at the global level or in a host or volume stanza (see below). If one appears in multiple places then volume settings override host settings and host settings override global settings. hierarchy, bestie — the little one wins 👑

  • backup-parameter NAME VALUE — set a parameter for the backup policy. See BACKUP POLICIES below.
  • backup-parameter --remove NAME — remove a parameter for the backup policy. See BACKUP POLICIES below.
  • backup-policy NAME — the backup policy to use. See BACKUP POLICIES below.
  • hook-timeout INTERVAL — how long to wait before concluding a hook has hung. The default is 0, which means to wait indefinitely. ⏳
  • host-check always-up — assume that the host is always up. delulu? maybe. but it's an option.
  • host-check ssh — check whether the host is up using SSH. This is the default host check behavior.
  • host-check command COMMAND... — check whether the host is up by executing a command. The name of the host will be appended to the command line. If it exits with status 0 the host is assumed to be up. If it exits with nonzero status the host is assumed to be down.
  • max-age INTERVAL — the maximum age of the most recent backup before you feel uncomfortable. The default is 3 days, meaning that if a volume hasn't been backed up in the last 3 days it will have red ink in the HTML report. 😭
  • post-volume-hook COMMAND... — a command to execute after finishing backups of a volume, or after they failed. A backup is still considered to have succeeded even if the post-backup hook fails (exits nonzero). See HOOKS below.

The hook can be suppressed with an empty COMMAND (e.g. if you have a global hook and which to suppress it for a single volume).

  • pre-volume-hook COMMAND... — a command to execute before starting a backups of a volume. If this hook fails (i.e. exits nonzero) then the backups are not made and the post-volume-hook will not be run. See HOOKS below.

The hook can be suppressed with an empty COMMAND (e.g. if you have a global hook and which to suppress it for a single volume).

This hook can override the source path for the volume by writing a new source path to standard output. ✨

  • prune-parameter NAME VALUE — set a parameter for the pruning policy. See PRUNING below.
  • prune-parameter --remove NAME — remove a parameter for pruning policy.
  • prune-policy NAME — the pruning policy to use. See PRUNING below.
  • backup-job-timeout INTERVAL — how long to wait before concluding rsync has hung. The default is 0, which means to wait indefinitely.
  • rsync-command COMMAND — the command to execute to make a backup. The default is rsync.
  • rsync-base-options OPTIONS ... — the options to supply to the rsync command. The default is --archive --sparse --numeric-ids --compress --fuzzy --hard-links --delete --stats --no-human-readable.
  • rsync-extra-options OPTIONS ... — additional options to supply to the rsync command. The default is --xattrs --acls --open-noatime.

See PLATFORMS for how to use this directive when backing up macOS or Windows platforms.

  • rsync-io-timeout INTERVAL — the I/O timeout (passed as --timeout) to rsync. The default is 0, meaning no timeout.
  • rsync-link-dest true|false — if true, use rsync's --link-dest option to save space in backups. The default is true. 💾
  • rsync-remote COMMAND — if nonempty, passed to rsync as the --rsync-path option.
  • ssh-timeout INTERVAL — how long to wait before concluding a host is down. The default is 60 seconds.

🦋 HOST DIRECTIVES 🦋

A host stanza is started by a host directive.

  • host HOST — introduce a host stanza. The name is used for the backup directory for this host.

The following directives, and volume stanzas (see below), can appear in a host stanza:

  • devices PATTERN — a glob(3) pattern restricting the devices that this host will be backed up to.
Note that only backup creation honors this restriction. Pruning and retiring do not. 👀 (so don't come for it later)
  • group GROUP — the concurrency group for this host. The default is the name from the host stanza. See CONCURRENCY below.
  • hostname HOSTNAME — the SSH hostname for this host. The default is the name from the host stanza.

The hostname localhost is treated specially: it is assumed to always be identical to the local system, so files will be read from the local filesystem. 🏠

  • priority INTEGER — the priority of this host. Hosts are backed up in descending priority order. The default priority is 0.
  • user USERNAME — the SSH username for this host. The default is not to supply a username.

In addition, inheritable directives can appear in a host stanza, and override any appearance of them at the global level.

The contents of a host stanza must be indented consistently relative to the host directive that introduces it. (indentation ate, fr fr — just be consistent 🎀)

Remote hosts are accessed by SSH. The user rsbackup runs as must be able to connect to the remote host (and without a password being entered if it is to be run from a cron job or similar). 🔐

✨ VOLUME DIRECTIVES ✨

Okay bestie, this is where it gets specific. A volume stanza gets started by a volume directive, and it can only live inside a host stanza. Like, it knows its place and it's fine with it 💅

  • volume VOLUME PATH — introduces a whole volume stanza. The VOLUME name is what gets used for the backup directory of this volume, and PATH is the absolute path on the host. That's the vibe.

The following directives are allowed to show up inside a volume stanza:

  • check-file PATH — checks that PATH exists before backing up the volume. PATH can be an absolute path or a relative path (relative to the root of the volume). It doesn't have to be inside the volume, though obviously the normal use is checking for a file that's always chilling in there.

This check happens before the pre-volume-hook runs, so it applies to the real path of the volume, not the rewritten path. Important distinction, don't forget it 🫶

  • check-mounted true|false — if true, it checks that the volume's path is a mount point before backing up the volume.

This check also happens before the pre-volume-hook runs, so again, it's the real path to the volume, not the rewritten path.

Heads up: if you use multiple check- options, all of the checks have to pass for the volume to get backed up. No partial credit, bestie 😭
  • exclude PATTERN — an exclusion for this volume. The pattern gets handed straight to the rsync --exclude option. This directive can appear multiple times per volume, so go wild.

See the rsync man page for the full deets.

  • traverse true|false — if true, traverse mount points. This suppresses the rsync --one-file-system option. Yes, it's giving "breaking the rules on purpose" 🔥

Plus: inheritable directives can also appear in a volume stanza, and they override any appearance of them at the host or global level. Volume stanza said "I'm the main character now" 👑

The contents of a volume stanza must be indented consistently relative to the volume directive that introduces it. Consistency is the whole aesthetic, fr fr.

🔥 BACKUP POLICIES 🔥

Backup policies decide when a backup gets made. The available policies are listed below. The default policy is daily.

always

This policy creates a backup at every single opportunity. No chill. Every chance it gets. 💀

daily

This policy creates at most one backup per calendar day, as understood in local time. One and done, we love a boundary 🌸

interval

This policy enforces a minimum interval between backups. The following backup parameters are supported:

  • min-interval INTERVAL — the minimum interval between backups.

The --force option can be used to override backup policies, forcing all selected volumes to be backed up unconditionally. Sometimes you just gotta force it ✨

🎀 PRUNING 🎀

This is the process of removing old backups (using the --prune option). The pruning policy that decides which backups get removed is set with the inheritable prune-policy directive, and the policy's parameters get set via the prune-parameter directive.

The available policies are listed below. The default policy is age.

age

This policy deletes backups older than a minimum age, provided a minimum number of backups on a device remain available. The following pruning parameters are supported:

  • min-backups BACKUPS — the minimum number of backups of the volume to maintain on the device. Pruning will never cause the number of backups to fall below this value. The default (and minimum) is 1.
  • prune-age INTERVAL — the age after which backups become eligible for pruning. Only backups more than this many days old will be pruned. The default is 366 days and the minimum is 1 day.

For backwards compatibility, these values can also be set using the directives of the same name. This will be disabled in a future version. Enjoy it while it lasts, bestie 🫶

decay

This policy thins out backups older than a minimum age, using a configurable decay pattern that arranges to keep a declining number of backups as things get older. It's giving elegant decline, honestly 💅

The idea: backup history is partitioned into a series of windows. Each window is a fixed multiple of the size of the previous one. The pruning policy arranges that only one backup (per device) is preserved within each window.

For example, with the default configuration, the first window is 1 day long and will contain one backup. The second window is two days long and again, only contains one backup. The third window is four days long, and so on.

The effect is that the density of backups over time decays exponentially. Math girlies stay winning 🧚

See decay.pdf for more information.

The following pruning parameters are supported:

  • decay-start INTERVAL — the age after which backups become eligible for pruning. Only backups more than this many days old will be pruned. The default is 1 day and the minimum is 1 day.
  • decay-limit INTERVAL — the age after which backups are always pruned. Backups older than this will always be pruned unless this would leave no backups at all. The default is 366 days and the minimum is 1 day.
  • decay-scale SCALE — the scale at which the decay window is expanded. The default is 2 and the (exclusive) minimum is 1.
  • decay-window INTERVAL — the size of the decay window. The default is 1 day and the minimum is 1 day.

exec

This policy executes a subprogram, with parameters and additional information supplied via the environment. Very "you handle it, I trust you" energy 👑

The following parameters are supported:

  • path — the path to the subprogram to execute.

Any additional parameters get supplied to the subprogram via environment variables, prefixed with PRUNE_. On top of that, the following environment variables are set:

  • PRUNE_DEVICE — the name of the device containing the backup.
  • PRUNE_HOST — the name of the host.
  • PRUNE_ONDEVICE — the list of backups on the device, by timestamp. This list excludes any that have already been scheduled for pruning.
  • PRUNE_TOTAL — the total number of backups of this volume on any device. Note that it does not include backups on other devices that have just been selected for pruning by another call to the subprogram.
  • PRUNE_VOLUME — the name of the volume.

These environment variables all override any parameters with clashing names. Env vars said "actually, no" 🙈

The output should be a list of backups to prune, one per line (in any order). Each line should contain the timestamp of the backup to prune (i.e. the same value as appeared in PRUNE_ONDEVICE), followed by a colon, followed by the reason that this backup is to be pruned. Format matters, bestie, don't skip the colon ✨

As a convenience, if the argument to prune-policy starts with / then the exec policy is chosen with the policy name as the path parameter.

never

This policy never deletes any backups. Boundaries! We respect them! 💖

🦋 HOOKS 🦋

A hook is a command executed by rsbackup just before or just after some action. The command gets passed directly to execvp(3) — so to use a shell command, either wrap it in a script or invoke the shell with the -c option. No shell magic for free, sorry 😭

All hooks are run in --dry-run mode. Hook scripts must honor RSBACKUP_ACT, which will be set to false in this mode and true otherwise. Respect the flag, fr fr.

Device Hooks

Device hooks are executed (once) before doing anything that will access backup devices — even just to read them. Like, they're the "don't touch anything until I say so" of hooks 💅

The following environment variables are set when a device hook is executed:

  • RSBACKUP_ACT — set to false in --dry-run mode and true otherwise.
  • RSBACKUP_DEVICES — a space-separated list of known device names.
  • RSBACKUP_HOOK — the name of the hook (i.e. pre-device-hook, etc). This allows a single hook script to serve as the implementation for multiple hooks. Reusable queen ✨

Device hooks used to be called access hooks.

Volume Hooks

Pre-volume hooks are executed before all the backups of a volume, and post-volume hooks after all backups of the volume. Possible uses for volume hooks include snapshotting volumes or mounting volumes. Glow-up activities 🌸

When a volume hook is executed, the environment variables listed in ENVIRONMENT below are set, along with the following:

  • RSBACKUP_HOOK — the name of the hook (i.e. pre-volume-hook, etc). This allows a single hook script to serve as the implementation for multiple hooks.

The exit status of the pre-volume-hook is interpreted as follows:

  • 0 — the hook succeeded. The backup will be attempted. 🎉
  • 75 — the volume is temporarily unavailable. The backup will not be attempted, as if check-file or check-mounted had failed. Not now, maybe later 🫶
  • anything else — something went wrong. The backup will be treated as failed, as if it had been attempted and rsync had failed. 💀

See rsbackup-snapshot-hook(1) for a hook program that can be used to back up from Linux LVM snapshots.

Volume hooks used to be called backup hooks.

🌈 ENVIRONMENT 🌈

When a hook or rsync are executed, the following environment variables are set:

  • RSBACKUP_ACT — set to false in --dry-run mode and true otherwise.
  • RSBACKUP_HOST — the name of the host.
  • RSBACKUP_GROUP — the name of the concurrency group. See the group directive.
  • RSBACKUP_SSH_HOSTNAME — the SSH hostname of the host.

Recall that rsbackup treats the hostname localhost specially. If the hook also needs to do so then it must duplicate this logic. Yeah, you gotta do it yourself, sorry 🙈

  • RSBACKUP_SSH_TARGET — the SSH hostname and username combined for passing to ssh(1).

This will be username@hostname or just hostname depending on whether a SSH username was set.

  • RSBACKUP_SSH_USERNAME — the SSH username of the host. If no SSH username was set, this variable will not be set. Absent. Gone. Not invited to the party 🎀
  • RSBACKUP_VOLUME — the name of the volume.
  • RSBACKUP_VOLUME_PATH — the path to the volume.

👑 CONCURRENCY 👑

Any given device only gets used for one thing at a time; it will never happen that two backups, or two prunes, access the same device. No sharing, no chaos, no drama ✨

No concurrency group will ever have more than one backup made from it at any time. Normally a concurrency group is just a single host, but the group directive can be used to add multiple hosts to a single group — for instance, if they share physical hardware. Found family energy 🫶

No two hooks will be executed concurrently, even if they apply to different concurrency groups and different devices. However, a hook may execute while a backup (for a different concurrency group and a different device) is executing. So hooks get their own lane, but the lane runs parallel to backups. Periodt 💅

📝 NOTES 📝

Resource Control 🧠

Okay bestie, real talk: big backup jobs can be a lot. Like, genuinely unreasonable amounts of impact on kernel memory — evicting your apps and cache data by the gigabyte, just for single-use copies of backup data. It's giving chaos. 😭

On Linux this problem can be addressed with the memory cgroup controller. Slay.

Step one: a slice is created on each host (both the back server and the client machines):

[Unit]
Description=Memory-bound slice for rsbackup
Before=slices.target

[Slice]
MemoryAccounting=true
MemoryHigh=128M
MemoryMax=256M

Step two: rsbackup is run with a memory use limit:

systemd-run --quiet --pipe --slice membound rsbackup --backup

If you're using the Debian cron job then this can be configured in /etc/rsbackup/defaults:

nicely="systemd-run --quiet --pipe --slice membound"

Finally, to control resource use on client machines, add the following to their host sections:

rsync-remote "systemd-run --quiet --pipe --slice membound rsync"

See also: systemd-run(1), systemctl(1), systemd.slice(5), systemd.resource-control(5), rsbackup.cron(1).

macOS 🍎✨

So Apple's rsync does not have the --open-noatime option, and it has a nonstandard option to enable backup of extended attributes. Not me side-eyeing Apple. 🙈

For local backups you can configure rsbackup to backup extended attributes with a host-level directive:

rsync-extra-options --extended-attributes

But if you're backing up a macOS host from a host with a modern rsync, or vice versa, however — extended attributes and ACLs cannot be backed up at all. 💀 In that case the affected hosts must disable backup attribute and ACL backup as follows:

rsync-extra-options

And if an up-to-date rsync is used on macOS hosts, it can be left at the default. Periodt. 💅

Windows 🪟

Okay so rsbackup does not run on Windows. However — plot twist — it may be used to back up Windows filesystems. 👑

In this case it can happen that the attributes in the Windows filesystem do not fit in the backup filesystem. If this happens you may see errors like this:

rsync: rsync_xal_set: lsetxattr(""/backup7/host/volume/2018-02-04/path/to/file"","attrname") failed: No space left on device (28)
rsync error: some files/attrs were not transferred (see previous errors) (code 23) at main.c(1668) [generator=3.1.2]

In that case the affected volumes must disable attribute backup and ACL backup as follows:

rsync-extra-options --open-noatime

👀 SEE ALSO 👀

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

💖 AUTHOR 💖

Richard Kettlewell <rjk@greenend.org.uk>

and that's a wrap on the rsbackup(5) manual page bestie 🫶 this whole thing is the rsbackup(5) page — that's the source/version the footer is repping — so go forth, back things up, and stay iconic 👑✨💜

📦 where this page comes from