1Rex::Config(3)        User Contributed Perl Documentation       Rex::Config(3)
2
3
4

NAME

6       Rex::Config - Handles Rex configuration
7

SYNOPSIS

9        use Rex::Config;
10
11        # set a config option
12        Rex::Config->set_exec_autodie(TRUE);
13
14        # get value of a config option
15        my $user = Rex::Config->get_user();
16

DESCRIPTION

18       This module holds all configuration options for Rex, and also allows
19       you to specify your own ones for your modules.
20
21       Please take a look at Rex::Commands first, which provides convenience
22       wrappers for many of these options.
23
24       While it's possible to use the methods below to set a configuration
25       option directly, their main intended purpose is to be used as internal
26       plumbing, and to provide an escape hatch in case there are no better
27       alternatives.
28

EXPORTED METHODS

30   set_autodie
31   get_autodie
32       Sets and gets the value of the $autodie configuration variable.
33
34       This controls whether Rex should "die()" if there's an error while
35       executing file system commands that are supposed to change the
36       contents.
37
38       Default is "undef".
39
40   set_use_net_openssh_if_present
41   get_use_net_openssh_if_present
42       Sets and gets the value of the $use_net_openssh_if_present
43       configuration variable.
44
45       This controls whether Rex should use Net::OpenSSH for connections if
46       that is available.
47
48       Default is "undef".
49
50   set_use_rex_kvm_agent
51   get_use_rex_kvm_agent
52       Sets and gets the value of the $use_rex_kvm_agent configuration
53       variable.
54
55       This controls whether Rex should setup and use a serial device for the
56       experimental Rex KVM agent <https://github.com/RexOps/rex-kvm-agent>
57       for managed VMs.
58
59       Default is "undef".
60
61   set_use_template_ng
62   get_use_template_ng
63       Sets and gets the value of the $use_template_ng configuration variable.
64
65       This controls whether Rex should use Rex::Template::NG to render
66       templates.
67
68       Default is "undef".
69
70   set_set_no_append
71   get_set_no_append
72       Sets and gets the value of the $set_no_append configuration variable.
73
74       This controls whether Rex should overwrite or append values of
75       configuration options when using the set command.
76
77       Default is "undef".
78
79   set_check_service_exists
80   get_check_service_exists
81       Sets and gets the value of the $check_service_exists configuration
82       variable.
83
84       This controls whether Rex should "die()" early if it is asked to manage
85       a service that doesn't exist.
86
87       Default is "undef".
88
89   set_register_cmdb_template
90   get_register_cmdb_template
91       Sets and gets the value of the $register_cmdb_template configuration
92       variable.
93
94       This controls whether Rex should make CMDB data available to be used in
95       templates as variables.
96
97       Default is "undef".
98
99   set_fallback_auth
100   get_fallback_auth
101       Sets and gets the value of the $fallback_auth configuration variable.
102
103       This can be used to define an array of hash references, each of them
104       containing authentication details to be tried during connection
105       attempts when the directly specified ones fail.
106
107       Default is "undef".
108
109   set_task_call_by_method
110   get_task_call_by_method
111       Sets and gets the value of the $task_call_by_method configuration
112       variable.
113
114       This controls whether calling tasks as a method is allowed or not.
115
116       Default is "undef".
117
118   set_disable_taskname_warning
119   get_disable_taskname_warning
120       Sets and gets the value of the $disable_taskname_warning configuration
121       variable.
122
123       This controls whether Rex should show or suppress the warning message
124       about task names that can not be used as Perl identifiers.
125
126       Default is "undef".
127
128   set_task_chaining_cmdline_args
129   get_task_chaining_cmdline_args
130       Sets and gets the value of the $task_chaining_cmdline_args
131       configuration variable.
132
133       This controls whether Rex should parse task arguments on the command
134       line per task, or should pass all arguments to all tasks.
135
136       Default is "undef".
137
138   set_verbose_run
139   get_verbose_run
140       Sets and gets the value of the $verbose_run configuration variable.
141
142       This controls whether Rex should show verbose output about executed run
143       commands. This means an error message if the command is not found, a
144       warning message if the exit code indicates an error, and an
145       informational message upon success.
146
147       Default is "undef".
148
149   set_exec_autodie
150   get_exec_autodie
151       Sets and gets the value of the $exec_autodie configuration variable.
152
153       This controls whether Rex should "die()" or not when the exit code of
154       executed run command indicate an error.
155
156       Default is "undef".
157
158   set_no_path_cleanup
159   get_no_path_cleanup
160       Sets and gets the value of the $no_path_cleanup configuration variable.
161
162       This controls whether Rex should clean up the $PATH before executing a
163       run command.
164
165       Default is "undef".
166
167   set_source_profile
168   get_source_profile
169       Sets and gets the value of the $source_profile configuration variable.
170
171       This controls whether Rex should source shell-specific profile files
172       before executing commands.
173
174       Default is "undef".
175
176   set_say_format
177   get_say_format
178       Sets and gets the value of the $say_format configuration variable.
179
180       This controls the output format of the built-in "say" command (see also
181       sayformat).
182
183       Default is "undef".
184
185   set_do_reporting
186   get_do_reporting
187       Sets and gets the value of the $do_reporting configuration variable.
188
189       This controls whether Rex should do reporting on executed resources
190       where it is supported. This only affects the data structures returned
191       internally.
192
193       Default is "undef".
194
195   set_report_type
196   get_report_type
197       Sets and gets the value of the $report_type configuration variable,
198       which can also be controlled via the "REX_REPORT_TYPE" environment
199       variable.
200
201       This selects the reporting type (format) Rex should use, e.g. 'YAML'.
202
203       Default is "undef".
204
205   set_sleep_hack
206   get_sleep_hack
207       Sets and gets the value of the $sleep_hack configuration variable.
208
209       This controls whether Rex should use or not an extra 10 ns long sleep
210       after executed commands.
211
212       This might help working around an issue when Rex runs inside a KVM
213       virtualized host and Net::SSH2/libssh2 <https://www.libssh2.org> is
214       used to connect to another VM on the same hardware.
215
216       Default is "undef".
217
218   set_cache_type
219   get_cache_type
220       Sets and gets the value of the $cache_type configuration variable,
221       which can also be controlled via the "REX_CACHE_TYPE" environment
222       variable.
223
224       This selects the cache type Rex should use, e.g. 'YAML'.
225
226       Default is 'Base'.
227
228   set_use_cache
229   get_use_cache
230       Sets and gets the value of the $use_cache configuration variable.
231
232       This controls whether Rex should use caching or not for runtime
233       information like CMDB contents, hardware and operating system
234       information, or the shell type that is being used to execute commands
235       on the managed endpoint.
236
237       Default is "undef".
238
239   set_openssh_opt
240   get_openssh_opt
241       Sets and gets the value of the $openssh_opt configuration variable,
242       which holds a hash of the SSH configuration options used for the
243       connection. See the ssh_config(5) man page
244       <http://man.openbsd.org/OpenBSD-current/man5/ssh_config.5> for the
245       available options.
246
247         Rex::Config->set_openssh_opt( $option => $value, );
248
249       There is a custom option named "initialize_options" specific to Rex,
250       which can be used to pass a hash reference describing the constructor
251       parameters
252       <https://metacpan.org/pod/Net::OpenSSH#Net::OpenSSH->new($host,-%opts)>
253       for the underlying Net::OpenSSH object:
254
255        Rex::Config->set_openssh_opt( initialize_options => { $parameter => $value, } );
256
257       Default is "undef".
258
259   set_sudo_without_locales
260   get_sudo_without_locales
261       Sets and gets the value of the $sudo_without_locales configuration
262       variable.
263
264       This controls whether Rex should execute sudo commands without setting
265       any locales via the "LC_ALL" environment variable.
266
267       Warning: if the locale is something else than "C" or "en_US", then
268       things will break!
269
270       Default is "undef".
271
272   set_sudo_without_sh
273   get_sudo_without_sh
274       Sets and gets the value of the $sudo_without_sh configuration variable.
275
276       This controls whether Rex should run sudo commands without "sh". This
277       might break things.
278
279       Default is "undef".
280
281   set_executor_for
282   get_executor_for
283       Sets and gets the keys and values of the %executor_for configuration
284       variable.
285
286       This sets the executor for a given file type when using the
287       "upload_and_run()" function of Rex::Helper::Run module.
288
289       Default is:
290
291        (
292          perl   => 'perl',
293          python => 'python',
294          ruby   => 'ruby',
295          bash   => 'bash',
296        )
297
298   set_tmp_dir
299   get_tmp_dir
300       Sets and gets the value of the $tmp_dir configuration variable.
301
302       This controls which directory Rex should use for temporary files.
303
304       Default is determined by the following logic:
305
306       •   try to use what "File::Spec->tmpdir" would return on the managed
307           endpoint
308
309       •   fall back to '/tmp'
310
311   set_path
312   get_path
313       Sets and gets the value of the $path configuration variable.
314
315       This controls which "PATH" Rex should use when executing run commands.
316       The value should be set as an array reference, and will be dereferenced
317       as such before returned by "get_path".
318
319       Default is
320
321        qw(
322          /bin
323          /sbin
324          /usr/bin
325          /usr/sbin
326          /usr/local/bin
327          /usr/local/sbin
328          /usr/pkg/bin
329          /usr/pkg/sbin
330        )
331
332   set_user
333   get_user
334       Sets and gets the value of the $user configuration variable, which also
335       can be set via the "REX_USER" environment variable.
336
337       This controls which user Rex should use for authentication.
338
339       Default is determined by the following logic:
340
341       •   value of "REX_USER" environment variable
342
343       •   user set by user command
344
345       •   user running Rex
346
347   set_password
348   get_password
349       Sets and gets the value of the $password configuration variable, which
350       also can be set via the "REX_PASSWORD" environment variable.
351
352       This controls what password Rex should use for authentication or as
353       passphrase when using private keys.
354
355       Default is "undef".
356
357   set_port
358   get_port
359       Sets and gets the value of the $port configuration variable.
360
361       This controls which port Rex should connect to.
362
363       "get_port" accepts an optional "server => $server" argument to return
364       the "port" setting for the given $server as optionally set in group
365       files.
366
367       Default is "undef".
368
369   set_sudo_password
370   get_sudo_password
371       Sets and gets the value of the $sudo_password configuration variable,
372       which can also be controlled via the "REX_SUDO_PASSWORD" environment
373       variable.
374
375       This controls what sudo password Rex should use.
376
377       Default is determined by the following logic:
378
379       •   value of "REX_SUDO_PASSWORD" environment variable
380
381       •   sudo password set by the sudo_password command
382
383       •   password set by the password command
384
385       •   empty string ('')
386
387   set_source_global_profile
388   get_source_global_profile
389       Sets and gets the value of the $source_global_profile configuration
390       variable.
391
392       This controls whether Rex should source "/etc/profile" before executing
393       commands.
394
395       Default is "undef".
396
397   set_max_connect_fails
398   get_max_connect_fails
399       Sets and gets the value of the $max_connect_fails configuration
400       variable.
401
402       This controls how many times Rex should retry to connect before giving
403       up.
404
405       "get_max_connect_fails" accepts an optional "server => $server"
406       argument to "connectionattempts" setting for the given $server as
407       optionally set in group files.
408
409       Default is "undef".
410
411   set_proxy_command
412   get_proxy_command
413       Sets and gets the value of the $proxy_command configuration variable.
414
415       This controls the SSH ProxyCommand Rex should set for connections when
416       Net::OpenSSH is used.
417
418       "get_proxy_command" accepts an optional "server => $server" argument to
419       return the "proxycommand" setting for the given $server as optionally
420       set in group files.
421
422       Default is "undef".
423
424   set_timeout
425   get_timeout
426       Sets and gets the value of the $timeout configuration variable.
427
428       This controls how many seconds Rex should wait for connections to
429       succeed when using SSH or Rex::Commands::Rsync.
430
431       "get_timeout" accepts an optional "server => $server" argument to
432       return the "connecttimeout" setting for the given $server as optionally
433       set in group files.
434
435       Default is "undef".
436
437   set_password_auth
438   get_password_auth
439       Sets and gets the value of the $password_auth configuration variable,
440       which can also be set by setting the "REX_AUTH_TYPE" environment
441       variable to "pass".
442
443       This controls whether Rex should use the password authentication
444       method.
445
446       Default is "undef".
447
448   set_key_auth
449   get_key_auth
450       Sets and gets the value of the $key_auth configuration variable, which
451       can also be set by setting the "REX_AUTH_TYPE" environment variable to
452       "key".
453
454       This controls whether Rex should use the key authentication method.
455
456       Default is "undef".
457
458   set_krb5_auth
459   get_krb5_auth
460       Sets and gets the value of the $krb5_auth configuration variable, which
461       can also be set by setting the "REX_AUTH_TYPE" environment variable to
462       "krb5".
463
464       This controls whether Rex should use the Kerberos 5 authentication
465       method.
466
467       Default is "undef".
468
469   set_public_key
470   get_public_key
471       Sets and gets the value of the $public_key configuration variable.
472
473       This controls which public key Rex should use when using Net::SSH2 for
474       connections.
475
476       Default is "undef".
477
478   set_private_key
479   get_private_key
480       Sets and gets the value of the $private_key configuration variable.
481
482       This controls which private key Rex should use with
483       Rex::Commands::Rsync or when using Net::SSH2 for connections.
484
485       Default is "undef".
486
487   set_parallelism
488   get_parallelism
489       Sets and gets the value of the $parallelism configuration variable.
490
491       This controls how many hosts Rex should connect to in parallel.
492
493       Default is 1.
494
495   set_log_filename
496   get_log_filename
497       Sets and gets the value of the $log_filename configuration variable.
498
499       This controls which file Rex should use for logging.
500
501       Default is "undef".
502
503   set_log_facility
504   get_log_facility
505       Sets and gets the value of the $log_facility configuration variable.
506
507       This controls which log facility Rex should use when logging to syslog.
508
509       Default is 'local0'.
510
511   set_environment
512   get_environment
513       Sets and gets the value of the $environment configuration variable.
514
515       This controls which environment Rex should use.
516
517       Default is ''.
518
519   set_distributor
520   get_distributor
521       Sets and gets the value of the $distributor configuration variable.
522
523       This controls which method Rex should use for distributing tasks for
524       parallel execution.
525
526       Default is 'Base'.
527
528   set_template_function
529   get_template_function
530       Sets and gets the value of the $template_function configuration
531       variable.
532
533       This controls the function to be used for rendering templates. The
534       value should be a subroutine reference that will be called with passing
535       two scalar references as positional arguments: first is template
536       content, second is template variables.
537
538       Default is determined by the following logic:
539
540       •   if Rex::Template::NG is loadable and use_template_ng is true, use
541           that
542
543       •   fall back to Rex::Template otherwise
544
545   set_no_tty
546   get_no_tty
547       Sets and gets the value of the $no_tty configuration variable.
548
549       This controls whether Rex should request a terminal when using
550       Net::SSH2 or allocate a pseudo-tty for the remote process when using
551       Net::OpenSSH.
552
553       Default is "undef".
554
555   set_allow_empty_groups
556   get_allow_empty_groups
557       Sets and gets the value of the $allow_empty_groups configuration
558       variable.
559
560       This controls whether Rex should allow empty groups of hosts or not.
561
562       Default is 0.
563
564   set_use_server_auth
565   get_use_server_auth
566       Sets and gets the value of the $use_server_auth configuration variable.
567
568       This controls whether Rex should use server-specific authentication
569       information from group files.
570
571       Default is 0.
572
573   set_waitpid_blocking_sleep_time
574   get_waitpid_blocking_sleep_time
575       Sets and gets the value of the $waitpid_blocking_sleep_time
576       configuration variable.
577
578       This controls how many seconds Rex should sleep between checking forks.
579
580       Default is 0.1.
581
582   set_write_utf8_files
583   get_write_utf8_files
584       Sets and gets the value of the $write_utf8_files configuration
585       variable.
586
587       This controls whether Rex should force "UTF-8" encoding when writing
588       files.
589
590       Default is "undef".
591
592   set_default_auth
593   get_default_auth
594       Sets and gets the value of the $default_auth configuration variable.
595
596       This controls whether Rex should attach default authentication info to
597       tasks.
598
599       Default is 1.
600
601   register_set_handler($handler_name, $code)
602       Register a handler that gets called by set.
603
604        Rex::Config->register_set_handler("foo", sub {
605          my ($value) = @_;
606          print "The user set foo -> $value\n";
607        });
608
609       And now you can use this handler in your Rexfile like this:
610
611        set foo => "bar";
612
613   register_config_handler($topic, $code)
614       With this function it is possible to register own sections in the users
615       config file ("$HOME/.rex/config.yml").
616
617       Example:
618
619        Rex::Config->register_config_handler("foo", sub {
620         my ($param) = @_;
621         print "bar is: " . $param->{bar} . "\n";
622        });
623
624       And now the user can set this in his configuration file:
625
626        base:
627          user: theuser
628          password: thepassw0rd
629        foo:
630          bar: baz
631
632
633
634perl v5.34.0                      2022-01-19                    Rex::Config(3)
Impressum