Rex::Config(3pm)

📦
version 1.16.1 · 7 versions
, in ubuntu resolute, ubuntu stonking

✨ Rex::Config(3pm) ✨

User Contributed Perl Documentation — ok bestie, sit down, hydrate, because this is THE page for everything your Rex config can do 🫶

🎀 NAME 🎀

Rex::Config — handlin' Rex configuration, that's the whole job, no cap.

🌸 SYNOPSIS 🌸

use Rex::Config;

# set a config option
Rex::Config->set_exec_autodie(TRUE);

# get value of a config option
my $user = Rex::Config->get_user();

🦋 DESCRIPTION 🦋

So like, this module is where all the configuration options for Rex live, and it also lets you roll your own ones for your own modules. Custom config? Iconic behavior, honestly.

Lowkey important: go peek at Rex::Commands first, bestie — it has convenience wrappers for a lot of these options and it will make your life so much easier. 💖

Now, technically you can use the methods below to set a configuration option directly. But their main character purpose is to be internal plumbing, plus an escape hatch for when there's literally no better alternative. So like… use them, but know what you're doing, iykyk. 👑

💅 EXPORTED METHODS 💅

⭐ set_autodie / get_autodie

Sets and gets the value of the $autodie configuration variable.

This one controls whether Rex should die() when there's an error while executing file system commands that are supposed to change the contents. Mess around and find out energy. 💀

Default is undef.

⭐ set_use_net_openssh_if_present / get_use_net_openssh_if_present

Sets and gets the value of the $use_net_openssh_if_present configuration variable.

This controls whether Rex should use Net::OpenSSH for connections if that is available. If it's there, use it, periodt.

Default is undef.

⭐ set_use_rex_kvm_agent / get_use_rex_kvm_agent

Sets and gets the value of the $use_rex_kvm_agent configuration variable.

This controls whether Rex should setup and use a serial device for the experimental Rex KVM agent <https://github.com/RexOps/rex-kvm-agent> for managed VMs. Experimental, so like, proceed with the cute little caution emoji energy 🧚

Default is undef.

⭐ set_use_template_ng / get_use_template_ng

Sets and gets the value of the $use_template_ng configuration variable.

This controls whether Rex should use Rex::Template::NG to render templates. Fancy templates, slay. ✨

Default is undef.

⭐ set_set_no_append / get_set_no_append

Sets and gets the value of the $set_no_append configuration variable.

This controls whether Rex should overwrite or append values of configuration options when using the set command. Overwrite vs append — pick your fighter. 🥊

Default is undef.

⭐ set_check_service_exists / get_check_service_exists

Sets and gets the value of the $check_service_exists configuration variable.

This controls whether Rex should die() early if it is asked to manage a service that doesn't exist. Early die() = fewer sad surprises fr fr.

Default is undef.

⭐ set_register_cmdb_template / get_register_cmdb_template

Sets and gets the value of the $register_cmdb_template configuration variable.

This controls whether Rex should make CMDB data available to be used in templates as variables. Your data, but in your templates. Gorgeous. 💖

Default is undef.

⭐ set_fallback_auth / get_fallback_auth

Sets and gets the value of the $fallback_auth configuration variable.

This can be used to define an array of hash references, each of them containing authentication details to be tried during connection attempts when the directly specified ones fail. It's the "if plan A ghosts me, plan B steps in" setting. 🙈

Default is undef.

⭐ set_task_call_by_method / get_task_call_by_method

Sets and gets the value of the $task_call_by_method configuration variable.

This controls whether calling tasks as a method is allowed or not. Yes or no, no in-between. ✋

Default is undef.

⭐ set_disable_taskname_warning / get_disable_taskname_warning

Sets and gets the value of the $disable_taskname_warning configuration variable.

This controls whether Rex should show or suppress the warning message about task names that can not be used as Perl identifiers. Sometimes you just don't want the notification, and that's valid. 💅

Default is undef.

⭐ set_task_chaining_cmdline_args / get_task_chaining_cmdline_args

Sets and gets the value of the $task_chaining_cmdline_args configuration variable.

This controls whether Rex should parse task arguments on the command line per task, or should pass all arguments to all tasks. One for each vs. all for everyone — both valid, depends on your vibe. 🎀

Default is undef.

⭐ set_verbose_run / get_verbose_run

