INFRASTRUCTURE.SH(1)

🎀 NAME 🎀

BeakerLib - infrastructure - mounting, backup and service helpers. This is the INFRASTRUCTURE.SH(1) page, bestie, and it's all about the helper functions.

🦋 DESCRIPTION 🦋

Okay so BeakerLib functions here are giving checking and mounting NFS shares, backing up and restoring files, and controlling running services. That's the whole vibe. ✨

💅 FUNCTIONS 💅

🌸 Mounting 🌸

rlMount

Create the mount point (if neccessary) and mount an NFS share. 🫶

rlMount [-o MOUNT_OPTS] server share mountpoint

• server — NFS server hostname.
• share — Shared directory name.
• mountpoint — Local mount point.
• MOUNT_OPTS — Mount options.

Returns 0 if mounting the share was successful.

rlCheckMount

Check either if a directory is a mountpoint, if it is a mountpoint to a specific server, or if it is a mountpoint to a specific export on a specific server and if it uses specific mount options. Vibe check, but for mounts. 💅

rlCheckMount [-o MOUNT_OPTS] mountpoint
rlCheckMount [-o MOUNT_OPTS] server mountpoint
rlCheckMount [-o MOUNT_OPTS] server share mountpoint

• mountpoint — Local mount point.
• server — NFS server hostname
• share — Shared directory name
• MOUNT_OPTS — Mount options to check (comma separated list)

With one parameter, returns 0 when specified directory exists and is a mountpoint. With two parameters, returns 0 when specific directory exists, is a mountpoint and an export from specific server is mounted there. With three parameters, returns 0 if a specific shared directory is mounted on a given server on a given mountpoint.

If the -o option is provided, returns 0 if the mountpoint uses all the given options, 2 otherwise.

rlAssertMount

Assertion making sure that given directory is a mount point, if it is a mountpoint to a specific server, or if it is a mountpoint to a specific export on a specific server and if it uses specific mount options. It asserts, bestie. ✅

rlAssertMount [-o MOUNT_OPTS]  mountpoint
rlAssertMount [-o MOUNT_OPTS]  server mountpoint
rlAssertMount [-o MOUNT_OPTS]  server share mountpoint

• mountpoint — Local mount point.
• server — NFS server hostname
• share — Shared directory name
• MOUNT_OPTS — Mount options to check (comma separated list)

With one parameter, returns 0 when specified directory exists and is a mountpoint. With two parameters, returns 0 when specific directory exists, is a mountpoint and an export from specific server is mounted there. With three parameters, returns 0 if a specific shared directory is mounted on a given server on a given mountpoint. Asserts PASS when the condition is true.

If the -o option is provided, asserts PASS if the above conditions are met and the mountpoint uses all the given options.

rlHash, rlUnhash

Hashes/Unhashes given string and prints the result to stdout. 🔐

rlHash [--decode] [--algorithm HASH_ALG] --stdin|STRING
rlUnhash [--algorithm HASH_ALG] --stdin|STRING

• --decode — Unhash given string.
• --algorithm — Use given hash algorithm. Currently supported algorithms:
  • base64
  • base64_ — this is standard base64 where '=' is replaced by '_'
  • hex
• --stdin — Get the string from stdin.
• STRING — String to be hashed/unhashed.

Defaults to hex. Default algorithm can be override using global variable rlHashAlgorithm.

Returns 0 if success.

🎀 Backup and Restore 🎀

rlFileBackup

Create a backup of files or directories (recursive). Can be used multiple times to add more files to backup. Backing up an already backed up file overwrites the original backup. Save it for later, bestie. 💾

rlFileBackup [--clean] [--namespace name] [--missing-ok|--no-missing-ok] file [file...]

You can use rlRun for asserting the result but keep in mind meaning of exit codes, especialy exit code 8, if using without --clean option.

