no_ssh([$task])

If you want to disable ssh connection for your complete tasks (for example if you only want to use libVirt) put this in the main section of your Rexfile.

 no_ssh;

If you want to disable ssh connection for a given task, put no_ssh in front of the task definition.

 no_ssh task "mytask", "myserver", sub {
   say "Do something without a ssh connection";
 };

task($name [, @servers], $funcref)

Create a local task (a server independent task)

 task "mytask", sub {
   say "Do something";
 };
    

If you call this task with (R)?ex it will run on your local machine. You can explicit run this task on other machines if you specify the -H command line parameter.

Create a server bound task.

 task "mytask", "server1", sub {
   say "Do something";
 };
    

You can also specify more than one server.

 task "mytask", "server1", "server2", "server3", sub {
   say "Do something";
 };
    

Or you can use some expressions to define more than one server.

 task "mytask", "server[1..3]", sub {
   say "Do something";
 };
    

If you want, you can overwrite the servers with the -H command line parameter.

Create a group bound task.

You can define server groups with the group function.

 group "allserver" => "server[1..3]", "workstation[1..10]";

 task "mytask", group => "allserver", sub {
   say "Do something";
 };
    

desc($description)

 desc "This is a task description of the following task";
 task "mytask", sub {
   say "Do something";
 }

group($name, @servers)

 group "servergroup", "www1", "www2", "www3", "memcache01", "memcache02", "memcache03";

Or with the expression syntax:

 group "servergroup", "www[1..3]", "memcache[01..03]";

If the "use_server_auth" feature flag is enabled, you can also specify server options after a server name with a hash reference:

 use Rex -feature => ['use_server_auth'];

 group "servergroup", "www1" => { user => "other" }, "www2";

These expressions are allowed:

• \d+..\d+ (range)

  The first number is the start and the second number is the end for numbering the servers.

   group "name", "www[1..3]"; # www1, www2, www3
      

• \d+..\d+/\d+ (range with step)

  Just like the range notation, but with an additional "step" defined. If step is omitted, it defaults to 1 (i.e. it behaves like a simple range expression).

   group "name", "www[1..5/2]";      # www1, www3, www5
   group "name", "www[111..133/11]"; # www111, www122, www133
      

• \d+,\d+,\d+ (list)

  With this variant you can define fixed values.

   group "name", "www[1,3,7,01]"; # www1, www3, www7, www01
      

• Mixed list, range and range with step

  You can mix the three variants above

   www[1..3,5,9..21/3]; # www1, www2, www3, www5, www9, www12, www15, www18, www21
      

batch($name, @tasks)

 batch "name", "task1", "task2", "task3";

And call it with the -b console parameter. rex -b name

user($user)

password($password)

auth(for => $entity, %data)

If you want to set special login information for a group you have to enable at least the 0.31 feature flag, and ensure the "group" is declared before the "auth" command.

Command line options to set locality or authentication details are still taking precedence, and may override these settings.

 # auth for groups
 
 use Rex -feature => ['0.31']; # activate setting auth for a group

 group frontends => "web[01..10]";
 group backends => "be[01..05]";
 
 auth for => "frontends" =>
            user => "root",
            password => "foobar";
 
 auth for => "backends" =>
            user => "admin",
            private_key => "/path/to/id_rsa",
            public_key => "/path/to/id_rsa.pub",
            sudo => TRUE;

 # auth for tasks
 
 task "prepare", group => ["frontends", "backends"], sub {
   # do something
 };
 
 auth for => "prepare" =>
            user => "root";

 # auth for multiple tasks with regular expression
 
 task "step_1", sub {
  # do something
 };
 
 task "step_2", sub {
  # do something
 };
 
 auth for => qr/step/ =>
   user     => $user,
   password => $password;

 # fallback auth
 auth fallback => {
   user        => "fallback_user1",
   password    => "fallback_pw1",
   public_key  => "",
   private_key => "",
 }, {
   user        => "fallback_user2",
   password    => "fallback_pw2",
   public_key  => "keys/public.key",
   private_key => "keys/private.key",
   sudo        => TRUE,
 };

port($port)

sudo_password($password)

timeout($seconds)

max_connect_retries($count)

get_random($count, @chars)

 my $rnd = get_random(8, 'a' .. 'z');