Sets and gets the value of the $verbose_run configuration variable.

This controls whether Rex should show verbose output about executed run commands. That means:

  • an error message if the command is not found,
  • a warning message if the exit code indicates an error,
  • and an informational message upon success.

So basically: Rex telling you the whole story, start to finish. 🗣️

Default is undef.

⭐ set_exec_autodie / get_exec_autodie

Sets and gets the value of the $exec_autodie configuration variable.

This controls whether Rex should die() or not when the exit code of executed run command indicate an error. Dramatic? Maybe. Effective? Extremely. 😭

Default is undef.

⭐ set_no_path_cleanup / get_no_path_cleanup

Sets and gets the value of the $no_path_cleanup configuration variable.

This controls whether Rex should use either the default or the explicitly configured PATH settings (via path or set_path) when executing commands or not.

Default is undef.

⭐ set_source_profile / get_source_profile

Sets and gets the value of the $source_profile configuration variable.

This controls whether Rex should source shell-specific profile files before executing commands. Gotta load the lore first. 📜

Default is undef.

⭐ set_say_format / get_say_format

Sets and gets the value of the $say_format configuration variable.

This controls the output format of the built-in say command (see also sayformat).

Default is undef.

⭐ set_do_reporting / get_do_reporting

Sets and gets the value of the $do_reporting configuration variable.

This controls whether Rex should do reporting on executed resources where it is supported. Heads up though: this only affects the data structures returned internally. It's a backstage thing, not a stage thing. 🎭

Default is undef.

⭐ set_report_type / get_report_type

Sets and gets the value of the $report_type configuration variable, which can also be controlled via the REX_REPORT_TYPE environment variable.

This selects the reporting type (format) Rex should use, e.g. 'YAML'.

Default is undef.

⭐ set_sleep_hack / get_sleep_hack

Sets and gets the value of the $sleep_hack configuration variable.

This controls whether Rex should use or not an extra 10 ns long sleep after executed commands.

This might help working around an issue when Rex runs inside a KVM virtualized host and Net::SSH2/libssh2 <https://www.libssh2.org> is used to connect to another VM on the same hardware. Ten whole nanoseconds of peace and quiet. 😴

Default is undef.

⭐ set_cache_type / get_cache_type

Sets and gets the value of the $cache_type configuration variable, which can also be controlled via the REX_CACHE_TYPE environment variable.

This selects the cache type Rex should use, e.g. 'YAML'.

Default is 'Base'. (Yes bestie, this one actually has a default-default, look at her go ✨)

⭐ set_use_cache / get_use_cache

Sets and gets the value of the $use_cache configuration variable.

This controls whether Rex should use caching or not for runtime information like CMDB contents, hardware and operating system information, or the shell type that is being used to execute commands on the managed endpoint.

Default is undef.

⭐ set_openssh_opt / get_openssh_opt

Sets and gets the value of the $openssh_opt configuration variable, which holds a hash of the SSH configuration options used for the connection. See the ssh_config(5) man page <http://man.openbsd.org/OpenBSD-current/man5/ssh_config.5> for the available options.

Rex::Config->set_openssh_opt( $option => $value, );

There is a custom option named initialize_options specific to Rex, which can be used to pass a hash reference describing the constructor parameters <https://metacpan.org/pod/Net::OpenSSH#Net::OpenSSH->new($host,-%opts)> for the underlying Net::OpenSSH object:

Rex::Config->set_openssh_opt( initialize_options => { $parameter => $value, } );

Default is undef.

⭐ set_sudo_without_locales / get_sudo_without_locales

Sets and gets the value of the $sudo_without_locales configuration variable.

This controls whether Rex should execute sudo commands without setting any locales via the LC_ALL environment variable.

⚠️ Warning: if the locale is something else than C or en_US, then things will break! Like, will-break-break. Do not test this on a Friday. 😭

Default is undef.

⭐ set_sudo_without_sh / get_sudo_without_sh

Sets and gets the value of the $sudo_without_sh configuration variable.

This controls whether Rex should run sudo commands without sh. This might break things. That's it, that's the warning, bestie said what she said. 🫠

Default is undef.

⭐ set_executor_for / get_executor_for

Sets and gets the keys and values of the %executor_for configuration variable.

This sets the executor for a given file type when using the upload_and_run() function of Rex::Helper::Run module.

Default is:

