rex - Man Page
execute tasks defined in a Rexfile
Description
The rex script can be used to execute tasks defined in a Rexfile from the command line.
Synopsis
rex -h # Show usage rex -T # List tasks rex uname # Run the 'uname' task rex -H server[01..10] uname # Run the 'uname' task on all the specified hosts rex -G production uname # Run 'uname' on hosts on the 'production' hostgroup rex deploy --gracefully # Pass '--gracefully' to the 'deploy' task
Usage
rex [<options>] [-H <host>] [-G <group>] <task> [<task-options>] rex -T[m|y|v] [<string>] -b Run batch -e Run the given code fragment -E Execute a task on the given environment -G|-g Execute a task on the given server groups -H Execute a task on the given hosts (space delimited) -z Execute a task on hosts from this command's output -K Public key file for the ssh connection -P Private key file for the ssh connection -p Password for the ssh connection -u Username for the ssh connection -d Show debug output -ddd Show more debug output (includes profiling output) -m Monochrome output: no colors -o Output format -q Quiet mode: no log output -qw Quiet mode: only output warnings and errors -Q Really quiet: output nothing -T List tasks -Ta List all tasks, including hidden -Tm List tasks in machine-readable format -Tv List tasks verbosely -Ty List tasks in YAML format -c Turn cache ON -C Turn cache OFF -f Use this file instead of Rexfile -F Force: disregard lock file -h Display this help message -M Load this module instead of Rexfile -O Pass additional options, like CMDB path -s Use sudo for every command -S Password for sudo -t Number of threads to use (aka 'parallelism' param) -v Display (R)?ex version
Rexfile
When you run rex it reads the file Rexfile in the current working directory. A Rexfile consists of 2 major parts: configuration and task definitions.
Configuration
See all the available commands in Rex::Commands.
Simple authentication
user 'bruce'; password 'batman'; pass_auth;
Key authentication
private_key '/path/to/your/private/key.file'; public_key '/path/to/your/public/key.file'; key_auth;
Define logging
logging to_file => 'rex.log'; logging to_syslog => 'local0';
Group your servers
Rex gives you the ability to define groups of servers. Groups can be defined the Rexfile:
group 'frontends' => 'frontend01', 'frontend02', 'frontend[03..09]';
Groups can also be defined in separate files, like server.ini:
# server.ini [frontends] frontend[01..04] # Rexfile use Rex::Group::Lookup::INI; groups_file 'file.ini'
See Rex::Group::Lookup::INI for more details, and check the Rex::Group::Lookup namespace for other formats.
Other configuration
timeout 10; # ssh timeout parallelism 2; # execute tasks in parallel
Defining tasks
A basic task looks like this:
# task description
desc 'This task tells you how long since the server was rebooted';
# task definition
task 'shortname', sub {
say run 'uptime';
};By default it will be targeted at the same host where `rex` is being executed.
You can also set a default server as the task's target:
desc 'This is a long description of a task';
task 'shortname',
'frontend01',
sub {
say run 'uptime';
};or even a default server group:
desc 'This is a long description of a task';
task 'shortname',
group => 'frontends',
sub {
say run 'uptime';
};The task options from the command line will be passed to the task as well:
# Rexfile
desc 'Get task options';
task 'get_task_options', sub {
my $task_options = shift;
my $option1 = $task_options->{option1};
};
# command line
rex get_task_options --option1=yesTab Completion
Tab completion scripts are provided for Bash and Zsh in the share <https://metacpan.org/release/Rex/source/share> directory. They provide completions for the available CLI options, hosts, groups, environments and tasks.