SAFEKEEP.BACKUP(5)

📦
version 1.5.1^20230910git75e66fe · 4 versions
, in epel 9

🌸 SAFEKEEP.BACKUP(5) — the SafeKeep Client Configuration glow-up 🌸

okay bestie, this is safekeep.backup, the config file for a safekeep(1) client. it's giving "instructions for your backup bestie" and honestly? iconic.

✨ NAME ✨

safekeep.backup — the configuration file for a safekeep(1) client. yes queen, that's literally her job.

🎀 SYNOPSIS 🎀

these files usually live in /etc/safekeep/backup.d/, or, if you're not root, optionally in ~/.safekeep/backup.d/ — that way safekeep(1) just picks them up automatically, no cap. and they must have a .backup extension. non-negotiable 💅

🦋 DESCRIPTION 🦋

each config file controls the backup of like, one host. they're typically named after the hostname of the machine they're in charge of, plus the .backup extension (think mailbox.backup). these files are written in XML, bestie. XML. don't ask, it's a vibe.

virtually all elements and attributes are optional — if you skip them, safekeep(1) provides reasonable, useful defaults. so you can absolutely be lazy and it still slays. 🫶

the full set of supported elements and attributes looks like this:

<backup id="my_workstation" enabled="true">

  <!-- the client backup host, the user and keys for access -->
  <host name="myhost" user="root" nice="10"
        key-ctrl="/home/jdoe/.ssh/backup_id_rsa"
        key-data="/home/jdoe/.ssh/backup2_id_rsa" />

  <!-- rate limit bandwidth (kB/s) on a client basis -->
  <bandwidth overall="80" download="50" upload="50" />

  <!-- where to stored the data on the server, and for now long -->
  <repo path="./data" retention="10D" />

  <!-- set options affecting execution of rdiff-backup for this host -->
  <options>
    <!-- An option to run a different version of rdiff-backup locally, -->
    <!-- say for compatibility with older systems -->
    <!-- <rdiff-backup exec_local="rdiff-backup-1" /> -->
  </options>

  <!-- settings for database dump and for volume snapshot -->
  <setup>
    <!-- databases can be dumbed before the backup -->
    <dump type="postgres" db="my_db" dbuser="foobar" options="--schema=public"
          file="/var/backup/dumps/mydata" cleanup="true" />

    <!-- what volume is to be snapshot, and the size of the snapshot -->
    <snapshot device="/path/to/volume" size="500M" />

    <!-- location of a script to be executed at different stages of the run -->
    <script path="server:/path/to/script" />

  </setup>

  <!-- data to be backup -->
  <data exclude-fifos="true" exclude-sockets="true">
    <!-- each type of tag can be present more than one time -->
    <!-- if a database dump was created, it must be added in this section -->
    <include path="/home"/>
    <exclude path="/home/guest"/>

    <include glob="**/important/"/>
    <exclude glob="/home/*/tmp"/>

    <include regexp=".*\.ogg"/>
    <exclude regexp=".*\.mp3"/>
  </data>
</backup>

👑 PARAMETERS 👑

