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 (has to be the first option of the
138 command), then file/dir backed up using this command (provided in
139 next options) will be (recursively) removed before we restore it.
140 This option implies --missing-ok, which 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 backed up files were not successfuly copied. Returns
166 8 if backed up files do not exist. This can be suppressed based on
167 other 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:
199 XXXXX
201 |||||
202 ||||\_ error parsing parameters
203 |||\__ could not find backup directory
204 ||\___ files cleanup failed
205 |\____ files restore failed
206 \_____ no files were restored nor cleaned
207 Services
209 Following routines implement comfortable way how to start/stop system
210 services with the possibility to restore them to their original state
211 after testing.
212 rlServiceStart
214 Make sure the given "service" is running with fresh configuration.
216 (Start it if it is stopped and restart if it is already running.) In
217 addition, when called for the first time, the current state is saved so
218 that the "service" can be restored to its original state when testing
219 is finished, see "rlServiceRestore".
220 rlServiceStart service [service...]
222 service
224 Name of the service(s) to start.
225 Returns number of services which failed to start/restart; thus zero is
227 returned when everything is OK.
228 rlServiceStop
230 Make sure the given "service" is stopped. Stop it if it is running and
232 do nothing when it is already stopped. In addition, when called for the
233 first time, the current state is saved so that the "service" can be
234 restored to its original state when testing is finished, see
235 "rlServiceRestore".
236 rlServiceStop service [service...]
238 service
240 Name of the service(s) to stop.
241 Returns number of services which failed to become stopped; thus zero is
243 returned when everything is OK.
244 rlServiceRestore
246 Restore given "service" into its original state (before the first
248 "rlServiceStart" or "rlServiceStop" was called). If "rlServiceStart"
249 was called on already running "service", "rlServiceRestore" will
250 restart the "service" when restoring its state.
251 rlServiceRestore [service...]
253 service
255 Name of the service(s) to restore to original state. All services
256 will be restored in reverse order if no service name is given.
257 Returns number of services which failed to get back to their original
259 state; thus zero is returned when everything is OK.
260 rlServiceStatus
262 Print status (output of `service SERVICE status` or `systemctl status
264 SERVICE`) of given "SERVICE".
265 rlServiceStatus SERVICE [SERVICE...]
267 SERVICE
269 The service to get the status of.
270 Returns service status return code of the last provided SERVICE.
272 rlServiceEnable
274 Enables selected services if needed, or does nothing if already
276 enabled. In addition, when called for the first time, the current
277 state is saved so that the "service" can be restored to its original
278 state when testing is finished, see "rlServiceRestore".
279 rlServiceEnable service [service...]
281 service
283 Name of the service(s) to enable.
284 Returns number of services which failed enablement; thus zero is
286 returned when everything is OK.
287 rlServiceDisable
289 Disables selected services if needed, or does nothing if already
291 disabled. In addition, when called for the first time, the current
292 state is saved so that the "service" can be restored to its original
293 state when testing is finished, see "rlServiceRestore".
294 rlServiceDisable service [service...]
296 service
298 Name of the service(s) to disable.
299 Returns number of services which failed disablement; thus zero is
301 returned when everything is OK.
302 Sockets
304 Following routines implement comfortable way how to start/stop system
305 sockets with the possibility to restore them to their original state
306 after testing.
307 rlSocketStart
309 Make sure the given "socket" is running. (Start it if stopped, leave it
311 if already running.) In addition, when called for the first time, the
312 current state is saved so that the "socket" can be restored to its
313 original state when testing is finished, see "rlSocketRestore".
314 rlSocketStart socket [socket...]
316 socket
318 Name of the socket(s) to start.
319 Returns number of sockets which failed to start/restart; thus zero is
321 returned when everything is OK.
322 rlSocketStop
324 Make sure the given "socket" is stopped. Stop it if it is running and
326 do nothing when it is already stopped. In addition, when called for the
327 first time, the current state is saved so that the "socket" can be
328 restored to its original state when testing is finished, see
329 "rlSocketRestore".
330 rlSocketStop socket [socket...]
332 socket
334 Name of the socket(s) to stop.
335 Returns number of sockets which failed to become stopped; thus zero is
337 returned when everything is OK.
338 rlSocketRestore
340 Restore given "socket" into its original state (before the first
342 "rlSocketStart" or "rlSocketStop" was called).
343 Warning !!! Xinetd process [even though it might have been used] is
345 NOT restored. It is recommended to call rlServiceRestore xinetd as
346 well.
347 rlSocketRestore socket [socket...]
349 socket
351 Name of the socket(s) to restore to original state.
352 Returns number of sockets which failed to get back to their original
354 state; thus zero is returned when everything is OK.
355 Cleanup management
357 Cleanup management works with a so-called cleanup buffer, which is a
358 temporary representation of what should be run at cleanup time, and a
359 final cleanup script (executable), which is generated from this buffer
360 and wraps it using BeakerLib essentials (journal initialization,
361 cleanup phase, ...). The cleanup script must always be updated on an
362 atomic basis (filesystem-wise) to allow an asynchronous execution by a
363 third party (ie. test watcher).
364 The test watcher usage is mandatory for the cleanup management system
366 to work properly as it is the test watcher that executes the actual
367 cleanup script. Limited, catastrophe-avoiding mechanism is in place
368 even when the test is not run in test watcher, but that should be seen
369 as a backup and such situation is to be avoided whenever possible.
370 The cleanup script shares all environment (variables, exported or not,
372 and functions) with the test itself - the cleanup append/prepend
373 functions "sample" or "snapshot" the environment at the time of their
374 call, IOW any changes to the test environment are synchronized to the
375 cleanup script only upon calling append/prepend. When the
376 append/prepend functions are called within a function which has local
377 variables, these will appear as global in the cleanup.
378 While the cleanup script receives $PWD from the test, its working dir
380 is set to the initial test execution dir even if $PWD contains
381 something else. It is impossible to use relative paths inside cleanup
382 reliably - certain parts of the cleanup might have been added under
383 different current directories (CWDs). Therefore always use absolute
384 paths in append/prepend cleanup or make sure you never 'cd' elsewhere
385 (ie. to a TmpDir).
386 rlCleanupAppend
388 Appends a string to the cleanup buffer and recreates the cleanup
390 script.
391 rlCleanupAppend string
393 Returns 0 if the operation was successful, 1 otherwise.
395 rlCleanupPrepend
397 Prepends a string to the cleanup buffer and recreates the cleanup
399 script.
400 rlCleanupPrepend string
402 Returns 0 if the operation was successful, 1 otherwise.
404
406 • Petr Muller <pmuller@redhat.com>
407 • Jan Hutar <jhutar@redhat.com>
409 • Petr Splichal <psplicha@redhat.com>
411 • Ales Zelinka <azelinka@redhat.com>
413 • Karel Srot <ksrot@redhat.com>
415perl v5.38.0 2023-07-19 INFRASTRUCTURE.SH(1)