SAFEKEEP(1)

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

okay so this is safekeep from the SafeKeep Manual, and bestie I need you to actually read this one because she's doing a lot 💅✨

💖 NAME 💖

safekeep — client/server backup script. that's the whole name. she's simple like that 🎀

🌸 SYNOPSIS 🌸

safekeep --server [-q] [-v] [--noemail] [--force] [-c file] [--cleanup]
[--tempdir=<tempdir>] <clientid>*

safekeep --keys [-q] [-v] [--noemail] [-c file] [-i file] [--status]
[--print] [--deploy] <clientid>*

safekeep --list [-q] [-v] [--noemail] [-c file] [--increments]
[--parsable-output] [--sizes] [--changed=<time>] [--at-time=<time>]
<clientid>*

safekeep --client [--cleanup]

safekeep -h | -V

🦋 DESCRIPTION 🦋

okay so SafeKeep is a client/server backup script, and what she does is take rdiff-backup (iconic, love her) and wrap her up in simple configuration and simple use. it's giving "glow-up for a tool that was already serving" 💅

she can run in server mode, client mode, SSH key management mode, or list mode. four modes, four vibes, all main character energy.

in server mode, SafeKeep parses a set of configuration files which defines a set of backup clients. for each backup client, SafeKeep connects to the client host over SSH (using a public key authentification system previously set up using safekeep --keys --deploy) and launches safekeep --client onto the client host. the client does the real backup and sends the data over SSH to the SafeKeep server, which stores it in the specified location. so like. the server is the manager, the client does the actual work. love a delegation moment 👑

in client mode, SafeKeep does a few setup steps, depending on the client configuration (database dump, LVM device snapshot), then backups the client data using rdiff-backup, and then cleanups the state (removes the database dumps, deactivates the LVM snapshots). get ready, do the thing, tidy up. she's organized fr fr 🧹

⚠️ heads up bestie: the client mode of SafeKeep should never be invoked manually. this mode is meant to be used only by the server mode of SafeKeep. the only exception to this is if run with the --cleanup option, which is used to remove LVM snapshots and mounts created by Safekeep, after a crash or some other failure, without a connection to the server. normally this cleanup would be performed through the server command safekeep --server --cleanup. so like. don't touch it unless you're cleaning up a mess 💀

the SSH key management mode is a helper mode for deploying or verifying the setup of the SSH authentification keys. she's the little assistant holding the keys 🔑

in list mode, SafeKeep lists the details of existing archives. this is basically an interface to the relevant options for rdiff-backup. just a cute little front end. we stan a wrapper ✨

in server, keys management and list mode, you can restrict the operation to a specific set of clients by listing the desired client IDs as arguments. if no client ID is given, SafeKeep will operate over all known clients. no thoughts, all clients 💜

each mode accepts a few options as described below. yes, there's a whole menu. we'll get through it together 🫶

🌈 OPERATION MODE 🌈

  • --server — selects the server mode 👑
  • --client — selects the client mode. this should never be invoked manually — the clients are started automatically by the server on the client machines using SSH 🙈
  • --keys — selects the SSH key management mode 🔑
  • --list — selects the list mode 📋
⚠️ important: please note that you must always specify an operation mode. earlier versions used do default to --server mode, but that proved to work out poorly in practice. so yeah. we don't do that anymore 💀

🎀 GENERAL OPTIONS 🎀

  • -c, --conf=FILE — specifies the configuration file location. if not specified at all, SafeKeep will default to /etc/safekeep/safekeep.conf, or optionally in ~/.safekeep/safekeep.conf for non-root users, if it exists. simply using this default is the recommended usage. she's literally telling you to just use the default. listen to her 🫶
  • -h, --help — selects the help mode, in which safekeep prints out the online help and exits 🌸
  • -V, --version — selects the version mode, in which safekeep prints out the version number and exits ⭐
  • -q, --quiet — decreases the verbosity level. can be specified more than once. shhh 🤫
  • -v, --verbose — increases the verbosity level. can be specified more than once. tell me everything 👀
  • --noemail — disables the sending of email, no matter what the settings within the configuration file. she said no inbox today 🚫📧

🔥 SERVER OPTIONS 🔥

  • --force — pass the --force option to rdiff-backup, allowing it to overwrite the backup directory metadata.
