1Rex::Config(3) User Contributed Perl Documentation Rex::Config(3)
2
3
4
6 Rex::Config - Handles Rex configuration
7
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
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
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 2021-07-21 Rex::Config(3)