1Rex::Commands::Run(3) User Contributed Perl DocumentationRex::Commands::Run(3)
2
6 Rex::Commands::Run - Execute a remote command
7
9 With this module you can run a command.
10
12 my $output = run 'ls -l';
13 sudo 'id';
14
16 Please note that Rex may set the "PATH" environment variable when
17 executing commands on the user's behalf to a different value compared
18 to executing the same commands manually. The following are available to
19 control the related behavior:
20 path command
22 set_path configuration option
23 no_path_cleanup feature flag
24 source_profile feature flag
25 source_global_profile feature flag
26
28 run($command [, $callback], %options)
29 This function will execute the given $command and returns the output.
30 In scalar context it returns the raw output as is, and in list context
31 it returns the list of output lines. The exit value of the command is
32 stored in the $? variable.
33 run 'uptime';
35 my $output = run 'uptime';
36 my @output_lines = run 'uptime';
37 Please note when the "tty" feature flag is enabled the combined output
39 containing both "STDOUT" and "STDERR" is returned via "STDOUT". When
40 using the "no_tty" feature flag, or the 1.0 feature bundle (or newer),
41 then run() returns only the "STDOUT" output of the command.
42 To access separate "STDOUT" and "STDERR" output, use a callback
44 subroutine, for example:
45 run 'uptime', sub {
47 my ( $stdout, $stderr ) = @_;
48 my $server = Rex::get_current_connection()->{server};
49 say "[$server] $stdout\n";
50 };
51 It also takes further options in a form of a hash. Supported options
53 are:
54 cwd => $path
56 Sets the working directory of the executed command to $path.
57 only_if => $condition_command
59 Executes the command only if $condition_command returns success.
60 unless => $condition_command
62 Executes the command if $condition_command returns failure.
63 only_notified => TRUE
65 Queues the command to be executed later upon notification.
66 env => { var1 => $value1, ..., varN => $valueN }
68 Sets environment variables for the given command.
69 timeout => value
71 Sets the timeout for the command to be run.
72 auto_die => TRUE
74 Die if the command returns with an exit code indicating failure. It
75 can be set globally via the exec_autodie feature flag.
76 command => $command_to_run
78 If present, Rex will execute $command_to_run, and treat the first
79 arugment as an identifier for the given run() block (e.g. to be
80 triggered with notify).
81 creates => $file_to_create
83 Tries to create $file_to_create upon execution, and skips execution
84 if the file already exists.
85 continuous_read => $callback
87 Calls $callback subroutine reference for each line of the command's
88 output, passing the line as an argument.
89 end_if_matched => qr{$pattern}
91 End execution early as soon as $pattern is detected in the
92 command's output.
93 Examples:
95 If you only want to run a command if another command succeeds or fails,
97 use the "only_if" or "unless" options.
98 run 'some-command',
100 only_if => 'pgrep httpd'; # only run if httpd is running
101 run 'some-other-command',
103 unless => 'pgrep httpd'; # only run if httpd is _not_ running
104 If you want to set custom environment variables you can do it like
106 this:
107 run 'my_command',
109 env => {
110 env_var_1 => 'the value for 1',
111 env_var_2 => 'the value for 2',
112 };
113 If you want to end the command upon receiving a certain output:
115 run 'my_command',
117 end_if_matched => qr{$pattern};
118 run($command, $arguments, %options)
120 This form will execute $command with the given $arguments pass as an
121 array reference. All arguments will be quoted by Rex with
122 "Net::OpenSSH::ShellQuoter->quoter()" according to the managed host's
123 shell.
124 run 'ls', [ '-l', '-t', '-r', '-a' ];
126 run 'ls', [ '/tmp', '-l' ], auto_die => TRUE;
127 run($command_description, command => $command, %options)
129 If you only want to run a command in certain cases, you can queue the
130 command and notify it to trigger its execution.
131 run 'extract-something',
133 command => 'tar -C /foo -xzf /tmp/foo.tgz',
134 only_notified => TRUE;
135 # some code ...
137 notify 'run', 'extract-something'; # now the command gets executed
139 can_run($command)
141 This function checks if a command is available in the path. It accepts
142 a list of commands, and returns the full path to the first command
143 found.
144 task 'uptime', sub {
146 if ( my $cmd = can_run( 'uptime', 'downtime' ) ) {
147 say run $cmd;
148 }
149 };
150 sudo
152 Run a single command, a code block, or all commands with "sudo". You
153 need perl to be available on the remote systems to use "sudo".
154 Depending on your remote sudo configuration, you may need to define a
156 sudo password with sudo_password first:
157 sudo_password 'my_sudo_password'; # hardcoding
159 Or alternatively, since Rexfile is plain perl, you can read the
161 password from terminal at the start:
162 use Term::ReadKey;
164 print 'I need sudo password: ';
166 ReadMode('noecho');
167 sudo_password ReadLine(0);
168 ReadMode('restore');
169 Similarly, it is also possible to read it from a secret file, database,
171 etc.
172 You can turn sudo on globally with:
174 sudo TRUE; # run _everything_ with sudo
176 To run only a specific command with sudo, use :
178 say sudo 'id'; # passing a remote command directly
180 say sudo { command => 'id' }; # passing anonymous hashref
181 say sudo { command => 'id', user => 'different' }; # run a single command with sudo as different user
183 To run multiple commands with "sudo", either use an anonymous code
185 reference directly:
186 sudo sub {
188 service 'nginx' => 'restart';
189 say run 'id';
190 };
191 or pass it via "command" (optionally along a different user):
193 sudo {
195 command => sub {
196 say run 'id';
197 say run 'pwd', cwd => '/home/different';
198 },
199 user => 'different',
200 };
201 Note that some users receive the error "sudo: sorry, you must have a
203 tty to run sudo". In this case you have to disable "requiretty" for
204 this user. You can do this in your sudoers file with the following
205 code:
206 Defaults:$username !requiretty
208perl v5.38.0 2023-08-07 Rex::Commands::Run(3)