(
  perl   => 'perl',
  python => 'python',
  ruby   => 'ruby',
  bash   => 'bash',
)

⭐ set_tmp_dir / get_tmp_dir

Sets and gets the value of the $tmp_dir configuration variable.

This controls which directory Rex should use for temporary files.

Default is determined by the following logic:

  • try to use what File::Spec->tmpdir would return on the managed endpoint
  • fall back to '/tmp'

⭐ set_path / get_path

Sets and gets the value of the $path configuration variable.

This controls which PATH Rex should use when executing commands via the Rex::Commands::Run module.

The value should be set as an array reference, and will be dereferenced as such before returned by get_path. The path command is a convenience wrapper for set_path, and accepts an array. Convenience? We love her. 🎀

Default is:

qw(
  /usr/gnu/bin
  /bin
  /sbin
  /usr/bin
  /usr/sbin
  /usr/local/bin
  /usr/local/sbin
  /usr/pkg/bin
  /usr/pkg/sbin
)

⭐ set_user / get_user

Sets and gets the value of the $user configuration variable, which also can be set via the REX_USER environment variable.

This controls which user Rex should use for authentication.

Default is determined by the following logic:

  • value of REX_USER environment variable
  • user set by user command
  • user running Rex

⭐ set_password / get_password

Sets and gets the value of the $password configuration variable, which also can be set via the REX_PASSWORD environment variable.

This controls what password Rex should use for authentication or as passphrase when using private keys.

Default is undef.

⭐ set_port / get_port

Sets and gets the value of the $port configuration variable.

This controls which port Rex should connect to.

get_port accepts an optional server => $server argument to return the port setting for the given $server as optionally set in group files. Cute little per-server override moment. 🦋

Default is undef.

⭐ set_sudo_password / get_sudo_password

Sets and gets the value of the $sudo_password configuration variable, which can also be controlled via the REX_SUDO_PASSWORD environment variable.

This controls what sudo password Rex should use.

Default is determined by the following logic:

  • value of REX_SUDO_PASSWORD environment variable
  • sudo password set by the sudo_password command
  • password set by the password command
  • empty string ('')

set_source_global_profile / get_source_global_profile

Okay so these two set and get the value of the $source_global_profile config variable 💅

What it actually does: it controls whether Rex should source /etc/profile before executing commands. That's it, that's the whole job.

Default is undef.

set_max_connect_fails / get_max_connect_fails

Sets and gets the value of the $max_connect_fails config variable ✨

This one controls how many times Rex should retry to connect before giving up. Like, Rex is NOT a quitter but even Rex has limits bestie 😭

Heads up tho: get_max_connect_fails accepts an optional server => $server argument — it'll hand you the connectionattempts setting for that given $server, as optionally set in group files.

Default is undef.

set_proxy_command / get_proxy_command

Sets and gets the value of the $proxy_command config variable 🦋

This controls the SSH ProxyCommand Rex should set for connections when Net::OpenSSH is used.

And get_proxy_command accepts an optional server => $server argument, which returns the proxycommand setting for the given $server as optionally set in group files.

Default is undef.

set_timeout / get_timeout

Sets and gets the value of the $timeout config variable ⏳

This controls how many seconds Rex should wait for connections to succeed when using SSH or Rex::Commands::Rsync. Basically the "how long do I hold my breath waiting for you" number.

get_timeout accepts an optional server => $server argument to return the connecttimeout setting for the given $server as optionally set in group files.

Default is undef.

set_password_auth / get_password_auth

Sets and gets the value of the $password_auth config variable 🔐 — which can ALSO be set by setting the REX_AUTH_TYPE environment variable to pass.

This controls whether Rex should use the password authentication method.

Default is undef.

set_key_auth / get_key_auth

Sets and gets the value of the $key_auth config variable 🗝️ — which can also be set by setting the REX_AUTH_TYPE environment variable to key.

This controls whether Rex should use the key authentication method.

Default is undef.

set_krb5_auth / get_krb5_auth

Sets and gets the value of the $krb5_auth config variable 🎫 — which can also be set by setting the REX_AUTH_TYPE environment variable to krb5.

This controls whether Rex should use the Kerberos 5 authentication method. Very fancy, very corporate, we love her.

Default is undef.

set_public_key / get_public_key

Sets and gets the value of the $public_key config variable ✨

