.\" 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::Task 3pm"
.TH Rex::Task 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::Task \- The Task Object
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Task Object. Typically you only need this class if you want to manipulate tasks after their initial creation.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Rex::Task;
\&
\& # create a new task
\& my $task = Rex::Task\->new( name => \*(Aqtesttask\*(Aq );
\& $task\->set_server(\*(Aqremoteserver\*(Aq);
\& $task\->set_code( sub { say \*(AqHello\*(Aq; } );
\& $task\->modify( \*(Aqno_ssh\*(Aq, 1 );
\&
\& # retrieve an existing task
\& use Rex::TaskList;
\&
\& my $existing_task = Rex::TaskList\->create\->get_task(\*(Aqmy_task\*(Aq);
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
This is the constructor.
.PP
.Vb 10
\& $task = Rex::Task\->new(
\&   func => sub { some_code_here },
\&   server => [ @server ],
\&   desc => $description,
\&   no_ssh => $no_ssh,
\&   hidden => $hidden,
\&   auth => {
\&     user      => $user,
\&     password   => $password,
\&     private_key => $private_key,
\&     public_key  => $public_key,
\&   },
\&   before => [sub {}, sub {}, ...],
\&   after  => [sub {}, sub {}, ...],
\&   around => [sub {}, sub {}, ...],
\&   before_task_start => [sub {}, sub {}, ...],
\&   after_task_finished => [sub {}, sub {}, ...],
\&   name => $task_name,
\&   executor => Rex::Interface::Executor\->create,
\&   opts => {key1 => val1, key2 => val2, ...},
\&   args => [arg1, arg2, ...],
\& );
.Ve
.SS "connection"
.IX Subsection "connection"
Returns the current connection object.
.SS "executor"
.IX Subsection "executor"
Returns the current executor object.
.SS "hidden"
.IX Subsection "hidden"
Returns true if the task is hidden. (Should not be displayed on ,,rex \-T''.)
.SS "server"
.IX Subsection "server"
Returns the servers on which the task should be executed as an ArrayRef.
.SS "set_server(@server)"
.IX Subsection "set_server(@server)"
With this method you can set new servers on which the task should be executed on.
.SS "delete_server"
.IX Subsection "delete_server"
Delete every server registered to the task.
.SS "current_server"
.IX Subsection "current_server"
Returns the current server on which the tasks gets executed right now.
.SS "desc"
.IX Subsection "desc"
Returns the description of a task.
.SS "set_desc($description)"
.IX Subsection "set_desc($description)"
Set the description of a task.
.SS "is_remote"
.IX Subsection "is_remote"
Returns true (1) if the task will be executed remotely.
.SS "is_local"
.IX Subsection "is_local"
Returns true (1) if the task gets executed on the local host.
.SS "is_http"
.IX Subsection "is_http"
Returns true (1) if the task gets executed over http protocol.
.SS "is_https"
.IX Subsection "is_https"
Returns true (1) if the task gets executed over https protocol.
.SS "is_openssh"
.IX Subsection "is_openssh"
Returns true (1) if the task gets executed with openssh.
.SS "want_connect"
.IX Subsection "want_connect"
Returns true (1) if the task will establish a connection to a remote system.
.SS "get_connection_type"
.IX Subsection "get_connection_type"
This method tries to guess the right connection type for the task and returns it.
.PP
Current return values are below:
.IP "\(bu" 4
\&\s-1SSH:\s0 connect to the remote server using Net::SSH2
.IP "\(bu" 4
OpenSSH: connect to the remote server using Net::OpenSSH
.IP "\(bu" 4
Local: runs locally (without any connections)
.IP "\(bu" 4
\&\s-1HTTP:\s0 uses experimental \s-1HTTP\s0 connection
.IP "\(bu" 4
\&\s-1HTTPS:\s0 uses experimental \s-1HTTPS\s0 connection
.IP "\(bu" 4
Fake: populate the connection properties, but do not connect
.Sp
So you can use this type to iterate over a list of remote hosts, but don't let rex build a connection. For example if you want to use Sys::Virt or other modules.
.ie n .SS "modify($key, $value)"
.el .SS "modify($key, \f(CW$value\fP)"
.IX Subsection "modify($key, $value)"
With this method you can modify values of the task.
.SS "rethink_connection"
.IX Subsection "rethink_connection"
Deletes current connection object.
.SS "user"
.IX Subsection "user"
Returns the username the task will use.
.SS "set_user($user)"
.IX Subsection "set_user($user)"
Set the username of a task.
.SS "password"
.IX Subsection "password"
Returns the password that will be used.
.SS "set_password($password)"
.IX Subsection "set_password($password)"
Set the password of the task.
.SS "name"
.IX Subsection "name"
Returns the name of the task.
.SS "code"
.IX Subsection "code"
Returns the code of the task.
.SS "set_code(\e&code_ref)"
.IX Subsection "set_code(&code_ref)"
Set the code of the task.
.ie n .SS "run_hook($server, $hook)"
.el .SS "run_hook($server, \f(CW$hook\fP)"
.IX Subsection "run_hook($server, $hook)"
This method is used internally to execute the specified hooks.
.ie n .SS "set_auth($key, $value)"
.el .SS "set_auth($key, \f(CW$value\fP)"
.IX Subsection "set_auth($key, $value)"
Set the authentication of the task.
.PP
.Vb 2
\& $task\->set_auth("user", "foo");
\& $task\->set_auth("password", "bar");
.Ve
.SS "merge_auth($server)"
.IX Subsection "merge_auth($server)"
Merges the authentication information from \f(CW$server\fR into the task.
Tasks authentication information have precedence.
.SS "get_sudo_password"
.IX Subsection "get_sudo_password"
Returns the sudo password.
.SS "parallelism"
.IX Subsection "parallelism"
Get the parallelism count of a task.
.SS "set_parallelism($count)"
.IX Subsection "set_parallelism($count)"
Set the parallelism of the task.
.SS "connect($server)"
.IX Subsection "connect($server)"
Initiate the connection to \f(CW$server\fR.
.SS "disconnect"
.IX Subsection "disconnect"
Disconnect from the current connection.
.SS "get_data"
.IX Subsection "get_data"
Dump task data.
.ie n .SS "run($server, %options)"
.el .SS "run($server, \f(CW%options\fP)"
.IX Subsection "run($server, %options)"
Run the task on \f(CW$server\fR, with \f(CW%options\fR.
.ie n .SS "modify_task($task, $key => $value)"
.el .SS "modify_task($task, \f(CW$key\fP => \f(CW$value\fP)"
.IX Subsection "modify_task($task, $key => $value)"
Modify \f(CW$task\fR, by setting \f(CW$key\fR to \f(CW$value\fR.
.SS "is_task"
.IX Subsection "is_task"
Returns \fBtrue\fR\|(1) if the passed object is a task.
.SS "get_tasks"
.IX Subsection "get_tasks"
Returns list of tasks.
.SS "get_desc"
.IX Subsection "get_desc"
Returns description of task.
.SS "exit_on_connect_fail"
.IX Subsection "exit_on_connect_fail"
Returns true if rex should exit on connect failure.
.SS "set_exit_on_connect_fail"
.IX Subsection "set_exit_on_connect_fail"
Sets if rex should exit on connect failure.
.SS "get_args"
.IX Subsection "get_args"
Returns arguments of task.
.SS "get_opts"
.IX Subsection "get_opts"
Returns options of task.
.SS "set_args"
.IX Subsection "set_args"
Sets arguments for task.
.SS "set_opt"
.IX Subsection "set_opt"
Sets an option for task.
.SS "set_opts"
.IX Subsection "set_opts"
Sets options for task.
.SS "clone"
.IX Subsection "clone"
Clones a task.