1INFRASTRUCTURE.SH(1)  User Contributed Perl Documentation INFRASTRUCTURE.SH(1)
2
3
4

NAME

6       BeakerLib - infrastructure - mounting, backup and service helpers
7

DESCRIPTION

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

FUNCTIONS

13   Mounting
14       rlMount
15
16       Create mount point (if neccessary) and mount a NFS share.
17
18           rlMount [-o MOUNT_OPTS] server share mountpoint
19
20       server
21           NFS server hostname.
22
23       share
24           Shared directory name.
25
26       mountpoint
27           Local mount point.
28
29       MOUNT_OPTS
30           Mount options.
31
32       Returns 0 if mounting the share was successful.
33
34       rlCheckMount
35
36       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
40           rlCheckMount [-o MOUNT_OPTS] mountpoint
41           rlCheckMount [-o MOUNT_OPTS] server mountpoint
42           rlCheckMount [-o MOUNT_OPTS] server share mountpoint
43
44       mountpoint
45           Local mount point.
46
47       server
48           NFS server hostname
49
50       share
51           Shared directory name
52
53       MOUNT_OPTS
54           Mount options to check (comma separated list)
55
56       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
62       If the -o option is provided, returns 0 if the mountpoint uses all the
63       given options, 2 otherwise.
64
65       rlAssertMount
66
67       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
71           rlAssertMount [-o MOUNT_OPTS]  mountpoint
72           rlAssertMount [-o MOUNT_OPTS]  server mountpoint
73           rlAssertMount [-o MOUNT_OPTS]  server share mountpoint
74
75       mountpoint
76           Local mount point.
77
78       server
79           NFS server hostname
80
81       share
82           Shared directory name
83
84       MOUNT_OPTS
85           Mount options to check (comma separated list)
86
87       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
94       If the -o option is provided, asserts PASS if the above conditions are
95       met and the mountpoint uses all the given options.
96
97       rlHash, rlUnhash
98
99       Hashes/Unhashes given string and prints the result to stdout.
100
101           rlHash [--decode] [--algorithm HASH_ALG] --stdin|STRING
102           rlUnhash [--algorithm HASH_ALG] --stdin|STRING
103
104       --decode
105           Unhash given string.
106
107       --algorithm
108           Use given hash algorithm.  Currently supported algorithms:
109             base64
110             base64_ - this is standard base64 where '=' is replaced by '_'
111             hex
112
113           Defaults to hex.  Default algorithm can be override using global
114           variable rlHashAlgorithm.
115
116       --stdin
117           Get the string from stdin.
118
119       STRING
120           String to be hashed/unhashed.
121
122       Returns 0 if success.
123
124   Backup and Restore
125       rlFileBackup
126
127       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
131           rlFileBackup [--clean] [--namespace name] [--missing-ok|--no-missing-ok] file [file...]
132
133       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
136       --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
143       --namespace name
144           Specifies the namespace to use.  Namespaces can be used to separate
145           backups and their restoration.
146
147       --missing-ok
148           Do not raise an error in case of missing file to backup.
149
150       --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
155       file
156           Files and/or directories to be backed up.
157
158       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
169       Example with --clean:
170
171           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
180       rlFileRestore
181
182       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
188           rlFileRestore [--namespace name]
189
190       You can use "rlRun" for asserting the result.
191
192       --namespace name
193           Specifies the namespace to use.  Namespaces can be used to separate
194           backups and their restoration.
195
196       Returns 0 if backup dir is found and files are restored successfully.
197
198       Return code bits meaning:
199
200           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
208   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
213       rlServiceStart
214
215       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
221           rlServiceStart service [service...]
222
223       service
224           Name of the service(s) to start.
225
226       Returns number of services which failed to start/restart; thus zero is
227       returned when everything is OK.
228
229       rlServiceStop
230
231       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
237           rlServiceStop service [service...]
238
239       service
240           Name of the service(s) to stop.
241
242       Returns number of services which failed to become stopped; thus zero is
243       returned when everything is OK.
244
245       rlServiceRestore
246
247       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
252           rlServiceRestore [service...]
253
254       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
258       Returns number of services which failed to get back to their original
259       state; thus zero is returned when everything is OK.
260
261       rlServiceStatus
262
263       Print status (output of `service SERVICE status` or `systemctl status
264       SERVICE`) of given "SERVICE".
265
266           rlServiceStatus SERVICE [SERVICE...]
267
268       SERVICE
269           The service to get the status of.
270
271       Returns service status return code of the last provided SERVICE.
272
273       rlServiceEnable
274
275       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
280           rlServiceEnable service [service...]
281
282       service
283           Name of the service(s) to enable.
284
285       Returns number of services which failed enablement; thus zero is
286       returned when everything is OK.
287
288       rlServiceDisable
289
290       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
295           rlServiceDisable service [service...]
296
297       service
298           Name of the service(s) to disable.
299
300       Returns number of services which failed disablement; thus zero is
301       returned when everything is OK.
302
303   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
308       rlSocketStart
309
310       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
315           rlSocketStart socket [socket...]
316
317       socket
318           Name of the socket(s) to start.
319
320       Returns number of sockets which failed to start/restart; thus zero is
321       returned when everything is OK.
322
323       rlSocketStop
324
325       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
331           rlSocketStop socket [socket...]
332
333       socket
334           Name of the socket(s) to stop.
335
336       Returns number of sockets which failed to become stopped; thus zero is
337       returned when everything is OK.
338
339       rlSocketRestore
340
341       Restore given "socket" into its original state (before the first
342       "rlSocketStart" or "rlSocketStop" was called).
343
344       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
348           rlSocketRestore socket [socket...]
349
350       socket
351           Name of the socket(s) to restore to original state.
352
353       Returns number of sockets which failed to get back to their original
354       state; thus zero is returned when everything is OK.
355
356   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
365       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
371       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
379       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
387       rlCleanupAppend
388
389       Appends a string to the cleanup buffer and recreates the cleanup
390       script.
391
392           rlCleanupAppend string
393
394       Returns 0 if the operation was successful, 1 otherwise.
395
396       rlCleanupPrepend
397
398       Prepends a string to the cleanup buffer and recreates the cleanup
399       script.
400
401           rlCleanupPrepend string
402
403       Returns 0 if the operation was successful, 1 otherwise.
404

AUTHORS

406       •   Petr Muller <pmuller@redhat.com>
407
408       •   Jan Hutar <jhutar@redhat.com>
409
410       •   Petr Splichal <psplicha@redhat.com>
411
412       •   Ales Zelinka <azelinka@redhat.com>
413
414       •   Karel Srot <ksrot@redhat.com>
415
416
417
418perl v5.38.0                      2023-07-19              INFRASTRUCTURE.SH(1)
Impressum