XML elements and attributes get referred to via XPath expressions: elements are separated by /, and attributes are introduced by @. it's giving file-path energy, iykyk.

  • /backup — the root element of the XML file. mandatory, bestie. you literally cannot skip this one. 💀
  • /backup/@id — this is the ID that safekeep(1) uses to address this host. if you specify it, it overrides the default value derived from the filename. optional, defaults to the filename without the .backup extension. and pls, use of the default value is highly recommended. 🥰
  • /backup/@enabled — if specified and set to false or 0, it disables this host. it's a nicer way to disable a host without renaming the file — no messy file renames, we love to see it. optional, defaults to true.
  • /backup/host/@name — the name or IP address of the client. if you need to back up the box that the server is running from, you can set this to "localhost". and listen, this is different from leaving it blank — it will establish an SSH session and use the user specified by /backup/host/@user. optional, defaults to local access.
  • /backup/host/@port — the network port to use when connecting to the client. it must be a number and it gets passed to the network connection agent, usually SSH. optional, defaults to not passing any port specification at all.
  • /backup/host/@user — the user name to use when connecting to the client. this user must have read permissions for the files that will be backed up, so it most likely needs to be root. like, it's basically always root. optional, defaults to the value given by client.user in safekeep.conf.
  • /backup/host/@nice — the nice adjustment for the client. this setting is normally not all that important, since most of the load rests on the server side. NB: if you change this value, you will have to re-deploy the auth keys. optional, defaults to no nice level. 🙈
  • /backup/host/@key-ctrl — the private key used to establish the SSH connection to the client for the control channel. use of the default value is recommended. optional, defaults to ~/.ssh/safekeep-server-ctrl-key.
  • /backup/host/@key-data — the private key used to establish the SSH connection to the client for the data channel. use of the default value is recommended. optional, defaults to ~/.ssh/safekeep-server-data-key.
  • /backup/bandwidth/@overall — the client bandwidth limit for both upload and download. it's an integer number of KB/s (peep the NOTES section in safekeep.conf(5) for more info, bestie). optional, and it overrides bandwidth.overall in safekeep.conf(5) if specified.
  • /backup/bandwidth/@download — the client bandwidth limit for download (see /backup/bandwidth/@overall for more info). optional, overrides /backup/bandwidth/@overall if specified.
  • /backup/bandwidth/@upload — the client bandwidth limit for upload (see /backup/bandwidth/@overall for more info). optional, overrides /backup/bandwidth/@overall if specified.
  • /backup/repo/@path — the path under which the backups will be stored. relative paths are based on the base.dir setting from safekeep.conf(5). since the default value for base.dir is the user's home directory, in a typical installation the data will be stored under /var/lib/safekeep/<id>/. if the directory does not exist, safekeep(1) will attempt to create it automatically — and the backup will fail altogether if the directory can not be created. optional, defaults to the client ID, see /backup/@id. use of the default value is highly recommended.
⚠️ NOTE: if you must set this value explicitly, you must make sure that the path is not shared between different boxes — a shared repository path will result in data loss. like, actual data loss. not cute. 💀
  • /backup/repo/@retention — specifies the duration for which the backup data will be retained. the incremental backup information in the destination directory that has been around longer than the retention time will be removed. the value specified by this attribute is a time interval: an integer followed by the character s, m, h, D, W, M, or Y, indicating seconds, minutes, hours, days, weeks, months, or years respectively — or a number of these concatenated. for example, 32m means 32 minutes, and 3W2D10h7s means 3 weeks, 2 days, 10 hours, and 7 seconds. in this context, a month means 30 days, a year is 365 days, and a day is always 86400 seconds.

note that backups of deleted files are covered by this operation. so if you deleted a file two weeks ago, backed up immediately afterward, and then ran safekeep(1) with a retention of 10D today, no trace of that file would remain. gone. poof. 🦋

finally, file selection options don't affect removal of incremental data. optional, defaults to empty (unlimited retention).

  • /backup/options/special-files/@include — NOTE: THIS OPTION HAS BEEN DEPRECATED. go look at the data attributes below instead, bestie. one of "true" or "false". if "true", the dump file will include all special files, including device files, fifo files and socket files. optional, defaults to false.

