NAME

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

DESCRIPTION

With this module you can run a command.

SYNOPSIS

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

EXPORTED FUNCTIONS

run($command [, $callback])

This function will execute the given command and returns the output.

 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",
   };

can_run($command)

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;
   }
 };

sudo

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";
 };