(R)?ex the friendly automation framework

News

2023-08-05
Rex-1.14.3

Rex-1.14.3 is now available on CPAN. It contains bug fixes for local package installation, command existence checks, and Git tests.

2023-05-05
Rex-1.14.2

The Rex-1.14.2 release is now available on CPAN. It contains bug fixes for running local commands on Windows, cloning git repositories, and test suite fixes for the upcoming perl-5.38.0 release.

2023-03-17
Call for papers TPRC 2023

Dean Hamstead from the The Perl and Raku Foundation Marketing Committee has sent an invitation to present about Rex at TPRC 2023. I’m posting it here to increase visibility.

2023-03-05
Rex-1.14.1

The Rex-1.14.1 release is now available on CPAN. It contains bug fixes and documentation updates.

2023-02-05
Rex-1.14.0

The Rex-1.14.0 release is now available on CPAN. It contains improved Rexfile loading, documentation updates, and bumps the minimum required Perl version to 5.12.5.

Events

2021-03-08
Learning automation using Rex

Ferenc Erki (FErki) will be the guest of Gábor Szabó on the next Code Maven live stream to learn about automation using Rex. Register for the free event via Code Maven or Meetup, and join the discussion!

2020-03-05
Unexpected use cases with Rex

Unexpected use cases with Rex at the 22nd German Perl/Raku Workshop 2020 in Erlangen by Ferenc Erki (FErki).

2019-11-09
Rex & Friends

Rex & Friends talk at the Barcelona Perl & Friends 2019 by Ferenc Erki (FErki).

» Home » Docs » FAQ

FAQ

Here we will maintain a list of frequently asked questions with their answers.

Is it called (R)?ex or Rex?

Rex stands for Remote execution. Both forms refer to the same thing: the friendly automation framework. Since automating tasks locally are just as fine as remotely, you can think of (R)?ex as a regular expression, marking the remote part optional.

Why does the run command not format the output?

The run command - called in array context - will return an array.

If you want to print the output to your terminal you have to call it in a scalar context.

my $output = run "df -h";
say $output;

How can I get the current server from within a task?

my $current_server = connection->server;

How can I pass parameters to a task?

task 'mytask', sub {
    my $parameters       = shift;
    my $parameter1_value = $parameters->{parameter1};
    my $parameter2_value = $parameters->{parameter2};
};

Then you can run mytask from CLI like this:

rex -H hostname mytask --parameter1=value1 --parameter2=value2

Or from Rex code either using run_task:

run_task 'my_task',
  params => { parameter1 => 'value1', parameter2 => 'value2' };

or calling the task as a function:

mytask( { parameter1 => 'value1', parameter2 => 'value2' } );

How can I run a block of code with one command?

One way to do it is to upload your script to the remote, and execute it there. You can use the Rex::Misc::ShellBlock module for that. After copying it into one of the Perl include directories, or into ./lib of your Rex project, you can run your shell code remotely as:

use Rex::Misc::ShellBlock;

task "myexec", sub {
    shell_block <<EOF;
    echo "hi"
EOF
};

See the included documentation of the module about how to use it to run code written in Perl, Python, or other languages.

How can I run a local script on the remote?

If you have a local script 'files/script', you can run it on the remote using the ShellBlock module referred to in the FAQ above. After you install as pointed out above, you can run the script remotely with the command:

use Rex::Misc::ShellBlock;
task "myexec", sub {
    shell_block template('files/script');
};

How do I run a local script on the remote under a different user?

Given the same scenario as above, but with the additional requirement to run the script as a different user, the solution looks like below:

use Rex::Misc::ShellBlock;
task "myexec", sub {
    sudo {
        command => sub {
            shell_block template('files/script');
        },
        user => 'root'
    };
};

How do I check the exit status of a remotely run command?

Rex assigns the exit code from the remote invocation of run or shell_block statements to the $? variable.

How do I use Rex's built-in logger for ERROR/WARN/INFO/DEBUG messages?

Rex::Logger::info("some message");            # for INFO  (green)
Rex::Logger::info( "some message", "warn" );  # for WARN  (yellow)
Rex::Logger::info( "some message", "error" ); # for ERROR (red)

How do I load all my custom modules easily?

There are plenty of CPAN modules providing this kind of functionality. For a comprehensive list and overview from some time ago, please read Neil Bowers' article about CPAN modules that (can) load other modules.

Since Rex is just Perl, simply use one of them, like Module::Find or Module::Pluggable.

This might affect when modules are loaded (e.g. at compilation time or at runtime), and/or in which order the modules are loaded. If you run into any troubles because of this, please make sure to specify the dependencies of the custom modules correctly.

How do I indicate the task failed to run properly?

Overall, the same way as in Perl. For example, raising an exception with die() in the task body will abort the task, and calling exit() will bail out from the whole rex process currently running.

How to add Rex support for a new operating system or virtualization method?

Please see the Contributing guide sections about Rex core vs extending Rex and Common scenarios.

Proudly powered by Perl and built with Statocles

GitHub repository and discussions / Chat on Matrix and IRC / Mailing list on Google Groups (retired: rex-users@freelists)

MetaCPAN / Twitter / StackShare / Server Fault   -.ô.-   Disclaimer