.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Rex::Commands 3pm"
.TH Rex::Commands 3pm "2023-08-09" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Rex::Commands \- All the basic commands
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is the core commands module.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& desc "Task description";
\&
\& task "taskname", sub { ... };
\& task "taskname", "server1", ..., "server20", sub { ... };
\&
\& group "group" => "server1", "server2", ...;
\&
\& user "user";
\&
\& password "password";
\&
\& environment live => sub {
\&   user "root";
\&   password "foobar";
\&   pass_auth;
\&   group frontend => "www01", "www02";
\& };
.Ve
.SH "COMMANDLIST"
.IX Header "COMMANDLIST"
.IP "\(bu" 4
Augeas config file management library Rex::Commands::Augeas
.IP "\(bu" 4
Cloud Management Rex::Commands::Cloud
.IP "\(bu" 4
Cron Management Rex::Commands::Cron
.IP "\(bu" 4
Database Commands Rex::Commands::DB
.IP "\(bu" 4
\&\s-1SCP\s0 Up\- and Download Rex::Commands::Upload, Rex::Commands::Download
.IP "\(bu" 4
File Manipulation Rex::Commands::File
.IP "\(bu" 4
Filesystem Manipulation Rex::Commands::Fs
.IP "\(bu" 4
Information Gathering Rex::Commands::Gather
.IP "\(bu" 4
Manipulation of /etc/hosts Rex::Commands::Host
.IP "\(bu" 4
Get an inventory of your Hardware Rex::Commands::Inventory
.IP "\(bu" 4
Manage your iptables rules Rex::Commands::Iptables
.IP "\(bu" 4
Kernel Commands Rex::Commands::Kernel
.IP "\(bu" 4
\&\s-1LVM\s0 Commands Rex::Commands::LVM
.IP "\(bu" 4
\&\s-1MD5\s0 checksums Rex::Commands::MD5
.IP "\(bu" 4
Network commands Rex::Commands::Network
.IP "\(bu" 4
Notify resources to execute Rex::Commands::Notify
.IP "\(bu" 4
Package Commands Rex::Commands::Pkg
.IP "\(bu" 4
Partition your storage device(s) Rex::Commands::Partition
.IP "\(bu" 4
Configure packages (via debconf) Rex::Commands::PkgConf
.IP "\(bu" 4
Process Management Rex::Commands::Process
.IP "\(bu" 4
Rsync Files Rex::Commands::Rsync
.IP "\(bu" 4
Run Remote Commands Rex::Commands::Run
.IP "\(bu" 4
Source control via Subversion/Git Rex::Commands::SCM
.IP "\(bu" 4
Manage System Services (sysvinit) Rex::Commands::Service
.IP "\(bu" 4
Simple TCP/alive checks Rex::Commands::SimpleCheck
.IP "\(bu" 4
Sync directories Rex::Commands::Sync
.IP "\(bu" 4
Sysctl Commands Rex::Commands::Sysctl
.IP "\(bu" 4
Live Tail files Rex::Commands::Tail
.IP "\(bu" 4
Upload local file to remote server Rex::Commands::Upload
.IP "\(bu" 4
Manage user and group accounts Rex::Commands::User
.IP "\(bu" 4
Manage your virtual environments Rex::Commands::Virtualization
.SH "EXPORTED FUNCTIONS"
.IX Header "EXPORTED FUNCTIONS"
.SS "no_ssh([$task])"
.IX Subsection "no_ssh([$task])"
Disable ssh for all tasks or a specified task.
.PP
If you want to disable ssh connection for your complete tasks (for example if you only want to use libVirt) put this in the main section of your Rexfile.
.PP
.Vb 1
\& no_ssh;
.Ve
.PP
If you want to disable ssh connection for a given task, put \fIno_ssh\fR in front of the task definition.
.PP
.Vb 3
\& no_ssh task "mytask", "myserver", sub {
\&   say "Do something without a ssh connection";
\& };
.Ve
.ie n .SS "task($name [, @servers], $funcref)"
.el .SS "task($name [, \f(CW@servers\fP], \f(CW$funcref\fP)"
.IX Subsection "task($name [, @servers], $funcref)"
This function will create a new task.
.IP "Create a local task (a server independent task)" 4
.IX Item "Create a local task (a server independent task)"
.Vb 3
\& task "mytask", sub {
\&   say "Do something";
\& };
.Ve
.Sp
If you call this task with (R)?ex it will run on your local machine. You can explicit run this task on other machines if you specify the \fI\-H\fR command line parameter.
.IP "Create a server bound task." 4
.IX Item "Create a server bound task."
.Vb 3
\& task "mytask", "server1", sub {
\&   say "Do something";
\& };
.Ve
.Sp
You can also specify more than one server.
.Sp
.Vb 3
\& task "mytask", "server1", "server2", "server3", sub {
\&   say "Do something";
\& };
.Ve
.Sp
Or you can use some expressions to define more than one server.
.Sp
.Vb 3
\& task "mytask", "server[1..3]", sub {
\&   say "Do something";
\& };
.Ve
.Sp
If you want, you can overwrite the servers with the \fI\-H\fR command line parameter.
.IP "Create a group bound task." 4
.IX Item "Create a group bound task."
You can define server groups with the \fIgroup\fR function.
.Sp
.Vb 1
\& group "allserver" => "server[1..3]", "workstation[1..10]";
\&
\& task "mytask", group => "allserver", sub {
\&   say "Do something";
\& };
.Ve
.SS "desc($description)"
.IX Subsection "desc($description)"
Set the description of the task, batch, or environment following it.
.PP
.Vb 4
\& desc \*(AqThis is the description of the following task\*(Aq;
\& task \*(Aqmytask\*(Aq, sub {
\&   say \*(AqDo something\*(Aq;
\& };
\&
\& desc \*(AqThis is the description of the following batch\*(Aq;
\& batch mybatch => \*(Aqtask1\*(Aq, \*(Aqtask2\*(Aq, \*(Aqtask3\*(Aq;
\&
\& desc \*(AqThis is the description of the following environment\*(Aq;
\& environment production => sub {
\&   ...
\& };
.Ve
.ie n .SS "group($name, @servers)"
.el .SS "group($name, \f(CW@servers\fP)"
.IX Subsection "group($name, @servers)"
With this function you can group servers, so that you don't need to write too much ;\-)
.PP
.Vb 1
\& group "servergroup", "www1", "www2", "www3", "memcache01", "memcache02", "memcache03";
.Ve
.PP
Or with the expression syntax:
.PP
.Vb 1
\& group "servergroup", "www[1..3]", "memcache[01..03]";
.Ve
.PP
If the \f(CW\*(C`use_server_auth\*(C'\fR feature flag is enabled, you can also specify server options after a server name with a hash reference:
.PP
.Vb 1
\& use Rex \-feature => [\*(Aquse_server_auth\*(Aq];
\&
\& group "servergroup", "www1" => { user => "other" }, "www2";
.Ve
.PP
These expressions are allowed:
.IP "\(bu" 4
\&\ed+..\ed+ (range)
.Sp
The first number is the start and the second number is the
end for numbering the servers.
.Sp
.Vb 1
\& group "name", "www[1..3]"; # www1, www2, www3
.Ve
.IP "\(bu" 4
\&\ed+..\ed+/\ed+ (range with step)
.Sp
Just like the range notation, but with an additional \*(L"step\*(R" defined.
If step is omitted, it defaults to 1 (i.e. it behaves like a simple range expression).
.Sp
.Vb 2
\& group "name", "www[1..5/2]";      # www1, www3, www5
\& group "name", "www[111..133/11]"; # www111, www122, www133
.Ve
.IP "\(bu" 4
\&\ed+,\ed+,\ed+ (list)
.Sp
With this variant you can define fixed values.
.Sp
.Vb 1
\& group "name", "www[1,3,7,01]"; # www1, www3, www7, www01
.Ve
.IP "\(bu" 4
Mixed list, range and range with step
.Sp
You can mix the three variants above
.Sp
.Vb 1
\& www[1..3,5,9..21/3]; # www1, www2, www3, www5, www9, www12, www15, www18, www21
.Ve
.ie n .SS "batch($name, @tasks)"
.el .SS "batch($name, \f(CW@tasks\fP)"
.IX Subsection "batch($name, @tasks)"
With the batch function you can call tasks in a batch.
.PP
.Vb 1
\& batch "name", "task1", "task2", "task3";
.Ve
.PP
And call it with the \fI\-b\fR console parameter. \fIrex \-b name\fR
.SS "user($user)"
.IX Subsection "user($user)"
Set the user for the ssh connection.
.SS "password($password)"
.IX Subsection "password($password)"
Set the password for the ssh connection (or for the private key file).
.ie n .SS "auth(for => $entity, %data)"
.el .SS "auth(for => \f(CW$entity\fP, \f(CW%data\fP)"
.IX Subsection "auth(for => $entity, %data)"
With this command you can set or modify authentication parameters for tasks and groups. (Please note this is different than setting authentication details for the members of a host group. If you are looking for that, please check out the group <https://metacpan.org/pod/Rex::Commands#group> command.)
.PP
If you want to set special login information for a group you have to enable at least the \f(CW0.31\fR feature flag, and ensure the \f(CW\*(C`group\*(C'\fR is declared before the \f(CW\*(C`auth\*(C'\fR command.
.PP
Command line options to set locality or authentication details are still taking precedence, and may override these settings.
.PP
.Vb 1
\& # auth for groups
\&
\& use Rex \-feature => [\*(Aq0.31\*(Aq]; # activate setting auth for a group
\&
\& group frontends => "web[01..10]";
\& group backends => "be[01..05]";
\&
\& auth for => "frontends" =>
\&            user => "root",
\&            password => "foobar";
\&
\& auth for => "backends" =>
\&            user => "admin",
\&            private_key => "/path/to/id_rsa",
\&            public_key => "/path/to/id_rsa.pub",
\&            sudo => TRUE;
\&
\& # auth for tasks
\&
\& task "prepare", group => ["frontends", "backends"], sub {
\&   # do something
\& };
\&
\& auth for => "prepare" =>
\&            user => "root";
\&
\& # auth for multiple tasks with regular expression
\&
\& task "step_1", sub {
\&  # do something
\& };
\&
\& task "step_2", sub {
\&  # do something
\& };
\&
\& auth for => qr/step/ =>
\&   user     => $user,
\&   password => $password;
\&
\& # fallback auth
\& auth fallback => {
\&   user        => "fallback_user1",
\&   password    => "fallback_pw1",
\&   public_key  => "",
\&   private_key => "",
\& }, {
\&   user        => "fallback_user2",
\&   password    => "fallback_pw2",
\&   public_key  => "keys/public.key",
\&   private_key => "keys/private.key",
\&   sudo        => TRUE,
\& };
.Ve
.SS "port($port)"
.IX Subsection "port($port)"
Set the port where the ssh server is listening.
.SS "sudo_password($password)"
.IX Subsection "sudo_password($password)"
Set the password for the sudo command.
.SS "timeout($seconds)"
.IX Subsection "timeout($seconds)"
Set the timeout for the ssh connection and other network related stuff.
.SS "max_connect_retries($count)"
.IX Subsection "max_connect_retries($count)"
Set the maximum number of connection retries.
.ie n .SS "get_random($count, @chars)"
.el .SS "get_random($count, \f(CW@chars\fP)"
.IX Subsection "get_random($count, @chars)"
Returns a random string of \f(CW$count\fR characters on the basis of \f(CW@chars\fR.
.PP
.Vb 1
\& my $rnd = get_random(8, \*(Aqa\*(Aq .. \*(Aqz\*(Aq);
.Ve
.SS "do_task($task)"
.IX Subsection "do_task($task)"
Call \f(CW$task\fR from another task. It will establish a new connection to the server defined in \f(CW$task\fR and then execute \f(CW$task\fR there.
.PP
.Vb 4
\& task "task1", "server1", sub {
\&   say "Running on server1";
\&   do_task "task2";
\& };
\&
\& task "task2", "server2", sub {
\&   say "Running on server2";
\& };
.Ve
.PP
You may also use an arrayRef for \f(CW$task\fR if you want to call multiple tasks.
.PP
.Vb 1
\& do_task [ qw/task1 task2 task3/ ];
.Ve
.ie n .SS "run_task($task_name, %option)"
.el .SS "run_task($task_name, \f(CW%option\fP)"
.IX Subsection "run_task($task_name, %option)"
Run a task on a given host.
.PP
.Vb 1
\& my $return = run_task "taskname", on => "192.168.3.56";
.Ve
.PP
Do something on server5 if memory is less than 100 \s-1MB\s0 free on server3.
.PP
.Vb 7
\& task "prepare", "server5", sub {
\&   my $free_mem = run_task "get_free_mem", on => "server3";
\&   if($free_mem < 100) {
\&     say "Less than 100 MB free mem on server3";
\&     # create a new server instance on server5 to unload server3
\&   }
\& };
\&
\& task "get_free_mem", sub {
\&    return memory\->{free};
\& };
.Ve
.PP
If called without a hostname the task is run localy.
.PP
.Vb 5
\& # this task will run on server5
\& task "prepare", "server5", sub {
\&   # this will call task check_something. but this task will run on localhost.
\&   my $check = run_task "check_something";
\& }
\&
\& task "check_something", "server4", sub {
\&   return "foo";
\& };
.Ve
.PP
If you want to add custom parameters for the task you can do it this way.
.PP
.Vb 3
\& task "prepare", "server5", sub {
\&  run_task "check_something", on => "foo", params => { param1 => "value1", param2 => "value2" };
\& };
.Ve
.ie n .SS "run_batch($batch_name, %option)"
.el .SS "run_batch($batch_name, \f(CW%option\fP)"
.IX Subsection "run_batch($batch_name, %option)"
Run a batch on a given host.
.PP
.Vb 1
\& my @return = run_batch "batchname", on => "192.168.3.56";
.Ve
.PP
It calls internally run_task, and passes it any option given.
.SS "public_key($key)"
.IX Subsection "public_key($key)"
Set the public key.
.SS "private_key($key)"
.IX Subsection "private_key($key)"
Set the private key.
.SS "pass_auth"
.IX Subsection "pass_auth"
If you want to use password authentication, then you need to call \fIpass_auth\fR.
.PP
.Vb 2
\& user "root";
\& password "root";
\&
\& pass_auth;
.Ve
.SS "key_auth"
.IX Subsection "key_auth"
If you want to use pubkey authentication, then you need to call \fIkey_auth\fR.
.PP
.Vb 3
\& user "bob";
\& private_key "/home/bob/.ssh/id_rsa"; # passphrase\-less key
\& public_key "/home/bob/.ssh/id_rsa.pub";
\&
\& key_auth;
.Ve
.SS "krb5_auth"
.IX Subsection "krb5_auth"
If you want to use kerberos authentication, then you need to call \fIkrb5_auth\fR.
This authentication mechanism is only available if you use Net::OpenSSH.
.PP
.Vb 3
\& set connection => "OpenSSH";
\& user "root";
\& krb5_auth;
.Ve
.SS "parallelism($count)"
.IX Subsection "parallelism($count)"
Will execute the tasks in parallel on the given servers. \f(CW$count\fR is the thread count to be used:
.PP
.Vb 1
\& parallelism \*(Aq2\*(Aq; # set parallelism to 2
.Ve
.PP
Alternatively, the following notation can be used to set thread count more dynamically:
.PP
.Vb 3
\& parallelism \*(Aqmax\*(Aq;     # set parallelism to the number of servers a task is asked to run on
\& parallelism \*(Aqmax/3\*(Aq;   # set parallelism to 1/3 of the number of servers
\& parallelism \*(Aqmax 10%\*(Aq; # set parallelism to 10% of the number of servers
.Ve
.PP
If an unrecognized value is passed, or the calculated thread count would be less than 1, Rex falls back to use a single thread.
.SS "proxy_command($cmd)"
.IX Subsection "proxy_command($cmd)"
Set a proxy command to use for the connection. This is only possible with OpenSSH connection method.
.PP
.Vb 2
\& set connection => "OpenSSH";
\& proxy_command "ssh user@jumphost nc %h %p 2>/dev/null";
.Ve
.SS "set_distributor($distributor)"
.IX Subsection "set_distributor($distributor)"
This sets the task distribution module. Default is \*(L"Base\*(R".
.PP
Possible values are: Base, Gearman, Parallel_ForkManager
.SS "template_function(sub { ... })"
.IX Subsection "template_function(sub { ... })"
This function sets the template processing function. So it is possible to change the template engine. For example to Template::Toolkit.
.SS "logging"
.IX Subsection "logging"
With this function you can define the logging behaviour of (R)?ex.
.IP "Logging to a file" 4
.IX Item "Logging to a file"
.Vb 1
\& logging to_file => "rex.log";
.Ve
.IP "Logging to syslog" 4
.IX Item "Logging to syslog"
.Vb 1
\& logging to_syslog => $facility;
.Ve
.ie n .SS "needs($package [, @tasks])"
.el .SS "needs($package [, \f(CW@tasks\fP])"
.IX Subsection "needs($package [, @tasks])"
With \fIneeds\fR you can define dependencies between tasks. The \*(L"needed\*(R" tasks will be called with the same server configuration as the calling task.
.PP
\&\fIneeds\fR will not execute before, around and after hooks.
.IP "Depend on all tasks in a given package." 4
.IX Item "Depend on all tasks in a given package."
Depend on all tasks in the package MyPkg. All tasks will be called with the server \fIserver1\fR.
.Sp
.Vb 3
\& task "mytask", "server1", sub {
\&   needs MyPkg;
\& };
.Ve
.IP "Depend on a single task in a given package." 4
.IX Item "Depend on a single task in a given package."
Depend on the \fIuname\fR task in the package MyPkg. The \fIuname\fR task will be called with the server \fIserver1\fR.
.Sp
.Vb 3
\& task "mytask", "server1", sub {
\&   needs MyPkg "uname";
\& };
.Ve
.IP "To call tasks defined in the Rexfile from within a module" 4
.IX Item "To call tasks defined in the Rexfile from within a module"
.Vb 3
\& task "mytask", "server1", sub {
\&   needs main "uname";
\& };
.Ve
.SS "include Module::Name"
.IX Subsection "include Module::Name"
Include a module without registering its tasks.
.PP
.Vb 4
\&  include qw/
\&    Module::One
\&    Module::Two
\&  /;
.Ve
.ie n .SS "environment($name => $code)"
.el .SS "environment($name => \f(CW$code\fP)"
.IX Subsection "environment($name => $code)"
Define an environment. With environments one can use the same task for different hosts. For example if you want to use the same task on your integration\-, test\- and production servers.
.PP
.Vb 4
\& # define default user/password
\& user "root";
\& password "foobar";
\& pass_auth;
\&
\& # define default frontend group containing only testwww01.
\& group frontend => "testwww01";
\&
\& # define live environment, with different user/password
\& # and a frontend server group containing www01, www02 and www03.
\& environment live => sub {
\&   user "root";
\&   password "livefoo";
\&   pass_auth;
\&
\&   group frontend => "www01", "www02", "www03";
\& };
\&
\& # define stage environment with default user and password. but with
\& # a own frontend group containing only stagewww01.
\& environment stage => sub {
\&   group frontend => "stagewww01";
\& };
\&
\& task "prepare", group => "frontend", sub {
\&    say run "hostname";
\& };
.Ve
.PP
Calling this task \fIrex prepare\fR will execute on testwww01.
Calling this task with \fIrex \-E live prepare\fR will execute on www01, www02, www03.
Calling this task \fIrex \-E stage prepare\fR will execute on stagewww01.
.PP
You can call the function within a task to get the current environment.
.PP
.Vb 5
\& task "prepare", group => "frontend", sub {
\&   if(environment() eq "dev") {
\&     say "i\*(Aqm in the dev environment";
\&   }
\& };
.Ve
.PP
If no \fI\-E\fR option is passed on the command line, the default environment
(named 'default') will be used.
.SS "\s-1LOCAL\s0(&)"
.IX Subsection "LOCAL(&)"
With the \s-1LOCAL\s0 function you can do local commands within a task that is defined to work on remote servers.
.PP
.Vb 3
\& task "mytask", "server1", "server2", sub {
\&    # this will call \*(Aquptime\*(Aq on the servers \*(Aqserver1\*(Aq and \*(Aqserver2\*(Aq
\&    say run "uptime";
\&
\&    # this will call \*(Aquptime\*(Aq on the local machine.
\&    LOCAL {
\&      say run "uptime";
\&    };
\& };
.Ve
.SS "path(@path)"
.IX Subsection "path(@path)"
Set the execution path for all commands.
.PP
.Vb 1
\& path "/bin", "/sbin", "/usr/bin", "/usr/sbin", "/usr/pkg/bin", "/usr/pkg/sbin";
.Ve
.PP
It's a convenience wrapper for the set_path configuration option.
.ie n .SS "set($key, $value)"
.el .SS "set($key, \f(CW$value\fP)"
.IX Subsection "set($key, $value)"
Set a configuration parameter. These variables can be used in templates as well.
.PP
.Vb 1
\& set database => "db01";
\&
\& task "prepare", sub {
\&   my $db = get "database";
\& };
.Ve
.PP
Or in a template
.PP
.Vb 1
\& DB: <%= $::database %>
.Ve
.PP
The following list of configuration parameters are Rex specific:
.ie n .SS "get($key, $value)"
.el .SS "get($key, \f(CW$value\fP)"
.IX Subsection "get($key, $value)"
Get a configuration parameter.
.PP
.Vb 1
\& set database => "db01";
\&
\& task "prepare", sub {
\&   my $db = get "database";
\& };
.Ve
.PP
Or in a template
.PP
.Vb 1
\& DB: <%= $::database %>
.Ve
.SS "before($task => sub {})"
.IX Subsection "before($task => sub {})"
Run code before executing the specified task.
.PP
The task name is a regular expression to find all tasks with a matching name. The special task name \f(CW\*(AqALL\*(Aq\fR can also be used to run code before all tasks.
.PP
If called repeatedly, each sub will be appended to a list of 'before' functions.
.PP
In this hook you can overwrite the server to which the task will connect to. The second argument is a reference to the
server object that will be used for the connection.
.PP
Please note, this must come after the definition of the specified task.
.PP
.Vb 4
\& before mytask => sub {
\&  my ($server, $server_ref, $cli_args) = @_;
\&  run "vzctl start vm$server";
\& };
.Ve
.SS "after($task => sub {})"
.IX Subsection "after($task => sub {})"
Run code after executing the specified task.
.PP
The task name is a regular expression to find all tasks with a matching name. The special task name \f(CW\*(AqALL\*(Aq\fR can be used to run code after all tasks.
.PP
If called repeatedly, each sub will be appended to a list of 'after' functions.
.PP
Please note, this must come after the definition of the specified task.
.PP
.Vb 3
\& after mytask => sub {
\&  my ($server, $failed, $cli_args) = @_;
\&  if($failed) { say "Connection to $server failed."; }
\&
\&  run "vzctl stop vm$server";
\& };
.Ve
.SS "around($task => sub {})"
.IX Subsection "around($task => sub {})"
Run code around the specified task (that is both before and after executing it).
.PP
The task name is a regular expression to find all tasks with a matching name. The special task name \f(CW\*(AqALL\*(Aq\fR can be used to run code around all tasks.
.PP
If called repeatedly, each sub will be appended to a list of 'around' functions.
.PP
In this hook you can overwrite the server to which the task will connect to. The second argument is a reference to the
server object that will be used for the connection.
.PP
Please note, this must come after the definition of the specified task.
.PP
.Vb 2
\& around mytask => sub {
\&  my ($server, $server_ref, $cli_args, $position) = @_;
\&
\&  unless($position) {
\&    say "Before Task\en";
\&  }
\&  else {
\&    say "After Task\en";
\&  }
\& };
.Ve
.SS "before_task_start($task => sub {})"
.IX Subsection "before_task_start($task => sub {})"
Run code before executing the specified task. This gets executed only once for a task.
.PP
The task name is a regular expression to find all tasks with a matching name. The special task name \f(CW\*(AqALL\*(Aq\fR can be used to run code before all tasks.
.PP
If called repeatedly, each sub will be appended to a list of 'before_task_start' functions.
.PP
Please note, this must come after the definition of the specified task.
.PP
.Vb 3
\& before_task_start mytask => sub {
\&   # do some things
\& };
.Ve
.SS "after_task_finished($task => sub {})"
.IX Subsection "after_task_finished($task => sub {})"
Run code after the task is finished (and after the ssh connection is terminated). This gets executed only once for a task.
.PP
The task name is a regular expression to find all tasks with a matching name. The special task name \f(CW\*(AqALL\*(Aq\fR can be used to run code after all tasks.
.PP
If called repeatedly, each sub will be appended to a list of 'after_task_finished' functions.
.PP
Please note, this must come after the definition of the specified task.
.PP
.Vb 3
\& after_task_finished mytask => sub {
\&   # do some things
\& };
.Ve
.SS "logformat($format)"
.IX Subsection "logformat($format)"
You can define the logging format with the following parameters.
.PP
\&\f(CW%D\fR \- Appends the current date yyyy-mm-dd HH:mm:ss
.PP
\&\f(CW%h\fR \- The target host
.PP
\&\f(CW%p\fR \- The pid of the running process
.PP
\&\f(CW%l\fR \- Loglevel (\s-1INFO\s0 or \s-1DEBUG\s0)
.PP
\&\f(CW%s\fR \- The Logstring
.PP
Default is: [%D] \f(CW%l\fR \- \f(CW%s\fR
.SS "connection"
.IX Subsection "connection"
This function returns the current connection object.
.PP
.Vb 3
\& task "foo", group => "baz", sub {
\&   say "Current Server: " . connection\->server;
\& };
.Ve
.SS "cache"
.IX Subsection "cache"
This function returns the current cache object.
.SS "profiler"
.IX Subsection "profiler"
Returns the profiler object for the current connection.
.ie n .SS "report($switch, $type)"
.el .SS "report($switch, \f(CW$type\fP)"
.IX Subsection "report($switch, $type)"
This function will initialize the reporting.
.PP
.Vb 1
\& report \-on => "YAML";
.Ve
.SS "source_global_profile(0|1)"
.IX Subsection "source_global_profile(0|1)"
If this option is set, every \fBrun()\fR command will first source /etc/profile before getting executed.
.SS "last_command_output"
.IX Subsection "last_command_output"
This function returns the output of the last \*(L"run\*(R" command.
.PP
On a debian system this example will return the output of \fIapt-get install foobar\fR.
.PP
.Vb 4
\& task "mytask", "myserver", sub {
\&   install "foobar";
\&   say last_command_output();
\& };
.Ve
.ie n .SS "case($compare, $option)"
.el .SS "case($compare, \f(CW$option\fP)"
.IX Subsection "case($compare, $option)"
This is a function to compare a string with some given options.
.PP
.Vb 5
\& task "mytask", "myserver", sub {
\&   my $ntp_service = case operating_system, {
\&                 Debian  => "ntp",
\&                 default => "ntpd",
\&               };
\&
\&   my $ntp_service = case operating_system, {
\&                 qr{debian}i => "ntp",
\&                 default    => "ntpd",
\&               };
\&
\&   my $ntp_service = case operating_system, {
\&                 qr{debian}i => "ntp",
\&                 default    => sub { return "foo"; },
\&               };
\& };
.Ve
.ie n .SS "set_executor_for($type, $executor)"
.el .SS "set_executor_for($type, \f(CW$executor\fP)"
.IX Subsection "set_executor_for($type, $executor)"
Set the executor for a special type. This is primary used for the upload_and_run helper function.
.PP
.Vb 1
\& set_executor_for perl => "/opt/local/bin/perl";
.Ve
.SS "tmp_dir($tmp_dir)"
.IX Subsection "tmp_dir($tmp_dir)"
Set the tmp directory on the remote host to store temporary files.
.SS "inspect($varRef)"
.IX Subsection "inspect($varRef)"
This function dumps the contents of a variable to \s-1STDOUT.\s0
.PP
.Vb 5
\& task "mytask", "myserver", sub {
\&   my $myvar = {
\&     name => "foo",
\&     sys  => "bar",
\&   };
\&
\&   inspect $myvar;
\& };
.Ve
.SS "sayformat($format)"
.IX Subsection "sayformat($format)"
You can define the format of the \fBsay()\fR function.
.PP
\&\f(CW%D\fR \- The current date yyyy-mm-dd HH:mm:ss
.PP
\&\f(CW%h\fR \- The target host
.PP
\&\f(CW%p\fR \- The pid of the running process
.PP
\&\f(CW%s\fR \- The Logstring
.PP
You can also define the following values:
.PP
default \- the default behaviour.
.PP
asis \- will print every single parameter in its own line. This is useful if you want to print the output of a command.