rex - execute tasks defined in a Rexfile
The rex script can be used to execute tasks defined in a Rexfile from the command line.
rex
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
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
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.
Rexfile
See all the available commands in Rex::Commands.
user 'bruce'; password 'batman'; pass_auth;
private_key '/path/to/your/private/key.file'; public_key '/path/to/your/public/key.file'; key_auth;
logging to_file => 'rex.log'; logging to_syslog => 'local0';
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
# 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.
Rex::Group::Lookup
timeout 10; # ssh timeout parallelism 2; # execute tasks in parallel
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=yes
Tab completion scripts are provided for Bash and Zsh in the share directory. They provide completions for the available CLI options, hosts, groups, environments and tasks.
To install Rex, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Rex
CPAN shell
perl -MCPAN -e shell install Rex
For more information on module installation, please visit the detailed CPAN module installation guide.