do_task($task)

 task "task1", "server1", sub {
   say "Running on server1";
   do_task "task2";
 };

 task "task2", "server2", sub {
   say "Running on server2";
 };

You may also use an arrayRef for $task if you want to call multiple tasks.

 do_task [ qw/task1 task2 task3/ ];

run_task($task_name, %option)

 my $return = run_task "taskname", on => "192.168.3.56";

Do something on server5 if memory is less than 100 MB free on server3.

 task "prepare", "server5", sub {
   my $free_mem = run_task "get_free_mem", on => "server3";
   if($free_mem < 100) {
     say "Less than 100 MB free mem on server3";
     # create a new server instance on server5 to unload server3
   }
 };

 task "get_free_mem", sub {
    return memory->{free};
 };

If called without a hostname the task is run localy.

 # this task will run on server5
 task "prepare", "server5", sub {
   # this will call task check_something. but this task will run on localhost.
   my $check = run_task "check_something";
 }

 task "check_something", "server4", sub {
   return "foo";
 };

If you want to add custom parameters for the task you can do it this way.

 task "prepare", "server5", sub {
  run_task "check_something", on => "foo", params => { param1 => "value1", param2 => "value2" };
 };

run_batch($batch_name, %option)

 my @return = run_batch "batchname", on => "192.168.3.56";

It calls internally run_task, and passes it any option given.

public_key($key)

private_key($key)

pass_auth

 user "root";
 password "root";

 pass_auth;

key_auth

 user "bob";
 private_key "/home/bob/.ssh/id_rsa"; # passphrase-less key
 public_key "/home/bob/.ssh/id_rsa.pub";

 key_auth;

krb5_auth

 set connection => "OpenSSH";
 user "root";
 krb5_auth;

parallelism($count)

 parallelism '2'; # set parallelism to 2

Alternatively, the following notation can be used to set thread count more dynamically:

 parallelism 'max';     # set parallelism to the number of servers a task is asked to run on
 parallelism 'max/3';   # set parallelism to 1/3 of the number of servers
 parallelism 'max 10%'; # set parallelism to 10% of the number of servers

If an unrecognized value is passed, or the calculated thread count would be less than 1, Rex falls back to use a single thread.

proxy_command($cmd)

 set connection => "OpenSSH";
 proxy_command "ssh user@jumphost nc %h %p 2>/dev/null";

set_distributor($distributor)

Possible values are: Base, Gearman, Parallel_ForkManager

template_function(sub { ... })

logging

Logging to a file

 logging to_file => "rex.log";
    

Logging to syslog

 logging to_syslog => $facility;
    

needs($package [, @tasks])

needs will not execute before, around and after hooks.

Depend on all tasks in a given package.

Depend on all tasks in the package MyPkg. All tasks will be called with the server server1.

 task "mytask", "server1", sub {
   needs MyPkg;
 };
    

Depend on a single task in a given package.

Depend on the uname task in the package MyPkg. The uname task will be called with the server server1.

 task "mytask", "server1", sub {
   needs MyPkg "uname";
 };
    

To call tasks defined in the Rexfile from within a module

 task "mytask", "server1", sub {
   needs main "uname";
 };
    

include Module::Name

  include qw/
    Module::One
    Module::Two
  /;

environment($name => $code)

 # define default user/password
 user "root";
 password "foobar";
 pass_auth;

 # define default frontend group containing only testwww01.
 group frontend => "testwww01";

 # define live environment, with different user/password
 # and a frontend server group containing www01, www02 and www03.
 environment live => sub {
   user "root";
   password "livefoo";
   pass_auth;

   group frontend => "www01", "www02", "www03";
 };

 # define stage environment with default user and password. but with
 # a own frontend group containing only stagewww01.
 environment stage => sub {
   group frontend => "stagewww01";
 };

 task "prepare", group => "frontend", sub {
    say run "hostname";
 };

Calling this task rex prepare will execute on testwww01. Calling this task with rex -E live prepare will execute on www01, www02, www03. Calling this task rex -E stage prepare will execute on stagewww01.

You can call the function within a task to get the current environment.

 task "prepare", group => "frontend", sub {
   if(environment() eq "dev") {
     say "i'm in the dev environment";
   }
 };

If no -E option is passed on the command line, the default environment (named 'default') will be used.