⚠️ this option is potentially dangerous, and should only be used if the backup directory becomes corrupt, and rdiff-backup error logs tells you to use this option. like, she's not playing. read the error log before you touch this 💀
  • --cleanup — remove LVM snapshots and mounts left by Safekeep after a crash or other failure. this will run also run the standard cleanup processes, such as the removal of an DB dumps, and forces a consistency check of the rdiff-backup destination directory. this is the prefered cleanup procedure and can be run with no danger of corrupting the system if there is nothing to cleanup. so like, safe to run even when there's nothing to do. we love a no-op that doesn't hurt anybody 🧹✨
  • --tempdir TEMPDIR — specifes a TEMPDIR for use with ‘rdiff-backup’. this overrides any TEMPDIR specified in the ‘safekeep.conf’. she has a spot for her stuff and it's this spot 🗂️

🦋 CLIENT OPTIONS 🦋

  • --cleanup — remove LVM snapshots and mounts left after a crash or other failure from the local system. unlike the equivalent --server option, it does not do any other of the standard cleanups.
⚠️ this option should only be used when it is not possible to refer to the server — for example, when the network connection to the server is no longer available. it's the emergency-only cleanup, iykyk 🙈

🔑 KEYS OPTIONS 🔑

  • -i FILE — forces ssh(1) to use FILE for the identity (private key) in RSA/DSA authentication. if not specified, ssh(1) will use its default identity files. pick your key, bestie 🔐
  • --status — display the key status for the clients. it is implied if no other option is specified. in effect this option prints the steps that will be taken when the keys are deployed to the client. it's a vibe check on your keys before you commit 💅
  • --print — display the authorization keys for the clients. this is useful in case you want to manually copy it into the client’s ~/.ssh/authorized_keys file. this option is seldom useful. she said it herself. seldom. not never, but like. seldom 🫠
  • --deploy — deploy the authorization keys on the clients. go go go 🚀

📋 LIST OPTIONS 📋

  • --increments — pass the --list-increments option to rdiff-backup, to list the number and date of partial incremental backups for the given or all clients. this is the default list option ⭐
  • --parseable-output — pass the --parsable-output option to rdiff-backup to generate output in a format that is easily parsed by other programs. yes the man page spells it two different ways, don't come for me, I'm reporting it exactly as written 💀 this currently only works with the --increments.
  • --sizes — pass the --list-increment-sizes option to rdiff-backup, to list the total size of all increment and mirror files by time for the given or all clients. note, this may take some time. she's doing math, give her a minute 😭
  • --changed=TIME — pass the --list-changed-since option for TIME to rdiff-backup, to list the files changed since TIME for the given clients. TIME is passed directly to rdiff-backup. note, this may take some time and generate considerable output. also, unlike rdiff-backup the is no option to select sub-directories. prepare for a wall of text ngl 📜
  • --at-time=TIME — pass the --list-at-time option for TIME to rdiff-backup, to list the files in the archive that were present at the given time for the given clients. note, this may take some time and generate considerable output. also, unlike rdiff-backup the is no option to select sub-directories. same energy, different time machine 🕰️

🌸 CONFIGURATION 🌸

normally the configuration files are placed in the /etc/safekeep/backup.d/ directory, or optionally in ~/.safekeep/backup.d/ for non-root users, from where they will get picked up automatically by SafeKeep. yes, she finds them herself. she's proactive 💅

each backup client is described by a configuration file in XML format. the minimum configuration file is:

<backup>
  <host name="my_workstation" />
</backup>

this will simply backup all relevant files (excluding temporary files, caches, etc) from the client with the address my_workstation. tiny file, big job. she ate 🍽️

a more realistic example:

<backup>
  <host name="my_workstation" />
  <repo retention="10D" />
  <setup>
      <dump type="postgres" dbuser="postgres" file="/var/lib/pgsql/backups/all_dbs" />
      <dump type="mysql" user="mysql" dbuser="dbbackup" db="adatabase" file="/var/backups/dumps/adatabase_dbs" />
      <dump type="mysql" user="mysql" dbuser="dbbackup" db="mysql" file="/var/backups/dumps/mysql_dbs" cleanup="true" />
      <snapshot device="/dev/mapper/VolGroup00-LogVol00" size="500M" />
  </setup>

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

    <include path="/etc"/>

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

    <include path="/root"/>

    <include path="/srv"/>

    <exclude path="/var/cache"/>
    <exclude path="/var/lock"/>
    <exclude path="/var/run"/>
    <exclude path="/var/tmp"/>
    <include path="/var/named/chroot/etc"/>
    <include path="/var/named/chroot/var/named"/>
    <exclude path="/var/named/chroot"/>
    <include path="/var"/>

    <exclude path="/"/>
  </data>
