1INFRASTRUCTURE.SH(1) User Contributed Perl Documentation INFRASTRUCTURE.SH(1)
2
6 BeakerLib - infrastructure - mounting, backup and service helpers
7
9 BeakerLib functions providing checking and mounting NFS shares, backing
10 up and restoring files and controlling running services.
11
13 Mounting
14 rlMount
15 Create mount point (if neccessary) and mount a NFS share.
17 rlMount [-o MOUNT_OPTS] server share mountpoint
19 server
21 NFS server hostname.
22 share
24 Shared directory name.
25 mountpoint
27 Local mount point.
28 MOUNT_OPTS
30 Mount options.
31 Returns 0 if mounting the share was successful.
33 rlCheckMount
35 Check either if a directory is a mountpoint, if it is a mountpoint to a
37 specific server, or if it is a mountpoint to a specific export on a
38 specific server and if it uses specific mount options.
39 rlCheckMount [-o MOUNT_OPTS] mountpoint
41 rlCheckMount [-o MOUNT_OPTS] server mountpoint
42 rlCheckMount [-o MOUNT_OPTS] server share mountpoint
43 mountpoint
45 Local mount point.
46 server
48 NFS server hostname
49 share
51 Shared directory name
52 MOUNT_OPTS
54 Mount options to check (comma separated list)
55 With one parameter, returns 0 when specified directory exists and is a
57 mountpoint. With two parameters, returns 0 when specific directory
58 exists, is a mountpoint and an export from specific server is mounted
59 there. With three parameters, returns 0 if a specific shared directory
60 is mounted on a given server on a given mountpoint
61 If the -o option is provided, returns 0 if the mountpoint uses all the
63 given options, 2 otherwise.
64 rlAssertMount
66 Assertion making sure that given directory is a mount point, if it is a
68 mountpoint to a specific server, or if it is a mountpoint to a specific
69 export on a specific server and if it uses specific mount options.
70 rlAssertMount [-o MOUNT_OPTS] mountpoint
72 rlAssertMount [-o MOUNT_OPTS] server mountpoint
73 rlAssertMount [-o MOUNT_OPTS] server share mountpoint
74 mountpoint
76 Local mount point.
77 server
79 NFS server hostname
80 share
82 Shared directory name
83 MOUNT_OPTS
85 Mount options to check (comma separated list)
86 With one parameter, returns 0 when specified directory exists and is a
88 mountpoint. With two parameters, returns 0 when specific directory
89 exists, is a mountpoint and an export from specific server is mounted
90 there. With three parameters, returns 0 if a specific shared directory
91 is mounted on a given server on a given mountpoint. Asserts PASS when
92 the condition is true.
93 If the -o option is provided, asserts PASS if the above conditions are
95 met and the mountpoint uses all the given options.
96 rlHash, rlUnhash
98 Hashes/Unhashes given string and prints the result to stdout.
100 rlHash [--decode] [--algorithm HASH_ALG] --stdin|STRING
102 rlUnhash [--algorithm HASH_ALG] --stdin|STRING
103 --decode
105 Unhash given string.
106 --algorithm
108 Use given hash algorithm. Currently supported algorithms:
109 base64
110 base64_ - this is standard base64 where '=' is replaced by '_'
111 hex
112 Defaults to hex. Default algorithm can be override using global
114 variable rlHashAlgorithm.
115 --stdin
117 Get the string from stdin.
118 STRING
120 String to be hashed/unhashed.
121 Returns 0 if success.
123 Backup and Restore
125 rlFileBackup
126 Create a backup of files or directories (recursive). Can be used
128 multiple times to add more files to backup. Backing up an already
129 backed up file overwrites the original backup.
130 rlFileBackup [--clean] [--namespace name] [--missing-ok|--no-missing-ok] file [file...]
132 You can use "rlRun" for asserting the result but keep in mind meaning
134 of exit codes, especialy exit code 8, if using without --clean option.
135 --clean
137 If this option is provided (have to be first option of the
138 command), then file/dir backuped using this command (provided in
139 next options) will be (recursively) removed before we will restore
140 it. This option implies --missing-ok, this can be overridden by
141 --no-missing-ok.
142 --namespace name
144 Specifies the namespace to use. Namespaces can be used to separate
145 backups and their restoration.
146 --missing-ok
148 Do not raise an error in case of missing file to backup.
149 --no-missing-ok
151 Do raise an error in case of missing file to backup. This is
152 useful with --clean. This behaviour can be globally set by global
153 variable BEAKERLIB_FILEBACKUP_MISSING_OK=false.
154 file
156 Files and/or directories to be backed up.
157 Returns 0 if the backup was successful. Returns 1 if parsing of
159 parameters was not successful. Returns 2 if no files specification was
160 provided. Returns 3 if BEAKERLIB_DIR variable is not set, e.g.
161 rlJournalStart was not executed. Returns 4 if creating of main backup
162 destination directories was not successful. Returns 5 if creating of
163 file specific backup destination directories was not successful.
164 Returns 6 if the copy of backed up files was not successful. Returns 7
165 if attributes of backedup files were not successfuly copied. Returns 8
166 if backed up files do not exist. This can be suppressed based on other
167 options.
168 Example with --clean:
170 touch cleandir/aaa
172 rlRun "rlFileBackup --clean cleandir/"
173 touch cleandir/bbb
174 ls cleandir/
175 aaa bbb
176 rlRun "rlFileRestore"
177 ls cleandir/
178 aaa
179 rlFileRestore
181 Restore backed up files to their original location. "rlFileRestore"
183 does not remove new files appearing after backup has been made. If you
184 don't want to leave anything behind just remove the whole original tree
185 before running "rlFileRestore", or see "--clean" option of
186 "rlFileBackup".
187 rlFileRestore [--namespace name]
189 You can use "rlRun" for asserting the result.
191 --namespace name
193 Specifies the namespace to use. Namespaces can be used to separate
194 backups and their restoration.
195 Returns 0 if backup dir is found and files are restored successfully.
197 Return code bits meaning XXXXX
199 |||||
200 ||||\_ error parsing parameters
201 |||\__ could not find backup directory
202 ||\___ files cleanup failed
203 |\____ files restore failed
204 \_____ no files were restored nor cleaned
205 Services
207 Following routines implement comfortable way how to start/stop system
208 services with the possibility to restore them to their original state
209 after testing.
210 rlServiceStart
212 Make sure the given "service" is running with fresh configuration.
214 (Start it if it is stopped and restart if it is already running.) In
215 addition, when called for the first time, the current state is saved so
216 that the "service" can be restored to its original state when testing
217 is finished, see "rlServiceRestore".
218 rlServiceStart service [service...]
220 service
222 Name of the service(s) to start.
223 Returns number of services which failed to start/restart; thus zero is
225 returned when everything is OK.
226 rlServiceStop
228 Make sure the given "service" is stopped. Stop it if it is running and
230 do nothing when it is already stopped. In addition, when called for the
231 first time, the current state is saved so that the "service" can be
232 restored to its original state when testing is finished, see
233 "rlServiceRestore".
234 rlServiceStop service [service...]
236 service
238 Name of the service(s) to stop.
239 Returns number of services which failed to become stopped; thus zero is
241 returned when everything is OK.
242 rlServiceRestore
244 Restore given "service" into its original state (before the first
246 "rlServiceStart" or "rlServiceStop" was called). If "rlServiceStart"
247 was called on already running "service", "rlServiceRestore" will
248 restart the "service" when restoring its state.
249 rlServiceRestore [service...]
251 service
253 Name of the service(s) to restore to original state. All services
254 will be restored in reverse order if no service name is given.
255 Returns number of services which failed to get back to their original
257 state; thus zero is returned when everything is OK.
258 rlServiceEnable
260 Enables selected services if needed, or does nothing if already
262 enabled. In addition, when called for the first time, the current
263 state is saved so that the "service" can be restored to its original
264 state when testing is finished, see "rlServiceRestore".
265 rlServiceEnable service [service...]
267 service
269 Name of the service(s) to enable.
270 Returns number of services which failed enablement; thus zero is
272 returned when everything is OK.
273 rlServiceDisable
275 Disables selected services if needed, or does nothing if already
277 disabled. In addition, when called for the first time, the current
278 state is saved so that the "service" can be restored to its original
279 state when testing is finished, see "rlServiceRestore".
280 rlServiceDisable service [service...]
282 service
284 Name of the service(s) to disable.
285 Returns number of services which failed disablement; thus zero is
287 returned when everything is OK.
288 Sockets
290 Following routines implement comfortable way how to start/stop system
291 sockets with the possibility to restore them to their original state
292 after testing.
293 rlSocketStart
295 Make sure the given "socket" is running. (Start it if stopped, leave it
297 if already running.) In addition, when called for the first time, the
298 current state is saved so that the "socket" can be restored to its
299 original state when testing is finished, see "rlSocketRestore".
300 rlSocketStart socket [socket...]
302 socket
304 Name of the socket(s) to start.
305 Returns number of sockets which failed to start/restart; thus zero is
307 returned when everything is OK.
308 rlSocketStop
310 Make sure the given "socket" is stopped. Stop it if it is running and
312 do nothing when it is already stopped. In addition, when called for the
313 first time, the current state is saved so that the "socket" can be
314 restored to its original state when testing is finished, see
315 "rlSocketRestore".
316 rlSocketStop socket [socket...]
318 socket
320 Name of the socket(s) to stop.
321 Returns number of sockets which failed to become stopped; thus zero is
323 returned when everything is OK.
324 rlSocketRestore
326 Restore given "socket" into its original state (before the first
328 "rlSocketStart" or "rlSocketStop" was called).
329 Warning !!! Xinetd process [even though it might have been used] is
331 NOT restored. It is recommended to call rlServiceRestore xinetd as
332 well.
333 rlSocketRestore socket [socket...]
335 socket
337 Name of the socket(s) to restore to original state.
338 Returns number of sockets which failed to get back to their original
340 state; thus zero is returned when everything is OK.
341 Cleanup management
343 Cleanup management works with a so-called cleanup buffer, which is a
344 temporary representation of what should be run at cleanup time, and a
345 final cleanup script (executable), which is generated from this buffer
346 and wraps it using BeakerLib essentials (journal initialization,
347 cleanup phase, ...). The cleanup script must always be updated on an
348 atomic basis (filesystem-wise) to allow an asynchronous execution by a
349 third party (ie. test watcher).
350 The test watcher usage is mandatory for the cleanup management system
352 to work properly as it is the test watcher that executes the actual
353 cleanup script. Limited, catastrophe-avoiding mechanism is in place
354 even when the test is not run in test watcher, but that should be seen
355 as a backup and such situation is to be avoided whenever possible.
356 The cleanup script shares all environment (variables, exported or not,
358 and functions) with the test itself - the cleanup append/prepend
359 functions "sample" or "snapshot" the environment at the time of their
360 call, IOW any changes to the test environment are synchronized to the
361 cleanup script only upon calling append/prepend. When the
362 append/prepend functions are called within a function which has local
363 variables, these will appear as global in the cleanup.
364 While the cleanup script receives $PWD from the test, its working dir
366 is set to the initial test execution dir even if $PWD contains
367 something else. It is impossible to use relative paths inside cleanup
368 reliably - certain parts of the cleanup might have been added under
369 different current directories (CWDs). Therefore always use absolute
370 paths in append/prepend cleanup or make sure you never 'cd' elsewhere
371 (ie. to a TmpDir).
372 rlCleanupAppend
374 Appends a string to the cleanup buffer and recreates the cleanup
376 script.
377 rlCleanupAppend string
379 Returns 0 if the operation was successful, 1 otherwise.
381 rlCleanupPrepend
383 Prepends a string to the cleanup buffer and recreates the cleanup
385 script.
386 rlCleanupPrepend string
388 Returns 0 if the operation was successful, 1 otherwise.
390
392 · Petr Muller <pmuller@redhat.com>
393 · Jan Hutar <jhutar@redhat.com>
395 · Petr Splichal <psplicha@redhat.com>
397 · Ales Zelinka <azelinka@redhat.com>
399 · Karel Srot <ksrot@redhat.com>
401perl v5.30.1 2020-01-28 INFRASTRUCTURE.SH(1)