GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
REX(1) User Contributed Perl Documentation REX(1)

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 -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.

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.

 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 <https://metacpan.org/release/Rex/source/share> directory. They provide completions for the available CLI options, hosts, groups, environments and tasks.
2021-07-05 perl v5.32.1

Search for    or go to Top of page |  Section 1 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.