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 run($command, $arguments, %options)
18 This form will execute $command with the given $arguments. $arguments
19 must be an array reference. The arguments will be quoted.
20 run "ls", ["-l", "-t", "-r", "-a"];
22 run "ls", ["/tmp", "-l"], auto_die => TRUE;
23 run($command_description, command => $command, %options)
25 This function will execute the given command and returns the output. In
26 scalar context it returns the raw output as is, and in list context it
27 returns the list of output lines. The exit value of the command is
28 stored in the $? variable.
29 task "uptime", "server01", sub {
31 say run "uptime";
32 run "uptime", sub {
33 my ($stdout, $stderr) = @_;
34 my $server = Rex::get_current_connection()->{server};
35 say "[$server] $stdout\n";
36 };
37 };
38 Supported options are:
40 cwd => $path
42 sets the working directory of the executed command to $path
43 only_if => $condition_command
44 executes the command only if $condition_command completes successfully
45 unless => $condition_command
46 executes the command unless $condition_command completes successfully
47 only_notified => TRUE
48 queues the command, to be executed upon notification (see below)
49 env => { var1 => $value1, ..., varN => $valueN }
50 sets environment variables in the environment of the command
51 timeout => value
52 sets the timeout for the command to be run
53 auto_die => TRUE
54 die if the command returns with a non-zero exit code
55 it can be set globally via the exec_autodie feature flag
56 command => $command_to_run
57 if set, run tries to execute the specified command and the first argument
58 becomes an identifier for the run block (e.g. to be triggered with notify)
59 creates => $file_to_create
60 tries to create $file_to_create upon execution
61 skips execution if the file already exists
62 continuous_read => $callback
63 calls $callback subroutine reference for each line of the command's output,
64 passing the line as an argument
65 Examples:
67 If you only want to run a command in special cases, you can queue the
69 command and notify it when you want to run it.
70 task "prepare", sub {
72 run "extract-something",
73 command => "tar -C /foo -xzf /tmp/foo.tgz",
74 only_notified => TRUE;
75 # some code ...
77 notify "run", "extract-something"; # now the command gets executed
79 };
80 If you only want to run a command if another command succeeds or fails,
82 you can use only_if or unless option.
83 run "some-command",
85 only_if => "ps -ef | grep -q httpd"; # only run if httpd is running
86 run "some-other-command",
88 unless => "ps -ef | grep -q httpd"; # only run if httpd is not running
89 If you want to set custom environment variables you can do it like
91 this:
92 run "my_command",
94 env => {
96 env_var_1 => "the value for 1",
97 env_var_2 => "the value for 2",
98 };
99 If you want to end the command upon receiving a certain output:
101 run "my_command",
102 end_if_matched => qr/PATTERN/;
103 can_run($command)
105 This function checks if a command is in the path or is available. You
106 can specify multiple commands, the first command found will be
107 returned.
108 task "uptime", sub {
110 if( my $cmd = can_run("uptime", "downtime") ) {
111 say run $cmd;
112 }
113 };
114 sudo
116 Run a single command, a code block, or all commands with "sudo". You
117 need perl to be available on the remote systems to use "sudo".
118 Depending on your remote sudo configuration, you may need to define a
120 sudo password with sudo_password first:
121 sudo_password 'my_sudo_password'; # hardcoding
123 Or alternatively, since Rexfile is plain perl, you can read the
125 password from terminal at the start:
126 use Term::ReadKey;
128 print 'I need sudo password: ';
130 ReadMode('noecho');
131 sudo_password ReadLine(0);
132 ReadMode('restore');
133 Similarly, it is also possible to read it from a secret file, database,
135 etc.
136 You can turn sudo on globally with:
138 sudo TRUE; # run _everything_ with sudo
140 To run only a specific command with sudo, use :
142 say sudo 'id'; # passing a remote command directly
144 say sudo { command => 'id' }; # passing anonymous hashref
145 say sudo { command => 'id', user => 'different' }; # run a single command with sudo as different user
147 To run multiple commands with "sudo", either use an anonymous code
149 reference directly:
150 sudo sub {
152 service 'nginx' => 'restart';
153 say run 'id';
154 };
155 or pass it via "command" (optionally along a different user):
157 sudo {
159 command => sub {
160 say run 'id';
161 say run 'pwd', cwd => '/home/different';
162 },
163 user => 'different',
164 };
165 Note that some users receive the error "sudo: sorry, you must have a
167 tty to run sudo". In this case you have to disable "requiretty" for
168 this user. You can do this in your sudoers file with the following
169 code:
170 Defaults:$username !requiretty
172perl v5.32.1 2021-03-06 Rex::Commands::Run(3)