aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rwxr-xr-xrex31
-rw-r--r--rex.man881
2 files changed, 63 insertions, 49 deletions
diff --git a/rex b/rex
index fe90754..12b6f3b 100755
--- a/rex
+++ b/rex
@@ -3290,7 +3290,7 @@ proc rex_group_select {} {
rex_command_common \
-usage {rex group select [OPTIONS] COMMAND [ARGS...]} \
- -docstring {Selects hosts on which COMMAND succeeds}
+ -docstring {Selects hosts on which COMMAND succeeds.}
if {![info exists config(default,selected)]} {
terror "no hosts match the predicate"
@@ -3308,7 +3308,7 @@ proc rex_group_pop {} {
rex_parse_cmdline \
-usage {rex group pop} \
- -docstring {Pop current hostgroup off the stack}
+ -docstring {Pop current hostgroup off the stack.}
unset -nocomplain config(default,selected)
unset -nocomplain config(default,predicate)
@@ -3321,7 +3321,7 @@ proc rex_group_push {} {
rex_parse_cmdline \
-usage {rex group push GROUP} \
- -docstring {Select the hostgroup}
+ -docstring {Select the hostgroup and push it on stack.}
if {$argc != 1} {
terror "bad arguments"
@@ -3343,7 +3343,8 @@ proc rex_group_swap {} {
rex_parse_cmdline \
-usage {rex group swap N} \
- -docstring {Exchange top of group stack with its Nth entry}
+ -docstring {Exchange top of group stack with its Nth entry.} \
+ -footer {Use 'rex group show -a' to inspect the stack.}
if {$argc != 1} {
terror "bad arguments"
@@ -3374,7 +3375,8 @@ proc rex_group_drop {} {
rex_parse_cmdline \
-usage {rex group drop N} \
- -docstring {Remove Nth frame from the hostgroup stack}
+ -docstring {Remove Nth frame from the hostgroup stack.} \
+ -footer {Use 'rex group show -a' to inspect the stack.}
set n [argcvshift]
@@ -3403,8 +3405,8 @@ proc rex_group_show {} {
set hosts false
rex_parse_cmdline \
- -usage {rex group show [hosts]} \
- -docstring {Show selected hostgroup} \
+ -usage {rex group show [OPTION]} \
+ -docstring {Show selected hostgroup.} \
-group global {
all,a
{show all stack entries}
@@ -3412,7 +3414,9 @@ proc rex_group_show {} {
hosts,H
{show hosts}
{uplevel 3 {set hosts true}}
- }
+ } \
+ -footer {Options are mutually exclusive.}
+
if {$argc != 0} {
terror "too many arguments"
@@ -3471,7 +3475,7 @@ proc rex_group {} {
::getopt::parse \
-usage {rex group COMMAND [OPTIONS] [ARGS]} \
- -docstring {Manipulate hostgroups} \
+ -docstring {Manipulate hostgroups.} \
-footer {COMMANDs are:
drop remove given fram from stack
pop pop currently selected hostgroup off stack
@@ -3484,7 +3488,7 @@ proc rex_group {} {
argc argv
if {[llength $argv] == 0} {
- terror "missing subcommand; try 'rex group --help' for details"
+ terror "missing subcommand; try 'rex group --help' for help"
exit 1
}
set subcom [argcvshift]
@@ -3498,7 +3502,7 @@ proc rex_group {} {
swap rex_group_swap
default {
- terror "unknown subcommand $subcom; try 'rex group --usage' for details"
+ terror "unknown subcommand $subcom; try 'rex group --usage' for help"
exit 1
}
}
@@ -3514,7 +3518,7 @@ proc rex_list {} {
rex_parse_cmdline \
-usage {rex list [groups]} \
-alias {{rex list [OPTIONS] hosts}} \
- -docstring {Lists hostgroups or hosts in a hostgroup} \
+ -docstring {Lists hostgroups or hosts in a hostgroup.} \
-description {In first form, produces a listing of the defined
hostgroups along with their descriptions.
@@ -3916,6 +3920,7 @@ set footer {COMMANDS are:
login log in to a host
list list available hostgroups or servers in a hostgroup
edit edit rex database file
+ group select a hostgroup and maintain a stack of hostfroups
Use `rex COMMAND --help', to obtain help for a particular COMMAND.
@@ -3998,8 +4003,6 @@ switch -- $config(mode) {
run rex_command
group rex_group
- select rex_select
- deselect rex_deselect
copy-to rex_copy_to
diff --git a/rex.man8 b/rex.man8
index 64c6cba..f732e81 100644
--- a/rex.man8
+++ b/rex.man8
@@ -1,5 +1,5 @@
.\" This file is part of rex - a remote execution utility -*- nroff -*-
-.\" Copyright (C) 2012-2017 Sergey Poznyakoff
+.\" Copyright (C) 2012-2019 Sergey Poznyakoff
.\"
.\" Rex is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
@@ -13,7 +13,7 @@
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with Rex. If not, see <http://www.gnu.org/licenses/>.
-.TH REX 8 "October 31, 2017" "REX" "Rex User Reference"
+.TH REX 8 "November 29, 2019" "REX" "Rex User Reference"
.ds ET /etc
.SH NAME
rex \- remote execution utility
@@ -184,7 +184,7 @@ Adds the listed hostnames to the list of hosts.
\fBhostname\fR \fIIP\fR \fINAME\fR
Registers \fINAME\fR in DNS cache as a hostname for the IPv4
address \fIIP\fR. This is useful if \fIIP\fR has no PTR record, or its
-PTR record is deemed unsutable for some reason.
+PTR record is deemed unsuitable for some reason.
.TP
\fBifmode\fR \fB{\fR \fImode\fR \fIbody\fR [\fImode\fR \fIbody\fR...] \fB}\fR
Matches the current mode agains each of \fImode\fR arguments. As soon
@@ -220,7 +220,7 @@ ifmode {
.RE
.TP
\fBoption\fR \fIOPTNAME\fR \fIVALUE\fR [\fIVALUE\fR...]
-Sets or unsets an \fBrex\fR option. \fIOPTNAME\fR is the long name of
+Sets or unsets a \fBrex\fR option. \fIOPTNAME\fR is the long name of
the option without the leading two dashes. For example, setting
.RS
.EX
@@ -290,11 +290,11 @@ configure it. See the subsection
.B Configuration files
for a detailed guide.
.SS Debugging
-To see what's going on during \fBrex\fR invocation. Use the
+To see what's going on during \fBrex\fR invocation, use the
\fB\-d (\fB\-\-debug\fR) option. This option is incremental, that is
the more times you repeat it in the command line, the more debugging
information is output. Currently, to obtain the most detailed
-information, it should be repeated three times (e.g. \B\-ddd\fR).
+information, it should be repeated three times (e.g. \fB\-ddd\fR).
.PP
Additional information is provided by the \fB\-l\fR
(\fB\-\-log\fR) option, which enables logging of the send/expect
@@ -386,9 +386,9 @@ The \fB\-b\fR option cancels the implied \fB\-\-prefix
\-\-no\-host\-header\fR settings.
.SS Transferring data prior to execution
If the program relies on some additional files to be present, these can
-be transferred to each host prior to running the program. This is
-done using the \fB\-D\fR (\fB\-\-data\-file\fR) option. The argument
-to this option names the file to be copied to the target host.
+be transferred to each host prior to running the program. The
+transfer is requested by the \fB\-D\fR (\fB\-\-data\-file\fR) option.
+The argument to this option names the file to be copied to the target host.
.PP
To transfer multiple files, repeat the \fB\-D\fR option for each of
them.
@@ -415,18 +415,18 @@ on each target host:
sed \-f repl prefix.txt /etc/passwd
.EE
.PP
-Note, that the result of expansion is always a file name, relative to
+Note, that the \fB{\fIN\fB}\fR notation expands to a file name relative to
the current working directory on the remote host. This means that
.PP
.EX
rex run \-D /tmp/prefix.txt \-D repl sed \-f {2} {1} /etc/passwd
.EE
.PP
-will result in exactly same command as the example above: the
+will result in exactly the same command as the example above: the
expansion of \fB{1}\fR will throw away the directory part from the
file name.
.PP
-Similarly, the token \fB{}\fR will be expanded to a space-separated
+Similarly, the token \fB{}\fR expands to a space-separated
list of file names passed with all \fB\-D\fR options, in the same
order they appear on the command line.
.PP
@@ -544,6 +544,11 @@ description of \fBshrc\fR key in \fBCONFIG ARRAY\fR.
.B COMMAND
Entered after sending the main command to the host.
.TP
+.B STATUS
+Entered when the command prompt is first seen after issuing the
+command. It is used by the \fBrex group select\fR to collect the
+return status of the command.
+.TP
.B LOGOUT
The very last state in the session lifetime. It is entered after
sending the terminating \fBexit\fR command to the host.
@@ -556,7 +561,7 @@ being processed:
.EX
proc transition {host state} {
if {$state == "INIT"} {
- puts \-nonewline stderr "$host... "
+ puts \-nonewline stderr "$host... "
} elseif {$state == "LOGOUT"} {
puts "done"
}
@@ -571,13 +576,14 @@ Invoked each time a new line of output is received from the host. The
parameter is the line received from the host (with trailing \fBCRLF\fR
characters).
.TP
-.B proc finish {host refname}
+.B proc finish {host refname status}
The \fBfinish\fR function is called when EOF has been received from
the \fBhost\fR. The \fBrefname\fR parameter is a name of the variable
keeping the entire text received from that host during the session.
This variable exists only if \fBrex\fR has been instructed to buffer
host output (see the \fB\-b\fR option). If it exists, the output text
-is stored as a list of lines.
+is stored as a list of lines. The \fBstatus\fR parameter is the exit
+status of the command.
.SS REX RUN OPTIONS
.TP
\fB\-b\fR, \fB\-\-buffer\-output\fR
@@ -617,11 +623,11 @@ Display short help summary.
Add \fIHOST\fR to the list. Multiple hosts can be specified as a
comma-delimited list (no whitespace around commas, please).
.TP
-\fB\-i\fR, \fB\-\-ignore-hosts\fR
+\fB\-i\fR, \fB\-\-ignore\-hosts\fR
Ignore the list of hosts read from the hostgroup file. Operate only
on hosts supplied in the command line (see the \fB\-\-host\fR option,
above). This is useful to preserve the settings from the hostgroup
-file while executing the command on the hosts defined on the command line.
+file while running the command on the hosts defined on the command line.
.TP
.BR \-I ", " \-\-interactive
Interactively ask for missing usernames and passwords.
@@ -630,7 +636,7 @@ Interactively ask for missing usernames and passwords.
Use \fICOMMAND\fR as interpreter for running \fIPROGRAM\fR. This
option implies
.BR \-\-copy .
-By default, \fBrex\fR determines the interpreter to use by analyzing
+By default, \fBrex\fR deduces the interpreter to use from
the first line of \fIPROGRAM\fR.
.TP
\fB\-j\fR, \fB\-\-jobs=\fIN\fR
@@ -711,6 +717,7 @@ Interactively ask for missing usernames and passwords.
.TP
\fB\-j\fR, \fB\-\-jobs=\fIN\fR
Run \fIN\fR jobs at once. Implies
+.BR "\-\-no\-host\-header \-\-prefix" .
.TP
\fB\-p\fR, \fB\-\-password=\fIPWD\fR
Set default password (unsafe!)
@@ -726,13 +733,13 @@ speaking, the command
is equivalent to
-\fBrex run \-D \fIFILE\fB cp {} \fIDEST\fR
+\fBrex run \-D \fIFILE\fB sudo cp {} \fIDEST\fR
.TP
\fB\-u\fR, \fB\-\-user=\fINAME\fR
Set default user name.
.TP
.BR \-w ", " \-\-confirm
-Prompt and wait for confirmation before each host.
+Prompt and wait for confirmation before proceeding with each host.
.TP
\fB\-X\fR, \fB\-\-exclude\-host=\fIHOST[\fB,\fINAME\fR...]
Remove \fIHOST\fR from the list. Multiple hosts can be specified as a
@@ -808,11 +815,12 @@ The output of \fBrex list groups\fR consists of two columns: the
group name and its description.
.PP
The second form lists hosts in a hostgroup selected by \fIOPTIONS\fR.
-At least one option must be present
+At least one option must be present.
.SS REX LIST OPTIONS
.TP
\fB\-h\fR, \fB\-\-help\fR
-Display short help summary.
+Display a short help summary.
+.TP
\fB\-H\fR, \fB\-\-host=\fIHOST[\fB,\fINAME\fR...]
Add \fIHOST\fR to the list. Multiple hosts can be specified as a
comma-delimited list (no whitespace around commas, please).
@@ -834,11 +842,11 @@ help summary.
\fBrex edit \fR[\fIFILE\fB]\fR
.EE
.PP
-Stars the editor defined by the \fBVISUAL\fR (or, if it is
+Starts the editor defined by the \fBVISUAL\fR (or, if it is
unset, \fBEDITOR\fR) environment variable for editing the
.B rex
database file \fIFILE\fR (or \fB~/.rex/db\fR, if used without argument).
-Upon exit from the editor, it compares the new content with the
+Upon exit from the editor, the command compares the new content with the
existing one. If changed, the user is prompted whether they wish to
save the changes.
.SH CONFIG ARRAY
@@ -851,7 +859,7 @@ it as they see fit. The valid keys in \fBconfig\fR are:
the command. See the description of the \fB\-\-data\-file\fR option.
.TP
.B debug
-(integer) Debug verbosity level. Defaults to 0, it is increased by
+(integer) Debug verbosity level. Defaults to 0. It is increased by
one with each \fB\-d\fR (\fB\-\-debug\fR) option. Biggest possible
value is 3.
.TP
@@ -872,11 +880,14 @@ List of hosts to run command on.
.TP
.B mode
Operation mode. The value is one of:
-.BR command ,
+.BR run ,
.BR copy-from ,
.BR copy-to ,
+.BR edit ,
+.BR group .
+.BR list ,
and
-.BR shell .
+.BR login .
.TP
.B pass
Password to use when no host or group-specific one is given (see \fBLogin
@@ -907,7 +918,7 @@ value of the environment variable
.BR USER .
.TP
.B option,buffer-output
-Buffer server output and print it only when the batch job is
+(boolean) Buffer server output and print it only when the batch job is
finished. See the \fB\-q\fR (\fB\-\-buffer\-output\fR) option.
.TP
.B option,confirm
@@ -929,7 +940,7 @@ option.
Set by the \fB\-i\fR (\fB\-\-ignore\-hosts\fR) command line option.
.TP
.B option,interactive
-Set by the \fB\-I\fR (\fB\-\-interactive) option.
+(boolean) Set by the \fB\-I\fR (\fB\-\-interactive) option.
.TP
.B option,jobs
(integer) Number of hosts to process in one batch. Default is 1. See
@@ -1082,9 +1093,9 @@ the \fBshrc\fR key in the rex database file.
.SS ZSH
Interaction with
.BR zsh (1)
-poses considerable problems because it spits out enormous amounts of
-escape sequences for colorization and other purposes, which makes it
-next to impossible to write an efficient regular expression for
+poses considerable problems because this shell spits out enormous
+amounts of escape sequences for colorization and other purposes, which
+makes it next to impossible to write an efficient regular expression for
recognizing command line prompts. To make matters even worse, it
ignores any changes made by \fBstty\fR.
.PP
@@ -1220,17 +1231,17 @@ Same with single-line output for each host.
rex run \-g web \-\-prefix \-\-no\-host\-header uptime
.EE
.IP \n+[step].
-Restart \fBhttpd\fR on each host (notice the use of \fBsudo\fR).
+Restart \fBhttpd\fR on each host (notice the use of \fB\-\-sudo\fR).
.PP
.EX
-rex run \-g web sudo /etc/init.d/httpd restart
+rex run \-g web --sudo /etc/init.d/httpd restart
.EE
.SH AUTHORS
Sergey Poznyakoff
.SH "BUG REPORTS"
Report bugs to <gray+rex@gnu.org.ua>.
.SH COPYRIGHT
-Copyright \(co 2012\-2017 Sergey Poznyakoff
+Copyright \(co 2012\-2019 Sergey Poznyakoff
.br
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>

Return to:

Send suggestions and report system problems to the System administrator.