1REX(1)                User Contributed Perl Documentation               REX(1)
2
3
4

NAME

6       rex - execute tasks defined in a Rexfile
7

DESCRIPTION

9       The "rex" script can be used to execute tasks defined in a Rexfile from
10       the command line.
11

SYNOPSIS

13        rex -h                      # Show usage
14        rex -T                      # List tasks
15        rex uname                   # Run the 'uname' task
16        rex -H server[01..10] uname # Run the 'uname' task on all the specified hosts
17        rex -G production uname     # Run 'uname' on hosts on the 'production' hostgroup
18        rex deploy --gracefully     # Pass '--gracefully' to the 'deploy' task
19

USAGE

21        rex [<options>] [-H <host>] [-G <group>] <task> [<task-options>]
22        rex -T[m|y|v] [<string>]
23
24        -b     Run batch
25        -e     Run the given code fragment
26        -E     Execute a task on the given environment
27        -G|-g  Execute a task on the given server groups
28        -H     Execute a task on the given hosts (space delimited)
29        -z     Execute a task on hosts from this command's output
30
31        -K     Public key file for the ssh connection
32        -P     Private key file for the ssh connection
33        -p     Password for the ssh connection
34        -u     Username for the ssh connection
35
36        -d     Show debug output
37        -ddd   Show more debug output (includes profiling output)
38        -m     Monochrome output: no colors
39        -o     Output format
40        -q     Quiet mode: no log output
41        -qw    Quiet mode: only output warnings and errors
42        -Q     Really quiet: output nothing
43
44        -T     List tasks
45        -Ta    List all tasks, including hidden
46        -Tm    List tasks in machine-readable format
47        -Tv    List tasks verbosely
48        -Ty    List tasks in YAML format
49
50        -c     Turn cache ON
51        -C     Turn cache OFF
52        -f     Use this file instead of Rexfile
53        -F     Force: disregard lock file
54        -h     Display this help message
55        -M     Load this module instead of Rexfile
56        -O     Pass additional options, like CMDB path
57        -s     Use sudo for every command
58        -S     Password for sudo
59        -t     Number of threads to use (aka 'parallelism' param)
60        -v     Display (R)?ex version
61

Rexfile

63       When you run "rex" it reads the file "Rexfile" in the current working
64       directory. A Rexfile consists of 2 major parts: configuration and task
65       definitions.
66
67   Configuration
68       See all the available commands in Rex::Commands.
69
70       Simple authentication
71
72        user 'bruce';
73        password 'batman';
74        pass_auth;
75
76       Key authentication
77
78        private_key '/path/to/your/private/key.file';
79        public_key '/path/to/your/public/key.file';
80        key_auth;
81
82       Define logging
83
84        logging to_file   => 'rex.log';
85        logging to_syslog => 'local0';
86
87       Group your servers
88
89       Rex gives you the ability to define groups of servers. Groups can be
90       defined the Rexfile:
91
92        group 'frontends' => 'frontend01', 'frontend02', 'frontend[03..09]';
93
94       Groups can also be defined in separate files, like "server.ini":
95
96        # server.ini
97        [frontends]
98        frontend[01..04]
99
100        # Rexfile
101        use Rex::Group::Lookup::INI;
102        groups_file 'file.ini'
103
104       See Rex::Group::Lookup::INI for more details, and check the
105       "Rex::Group::Lookup" namespace for other formats.
106
107   Other configuration
108        timeout 10;    # ssh timeout
109        parallelism 2; # execute tasks in parallel
110
111   Defining tasks
112       A basic task looks like this:
113
114        # task description
115        desc 'This task tells you how long since the server was rebooted';
116
117        # task definition
118        task 'shortname', sub {
119          say run 'uptime';
120        };
121
122       By default it will be targeted at the same host where `rex` is being
123       executed.
124
125       You can also set a default server as the task's target:
126
127        desc 'This is a long description of a task';
128        task 'shortname',
129          'frontend01',
130          sub {
131            say run 'uptime';
132          };
133
134       or even a default server group:
135
136        desc 'This is a long description of a task';
137        task 'shortname',
138          group => 'frontends',
139          sub {
140            say run 'uptime';
141          };
142
143       The task options from the command line will be passed to the task as
144       well:
145
146        # Rexfile
147        desc 'Get task options';
148        task 'get_task_options', sub {
149          my $task_options = shift;
150          my $option1 = $task_options->{option1};
151        };
152
153        # command line
154        rex get_task_options --option1=yes
155

TAB COMPLETION

157       Tab completion scripts are provided for Bash and Zsh in the share
158       <https://metacpan.org/release/Rex/source/share> directory. They provide
159       completions for the available CLI options, hosts, groups, environments
160       and tasks.
161
162
163
164perl v5.38.0                      2023-08-07                            REX(1)
Impressum