LOCAL(&)

 task "mytask", "server1", "server2", sub {
    # this will call 'uptime' on the servers 'server1' and 'server2'
    say run "uptime";

    # this will call 'uptime' on the local machine.
    LOCAL {
      say run "uptime";
    };
 };

path(@path)

 path "/bin", "/sbin", "/usr/bin", "/usr/sbin", "/usr/pkg/bin", "/usr/pkg/sbin";

set($key, $value)

 set database => "db01";

 task "prepare", sub {
   my $db = get "database";
 };

Or in a template

 DB: <%= $::database %>

The following list of configuration parameters are Rex specific:

get($key, $value)

 set database => "db01";

 task "prepare", sub {
   my $db = get "database";
 };

Or in a template

 DB: <%= $::database %>

before($task => sub {})

The task name is a regular expression to find all tasks with a matching name. The special task name 'ALL' can also be used to run code before all tasks.

If called repeatedly, each sub will be appended to a list of 'before' functions.

In this hook you can overwrite the server to which the task will connect to. The second argument is a reference to the server object that will be used for the connection.

Please note, this must come after the definition of the specified task.

 before mytask => sub {
  my ($server, $server_ref, $cli_args) = @_;
  run "vzctl start vm$server";
 };

after($task => sub {})

The task name is a regular expression to find all tasks with a matching name. The special task name 'ALL' can be used to run code after all tasks.

If called repeatedly, each sub will be appended to a list of 'after' functions.

Please note, this must come after the definition of the specified task.

 after mytask => sub {
  my ($server, $failed, $cli_args) = @_;
  if($failed) { say "Connection to $server failed."; }

  run "vzctl stop vm$server";
 };

around($task => sub {})

The task name is a regular expression to find all tasks with a matching name. The special task name 'ALL' can be used to run code around all tasks.

If called repeatedly, each sub will be appended to a list of 'around' functions.

In this hook you can overwrite the server to which the task will connect to. The second argument is a reference to the server object that will be used for the connection.

Please note, this must come after the definition of the specified task.

 around mytask => sub {
  my ($server, $server_ref, $cli_args, $position) = @_;

  unless($position) {
    say "Before Task\n";
  }
  else {
    say "After Task\n";
  }
 };

before_task_start($task => sub {})

The task name is a regular expression to find all tasks with a matching name. The special task name 'ALL' can be used to run code before all tasks.

If called repeatedly, each sub will be appended to a list of 'before_task_start' functions.

Please note, this must come after the definition of the specified task.

 before_task_start mytask => sub {
   # do some things
 };

after_task_finished($task => sub {})

The task name is a regular expression to find all tasks with a matching name. The special task name 'ALL' can be used to run code after all tasks.

If called repeatedly, each sub will be appended to a list of 'after_task_finished' functions.

Please note, this must come after the definition of the specified task.

 after_task_finished mytask => sub {
   # do some things
 };

logformat($format)

%D - Appends the current date yyyy-mm-dd HH:mm:ss

%h - The target host

%p - The pid of the running process

%l - Loglevel (INFO or DEBUG)

%s - The Logstring

Default is: [%D] %l - %s

connection

 task "foo", group => "baz", sub {
   say "Current Server: " . connection->server;
 };

cache

profiler

report($switch, $type)

 report -on => "YAML";

source_global_profile(0|1)

last_command_output

On a debian system this example will return the output of apt-get install foobar.

 task "mytask", "myserver", sub {
   install "foobar";
   say last_command_output();
 };

case($compare, $option)

 task "mytask", "myserver", sub {
   my $ntp_service = case operating_system, {
                 Debian  => "ntp",
                 default => "ntpd",
               };

   my $ntp_service = case operating_system, {
                 qr{debian}i => "ntp",
                 default    => "ntpd",
               };

   my $ntp_service = case operating_system, {
                 qr{debian}i => "ntp",
                 default    => sub { return "foo"; },
               };
 };

set_executor_for($type, $executor)

 set_executor_for perl => "/opt/local/bin/perl";

tmp_dir($tmp_dir)

inspect($varRef)

task "mytask", "myserver", sub { my $myvar = { name => "foo", sys => "bar", };

  inspect $myvar;
};

sayformat($format)

%D - The current date yyyy-mm-dd HH:mm:ss

%h - The target host

%p - The pid of the running process

%s - The Logstring

You can also define the following values:

default - the default behaviour.

asis - will print every single parameter in its own line. This is useful if you want to print the output of a command.