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 run($command [, $callback], %options)
17 This function will execute the given $command and returns the output.
18 In scalar context it returns the raw output as is, and in list context
19 it returns the list of output lines. The exit value of the command is
20 stored in the $? variable.
21 run 'uptime';
23 my $output = run 'uptime';
24 my @output_lines = run 'uptime';
25 It supports optional callbacks as subroutine reference, which will
27 receive the command's output sent to "STDOUT" and "STDERR".
28 run 'uptime', sub {
30 my ( $stdout, $stderr ) = @_;
31 my $server = Rex::get_current_connection()->{server};
32 say "[$server] $stdout\n";
33 };
34 It also takes further options in a form of a hash. Supported options
36 are:
37 cwd => $path
39 Sets the working directory of the executed command to $path.
40 only_if => $condition_command
42 Executes the command only if $condition_command returns success.
43 unless => $condition_command
45 Executes the command if $condition_command returns failure.
46 only_notified => TRUE
48 Queues the command to be executed later upon notification.
49 env => { var1 => $value1, ..., varN => $valueN }
51 Sets environment variables for the given command.
52 timeout => value
54 Sets the timeout for the command to be run.
55 auto_die => TRUE
57 Die if the command returns with an exit code indicating failure. It
58 can be set globally via the exec_autodie feature flag.
59 command => $command_to_run
61 If present, Rex will execute $command_to_run, and treat the first
62 arugment as an identifier for the given "run()" block (e.g. to be
63 triggered with notify).
64 creates => $file_to_create
66 Tries to create $file_to_create upon execution, and skips execution
67 if the file already exists.
68 continuous_read => $callback
70 Calls $callback subroutine reference for each line of the command's
71 output, passing the line as an argument.
72 end_if_matched => qr{$pattern}
74 End execution early as soon as $pattern is detected in the
75 command's output.
76 Examples:
78 If you only want to run a command if another command succeeds or fails,
80 use the "only_if" or "unless" options.
81 run 'some-command',
83 only_if => 'pgrep httpd'; # only run if httpd is running
84 run 'some-other-command',
86 unless => 'pgrep httpd'; # only run if httpd is _not_ running
87 If you want to set custom environment variables you can do it like
89 this:
90 run 'my_command',
92 env => {
93 env_var_1 => 'the value for 1',
94 env_var_2 => 'the value for 2',
95 };
96 If you want to end the command upon receiving a certain output:
98 run 'my_command',
100 end_if_matched => qr{$pattern};
101 run($command, $arguments, %options)
103 This form will execute $command with the given $arguments pass as an
104 array reference. All arguments will be quoted by Rex with
105 "Net::OpenSSH::ShellQuoter-"quoter()> according to the managed host's
106 shell.
107 run 'ls', [ '-l', '-t', '-r', '-a' ];
109 run 'ls', [ '/tmp', '-l' ], auto_die => TRUE;
110 run($command_description, command => $command, %options)
112 If you only want to run a command in certain cases, you can queue the
113 command and notify it to trigger its execution.
114 run 'extract-something',
116 command => 'tar -C /foo -xzf /tmp/foo.tgz',
117 only_notified => TRUE;
118 # some code ...
120 notify 'run', 'extract-something'; # now the command gets executed
122 can_run($command)
124 This function checks if a command is available in the path. It accepts
125 a list of commands, and returns the full path to the first command
126 found.
127 task 'uptime', sub {
129 if ( my $cmd = can_run( 'uptime', 'downtime' ) ) {
130 say run $cmd;
131 }
132 };
133 sudo
135 Run a single command, a code block, or all commands with "sudo". You
136 need perl to be available on the remote systems to use "sudo".
137 Depending on your remote sudo configuration, you may need to define a
139 sudo password with sudo_password first:
140 sudo_password 'my_sudo_password'; # hardcoding
142 Or alternatively, since Rexfile is plain perl, you can read the
144 password from terminal at the start:
145 use Term::ReadKey;
147 print 'I need sudo password: ';
149 ReadMode('noecho');
150 sudo_password ReadLine(0);
151 ReadMode('restore');
152 Similarly, it is also possible to read it from a secret file, database,
154 etc.
155 You can turn sudo on globally with:
157 sudo TRUE; # run _everything_ with sudo
159 To run only a specific command with sudo, use :
161 say sudo 'id'; # passing a remote command directly
163 say sudo { command => 'id' }; # passing anonymous hashref
164 say sudo { command => 'id', user => 'different' }; # run a single command with sudo as different user
166 To run multiple commands with "sudo", either use an anonymous code
168 reference directly:
169 sudo sub {
171 service 'nginx' => 'restart';
172 say run 'id';
173 };
174 or pass it via "command" (optionally along a different user):
176 sudo {
178 command => sub {
179 say run 'id';
180 say run 'pwd', cwd => '/home/different';
181 },
182 user => 'different',
183 };
184 Note that some users receive the error "sudo: sorry, you must have a
186 tty to run sudo". In this case you have to disable "requiretty" for
187 this user. You can do this in your sudoers file with the following
188 code:
189 Defaults:$username !requiretty
191perl v5.36.0 2022-07-20 Rex::Commands::Run(3)