NOTE: specification of no options is equivalent to false, but the inclusion of other options may cause the underlying backup defaults to be use. (yes, "to be use". we don't fix it, we respect it. 💅)

  • /backup/options/rdiff-backup/@append — append the specified options to the current rdiff-backup run. this is planned to be specific to the current rdiff-backup, and different options will be made available for other backends.
  • /backup/options/rdiff-backup/@exec_local — executable to be run on the local host. optional, defaults to rdiff-backup.
  • /backup/options/rdiff-backup/@exec_remote — executable to be run on the remote host. optional, defaults to rdiff-backup.
  • /backup/setup/@writable — a boolean (i.e. "true" or "false") to set mount as writable or not, including snapshots and bind mounts. this is normally not required, and, if set, overrides the system default — but it is overridden by a snapshot option. in general the system default is to create non-writable mount for both snapshots and bind mounts. optional for a <setup> element.
  • /backup/setup/dump/@type — one of "postgres" or "mysql". mandatory for a <dump> element. pick one, babe. 🌈
  • /backup/setup/dump/@db — name of the database to dump. if not specified, it defaults to all databases maintained in the RDBMS specified by type. optional, defaults to all databases.
  • /backup/setup/dump/@save-db-name — specify if CREATE DATABASE instructions are included in database dumps. if the option is not specified then the result defaults to what is natural for the default database dump function. if the option is "true" then CREATE DATABASE are added in all cases. if the option is "false" then no CREATE DATABASE statement is added.

NOTE: for Postgres it is not possible to suppress the CREATE DATABASE statement when dumping all databases, i.e. no single database named, in which case this option is ignored. optional, defaults to not set.

  • /backup/setup/dump/@dbuser — name of the database user to use while doing the dump. optional, defaults to whatever the database determines based on the system user.
  • /backup/setup/dump/@dbpasswd — password of the database user to use while doing the dump.
🚨 NB: this makes the DB password available in a plain text file. make sure you use appropriate read permissions on the backup configuration file to prevent unauthorized access to the password. like please. for me. 🙏

optional, it has no default value.

  • /backup/setup/dump/@options — extra options to be passed along to the dump command. this is database specific, and it is passed along as-is. please refer to your database documentation for possible values that you can pass along. optional, it has no default value.
  • /backup/setup/dump/@user — the system user the dump runs as, bestie. Heads up tho: using this means safekeep(1) has to be running as root on the client 😤. Optional, and it defaults to whichever user safekeep(1) is running as on the client side 💅
  • /backup/setup/dump/@file — the full path to the dump file over on the client host. This one's mandatory for a <dump> element, no skipping 🙅‍♀️
  • /backup/setup/dump/@cleanup — either "true" or "false". If it's "true", the dump file gets yeeted off the client system once the backup is done 🗑️. Ngl it's usually pointless to delete it, since it'll just get created again for every single backup — so like, you need the space either way. Optional, defaults to false.
  • /backup/setup/snapshot/@device — the path (device location) of the client LVM volume we snapshot before the backup kicks off. Important: the snapshot happens on the client machines, and it keeps your data in a consistent state for the whole backup process ✨. You can specify multiple snapshots — and the order matters, the associated filesystems get mounted in the order you give them 👑. Also: this feature needs safekeep(1) running as root on the client. Mandatory for a <snapshot> element.
  • /backup/setup/snapshot/@size — how big the snapshot is. There must be unallocated space on the volume group. Highly recommend making it like 15-20% of the original device's size 💖. You can give it as a percentage, e.g. 20%, which is literally 20% of the logical volume. Other values as listed for lvcreate(8) work too. Optional, defaults to snapshot.size as specified in safekeep.conf.
  • /backup/setup/snapshot/@tag — a list of tags to slap on the snapshot, via the --addtag argument to lvcreate(8) 🏷️. The @tag entry is a ,-separated list of tags, and an @ gets automatically added to each generated tag. Optional for a <snapshot> element.
  • /backup/setup/snapshot/@mountoptions — mount options used with the snapshot device. Normally you don't need this, the defaults suit routine usage 🎀. Optional for a <snapshot> element.
  • /backup/setup/snapshot/@writable — a boolean (so, "true" or "false") setting whether the snapshot mount is writable or not. Normally not required, and if you do set it, it overrides other settings from the setup option or the system default 💀. Optional for a <snapshot> element.
  • /backup/setup/script/@path — runs the script at this path on the client or server at certain steps of the backup process. It gets executed with four arguments:
    • Backup id (/backup/@id)
    • Backup step
    • Backup root directory (valid after creation of a snapshot) for client, or the safekeep backup directory for server
    • Run-on parameter, i.e. client or server

For client-side scripts, the location optionally consists of an optional host plus a mandatory path, separated by a ":", where the host part is either "client" or "server". If you don't specify a host part, it's first looked for on the client, and if it's not found there, then it's looked for on the server. If it's not found on either, a warning gets raised 🚨. Only one <script> element may be specified. See the CLIENT AND SERVER SCRIPTS section for more. Mandatory for a <script> element.

  • /backup/setup/script/@run-on — run the script on the "server" or the "client". Optional, defaults to client 🫶
  • /backup/data/@exclude-devices — one of "true" or "false". If "true", the dump file excludes all device files. Optional, defaults to false. NOTE: specifying no attributes is equivalent to false, but the inclusion of other options may cause the underlying backup defaults to be used 👀
  • /backup/data/@exclude-fifos — one of "true" or "false". If "true", the dump file excludes all fifos. Optional, defaults to false. NOTE: specifying no attributes is equivalent to false, but the inclusion of other options may cause the underlying backup defaults to be used 👀
  • /backup/data/@exclude-sockets — one of "true" or "false". If "true", the dump file excludes all sockets. Optional, defaults to false. NOTE: specifying no attribute is equivalent to false, but the inclusion of other options may cause the underlying backup defaults to be used 👀
  • /backup/data/exclude/@path — excludes the file or files matched by the path. If a directory gets matched, then the files under that directory are matched too 🦋. See the FILE SELECTION section for more.
  • /backup/data/include/@path — includes the file or files matched by the path. If a directory gets matched, then the files under that directory are matched too 🦋. See the FILE SELECTION section for more.
  • /backup/data/exclude/@glob — excludes the file or files matched by the shell pattern. If a directory gets matched, then the files under that directory are matched too 🌸. See the FILE SELECTION section for more.
  • /backup/data/include/@glob — includes the file or files matched by the shell pattern. If a directory gets matched, then the files under that directory are matched too 🌸. See the FILE SELECTION section for more.
  • /backup/data/exclude/@regexp — excludes the file or files matched by the regular expression. If a directory gets matched, then the files under that directory are matched too 💜. See the FILE SELECTION section for more.
  • /backup/data/include/@regexp — includes the file or files matched by the regular expression. If a directory gets matched, then the files under that directory are matched too 💜. See the FILE SELECTION section for more.

🌈 FILE SELECTION 🌈

Okay so safekeep(1) does file selection kinda like rdiff-backup(1) does — iconic behavior, honestly. When rdiff-backup runs, it searches through the source directory you gave it and backs up all the files specified by the file selection system ✨.

That file selection system is made up of a bunch of file selection conditions, which you set using one of the <include>/<exclude> elements. Each condition either matches or doesn't match a given file. A file gets included or excluded by the system when the first matching condition says include or exclude respectively — first match wins, periodt 💅. And if a file matches no include or exclude statement at all? It's excluded by default. Sorry babe 😭.

When backing up, if a file is excluded, safekeep(1) acts like that file straight up doesn't exist in the source directory 🙈.

For more on file selection semantics, please see rdiff-backup(1) — the lore is all there 📖.

🎀 CLIENT AND SCRIPTS 🎀

safekeep(1) supports optionally executing a script or program on the client or server systems at different steps while the backup is running 🏃‍♀️💨.

Right now, only a single script — either client-side or server-side — can be specified for a client.

For client-side scripts, the script may live on either the server or the client. If it's on the server, then the file gets copied over to the client into a temporary directory before it runs. Note that this directory lives wherever the system normally creates temporary files, and it's possible that executing scripts is disallowed there 😬. In that case, the recommendation is to use a client-based script instead. Also, the script is copied from the server line by line, so it is not suitable for passing binary files. Bestie. Do not. 💀

For server-side scripts, the script must be located on the server. Simple as that 🫶.

Note: specifying a script that doesn't exist is not considered an error — it's treated the same as not specifying a script at all. However, if the specified path does match a file or directory, the security tests listed below will run 👑

This script is executed with the following four arguments:

  • Safekeep step
  • Backup id
  • Backup root directory, which may be set during the creation of a snapshot for client, or the safekeep backup directory for server
  • Run-on parameter, i.e. client or server

For both client-side and server-side scripts, the steps currently defined and the tokens passed are:

  • STARTUP — prior to any execution. But if it exits with a non-zero status, that constitutes an error and the backup is aborted 🛑.
  • PRE-SETUP — prior to running any setup steps. A non-zero status is considered a warning and execution continues.
  • POST-SETUP — after setup, but prior to execution of the backup. A non-zero status is considered a warning, and execution continues.
  • POST-BACKUP — after execution of the backup. A non-zero status is considered a warning, and execution continues.
  • POST-SCRUB — after execution of a server cleanup step, normally only seen after a backup failure. A non-zero status is considered a warning, and execution continues.

Due to security considerations, a number of checks are made on this script prior to execution, and failure of any of these steps will cause the backup for that client to be aborted 😤. The following tests are applied prior to each execution of the script (so like, multiple times per backup), in order:

  • script is a regular file, not a directory or special file
  • script is executable by the user running on the client system
  • script is owned by root or the user running on the client system
  • script is NOT writable by anyone except the script owner
Note: no test is made on the ownership of the parent directory or any other directories. Just so you know 👀

🗂️ FILES 🗂️

/etc/safekeep/backup.d/
~/.safekeep/backup.d/

👀 SEE ALSO 👀

safekeep(1), safekeep.conf(5), rdiff-backup(1), lvcreate(8)

💖 AUTHOR 💖

This man page was originally written by Dimi Paun <dimi@lattica.com[1]>. Thank you Dimi, we love you fr fr 🫶

📝 NOTES 📝

  1. dimi@lattica.com mailto:dimi@lattica.com

And that's the whole vibe check bestie — this is safekeep, dated 09/10/2023, and you just read SAFEKEEP.BACKUP(5) ✨🎀 Go forth and back up responsibly, mwah 💅

📦 where this page comes from