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 Examples:
64 If you only want to run a command in special cases, you can queue the
66 command and notify it when you want to run it.
67 task "prepare", sub {
69 run "extract-something",
70 command => "tar -C /foo -xzf /tmp/foo.tgz",
71 only_notified => TRUE;
72 # some code ...
74 notify "run", "extract-something"; # now the command gets executed
76 };
77 If you only want to run a command if another command succeeds or fails,
79 you can use only_if or unless option.
80 run "some-command",
82 only_if => "ps -ef | grep -q httpd"; # only run if httpd is running
83 run "some-other-command",
85 unless => "ps -ef | grep -q httpd"; # only run if httpd is not running
86 If you want to set custom environment variables you can do it like
88 this:
89 run "my_command",
91 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",
99 end_if_matched => qr/PATTERN/;
100 can_run($command)
102 This function checks if a command is in the path or is available. You
103 can specify multiple commands, the first command found will be
104 returned.
105 task "uptime", sub {
107 if( my $cmd = can_run("uptime", "downtime") ) {
108 say run $cmd;
109 }
110 };
111 sudo
113 Run a single command, a code block, or all commands with "sudo". You
114 need perl to be available on the remote systems to use "sudo".
115 Depending on your remote sudo configuration, you may need to define a
117 sudo password with sudo_password first:
118 sudo_password 'my_sudo_password'; # hardcoding
120 Or alternatively, since Rexfile is plain perl, you can read the
122 password from terminal at the start:
123 use Term::ReadKey;
125 print 'I need sudo password: ';
127 ReadMode('noecho');
128 sudo_password ReadLine(0);
129 ReadMode('restore');
130 Similarly, it is also possible to read it from a secret file, database,
132 etc.
133 You can turn sudo on globally with:
135 sudo TRUE; # run _everything_ with sudo
137 To run only a specific command with sudo, use :
139 say sudo 'id'; # passing a remote command directly
141 say sudo { command => 'id' }; # passing anonymous hashref
142 say sudo { command => 'id', user => 'different' }; # run a single command with sudo as different user
144 # running a single command with sudo as different user, and `cd` to another directory too
146 say sudo { command => 'id', user => 'different', cwd => '/home/different' };
147 Passing an anonymous coderef to "sudo" allows for running the commands
149 in the sub with sudo:
150 sudo sub {
152 service 'nginx' => 'restart';
153 say run 'id';
154 };
155perl v5.28.1 2017-03-01 Rex::Commands::Run(3)