• --clean — If this option is provided (has to be the first option of the command), then file/dir backed up using this command (provided in next options) will be (recursively) removed before we restore it. This option implies --missing-ok, which can be overridden by --no-missing-ok.
• --namespace name — Specifies the namespace to use. Namespaces can be used to separate backups and their restoration.
• --missing-ok — Do not raise an error in case of missing file to backup.
• --no-missing-ok — Do raise an error in case of missing file to backup. This is useful with --clean. This behaviour can be globally set by global variable BEAKERLIB_FILEBACKUP_MISSING_OK=false.
• file — Files and/or directories to be backed up.

Returns 0 if the backup was successful. Returns 1 if parsing of parameters was not successful. Returns 2 if no files specification was provided. Returns 3 if BEAKERLIB_DIR variable is not set, e.g. rlJournalStart was not executed. Returns 4 if creating of main backup destination directories was not successful. Returns 5 if creating of file specific backup destination directories was not successful. Returns 6 if the copy of backed up files was not successful. Returns 7 if attributes of backed up files were not successfuly copied. Returns 8 if backed up files do not exist. This can be suppressed based on other options.

Heads up: exit code 8 is the missing-file one, and it can be suppressed based on other options. iykyk 👀

Example with --clean:

touch cleandir/aaa
rlRun "rlFileBackup --clean cleandir/"
touch cleandir/bbb
ls cleandir/
aaa   bbb
rlRun "rlFileRestore"
ls cleandir/
aaa

rlFileRestore

Restore backed up files to their original location. rlFileRestore does not remove new files appearing after backup has been made. If you don't want to leave anything behind just remove the whole original tree before running rlFileRestore, or see --clean option of rlFileBackup. Put it back, put it back. 🔁

rlFileRestore [--namespace name]

You can use rlRun for asserting the result.

• --namespace name — Specifies the namespace to use. Namespaces can be used to separate backups and their restoration.

Returns 0 if backup dir is found and files are restored successfully.

Return code bits meaning:

XXXXX
|||||
||||\_ error parsing parameters
|||\__ could not find backup directory
||\___ files cleanup failed
|\____ files restore failed
\_____ no files were restored nor cleaned

💖 Services 💖

Following routines implement comfortable way how to start/stop system services with the possibility to restore them to their original state after testing. Service girlies, rise. 🧚

rlServiceStart

Make sure the given service is running with fresh configuration. (Start it if it is stopped and restart if it is already running.) In addition, when called for the first time, the current state is saved so that the service can be restored to its original state when testing is finished, see rlServiceRestore. 🔥

rlServiceStart service [service...]

• service — Name of the service(s) to start.

Returns number of services which failed to start/restart; thus zero is returned when everything is OK.

rlServiceStop

Make sure the given service is stopped. Stop it if it is running and do nothing when it is already stopped. In addition, when called for the first time, the current state is saved so that the service can be restored to its original state when testing is finished, see rlServiceRestore. 💅

rlServiceStop service [service...]

• service — Name of the service(s) to stop.

Returns number of services which failed to become stopped; thus zero is returned when everything is OK.

rlServiceRestore

Restore given service into its original state (before the first rlServiceStart or rlServiceStop was called). If rlServiceStart was called on already running service, rlServiceRestore will restart the service when restoring its state. Rewind the timeline. ⏪

rlServiceRestore [service...]

• service — Name of the service(s) to restore to original state. All services will be restored in reverse order if no service name is given.

Returns number of services which failed to get back to their original state; thus zero is returned when everything is OK.

rlServiceStatus

Print status (output of service SERVICE status or systemctl status SERVICE) of given SERVICE. Status check, bestie. 🩺

rlServiceStatus SERVICE [SERVICE...]

• SERVICE — The service to get the status of.

Returns service status return code of the last provided SERVICE.

rlServiceEnable

Enables selected services if needed, or does nothing if already enabled. In addition, when called for the first time, the current state is saved so that the service can be restored to its original state when testing is finished, see rlServiceRestore. ✨

rlServiceEnable service [service...]

• service — Name of the service(s) to enable.

Returns number of services which failed enablement; thus zero is returned when everything is OK.

rlServiceDisable

