Provided by: rex_1.14.3-1_all bug

NAME

       Rex::Config - Handles Rex configuration

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

       This module holds all configuration options for Rex, and also allows you to specify your
       own ones for your modules.

       Please take a look at Rex::Commands first, which provides convenience wrappers for many of
       these options.

       While it's possible to use the methods below to set a configuration option directly, their
       main intended purpose is to be used as internal plumbing, and to provide an escape hatch
       in case there are no better alternatives.

EXPORTED METHODS

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

       This controls whether Rex should "die()" if there's an error while executing file system
       commands that are supposed to change the contents.

       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.

       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.

       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.

       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.

       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.

       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.

       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.

       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.

       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.

       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.

       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. This
       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.

       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.

       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.

       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.
       This only affects the data structures returned internally.

       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.

       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'.

   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!

       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.

       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.

       Default is

        qw(
          /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.

       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
       Sets and gets the value of the $source_global_profile configuration variable.

       This controls whether Rex should source "/etc/profile" before executing commands.

       Default is "undef".

   set_max_connect_fails
   get_max_connect_fails
       Sets and gets the value of the $max_connect_fails configuration variable.

       This controls how many times Rex should retry to connect before giving up.

       "get_max_connect_fails" accepts an optional "server => $server" argument to
       "connectionattempts" setting for the 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 configuration variable.

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

       "get_proxy_command" accepts an optional "server => $server" argument to return 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 configuration variable.

       This controls how many seconds Rex should wait for connections to succeed when using SSH
       or Rex::Commands::Rsync.

       "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 configuration 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 configuration 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 configuration 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.

       Default is "undef".

   set_public_key
   get_public_key
       Sets and gets the value of the $public_key configuration 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 configuration variable.

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

       Default is "undef".

   set_parallelism
   get_parallelism
       Sets and gets the value of the $parallelism configuration variable.

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

       Default is 1.

   set_log_filename
   get_log_filename
       Sets and gets the value of the $log_filename configuration 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 configuration 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 configuration variable.

       This controls which environment Rex should use.

       Default is ''.

   set_distributor
   get_distributor
       Sets and gets the value of the $distributor configuration 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 configuration 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:

       •   if Rex::Template::NG is loadable and use_template_ng is true, use that

       •   fall back to Rex::Template otherwise

   set_no_tty
   get_no_tty
       Sets and gets the value of the $no_tty configuration 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 configuration 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 configuration 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 configuration variable.

       This controls how many seconds Rex should sleep between checking forks.

       Default is 0.1.

   set_write_utf8_files
   get_write_utf8_files
       Sets and gets the value of the $write_utf8_files configuration 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 configuration variable.

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

       Default is 1.

   register_set_handler($handler_name, $code)
       Register a handler that gets called by set.

        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").

       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