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 a
85       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 use either the default or the
163       explicitly configured "PATH" settings (via path or set_path) when
164       executing commands or not.
165
166       Default is "undef".
167
168   set_source_profile
169   get_source_profile
170       Sets and gets the value of the $source_profile configuration variable.
171
172       This controls whether Rex should source shell-specific profile files
173       before executing commands.
174
175       Default is "undef".
176
177   set_say_format
178   get_say_format
179       Sets and gets the value of the $say_format configuration variable.
180
181       This controls the output format of the built-in "say" command (see also
182       sayformat).
183
184       Default is "undef".
185
186   set_do_reporting
187   get_do_reporting
188       Sets and gets the value of the $do_reporting configuration variable.
189
190       This controls whether Rex should do reporting on executed resources
191       where it is supported. This only affects the data structures returned
192       internally.
193
194       Default is "undef".
195
196   set_report_type
197   get_report_type
198       Sets and gets the value of the $report_type configuration variable,
199       which can also be controlled via the "REX_REPORT_TYPE" environment
200       variable.
201
202       This selects the reporting type (format) Rex should use, e.g. 'YAML'.
203
204       Default is "undef".
205
206   set_sleep_hack
207   get_sleep_hack
208       Sets and gets the value of the $sleep_hack configuration variable.
209
210       This controls whether Rex should use or not an extra 10 ns long sleep
211       after executed commands.
212
213       This might help working around an issue when Rex runs inside a KVM
214       virtualized host and Net::SSH2/libssh2 <https://www.libssh2.org> is
215       used to connect to another VM on the same hardware.
216
217       Default is "undef".
218
219   set_cache_type
220   get_cache_type
221       Sets and gets the value of the $cache_type configuration variable,
222       which can also be controlled via the "REX_CACHE_TYPE" environment
223       variable.
224
225       This selects the cache type Rex should use, e.g. 'YAML'.
226
227       Default is 'Base'.
228
229   set_use_cache
230   get_use_cache
231       Sets and gets the value of the $use_cache configuration variable.
232
233       This controls whether Rex should use caching or not for runtime
234       information like CMDB contents, hardware and operating system
235       information, or the shell type that is being used to execute commands
236       on the managed endpoint.
237
238       Default is "undef".
239
240   set_openssh_opt
241   get_openssh_opt
242       Sets and gets the value of the $openssh_opt configuration variable,
243       which holds a hash of the SSH configuration options used for the
244       connection. See the ssh_config(5) man page
245       <http://man.openbsd.org/OpenBSD-current/man5/ssh_config.5> for the
246       available options.
247
248         Rex::Config->set_openssh_opt( $option => $value, );
249
250       There is a custom option named "initialize_options" specific to Rex,
251       which can be used to pass a hash reference describing the constructor
252       parameters
253       <https://metacpan.org/pod/Net::OpenSSH#Net::OpenSSH->new($host,-%opts)>
254       for the underlying Net::OpenSSH object:
255
256        Rex::Config->set_openssh_opt( initialize_options => { $parameter => $value, } );
257
258       Default is "undef".
259
260   set_sudo_without_locales
261   get_sudo_without_locales
262       Sets and gets the value of the $sudo_without_locales configuration
263       variable.
264
265       This controls whether Rex should execute sudo commands without setting
266       any locales via the "LC_ALL" environment variable.
267
268       Warning: if the locale is something else than "C" or "en_US", then
269       things will break!
270
271       Default is "undef".
272
273   set_sudo_without_sh
274   get_sudo_without_sh
275       Sets and gets the value of the $sudo_without_sh configuration variable.
276
277       This controls whether Rex should run sudo commands without "sh". This
278       might break things.
279
280       Default is "undef".
281
282   set_executor_for
283   get_executor_for
284       Sets and gets the keys and values of the %executor_for configuration
285       variable.
286
287       This sets the executor for a given file type when using the
288       upload_and_run() function of Rex::Helper::Run module.
289
290       Default is:
291
292        (
293          perl   => 'perl',
294          python => 'python',
295          ruby   => 'ruby',
296          bash   => 'bash',
297        )
298
299   set_tmp_dir
300   get_tmp_dir
301       Sets and gets the value of the $tmp_dir configuration variable.
302
303       This controls which directory Rex should use for temporary files.
304
305       Default is determined by the following logic:
306
307       •   try to use what "File::Spec->tmpdir" would return on the managed
308           endpoint
309
310       •   fall back to '/tmp'
311
312   set_path
313   get_path
314       Sets and gets the value of the $path configuration variable.
315
316       This controls which "PATH" Rex should use when executing commands via
317       the Rex::Commands::Run module.
318
319       The value should be set as an array reference, and will be dereferenced
320       as such before returned by "get_path". The path command is a
321       convenience wrapper for "set_path", and accepts an array.
322
323       Default is
324
325        qw(
326          /bin
327          /sbin
328          /usr/bin
329          /usr/sbin
330          /usr/local/bin
331          /usr/local/sbin
332          /usr/pkg/bin
333          /usr/pkg/sbin
334        )
335
336   set_user
337   get_user
338       Sets and gets the value of the $user configuration variable, which also
339       can be set via the "REX_USER" environment variable.
340
341       This controls which user Rex should use for authentication.
342
343       Default is determined by the following logic:
344
345       •   value of "REX_USER" environment variable
346
347       •   user set by user command
348
349       •   user running Rex
350
351   set_password
352   get_password
353       Sets and gets the value of the $password configuration variable, which
354       also can be set via the "REX_PASSWORD" environment variable.
355
356       This controls what password Rex should use for authentication or as
357       passphrase when using private keys.
358
359       Default is "undef".
360
361   set_port
362   get_port
363       Sets and gets the value of the $port configuration variable.
364
365       This controls which port Rex should connect to.
366
367       "get_port" accepts an optional "server => $server" argument to return
368       the "port" setting for the given $server as optionally set in group
369       files.
370
371       Default is "undef".
372
373   set_sudo_password
374   get_sudo_password
375       Sets and gets the value of the $sudo_password configuration variable,
376       which can also be controlled via the "REX_SUDO_PASSWORD" environment
377       variable.
378
379       This controls what sudo password Rex should use.
380
381       Default is determined by the following logic:
382
383       •   value of "REX_SUDO_PASSWORD" environment variable
384
385       •   sudo password set by the sudo_password command
386
387       •   password set by the password command
388
389       •   empty string ('')
390
391   set_source_global_profile
392   get_source_global_profile
393       Sets and gets the value of the $source_global_profile configuration
394       variable.
395
396       This controls whether Rex should source "/etc/profile" before executing
397       commands.
398
399       Default is "undef".
400
401   set_max_connect_fails
402   get_max_connect_fails
403       Sets and gets the value of the $max_connect_fails configuration
404       variable.
405
406       This controls how many times Rex should retry to connect before giving
407       up.
408
409       "get_max_connect_fails" accepts an optional "server => $server"
410       argument to "connectionattempts" setting for the given $server as
411       optionally set in group files.
412
413       Default is "undef".
414
415   set_proxy_command
416   get_proxy_command
417       Sets and gets the value of the $proxy_command configuration variable.
418
419       This controls the SSH ProxyCommand Rex should set for connections when
420       Net::OpenSSH is used.
421
422       "get_proxy_command" accepts an optional "server => $server" argument to
423       return the "proxycommand" setting for the given $server as optionally
424       set in group files.
425
426       Default is "undef".
427
428   set_timeout
429   get_timeout
430       Sets and gets the value of the $timeout configuration variable.
431
432       This controls how many seconds Rex should wait for connections to
433       succeed when using SSH or Rex::Commands::Rsync.
434
435       "get_timeout" accepts an optional "server => $server" argument to
436       return the "connecttimeout" setting for the given $server as optionally
437       set in group files.
438
439       Default is "undef".
440
441   set_password_auth
442   get_password_auth
443       Sets and gets the value of the $password_auth configuration variable,
444       which can also be set by setting the "REX_AUTH_TYPE" environment
445       variable to "pass".
446
447       This controls whether Rex should use the password authentication
448       method.
449
450       Default is "undef".
451
452   set_key_auth
453   get_key_auth
454       Sets and gets the value of the $key_auth configuration variable, which
455       can also be set by setting the "REX_AUTH_TYPE" environment variable to
456       "key".
457
458       This controls whether Rex should use the key authentication method.
459
460       Default is "undef".
461
462   set_krb5_auth
463   get_krb5_auth
464       Sets and gets the value of the $krb5_auth configuration variable, which
465       can also be set by setting the "REX_AUTH_TYPE" environment variable to
466       "krb5".
467
468       This controls whether Rex should use the Kerberos 5 authentication
469       method.
470
471       Default is "undef".
472
473   set_public_key
474   get_public_key
475       Sets and gets the value of the $public_key configuration variable.
476
477       This controls which public key Rex should use when using Net::SSH2 for
478       connections.
479
480       Default is "undef".
481
482   set_private_key
483   get_private_key
484       Sets and gets the value of the $private_key configuration variable.
485
486       This controls which private key Rex should use with
487       Rex::Commands::Rsync or when using Net::SSH2 for connections.
488
489       Default is "undef".
490
491   set_parallelism
492   get_parallelism
493       Sets and gets the value of the $parallelism configuration variable.
494
495       This controls how many hosts Rex should connect to in parallel.
496
497       Default is 1.
498
499   set_log_filename
500   get_log_filename
501       Sets and gets the value of the $log_filename configuration variable.
502
503       This controls which file Rex should use for logging.
504
505       Default is "undef".
506
507   set_log_facility
508   get_log_facility
509       Sets and gets the value of the $log_facility configuration variable.
510
511       This controls which log facility Rex should use when logging to syslog.
512
513       Default is 'local0'.
514
515   set_environment
516   get_environment
517       Sets and gets the value of the $environment configuration variable.
518
519       This controls which environment Rex should use.
520
521       Default is ''.
522
523   set_distributor
524   get_distributor
525       Sets and gets the value of the $distributor configuration variable.
526
527       This controls which method Rex should use for distributing tasks for
528       parallel execution.
529
530       Default is 'Base'.
531
532   set_template_function
533   get_template_function
534       Sets and gets the value of the $template_function configuration
535       variable.
536
537       This controls the function to be used for rendering templates. The
538       value should be a subroutine reference that will be called with passing
539       two scalar references as positional arguments: first is template
540       content, second is template variables.
541
542       Default is determined by the following logic:
543
544       •   if Rex::Template::NG is loadable and use_template_ng is true, use
545           that
546
547       •   fall back to Rex::Template otherwise
548
549   set_no_tty
550   get_no_tty
551       Sets and gets the value of the $no_tty configuration variable.
552
553       This controls whether Rex should request a terminal when using
554       Net::SSH2 or allocate a pseudo-tty for the remote process when using
555       Net::OpenSSH.
556
557       Default is "undef".
558
559   set_allow_empty_groups
560   get_allow_empty_groups
561       Sets and gets the value of the $allow_empty_groups configuration
562       variable.
563
564       This controls whether Rex should allow empty groups of hosts or not.
565
566       Default is 0.
567
568   set_use_server_auth
569   get_use_server_auth
570       Sets and gets the value of the $use_server_auth configuration variable.
571
572       This controls whether Rex should use server-specific authentication
573       information from group files.
574
575       Default is 0.
576
577   set_waitpid_blocking_sleep_time
578   get_waitpid_blocking_sleep_time
579       Sets and gets the value of the $waitpid_blocking_sleep_time
580       configuration variable.
581
582       This controls how many seconds Rex should sleep between checking forks.
583
584       Default is 0.1.
585
586   set_write_utf8_files
587   get_write_utf8_files
588       Sets and gets the value of the $write_utf8_files configuration
589       variable.
590
591       This controls whether Rex should force "UTF-8" encoding when writing
592       files.
593
594       Default is "undef".
595
596   set_default_auth
597   get_default_auth
598       Sets and gets the value of the $default_auth configuration variable.
599
600       This controls whether Rex should attach default authentication info to
601       tasks.
602
603       Default is 1.
604
605   register_set_handler($handler_name, $code)
606       Register a handler that gets called by set.
607
608        Rex::Config->register_set_handler("foo", sub {
609          my ($value) = @_;
610          print "The user set foo -> $value\n";
611        });
612
613       And now you can use this handler in your Rexfile like this:
614
615        set foo => "bar";
616
617   register_config_handler($topic, $code)
618       With this function it is possible to register own sections in the users
619       config file ("$HOME/.rex/config.yml").
620
621       Example:
622
623        Rex::Config->register_config_handler("foo", sub {
624         my ($param) = @_;
625         print "bar is: " . $param->{bar} . "\n";
626        });
627
628       And now the user can set this in his configuration file:
629
630        base:
631          user: theuser
632          password: thepassw0rd
633        foo:
634          bar: baz
635
636
637
638perl v5.36.1                      2023-08-07                    Rex::Config(3)
Impressum