1Rex::Commands::Run(3) User Contributed Perl DocumentationRex::Commands::Run(3)
2
3
4

NAME

6       Rex::Commands::Run - Execute a remote command
7

DESCRIPTION

9       With this module you can run a command.
10

SYNOPSIS

12        my $output = run 'ls -l';
13        sudo 'id';
14

CONFIGURATION AND ENVIRONMENT

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
21       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

EXPORTED FUNCTIONS

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
34        run 'uptime';
35        my $output       = run 'uptime';
36        my @output_lines = run 'uptime';
37
38       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
43       To access separate "STDOUT" and "STDERR" output, use a callback
44       subroutine, for example:
45
46        run 'uptime', sub {
47          my ( $stdout, $stderr ) = @_;
48          my $server = Rex::get_current_connection()->{server};
49          say "[$server] $stdout\n";
50        };
51
52       It also takes further options in a form of a hash. Supported options
53       are:
54
55       cwd => $path
56           Sets the working directory of the executed command to $path.
57
58       only_if => $condition_command
59           Executes the command only if $condition_command returns success.
60
61       unless => $condition_command
62           Executes the command if $condition_command returns failure.
63
64       only_notified => TRUE
65           Queues the command to be executed later upon notification.
66
67       env => { var1 => $value1, ..., varN => $valueN }
68           Sets environment variables for the given command.
69
70       timeout => value
71           Sets the timeout for the command to be run.
72
73       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
77       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
82       creates => $file_to_create
83           Tries to create $file_to_create upon execution, and skips execution
84           if the file already exists.
85
86       continuous_read => $callback
87           Calls $callback subroutine reference for each line of the command's
88           output, passing the line as an argument.
89
90       end_if_matched => qr{$pattern}
91           End execution early as soon as $pattern is detected in the
92           command's output.
93
94       Examples:
95
96       If you only want to run a command if another command succeeds or fails,
97       use the "only_if" or "unless" options.
98
99        run 'some-command',
100          only_if => 'pgrep httpd'; # only run if httpd is running
101
102        run 'some-other-command',
103          unless => 'pgrep httpd'; # only run if httpd is _not_ running
104
105       If you want to set custom environment variables you can do it like
106       this:
107
108        run 'my_command',
109          env => {
110            env_var_1 => 'the value for 1',
111            env_var_2 => 'the value for 2',
112          };
113
114       If you want to end the command upon receiving a certain output:
115
116        run 'my_command',
117          end_if_matched => qr{$pattern};
118
119   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
125        run 'ls', [ '-l', '-t', '-r', '-a' ];
126        run 'ls', [ '/tmp', '-l' ], auto_die => TRUE;
127
128   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
132        run 'extract-something',
133          command       => 'tar -C /foo -xzf /tmp/foo.tgz',
134          only_notified => TRUE;
135
136        # some code ...
137
138        notify 'run', 'extract-something'; # now the command gets executed
139
140   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
145        task 'uptime', sub {
146          if ( my $cmd = can_run( 'uptime', 'downtime' ) ) {
147            say run $cmd;
148          }
149        };
150
151   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
155       Depending on your remote sudo configuration, you may need to define a
156       sudo password with sudo_password first:
157
158        sudo_password 'my_sudo_password'; # hardcoding
159
160       Or alternatively, since Rexfile is plain perl, you can read the
161       password from terminal at the start:
162
163        use Term::ReadKey;
164
165        print 'I need sudo password: ';
166        ReadMode('noecho');
167        sudo_password ReadLine(0);
168        ReadMode('restore');
169
170       Similarly, it is also possible to read it from a secret file, database,
171       etc.
172
173       You can turn sudo on globally with:
174
175        sudo TRUE; # run _everything_ with sudo
176
177       To run only a specific command with sudo, use :
178
179        say sudo 'id';                # passing a remote command directly
180        say sudo { command => 'id' }; # passing anonymous hashref
181
182        say sudo { command => 'id', user => 'different' }; # run a single command with sudo as different user
183
184       To run multiple commands with "sudo", either use an anonymous code
185       reference directly:
186
187        sudo sub {
188            service 'nginx' => 'restart';
189            say run 'id';
190        };
191
192       or pass it via "command" (optionally along a different user):
193
194        sudo {
195            command => sub {
196                say run 'id';
197                say run 'pwd', cwd => '/home/different';
198            },
199            user => 'different',
200        };
201
202       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
207          Defaults:$username !requiretty
208
209
210
211perl v5.36.1                      2023-08-07             Rex::Commands::Run(3)
Impressum