.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "REX 1p"
.TH REX 1p "2023-03-06" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
rex \- execute tasks defined in a Rexfile
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`rex\*(C'\fR script can be used to execute tasks defined in a Rexfile from the command line.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\& rex \-h                      # Show usage
\& rex \-T                      # List tasks
\& rex uname                   # Run the \*(Aquname\*(Aq task
\& rex \-H server[01..10] uname # Run the \*(Aquname\*(Aq task on all the specified hosts
\& rex \-G production uname     # Run \*(Aquname\*(Aq on hosts on the \*(Aqproduction\*(Aq hostgroup
\& rex deploy \-\-gracefully     # Pass \*(Aq\-\-gracefully\*(Aq to the \*(Aqdeploy\*(Aq task
.Ve
.SH "USAGE"
.IX Header "USAGE"
.Vb 2
\& 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\*(Aqs 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 \*(Aqparallelism\*(Aq param)
\& \-v     Display (R)?ex version
.Ve
.SH "Rexfile"
.IX Header "Rexfile"
When you run \f(CW\*(C`rex\*(C'\fR it reads the file \f(CW\*(C`Rexfile\*(C'\fR in the current working
directory. A Rexfile consists of 2 major parts: configuration and task
definitions.
.SS "Configuration"
.IX Subsection "Configuration"
See all the available commands in Rex::Commands.
.PP
\fISimple authentication\fR
.IX Subsection "Simple authentication"
.PP
.Vb 3
\& user \*(Aqbruce\*(Aq;
\& password \*(Aqbatman\*(Aq;
\& pass_auth;
.Ve
.PP
\fIKey authentication\fR
.IX Subsection "Key authentication"
.PP
.Vb 3
\& private_key \*(Aq/path/to/your/private/key.file\*(Aq;
\& public_key \*(Aq/path/to/your/public/key.file\*(Aq;
\& key_auth;
.Ve
.PP
\fIDefine logging\fR
.IX Subsection "Define logging"
.PP
.Vb 2
\& logging to_file   => \*(Aqrex.log\*(Aq;
\& logging to_syslog => \*(Aqlocal0\*(Aq;
.Ve
.PP
\fIGroup your servers\fR
.IX Subsection "Group your servers"
.PP
Rex gives you the ability to define groups of servers. Groups can be defined the Rexfile:
.PP
.Vb 1
\& group \*(Aqfrontends\*(Aq => \*(Aqfrontend01\*(Aq, \*(Aqfrontend02\*(Aq, \*(Aqfrontend[03..09]\*(Aq;
.Ve
.PP
Groups can also be defined in separate files, like \f(CW\*(C`server.ini\*(C'\fR:
.PP
.Vb 3
\& # server.ini
\& [frontends]
\& frontend[01..04]
\&
\& # Rexfile
\& use Rex::Group::Lookup::INI;
\& groups_file \*(Aqfile.ini\*(Aq
.Ve
.PP
See Rex::Group::Lookup::INI for more details, and check the \f(CW\*(C`Rex::Group::Lookup\*(C'\fR namespace for other formats.
.SS "Other configuration"
.IX Subsection "Other configuration"
.Vb 2
\& timeout 10;    # ssh timeout
\& parallelism 2; # execute tasks in parallel
.Ve
.SS "Defining tasks"
.IX Subsection "Defining tasks"
A basic task looks like this:
.PP
.Vb 2
\& # task description
\& desc \*(AqThis task tells you how long since the server was rebooted\*(Aq;
\&
\& # task definition
\& task \*(Aqshortname\*(Aq, sub {
\&   say run \*(Aquptime\*(Aq;
\& };
.Ve
.PP
By default it will be targeted at the same host where `rex` is being executed.
.PP
You can also set a default server as the task's target:
.PP
.Vb 6
\& desc \*(AqThis is a long description of a task\*(Aq;
\& task \*(Aqshortname\*(Aq,
\&   \*(Aqfrontend01\*(Aq,
\&   sub {
\&     say run \*(Aquptime\*(Aq;
\&   };
.Ve
.PP
or even a default server group:
.PP
.Vb 6
\& desc \*(AqThis is a long description of a task\*(Aq;
\& task \*(Aqshortname\*(Aq,
\&   group => \*(Aqfrontends\*(Aq,
\&   sub {
\&     say run \*(Aquptime\*(Aq;
\&   };
.Ve
.PP
The task options from the command line will be passed to the task as well:
.PP
.Vb 6
\& # Rexfile
\& desc \*(AqGet task options\*(Aq;
\& task \*(Aqget_task_options\*(Aq, sub {
\&   my $task_options = shift;
\&   my $option1 = $task_options\->{option1};
\& };
\&
\& # command line
\& rex get_task_options \-\-option1=yes
.Ve
.SH "TAB COMPLETION"
.IX Header "TAB 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 \s-1CLI\s0 options, hosts, groups, environments and tasks.