This controls which public key Rex should use when using Net::SSH2 for connections.

Default is undef.

set_private_key / get_private_key

Sets and gets the value of the $private_key config variable 🔑

This controls which private key Rex should use with Rex::Commands::Rsync or when using Net::SSH2 for connections.

Default is undef.

Bestie. The private key is the SECRET one. Don't be posting it in the group chat 💀

set_parallelism / get_parallelism

Sets and gets the value of the $parallelism config variable 🌈

This controls how many hosts Rex should connect to in parallel. Multitasking queen behaviour.

Default is 1.

set_log_filename / get_log_filename

Sets and gets the value of the $log_filename config variable 📝

This controls which file Rex should use for logging.

Default is undef.

set_log_facility / get_log_facility

Sets and gets the value of the $log_facility config variable 🏠

This controls which log facility Rex should use when logging to syslog.

Default is 'local0'.

set_environment / get_environment

Sets and gets the value of the $environment config variable 🌸

This controls which environment Rex should use.

Default is ''.

set_distributor / get_distributor

Sets and gets the value of the $distributor config variable 📦

This controls which method Rex should use for distributing tasks for parallel execution.

Default is 'Base'.

set_template_function / get_template_function

Sets and gets the value of the $template_function config variable 🎀

This controls the function to be used for rendering templates. The value should be a subroutine reference that will be called with passing two scalar references as positional arguments: first is template content, second is template variables.

Default is determined by the following logic:

  1. if Rex::Template::NG is loadable and use_template_ng is true, use that
  2. fall back to Rex::Template otherwise

set_no_tty / get_no_tty

Sets and gets the value of the $no_tty config variable 🖥️

This controls whether Rex should request a terminal when using Net::SSH2 or allocate a pseudo-tty for the remote process when using Net::OpenSSH.

Default is undef.

set_allow_empty_groups / get_allow_empty_groups

Sets and gets the value of the $allow_empty_groups config variable 🫶

This controls whether Rex should allow empty groups of hosts or not.

Default is 0.

set_use_server_auth / get_use_server_auth

Sets and gets the value of the $use_server_auth config variable 🔒

This controls whether Rex should use server-specific authentication information from group files.

Default is 0.

set_waitpid_blocking_sleep_time / get_waitpid_blocking_sleep_time

Sets and gets the value of the $waitpid_blocking_sleep_time config variable 😴

This controls how many seconds Rex should sleep between checking forks. Lil nap break, she deserves it.

Default is 0.1.

set_write_utf8_files / get_write_utf8_files

Sets and gets the value of the $write_utf8_files config variable ✨

This controls whether Rex should force UTF-8 encoding when writing files.

Default is undef.

set_default_auth / get_default_auth

Sets and gets the value of the $default_auth config variable 🔑

This controls whether Rex should attach default authentication info to tasks.

Default is 1.

set_augeas_commands_prepend / get_augeas_commands_prepend

Sets and gets the value of the $augeas_commands_prepend config variable 🌿

This controls the list of commands Rex should prepend at the beginning of the command file for Augeas operations.

Default is "[]".

set_local_augeas_backend / get_local_augeas_backend

Sets and gets the value of the $local_augeas_backend config variable 🌱

This controls which Augeas backend to use for local operations, augtool or Config::Augeas.

Default is Config::Augeas.

✨ Custom handler registration ✨

register_set_handler($handler_name, $code)

Register a handler that gets called by set. Obsessed with the flexibility honestly 💅

Rex::Config->register_set_handler("foo", sub {
  my ($value) = @_;
  print "The user set foo -> $value\n";
});

And now you can use this handler in your Rexfile like this:

set foo => "bar";

register_config_handler($topic, $code)

With this function it is possible to register own sections in the users config file ($HOME/.rex/config.yml). Your config, your rules, main character energy 👑

Example:

Rex::Config->register_config_handler("foo", sub {
 my ($param) = @_;
 print "bar is: " . $param->{bar} . "\n";
});

And now the user can set this in his configuration file:

base:
  user: theuser
  password: thepassw0rd
foo:
  bar: baz

And that's the whole page bestie, no cap, fr fr 🫶 This one's from perl v5.40.1, dated 2025-10-03, and it's the Rex::Config(3pm) manpage — go forth and configure your little heart out 💖✨🎀🦋🌸

📦 where this page comes from