.\" 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::Run 3pm"
.TH Rex::Commands::Run 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::Run \- Execute a remote command
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
With this module you can run a command.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& my $output = run \*(Aqls \-l\*(Aq;
\& sudo \*(Aqid\*(Aq;
.Ve
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
Please note that Rex may set the \f(CW\*(C`PATH\*(C'\fR environment variable when executing commands on the user's behalf to a different value compared to executing the same commands manually. The following are available to control the related behavior:
.IP "path command" 4
.IX Item "path command"
.PD 0
.IP "set_path configuration option" 4
.IX Item "set_path configuration option"
.IP "no_path_cleanup feature flag" 4
.IX Item "no_path_cleanup feature flag"
.IP "source_profile feature flag" 4
.IX Item "source_profile feature flag"
.IP "source_global_profile feature flag" 4
.IX Item "source_global_profile feature flag"
.PD
.SH "EXPORTED FUNCTIONS"
.IX Header "EXPORTED FUNCTIONS"
.ie n .SS "run($command [, $callback], %options)"
.el .SS "run($command [, \f(CW$callback\fP], \f(CW%options\fP)"
.IX Subsection "run($command [, $callback], %options)"
This function will execute the given \f(CW$command\fR and returns the output. In
scalar context it returns the raw output as is, and in list context it
returns the list of output lines. The exit value of the command is stored
in the \f(CW$?\fR variable.
.PP
.Vb 3
\& run \*(Aquptime\*(Aq;
\& my $output       = run \*(Aquptime\*(Aq;
\& my @output_lines = run \*(Aquptime\*(Aq;
.Ve
.PP
Please note when the \f(CW\*(C`tty\*(C'\fR feature flag is enabled the
combined output containing both \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR is returned
via \f(CW\*(C`STDOUT\*(C'\fR. When using the \f(CW\*(C`no_tty\*(C'\fR feature flag, or
the \f(CW1.0\fR feature bundle (or newer), then \f(CW\*(C`run()\*(C'\fR returns
only the \f(CW\*(C`STDOUT\*(C'\fR output of the command.
.PP
To access separate \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR output, use a callback
subroutine, for example:
.PP
.Vb 5
\& run \*(Aquptime\*(Aq, sub {
\&   my ( $stdout, $stderr ) = @_;
\&   my $server = Rex::get_current_connection()\->{server};
\&   say "[$server] $stdout\en";
\& };
.Ve
.PP
It also takes further options in a form of a hash. Supported options are:
.ie n .IP "cwd => $path" 4
.el .IP "cwd => \f(CW$path\fR" 4
.IX Item "cwd => $path"
Sets the working directory of the executed command to \f(CW$path\fR.
.ie n .IP "only_if => $condition_command" 4
.el .IP "only_if => \f(CW$condition_command\fR" 4
.IX Item "only_if => $condition_command"
Executes the command only if \f(CW$condition_command\fR returns success.
.ie n .IP "unless => $condition_command" 4
.el .IP "unless => \f(CW$condition_command\fR" 4
.IX Item "unless => $condition_command"
Executes the command if \f(CW$condition_command\fR returns failure.
.IP "only_notified => \s-1TRUE\s0" 4
.IX Item "only_notified => TRUE"
Queues the command to be executed later upon notification.
.ie n .IP "env => { var1 => $value1, ..., varN => $valueN }" 4
.el .IP "env => { var1 => \f(CW$value1\fR, ..., varN => \f(CW$valueN\fR }" 4
.IX Item "env => { var1 => $value1, ..., varN => $valueN }"
Sets environment variables for the given command.
.IP "timeout => value" 4
.IX Item "timeout => value"
Sets the timeout for the command to be run.
.IP "auto_die => \s-1TRUE\s0" 4
.IX Item "auto_die => TRUE"
Die if the command returns with an exit code indicating failure. It can be set globally via the exec_autodie feature flag.
.ie n .IP "command => $command_to_run" 4
.el .IP "command => \f(CW$command_to_run\fR" 4
.IX Item "command => $command_to_run"
If present, Rex will execute \f(CW$command_to_run\fR, and treat the first argument as an identifier for the given \f(CW\*(C`run()\*(C'\fR block (e.g. to be triggered with notify).
.ie n .IP "creates => $file_to_create" 4
.el .IP "creates => \f(CW$file_to_create\fR" 4
.IX Item "creates => $file_to_create"
Tries to create \f(CW$file_to_create\fR upon execution, and skips execution if the file already exists.
.ie n .IP "continuous_read => $callback" 4
.el .IP "continuous_read => \f(CW$callback\fR" 4
.IX Item "continuous_read => $callback"
Calls \f(CW$callback\fR subroutine reference for each line of the command's output, passing the line as an argument.
.IP "end_if_matched => qr{$pattern}" 4
.IX Item "end_if_matched => qr{$pattern}"
End execution early as soon as \f(CW$pattern\fR is detected in the command's output.
.PP
Examples:
.PP
If you only want to run a command if another command succeeds or fails, use the \f(CW\*(C`only_if\*(C'\fR or \f(CW\*(C`unless\*(C'\fR options.
.PP
.Vb 2
\& run \*(Aqsome\-command\*(Aq,
\&   only_if => \*(Aqpgrep httpd\*(Aq; # only run if httpd is running
\&
\& run \*(Aqsome\-other\-command\*(Aq,
\&   unless => \*(Aqpgrep httpd\*(Aq; # only run if httpd is _not_ running
.Ve
.PP
If you want to set custom environment variables you can do it like this:
.PP
.Vb 5
\& run \*(Aqmy_command\*(Aq,
\&   env => {
\&     env_var_1 => \*(Aqthe value for 1\*(Aq,
\&     env_var_2 => \*(Aqthe value for 2\*(Aq,
\&   };
.Ve
.PP
If you want to end the command upon receiving a certain output:
.PP
.Vb 2
\& run \*(Aqmy_command\*(Aq,
\&   end_if_matched => qr{$pattern};
.Ve
.ie n .SS "run($command, $arguments, %options)"
.el .SS "run($command, \f(CW$arguments\fP, \f(CW%options\fP)"
.IX Subsection "run($command, $arguments, %options)"
This form will execute \f(CW$command\fR with the given \f(CW$arguments\fR pass as an array reference.
All arguments will be quoted by Rex with \f(CW\*(C`Net::OpenSSH::ShellQuoter\->quoter()\*(C'\fR according to the managed host's shell.
.PP
.Vb 2
\& run \*(Aqls\*(Aq, [ \*(Aq\-l\*(Aq, \*(Aq\-t\*(Aq, \*(Aq\-r\*(Aq, \*(Aq\-a\*(Aq ];
\& run \*(Aqls\*(Aq, [ \*(Aq/tmp\*(Aq, \*(Aq\-l\*(Aq ], auto_die => TRUE;
.Ve
.ie n .SS "run($command_description, command => $command, %options)"
.el .SS "run($command_description, command => \f(CW$command\fP, \f(CW%options\fP)"
.IX Subsection "run($command_description, command => $command, %options)"
If you only want to run a command in certain cases, you can queue the command
and notify it to trigger its execution.
.PP
.Vb 3
\& run \*(Aqextract\-something\*(Aq,
\&   command       => \*(Aqtar \-C /foo \-xzf /tmp/foo.tgz\*(Aq,
\&   only_notified => TRUE;
\&
\& # some code ...
\&
\& notify \*(Aqrun\*(Aq, \*(Aqextract\-something\*(Aq; # now the command gets executed
.Ve
.SS "can_run($command)"
.IX Subsection "can_run($command)"
This function checks if a command is available in the path. It accepts a list of commands, and returns the full path to the first command found.
.PP
.Vb 5
\& task \*(Aquptime\*(Aq, sub {
\&   if ( my $cmd = can_run( \*(Aquptime\*(Aq, \*(Aqdowntime\*(Aq ) ) {
\&     say run $cmd;
\&   }
\& };
.Ve
.SS "sudo"
.IX Subsection "sudo"
Run a single command, a code block, or all commands with \f(CW\*(C`sudo\*(C'\fR. You need perl to be available on the remote systems to use \f(CW\*(C`sudo\*(C'\fR.
.PP
Depending on your remote sudo configuration, you may need to define a sudo password with \fIsudo_password\fR first:
.PP
.Vb 1
\& sudo_password \*(Aqmy_sudo_password\*(Aq; # hardcoding
.Ve
.PP
Or alternatively, since Rexfile is plain perl, you can read the password from terminal at the start:
.PP
.Vb 1
\& use Term::ReadKey;
\&
\& print \*(AqI need sudo password: \*(Aq;
\& ReadMode(\*(Aqnoecho\*(Aq);
\& sudo_password ReadLine(0);
\& ReadMode(\*(Aqrestore\*(Aq);
.Ve
.PP
Similarly, it is also possible to read it from a secret file, database, etc.
.PP
You can turn sudo on globally with:
.PP
.Vb 1
\& sudo TRUE; # run _everything_ with sudo
.Ve
.PP
To run only a specific command with sudo, use :
.PP
.Vb 2
\& say sudo \*(Aqid\*(Aq;                # passing a remote command directly
\& say sudo { command => \*(Aqid\*(Aq }; # passing anonymous hashref
\&
\& say sudo { command => \*(Aqid\*(Aq, user => \*(Aqdifferent\*(Aq }; # run a single command with sudo as different user
.Ve
.PP
To run multiple commands with \f(CW\*(C`sudo\*(C'\fR, either use an anonymous code reference directly:
.PP
.Vb 4
\& sudo sub {
\&     service \*(Aqnginx\*(Aq => \*(Aqrestart\*(Aq;
\&     say run \*(Aqid\*(Aq;
\& };
.Ve
.PP
or pass it via \f(CW\*(C`command\*(C'\fR (optionally along a different user):
.PP
.Vb 7
\& sudo {
\&     command => sub {
\&         say run \*(Aqid\*(Aq;
\&         say run \*(Aqpwd\*(Aq, cwd => \*(Aq/home/different\*(Aq;
\&     },
\&     user => \*(Aqdifferent\*(Aq,
\& };
.Ve
.PP
\&\fBNote\fR that some users receive the error \f(CW\*(C`sudo: sorry, you must have a tty
to run sudo\*(C'\fR. In this case you have to disable \f(CW\*(C`requiretty\*(C'\fR for this user.
You can do this in your sudoers file with the following code:
.PP
.Vb 1
\&   Defaults:$username !requiretty
.Ve