beakerlib-infrastructure man page

BeakerLib — infrastructure — mounting, backup and service helpers

Description

BeakerLib functions providing checking and mounting NFS shares, backing up and restoring files and controlling running services.

Functions

Mounting

rlMount

Create mount point (if neccessary) and mount a 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.

rlCheckMount mountpoint
rlCheckMount server mountpoint
rlCheckMount server share mountpoint
mountpoint
Local mount point.
server
NFS server hostname
share
Shared direcotry name

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

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.

rlAssertMount mountpoint
rlAssertMount server mountpoint
rlAssertMount server share mountpoint
mountpoint
Local mount point.
server
NFS server hostname
share
Shared directory name

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.

rlHash, rlUnhash

Hashes/Unhashes given string.

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

Defaults to hex. Default algorithm can be override using global variable rlHashAlgorithm.
--stdin
Get the string from stdin.
STRING
String to be hashed/unhashed.

Returns 0 if success.

Example with --clean:

hash=rlHash "text"

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.

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 (have to be first option of the command), then file/dir backuped using this command (provided in next options) will be (recursively) removed before we will restore it. This option implies --missing-ok, this 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 backedup files were not successfuly copied. Returns 8 if backed up files does not exist. This can be suppressed based on other options.

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".

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.

Services

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

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).

rlServiceRestore service [service...]
service
Name of the service(s) to restore to original state.

Returns number of services which failed to get back to their original state; 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.

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.

rlSocketRestore socket [socket...]
socket
Name of the socket(s) to restore to original state.

Returns 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 as it is the test watcher that executes the actual cleanup script. 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.

Since the cleanup script runs as a separate script, the environment IS NOT SHARED, except for BEAKERLIB_DIR, which is exported explicitly upon cleanup script generation - that means no other variables are shared between the test and the cleanup script, therefore make sure to add only fully expanded strings, not variable names.

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>

Info

2015-10-29 perl v5.22.1 User Contributed Perl Documentation