Running ad-hoc commands as shown in Minimum Viable Rex provides a good way to start benefiting from Rex, the friendly automation framework. Then sometimes we have to repeat our typical procedures. Other times it would work best if we could enable others to follow the same steps.

Just like GNU Make uses a Makefile to describe actions, Rex uses a Rexfile to describe our common procedures as code through the following foundational elements:

• dependencies
• configuration
• inventory
• authentication
• tasks
• arbitrary Perl code

While we may treat most elements optional depending on the use case, let’s take an initial look at each.

Dependencies

To use Rex, we have to import it first:

use Rex;

This loads the Rex module, and configures common default settings, like initializing the random number seed, and detecting preferred dependencies for remote management, such as Net::OpenSSH. It also enables the strict and warnings pragmas.

As Rex evolved over the years we introduced a -feature flag to import the features and configuration we deem necessary for the intended out-of-the-box experience, while also providing a way to (de)activate the desired features for the given solution as a whole.

Please see the feature flags section of the documentation to learn more about the available ones (also offline via perldoc Rex.)

For new projects, I generally recommend starting out with activating the latest versioned feature bundle, and exec_autodie to stop executing early upon any errors (much like set -e or set -o errexit does with Bash):

use Rex -feature => [ '1.4', 'exec_autodie' ];

I find it useful to think about Rex feature flags the same way as the feature concept Perl itself has to control different language features.

Since Rex code does not differ from Perl code (in fact, internally we even require the Rexfile), we may also import any other Perl module we would like to use. For example:

use Data::Printer;

Configuration

Rex provides a wide range of configuration options to allow fine-tuning its behavior to the given use case at hand.

For example, we implement the above exec_autodie feature flag via the following call:

Rex::Config->set_exec_autodie(1);

Most other feature flags work similarly too.

The Rex::Commands module also provides convenience wrappers for some configuration options. For example the following two calls results in configuring the same output format for say() calls:

sayformat '%h %s'; # prefix the %s message with its %h source host

Rex::Config->set_say_format('%h %s');

While internally Rex::Config handles Rex configuration (see also perldoc Rex::Config), I recommend using feature flags and convenience wrappers when possible, keeping the direct approach in mind as a possibility just in case.

Inventory

Rex considers the local host as the default target for its operations, though we often need to manage remote endpoints too. The inventory helps describe the hosts and host groups our code aims to manage.

The group() command defines a named host group as a list of hosts:

group 'webservers' => 'www1', 'www2', 'www3';

It also supports expressions to describe ranges, for example this expands to the same three hosts as above:

group 'webservers' => 'www[1..3]';

Authentication

To manage remote hosts, we need to specify how to log in remotely to these.

Rex has a modular connection layer, and currently supports two different SSH backends:

1. Net::SSH2 which depends on libssh2
2. Net::OpenSSH, which depends on the OpenSSH binary

These implementations support different authentication methods, like passwords, key files, and SSH agents.

When the Rexfile does not specify any authentication details, Rex tries to figure out what to use based on the current environments, available modules, files, and SSH configuration.

While one may find that comfortable, some use cases work best when we describe these details explicitly.

The user() command specifies the username to use for logins:

user 'rex';

To use password authentication specify the password too, optionally forcing this method with pass_auth():

password 'secret_ssh_password';
pass_auth; # optionally forcing password authentication

To force key-based authentication, use key_auth(), and in case of Net:SSH2 backend, also specify which keys to use:

key_auth;
private_key '/path/to/private.key'; # only mandatory with Net::SSH2
public_key '/path/to/public.key';   # only mandatory with Net::SSH2

In case a passphrase protects the key, specify that with password():

key_auth;
password 'secret_key_passphrase';

When using an SSH agent, omit pass_auth() and key_auth().

Tasks

A task describes the steps Rex executes on the specified targets.

In general, a task has:

1. a description (optional, though recommended)
2. a name
3. a default target: either a host group from the inventory, a list of hosts, or omitted to manage the local machine
4. the code steps to follow while executing the task

This general structure looks like the following:

desc $description_of_following_task;
task $task_name, @target_hosts_or_host_groups, sub {
    ... # steps
};

For example, the following task named chrony installs the software package called chrony, sets up a basic configuration file for it, ensures running the chronyd service, and does all that on every host in the webservers host group:

desc 'Manage chrony';    # description of next task
task 'chrony',           # task name
  group => 'webservers', # default target host group
  sub {
    pkg 'chrony',          # manage the chrony package
      ensure => 'present'; # ensure its presence

    file '/etc/chrony/chrony.conf',            # manage the chrony config file
      content => "ipool pool.ntp.org\tiburst"; # ensure its content

    service 'chronyd',                         # manage the chronyd service
      ensure => 'started';                     # ensure it runs now and on boot
  };

Given that the modules in the Rex::Commands namespace implement the pkg(), file(), and service() functions, we call these Rex commands – and these manage package, file, and service resources accordingly.

Arbitrary Perl code

Since Rex code does not differ from Perl code, it makes Rexfiles seamlessly extendable with custom logic.

These may implement API calls to build the inventory from external sources, or retrieve secrets from an encrypted store – practically anything else Perl can do, and the use case requires.

Notably, this includes the following capabilities:

1. include documentation in POD format, and display it later with perldoc
2. use other programming languages through the Inline modules, or FFI::Platypus

Example

Let’s consider the following example Rexfile based on the above details:

use Rex -feature => [ '1.4', 'exec_autodie' ];

sayformat '%h %s';

group webservers => 'www[1..3]';

user 'root';

desc 'Manage chrony';
task 'chrony',
  group => 'webservers',
  sub {
    pkg 'chrony', ensure => 'present';

    file '/etc/chrony/chrony.conf', content => "ipool pool.ntp.org\tiburst";

    service 'chronyd', ensure => 'started';
  };

Given that Rexfile, rex -T lists the tasks and inventory as the following:

$ rex -T
Tasks
 chrony  Manage chrony
Server Groups
 webservers  www[1..3]

The verbose version with rex -Tv also shows the tasks with their default targets, expanding any host group expressions:

$ rex -Tv
Tasks
 chrony  Manage chrony
    Servers: www1, www2, www3
Server Groups
 webservers  www[1..3]

Running rex chrony executes the task named chrony:

$ rex chrony
[2025-04-02 13:14:33] INFO - Running task chrony on www1
[2025-04-02 13:14:35] INFO - Installing chrony.
[2025-04-02 13:14:39] INFO - Running task chrony on www2
[2025-04-02 13:14:41] INFO - Installing chrony.
[2025-04-02 13:14:46] INFO - Running task chrony on www3
[2025-04-02 13:14:47] INFO - Installing chrony.
[2025-04-02 13:14:52] INFO - All tasks successful on all hosts

Summary

Rexfiles help to turn the manual and ad-hoc steps of common procedures into code, which allows reproducible results between runs, and enables others to follow the same steps.

Its flexibility allows both writing just enough details that we deem relevant for the given use case and situation, and adding more details incrementally when needed.