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 (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
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 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
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 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
206   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
211       rlServiceStart
212
213       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
219           rlServiceStart service [service...]
220
221       service
222           Name of the service(s) to start.
223
224       Returns number of services which failed to start/restart; thus zero is
225       returned when everything is OK.
226
227       rlServiceStop
228
229       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
235           rlServiceStop service [service...]
236
237       service
238           Name of the service(s) to stop.
239
240       Returns number of services which failed to become stopped; thus zero is
241       returned when everything is OK.
242
243       rlServiceRestore
244
245       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
250           rlServiceRestore [service...]
251
252       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
256       Returns number of services which failed to get back to their original
257       state; thus zero is returned when everything is OK.
258
259       rlServiceEnable
260
261       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
266           rlServiceEnable service [service...]
267
268       service
269           Name of the service(s) to enable.
270
271       Returns number of services which failed enablement; thus zero is
272       returned when everything is OK.
273
274       rlServiceDisable
275
276       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
281           rlServiceDisable service [service...]
282
283       service
284           Name of the service(s) to disable.
285
286       Returns number of services which failed disablement; thus zero is
287       returned when everything is OK.
288
289   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
294       rlSocketStart
295
296       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
301           rlSocketStart socket [socket...]
302
303       socket
304           Name of the socket(s) to start.
305
306       Returns number of sockets which failed to start/restart; thus zero is
307       returned when everything is OK.
308
309       rlSocketStop
310
311       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
317           rlSocketStop socket [socket...]
318
319       socket
320           Name of the socket(s) to stop.
321
322       Returns number of sockets which failed to become stopped; thus zero is
323       returned when everything is OK.
324
325       rlSocketRestore
326
327       Restore given "socket" into its original state (before the first
328       "rlSocketStart" or "rlSocketStop" was called).
329
330       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
334           rlSocketRestore socket [socket...]
335
336       socket
337           Name of the socket(s) to restore to original state.
338
339       Returns number of sockets which failed to get back to their original
340       state; thus zero is returned when everything is OK.
341
342   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
351       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
357       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
365       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
373       rlCleanupAppend
374
375       Appends a string to the cleanup buffer and recreates the cleanup
376       script.
377
378           rlCleanupAppend string
379
380       Returns 0 if the operation was successful, 1 otherwise.
381
382       rlCleanupPrepend
383
384       Prepends a string to the cleanup buffer and recreates the cleanup
385       script.
386
387           rlCleanupPrepend string
388
389       Returns 0 if the operation was successful, 1 otherwise.
390

AUTHORS

392       ·   Petr Muller <pmuller@redhat.com>
393
394       ·   Jan Hutar <jhutar@redhat.com>
395
396       ·   Petr Splichal <psplicha@redhat.com>
397
398       ·   Ales Zelinka <azelinka@redhat.com>
399
400       ·   Karel Srot <ksrot@redhat.com>
401
402
403
404perl v5.28.1                      2019-04-04              INFRASTRUCTURE.SH(1)
Impressum