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 a
85 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 use either the default or the
163 explicitly configured "PATH" settings (via path or set_path) when
164 executing commands or not.
165 Default is "undef".
167 set_source_profile
169 get_source_profile
170 Sets and gets the value of the $source_profile configuration variable.
171 This controls whether Rex should source shell-specific profile files
173 before executing commands.
174 Default is "undef".
176 set_say_format
178 get_say_format
179 Sets and gets the value of the $say_format configuration variable.
180 This controls the output format of the built-in "say" command (see also
182 sayformat).
183 Default is "undef".
185 set_do_reporting
187 get_do_reporting
188 Sets and gets the value of the $do_reporting configuration variable.
189 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 Default is "undef".
195 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 This selects the reporting type (format) Rex should use, e.g. 'YAML'.
203 Default is "undef".
205 set_sleep_hack
207 get_sleep_hack
208 Sets and gets the value of the $sleep_hack configuration variable.
209 This controls whether Rex should use or not an extra 10 ns long sleep
211 after executed commands.
212 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 Default is "undef".
218 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 This selects the cache type Rex should use, e.g. 'YAML'.
226 Default is 'Base'.
228 set_use_cache
230 get_use_cache
231 Sets and gets the value of the $use_cache configuration variable.
232 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 Default is "undef".
239 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 Rex::Config->set_openssh_opt( $option => $value, );
249 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 Rex::Config->set_openssh_opt( initialize_options => { $parameter => $value, } );
257 Default is "undef".
259 set_sudo_without_locales
261 get_sudo_without_locales
262 Sets and gets the value of the $sudo_without_locales configuration
263 variable.
264 This controls whether Rex should execute sudo commands without setting
266 any locales via the "LC_ALL" environment variable.
267 Warning: if the locale is something else than "C" or "en_US", then
269 things will break!
270 Default is "undef".
272 set_sudo_without_sh
274 get_sudo_without_sh
275 Sets and gets the value of the $sudo_without_sh configuration variable.
276 This controls whether Rex should run sudo commands without "sh". This
278 might break things.
279 Default is "undef".
281 set_executor_for
283 get_executor_for
284 Sets and gets the keys and values of the %executor_for configuration
285 variable.
286 This sets the executor for a given file type when using the
288 upload_and_run() function of Rex::Helper::Run module.
289 Default is:
291 (
293 perl => 'perl',
294 python => 'python',
295 ruby => 'ruby',
296 bash => 'bash',
297 )
298 set_tmp_dir
300 get_tmp_dir
301 Sets and gets the value of the $tmp_dir configuration variable.
302 This controls which directory Rex should use for temporary files.
304 Default is determined by the following logic:
306 • try to use what "File::Spec->tmpdir" would return on the managed
308 endpoint
309 • fall back to '/tmp'
311 set_path
313 get_path
314 Sets and gets the value of the $path configuration variable.
315 This controls which "PATH" Rex should use when executing commands via
317 the Rex::Commands::Run module.
318 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 Default is
324 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 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 This controls which user Rex should use for authentication.
342 Default is determined by the following logic:
344 • value of "REX_USER" environment variable
346 • user set by user command
348 • user running Rex
350 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 This controls what password Rex should use for authentication or as
357 passphrase when using private keys.
358 Default is "undef".
360 set_port
362 get_port
363 Sets and gets the value of the $port configuration variable.
364 This controls which port Rex should connect to.
366 "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 Default is "undef".
372 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 This controls what sudo password Rex should use.
380 Default is determined by the following logic:
382 • value of "REX_SUDO_PASSWORD" environment variable
384 • sudo password set by the sudo_password command
386 • password set by the password command
388 • empty string ('')
390 set_source_global_profile
392 get_source_global_profile
393 Sets and gets the value of the $source_global_profile configuration
394 variable.
395 This controls whether Rex should source "/etc/profile" before executing
397 commands.
398 Default is "undef".
400 set_max_connect_fails
402 get_max_connect_fails
403 Sets and gets the value of the $max_connect_fails configuration
404 variable.
405 This controls how many times Rex should retry to connect before giving
407 up.
408 "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 Default is "undef".
414 set_proxy_command
416 get_proxy_command
417 Sets and gets the value of the $proxy_command configuration variable.
418 This controls the SSH ProxyCommand Rex should set for connections when
420 Net::OpenSSH is used.
421 "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 Default is "undef".
427 set_timeout
429 get_timeout
430 Sets and gets the value of the $timeout configuration variable.
431 This controls how many seconds Rex should wait for connections to
433 succeed when using SSH or Rex::Commands::Rsync.
434 "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 Default is "undef".
440 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 This controls whether Rex should use the password authentication
448 method.
449 Default is "undef".
451 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 This controls whether Rex should use the key authentication method.
459 Default is "undef".
461 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 This controls whether Rex should use the Kerberos 5 authentication
469 method.
470 Default is "undef".
472 set_public_key
474 get_public_key
475 Sets and gets the value of the $public_key configuration variable.
476 This controls which public key Rex should use when using Net::SSH2 for
478 connections.
479 Default is "undef".
481 set_private_key
483 get_private_key
484 Sets and gets the value of the $private_key configuration variable.
485 This controls which private key Rex should use with
487 Rex::Commands::Rsync or when using Net::SSH2 for connections.
488 Default is "undef".
490 set_parallelism
492 get_parallelism
493 Sets and gets the value of the $parallelism configuration variable.
494 This controls how many hosts Rex should connect to in parallel.
496 Default is 1.
498 set_log_filename
500 get_log_filename
501 Sets and gets the value of the $log_filename configuration variable.
502 This controls which file Rex should use for logging.
504 Default is "undef".
506 set_log_facility
508 get_log_facility
509 Sets and gets the value of the $log_facility configuration variable.
510 This controls which log facility Rex should use when logging to syslog.
512 Default is 'local0'.
514 set_environment
516 get_environment
517 Sets and gets the value of the $environment configuration variable.
518 This controls which environment Rex should use.
520 Default is ''.
522 set_distributor
524 get_distributor
525 Sets and gets the value of the $distributor configuration variable.
526 This controls which method Rex should use for distributing tasks for
528 parallel execution.
529 Default is 'Base'.
531 set_template_function
533 get_template_function
534 Sets and gets the value of the $template_function configuration
535 variable.
536 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 Default is determined by the following logic:
543 • if Rex::Template::NG is loadable and use_template_ng is true, use
545 that
546 • fall back to Rex::Template otherwise
548 set_no_tty
550 get_no_tty
551 Sets and gets the value of the $no_tty configuration variable.
552 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 Default is "undef".
558 set_allow_empty_groups
560 get_allow_empty_groups
561 Sets and gets the value of the $allow_empty_groups configuration
562 variable.
563 This controls whether Rex should allow empty groups of hosts or not.
565 Default is 0.
567 set_use_server_auth
569 get_use_server_auth
570 Sets and gets the value of the $use_server_auth configuration variable.
571 This controls whether Rex should use server-specific authentication
573 information from group files.
574 Default is 0.
576 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 This controls how many seconds Rex should sleep between checking forks.
583 Default is 0.1.
585 set_write_utf8_files
587 get_write_utf8_files
588 Sets and gets the value of the $write_utf8_files configuration
589 variable.
590 This controls whether Rex should force "UTF-8" encoding when writing
592 files.
593 Default is "undef".
595 set_default_auth
597 get_default_auth
598 Sets and gets the value of the $default_auth configuration variable.
599 This controls whether Rex should attach default authentication info to
601 tasks.
602 Default is 1.
604 register_set_handler($handler_name, $code)
606 Register a handler that gets called by set.
607 Rex::Config->register_set_handler("foo", sub {
609 my ($value) = @_;
610 print "The user set foo -> $value\n";
611 });
612 And now you can use this handler in your Rexfile like this:
614 set foo => "bar";
616 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 Example:
622 Rex::Config->register_config_handler("foo", sub {
624 my ($param) = @_;
625 print "bar is: " . $param->{bar} . "\n";
626 });
627 And now the user can set this in his configuration file:
629 base:
631 user: theuser
632 password: thepassw0rd
633 foo:
634 bar: baz
635perl v5.36.1 2023-08-07 Rex::Config(3)