Disables selected services if needed, or does nothing if already disabled. In addition, when called for the first time, the current state is saved so that the service can be restored to its original state when testing is finished, see rlServiceRestore. 🚫

rlServiceDisable service [service...]

• service — Name of the service(s) to disable.

Returns number of services which failed disablement; thus zero is returned when everything is OK.

🦋 Sockets 🦋

Following routines implement comfortable way how to start/stop system sockets with the possibility to restore them to their original state after testing. Socket slay. 🧦

rlSocketStart

Make sure the given socket is running. (Start it if stopped, leave it if already running.) In addition, when called for the first time, the current state is saved so that the socket can be restored to its original state when testing is finished, see rlSocketRestore. 🌟

rlSocketStart socket [socket...]

• socket — Name of the socket(s) to start.

Returns number of sockets which failed to start/restart; thus zero is returned when everything is OK.

rlSocketStop

Make sure the given socket is stopped. Stop it if it is running and do nothing when it is already stopped. In addition, when called for the first time, the current state is saved so that the socket can be restored to its original state when testing is finished, see rlSocketRestore. 💤

rlSocketStop socket [socket...]

• socket — Name of the socket(s) to stop.

Returns number of sockets which failed to become stopped; thus zero is returned when everything is OK.

rlSocketRestore

Restore given socket into its original state (before the first rlSocketStart or rlSocketStop was called). 🫶

🚨 Warning !!! Xinetd process [even though it might have been used] is NOT restored. It is recommended to call rlServiceRestore xinetd as well.

Here's the synopsis, bestie:

rlSocketRestore socket [socket...]

• socket — Name of the socket(s) to restore to original state.

It returns the number of sockets which failed to get back to their original state; thus zero is returned when everything is OK ✨.

---

🧹 Cleanup management 🧽

Cleanup management works with a so-called cleanup buffer, which is a temporary representation of what should be run at cleanup time, and a final cleanup script (executable), which is generated from this buffer and wraps it using BeakerLib essentials (journal initialization, cleanup phase, ...). The cleanup script must always be updated on an atomic basis (filesystem-wise) to allow an asynchronous execution by a third party (ie. test watcher) 👀.

The test watcher usage is mandatory for the cleanup management system to work properly, because it is the test watcher that executes the actual cleanup script. A limited, catastrophe-avoiding mechanism is in place even when the test is not run in test watcher, but that should be seen as a backup and such situation is to be avoided whenever possible 🫶.

The cleanup script shares all environment (variables, exported or not, and functions) with the test itself. The cleanup append/prepend functions "sample" or "snapshot" the environment at the time of their call — IOW any changes to the test environment are synchronized to the cleanup script only upon calling append/prepend. When the append/prepend functions are called within a function which has local variables, these will appear as global in the cleanup 👀.

While the cleanup script receives $PWD from the test, its working dir is set to the initial test execution dir even if $PWD contains something else. It is impossible to use relative paths inside cleanup reliably — certain parts of the cleanup might have been added under different current directories (CWDs). Therefore always use absolute paths in append/prepend cleanup or make sure you never cd elsewhere (ie. to a TmpDir) 📁.

🧵 rlCleanupAppend

Appends a string to the cleanup buffer and recreates the cleanup script.

rlCleanupAppend string

Returns 0 if the operation was successful, 1 otherwise.

🧵 rlCleanupPrepend

Prepends a string to the cleanup buffer and recreates the cleanup script.

rlCleanupPrepend string

Returns 0 if the operation was successful, 1 otherwise.

---

🌟 AUTHORS 🌟

• Petr Muller — pmuller@redhat.com
• Jan Hutar — jhutar@redhat.com
• Petr Splichal — psplicha@redhat.com
• Ales Zelinka — azelinka@redhat.com
• Karel Srot — ksrot@redhat.com

---

That's the whole INFRASTRUCTURE.SH(1) page, bestie 💅 Signing off from perl v5.32.1, dated 2026-04-07 — iconic, no cap 💖✨🎀