Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Rex::Config(3)	      User Contributed Perl Documentation	Rex::Config(3)

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	clean up the $PATH before executing a
       run command.

       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:

       o   try to use what "File::Spec->tmpdir"	would return on	the managed
	   endpoint

       o   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	run commands.
       The value should	be set as an array reference, and will be dereferenced
       as such before returned by "get_path".

       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:

       o   value of "REX_USER" environment variable

       o   user	set by user command

       o   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:

       o   value of "REX_SUDO_PASSWORD"	environment variable

       o   sudo	password set by	the sudo_password command

       o   password set	by the password	command

       o   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:

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

       o   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

perl v5.32.0			  2020-08-05			Rex::Config(3)

NAME | SYNOPSIS | DESCRIPTION | EXPORTED METHODS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Rex::Config&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help