beakerlib-infrastructure - Man Page

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 and if it uses specific mount options.

    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.

    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

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.

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

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.

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

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). If rlServiceStart was called on already running service, rlServiceRestore will restart the service when restoring its state.

    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.

    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.

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

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.