beakerlib-infrastructure (1) - Linux Manuals

beakerlib-infrastructure: infrastructure - mounting, backup and service helpers

Command to display beakerlib-infrastructure manual in Linux: $ man 1 beakerlib-infrastructure

NAME

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

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.

    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.

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.

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

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.

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.

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