1Rex::Config(3) User Contributed Perl Documentation Rex::Config(3)
2
6 Rex::Config - Handles Rex configuration
7
9 use Rex::Config;
10 # set a config option
12 Rex::Config->set_exec_autodie(TRUE);
13 # get value of a config option
15 my $user = Rex::Config->get_user();
16
18 This module holds all configuration options for Rex, and also allows
19 you to specify your own ones for your modules.
20 Please take a look at Rex::Commands first, which provides convenience
22 wrappers for many of these options.
23 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
30 set_autodie
31 get_autodie
32 Sets and gets the value of the $autodie configuration variable.
33 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 Default is "undef".
39 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 This controls whether Rex should use Net::OpenSSH for connections if
46 that is available.
47 Default is "undef".
49 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 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 Default is "undef".
60 set_use_template_ng
62 get_use_template_ng
63 Sets and gets the value of the $use_template_ng configuration variable.
64 This controls whether Rex should use Rex::Template::NG to render
66 templates.
67 Default is "undef".
69 set_set_no_append
71 get_set_no_append
72 Sets and gets the value of the $set_no_append configuration variable.
73 This controls whether Rex should overwrite or append values of
75 configuration options when using the set command.
76 Default is "undef".
78 set_check_service_exists
80 get_check_service_exists
81 Sets and gets the value of the $check_service_exists configuration
82 variable.
83 This controls whether Rex should "die()" early if it is asked to manage
85 a service that doesn't exist.
86 Default is "undef".
88 set_register_cmdb_template
90 get_register_cmdb_template
91 Sets and gets the value of the $register_cmdb_template configuration
92 variable.
93 This controls whether Rex should make CMDB data available to be used in
95 templates as variables.
96 Default is "undef".
98 set_fallback_auth
100 get_fallback_auth
101 Sets and gets the value of the $fallback_auth configuration variable.
102 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 Default is "undef".
108 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 This controls whether calling tasks as a method is allowed or not.
115 Default is "undef".
117 set_disable_taskname_warning
119 get_disable_taskname_warning
120 Sets and gets the value of the $disable_taskname_warning configuration
121 variable.
122 This controls whether Rex should show or suppress the warning message
124 about task names that can not be used as Perl identifiers.
125 Default is "undef".
127 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 This controls whether Rex should parse task arguments on the command
134 line per task, or should pass all arguments to all tasks.
135 Default is "undef".
137 set_verbose_run
139 get_verbose_run
140 Sets and gets the value of the $verbose_run configuration variable.
141 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 Default is "undef".
148 set_exec_autodie
150 get_exec_autodie
151 Sets and gets the value of the $exec_autodie configuration variable.
152 This controls whether Rex should "die()" or not when the exit code of
154 executed run command indicate an error.
155 Default is "undef".
157 set_no_path_cleanup
159 get_no_path_cleanup
160 Sets and gets the value of the $no_path_cleanup configuration variable.
161 This controls whether Rex should clean up the $PATH before executing a
163 run command.
164 Default is "undef".
166 set_source_profile
168 get_source_profile
169 Sets and gets the value of the $source_profile configuration variable.
170 This controls whether Rex should source shell-specific profile files
172 before executing commands.
173 Default is "undef".
175 set_say_format
177 get_say_format
178 Sets and gets the value of the $say_format configuration variable.
179 This controls the output format of the built-in "say" command (see also
181 sayformat).
182 Default is "undef".
184 set_do_reporting
186 get_do_reporting
187 Sets and gets the value of the $do_reporting configuration variable.
188 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 Default is "undef".
194 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 This selects the reporting type (format) Rex should use, e.g. 'YAML'.
202 Default is "undef".
204 set_sleep_hack
206 get_sleep_hack
207 Sets and gets the value of the $sleep_hack configuration variable.
208 This controls whether Rex should use or not an extra 10 ns long sleep
210 after executed commands.
211 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 Default is "undef".
217 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 This selects the cache type Rex should use, e.g. 'YAML'.
225 Default is 'Base'.
227 set_use_cache
229 get_use_cache
230 Sets and gets the value of the $use_cache configuration variable.
231 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 Default is "undef".
238 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 Rex::Config->set_openssh_opt( $option => $value, );
248 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 Rex::Config->set_openssh_opt( initialize_options => { $parameter => $value, } );
256 Default is "undef".
258 set_sudo_without_locales
260 get_sudo_without_locales
261 Sets and gets the value of the $sudo_without_locales configuration
262 variable.
263 This controls whether Rex should execute sudo commands without setting
265 any locales via the "LC_ALL" environment variable.
266 Warning: if the locale is something else than "C" or "en_US", then
268 things will break!
269 Default is "undef".
271 set_sudo_without_sh
273 get_sudo_without_sh
274 Sets and gets the value of the $sudo_without_sh configuration variable.
275 This controls whether Rex should run sudo commands without "sh". This
277 might break things.
278 Default is "undef".
280 set_executor_for
282 get_executor_for
283 Sets and gets the keys and values of the %executor_for configuration
284 variable.
285 This sets the executor for a given file type when using the
287 "upload_and_run()" function of Rex::Helper::Run module.
288 Default is:
290 (
292 perl => 'perl',
293 python => 'python',
294 ruby => 'ruby',
295 bash => 'bash',
296 )
297 set_tmp_dir
299 get_tmp_dir
300 Sets and gets the value of the $tmp_dir configuration variable.
301 This controls which directory Rex should use for temporary files.
303 Default is determined by the following logic:
305 • try to use what "File::Spec->tmpdir" would return on the managed
307 endpoint
308 • fall back to '/tmp'
310 set_path
312 get_path
313 Sets and gets the value of the $path configuration variable.
314 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 Default is
320 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 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 This controls which user Rex should use for authentication.
338 Default is determined by the following logic:
340 • value of "REX_USER" environment variable
342 • user set by user command
344 • user running Rex
346 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 This controls what password Rex should use for authentication or as
353 passphrase when using private keys.
354 Default is "undef".
356 set_port
358 get_port
359 Sets and gets the value of the $port configuration variable.
360 This controls which port Rex should connect to.
362 "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 Default is "undef".
368 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 This controls what sudo password Rex should use.
376 Default is determined by the following logic:
378 • value of "REX_SUDO_PASSWORD" environment variable
380 • sudo password set by the sudo_password command
382 • password set by the password command
384 • empty string ('')
386 set_source_global_profile
388 get_source_global_profile
389 Sets and gets the value of the $source_global_profile configuration
390 variable.
391 This controls whether Rex should source "/etc/profile" before executing
393 commands.
394 Default is "undef".
396 set_max_connect_fails
398 get_max_connect_fails
399 Sets and gets the value of the $max_connect_fails configuration
400 variable.
401 This controls how many times Rex should retry to connect before giving
403 up.
404 "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 Default is "undef".
410 set_proxy_command
412 get_proxy_command
413 Sets and gets the value of the $proxy_command configuration variable.
414 This controls the SSH ProxyCommand Rex should set for connections when
416 Net::OpenSSH is used.
417 "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 Default is "undef".
423 set_timeout
425 get_timeout
426 Sets and gets the value of the $timeout configuration variable.
427 This controls how many seconds Rex should wait for connections to
429 succeed when using SSH or Rex::Commands::Rsync.
430 "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 Default is "undef".
436 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 This controls whether Rex should use the password authentication
444 method.
445 Default is "undef".
447 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 This controls whether Rex should use the key authentication method.
455 Default is "undef".
457 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 This controls whether Rex should use the Kerberos 5 authentication
465 method.
466 Default is "undef".
468 set_public_key
470 get_public_key
471 Sets and gets the value of the $public_key configuration variable.
472 This controls which public key Rex should use when using Net::SSH2 for
474 connections.
475 Default is "undef".
477 set_private_key
479 get_private_key
480 Sets and gets the value of the $private_key configuration variable.
481 This controls which private key Rex should use with
483 Rex::Commands::Rsync or when using Net::SSH2 for connections.
484 Default is "undef".
486 set_parallelism
488 get_parallelism
489 Sets and gets the value of the $parallelism configuration variable.
490 This controls how many hosts Rex should connect to in parallel.
492 Default is 1.
494 set_log_filename
496 get_log_filename
497 Sets and gets the value of the $log_filename configuration variable.
498 This controls which file Rex should use for logging.
500 Default is "undef".
502 set_log_facility
504 get_log_facility
505 Sets and gets the value of the $log_facility configuration variable.
506 This controls which log facility Rex should use when logging to syslog.
508 Default is 'local0'.
510 set_environment
512 get_environment
513 Sets and gets the value of the $environment configuration variable.
514 This controls which environment Rex should use.
516 Default is ''.
518 set_distributor
520 get_distributor
521 Sets and gets the value of the $distributor configuration variable.
522 This controls which method Rex should use for distributing tasks for
524 parallel execution.
525 Default is 'Base'.
527 set_template_function
529 get_template_function
530 Sets and gets the value of the $template_function configuration
531 variable.
532 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 Default is determined by the following logic:
539 • if Rex::Template::NG is loadable and use_template_ng is true, use
541 that
542 • fall back to Rex::Template otherwise
544 set_no_tty
546 get_no_tty
547 Sets and gets the value of the $no_tty configuration variable.
548 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 Default is "undef".
554 set_allow_empty_groups
556 get_allow_empty_groups
557 Sets and gets the value of the $allow_empty_groups configuration
558 variable.
559 This controls whether Rex should allow empty groups of hosts or not.
561 Default is 0.
563 set_use_server_auth
565 get_use_server_auth
566 Sets and gets the value of the $use_server_auth configuration variable.
567 This controls whether Rex should use server-specific authentication
569 information from group files.
570 Default is 0.
572 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 This controls how many seconds Rex should sleep between checking forks.
579 Default is 0.1.
581 set_write_utf8_files
583 get_write_utf8_files
584 Sets and gets the value of the $write_utf8_files configuration
585 variable.
586 This controls whether Rex should force "UTF-8" encoding when writing
588 files.
589 Default is "undef".
591 set_default_auth
593 get_default_auth
594 Sets and gets the value of the $default_auth configuration variable.
595 This controls whether Rex should attach default authentication info to
597 tasks.
598 Default is 1.
600 register_set_handler($handler_name, $code)
602 Register a handler that gets called by set.
603 Rex::Config->register_set_handler("foo", sub {
605 my ($value) = @_;
606 print "The user set foo -> $value\n";
607 });
608 And now you can use this handler in your Rexfile like this:
610 set foo => "bar";
612 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 Example:
618 Rex::Config->register_config_handler("foo", sub {
620 my ($param) = @_;
621 print "bar is: " . $param->{bar} . "\n";
622 });
623 And now the user can set this in his configuration file:
625 base:
627 user: theuser
628 password: thepassw0rd
629 foo:
630 bar: baz
631perl v5.34.0 2022-01-19 Rex::Config(3)