</backup>

in this case, SafeKeep will dump all databases managed by PostgreSQL, snapshot the disk via LVM, and proceed to backup /etc, /home, /root, /srv, /var, while excluding some unneeded files and directories. older data will be retained for 10 days. look at her go. multi-tasking queen 👑

for full reference documentation of the configuration format, see safekeep.backup(5). she has lore. read the lore 📖

🎀 CLIENT IDS 🎀

normally the client IDs are generated automatically from the configuration filenames without the extension. e.g. if a configuration file is named my_workstation.conf, the client ID becomes my_workstation. cute, right? for more information on this topic, see safekeep.backup(5). again with the lore 🦋

🔑 KEY DEPLOYMENT 🔑

the safekeep(1) server needs to access the clients in order to conduct the backup. to that end, it establishes two ssh(1) pipes: one for control, and one for data. two pipes, because one is for talking and one is for the actual haul 📦

to simplify the deployment of the keys, safekeep(1) has a key deploy mode. thoughtful of her 💅

when deploying keys using the built-in key management functionality, safekeep(1) needs to be invoked as the user under which it will function as a server. by default, that user is safekeep. for extra security, you can not login into that account, so you have to invoke safekeep(1) as root:

[root@yourbox ~] # safekeep --keys --deploy

root energy only for this one, bestie 👑

⭐ RESTORING ⭐

since safekeep(1) is built around rdiff-backup(1), it doesn’t have any built-in restore capabilities. it simply relies on rdiff-backup to perform this task. she said "restoring is not my department, that's my girl rdiff-backup" 🫶

to do so, you just need to know the directory where the data is actually stored. in a typical installation, for a box configured via the file /etc/safekeep/backup.d/mybox.backup, the data will be stored under /var/lib/safekeep/mybox/. please refer to safekeep.backup(5) for more information on this matter. (lore again. told you.) 📚

once you have determined where the data will be stored (we’ll continue the example above), all you have to do is run rdiff-backup:

# rdiff-backup -r 1s /var/lib/safekeep/mybox my-restore-dir

you will be able to find more information on the restore procedure in the rdiff-backup(1) man page. that's her man page, not this one. go read it, she's great 💜

🎀 FILE SELECTION 🎀

Okay bestie, this is the part where you really have to pay attention, because this is where everyone messes up. 💀

The include/exclude directives that control file selection are matched in the order they appear in the configuration file, and the first one that matches decides whether the file gets included or excluded. First match wins, periodt. 👑

So because of that, you have to put the more specific ones first — otherwise the more generic specs will always win and your fine-tuned rules will do absolutely nothing. 😭

Like, watch this. This is the ✨wrong✨ way:

...
    <include path="/home"/>
    <exclude path="/home/joe"/>
...

This will NOT do what you expect, and I cannot stress this enough. 😤 Because /home matches before /home/joe does, every single file under /home gets included. Yes, including Joe's. 🫠

The correct way is to just flip the two around, bestie:

...
    <exclude path="/home/joe"/>
    <include path="/home"/>
...

Specific first, generic second. That's the whole vibe check. 🦋

Please see safekeep.backup(5) for all the deets on file selection — it has the whole story. 📖

✨ SEE ALSO ✨

Go read them, they're giving main character energy too. 💅

💖 AUTHOR 💖

Written by Dimi Paun <dimi@lattica.com> and Stelian Pop <stelian@lattica.com>. Legends, honestly. 👑

🧚 NOTES 🧚

  1. dimi@lattica.com — mailto:dimi@lattica.com
  2. stelian@lattica.com — mailto:stelian@lattica.com

That's the whole page, bestie — go back up files with confidence now. 🌸 This was safekeep, dated 09/10/2023, and it ate, no cap. 💜🫶

📦 where this page comes from