Jan Gehring > Rex-0.53.1 > Rex::Commands::Run



Annotate this POD


New  5
Open  1
View/Report Bugs
Module Version: 0.53.1   Source  


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


With this module you can run a command.


 my $output = run "ls -l";
 sudo "id";


run($command [, $callback])

This function will execute the given command and returns the output. In scalar context it returns the raw output as is, and in list context it returns the list of output lines. The exit value of the command is stored in the $? variable.

 task "uptime", "server01", sub {
   say run "uptime";
   run "uptime", sub {
     my ($stdout, $stderr) = @_;
     my $server = Rex::get_current_connection()->{server};
     say "[$server] $stdout\n";

If you only want to run a command in special cases, you can queue the command and notify it when you want to run it.

 task "prepare", sub {
   run "extract-something",
     command     => "tar -C /foo -xzf /tmp/foo.tgz",
     only_notified => TRUE;

   # some code ...

   notify "run", "extract-something";  # now the command gets executed

If you only want to run a command if an other command succeed or fail, you can use only_if or unless option.

 run "some-command",
   only_if => "ps -ef | grep -q httpd";   # only run if httpd is running

 run "some-other-command",
   unless => "ps -ef | grep -q httpd";    # only run if httpd is not running

If you want to set custom environment variables you can do this like this:

 run "my_command",
   env => {
     env_var_1 => "the value for 1",
     env_var_2 => "the value for 2",

If you want to end the command upon receiving a certain output: run "my_command", end_if_matched => qr/PATTERN/;


This function checks if a command is in the path or is available. You can specify multiple commands, the first command found will be returned.

 task "uptime", sub {
   if( my $cmd = can_run("uptime", "downtime") ) {
     say run $cmd;

Run a command with sudo. Define the password for sudo with sudo_password.

You can use this function to run one command with sudo privileges or to turn on sudo globaly.

 user "unprivuser";
 sudo_password "f00b4r";
 sudo -on;  # turn sudo globaly on

 task prepare => sub {
   install "apache2";
   file "/etc/ntp.conf",
     source => "files/etc/ntp.conf",
     owner  => "root",
     mode  => 640;

Or, if you don't turning sudo globaly on.

 task prepare => sub {
   file "/tmp/foo.txt",
     content => "this file was written without sudo privileges\n";

   # everything in this section will be executed with sudo privileges
   sudo sub {
     install "apache2";
     file "/tmp/foo2.txt",
       content => "this file was written with sudo privileges\n";

Run only one command within sudo.

 task "eth1-down", sub {
  sudo "ifconfig eth1 down";
syntax highlighting: