aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org>2022-03-17 14:56:56 +0200
committerSergey Poznyakoff <gray@gnu.org>2022-03-17 14:07:20 +0100
commit473debc4205564641faf55e17d5a3c67691c1681 (patch)
tree8aad412625980454c758bc4a9082db74b226995e
parentb323ea003fe32c1e500caa425706542d0efcbd45 (diff)
downloadrex-master.tar.gz
rex-master.tar.bz2
Version 4.1HEADv4.1master
Document the rex group command.
-rw-r--r--NEWS41
-rwxr-xr-xinstall2
-rwxr-xr-xrex14
-rw-r--r--rex.man8105
4 files changed, 132 insertions, 30 deletions
diff --git a/NEWS b/NEWS
index 63f9e6f..831dec2 100644
--- a/NEWS
+++ b/NEWS
@@ -1,8 +1,45 @@
-Rex NEWS -- history of user-visible changes. 2019-11-28
+Rex NEWS -- history of user-visible changes. 2022-03-17
See the end of file for copying conditions.
Please send bug reports and suggestions to <gray+rex@gnu.org.ua>
+Version 4.1, 2022-03-17
+
+* Hostgroup stack
+
+Rex now maintains a stack of hostgroups. Once you push a hostgroup
+name on stack, that hostgroup will be used by any subsequent rex
+command, unless it is given the -g option. The new command "group"
+(see below) provides ways to pop items off the stack, swap arbitrary
+element with the top of stack, select new hostgroups on the fly, etc.
+
+* New command: rex group
+
+The "rex group" command has the following forms:
+
+ rex group push GROUP
+ Push GROUP on stack.
+
+ rex group pop
+ Pop the topmost group off the stack.
+
+ rex group swap N
+ Exchange top of the stack with the Nth element (0-based).
+
+ rex group drop N
+ Remove Nth element from the stack.
+
+ rex group select COMMAND ARGS...
+ Create on top of the stack a temporary group that contains
+ those hosts from the current hostgroup where the supplied
+ shell command returns success, i.e. exits with code 0.
+
+ rex group show
+ List the contents of the hostgroup stack.
+
+* Add configuration function for overriding PTR records from rc files
+
+
Version 4.0, 2016-10-01
This release provide a set of commands for use in rc files. The use
@@ -203,7 +240,7 @@ Initial version.
=========================================================================
Copyright information:
-Copyright (C) 2012-2019 Sergey Poznyakoff
+Copyright (C) 2012-2022 Sergey Poznyakoff
Permission is granted to anyone to make or distribute verbatim copies
of this document as received, in any medium, provided that the
diff --git a/install b/install
index b25256c..42e5215 100755
--- a/install
+++ b/install
@@ -2,7 +2,7 @@
# Apart from these three lines, it is actually a -*- tcl -*- script \
exec expect "$0" -- "$@"
# This file is part of rex
-# Copyright (C) 2012-2016 Sergey Poznyakoff
+# Copyright (C) 2012-2022 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
diff --git a/rex b/rex
index d8f505d..9d01aa7 100755
--- a/rex
+++ b/rex
@@ -2,7 +2,7 @@
# Apart from these three lines, it is actually a -*- tcl -*- script \
exec expect "$0" -- "$@"
# This is rex - a remote execution utility
-# Copyright (C) 2012-2016 Sergey Poznyakoff
+# Copyright (C) 2012-2022 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
@@ -17,7 +17,7 @@ exec expect "$0" -- "$@"
# You should have received a copy of the GNU General Public License
# along with Rex. If not, see <http://www.gnu.org/licenses/>.
-set version "4.0"
+set version "4.1"
set sysconfdir "/etc/rex"
set usrconfdir "$env(HOME)/.rex"
set defaultfile "$usrconfdir/default"
@@ -1404,7 +1404,7 @@ proc prversion {} {
global version
puts "rex $version"
- puts {Copyright (C) 2012-2016 Sergey Poznyakoff
+ puts {Copyright (C) 2012-2022 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
@@ -3304,12 +3304,18 @@ proc rex_group_select {} {
}
proc rex_group_pop {} {
+ global argc
global config
rex_parse_cmdline \
-usage {rex group pop} \
-docstring {Pop current hostgroup off the stack.}
+ if {$argc != 0} {
+ terror "too many arguments"
+ exit 2
+ }
+
unset -nocomplain config(default,selected)
unset -nocomplain config(default,predicate)
::config::pop
@@ -3317,6 +3323,8 @@ proc rex_group_pop {} {
}
proc rex_group_push {} {
+ global argc
+ global argv
global config
rex_parse_cmdline \
diff --git a/rex.man8 b/rex.man8
index f732e81..37eb1cd 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-2019 Sergey Poznyakoff
+.\" Copyright (C) 2012-2022 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 "November 29, 2019" "REX" "Rex User Reference"
+.TH REX 8 "March 17, 2022" "REX" "Rex User Reference"
.ds ET /etc
.SH NAME
rex \- remote execution utility
@@ -29,7 +29,7 @@ rex \- remote execution utility
[\fB\-\-verbose\fR]\
[\fB\-\-version\fR]\
[\fB\-\-help\fR]\
- \fICOMMAND\fR
+ \fICOMMAND\fR\
[\fIARG\fR...]
.SH DESCRIPTION
.B Rex
@@ -53,8 +53,7 @@ of several hosts at once. If you have a set of hosts which you often
work with, it's best to use a
.IR hostgroup .
.PP
-A \fIhostgroup\fR defines a list of hosts and, optionally,
-a set of
+Hostgroup defines a list of hosts and, optionally, a set of
.B rex
settings to use when running commands on them. Each hostgroup is
identified by its name and is defined in a separate disk file. See
@@ -78,6 +77,23 @@ rex copy \-g\fINAME\fR \fIFILE\fR /tmp
copies \fIFILE\fR to the directory \fB/tmp\fR on each host from this
hostgroup.
.PP
+If the \fB\-g\fR option is omitted, \fBrex\fR will use the hostgroup
+from the top of the hostgroup stack or, if it is empty, the
+default hostgroup.
+.PP
+\fIHostgroup stack\fR is maintained using the \fBrex group\fR command.
+Once the user pushes a hostgroup name on it, that hostgroup will be
+used by any subsequent \fBrex\fR command, unless it is given the
+\fB\-g\fR option. The \fBrex group\fR command provides ways to pop
+items off the stack, swap arbitrary element and the top of the stack,
+select new hostgroups on the fly, etc. See the section
+.B REX GROUP
+below for a detailed discussion of hostgroup stack.
+.PP
+The \fBdefault hostgroup\fR is used if the hostgroup stack is empty.
+It is defined using the \fBoption group\fR statement in the
+configuration file.
+.PP
The list of hosts in a hostgroup can be modified for the duration of a
single \fBrex\fR command by using the \fB\-H\fR and \fB\-X\fR options.
The \fB\-H\fR (\fB\-\-host\fR) option works exactly as described
@@ -86,8 +102,8 @@ to ignore the list of hosts defined in the hostgroup and operate only
on those supplied with the \fB\-\-host\fR options.
.PP
The \fB\-X\fR (\fB\-\-exclude\fR) option instructs \fBrex\fR to remove
-its argument from the list of hosts. The argument must be a domain
-name or IP address of the host. It need not be exactly the same name
+its argument from the list of hosts. Its argument is the domain name
+or IP address of the host. It need not be exactly the same name
or IP as the one used in the \fBset hosts\fR statement in the \fBrc\fR
file. It suffices that it resolves to the same IP as one of the hosts
listed in the hostgroup.
@@ -187,7 +203,7 @@ address \fIIP\fR. This is useful if \fIIP\fR has no PTR record, or its
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
+Matches the current mode against each of \fImode\fR arguments. As soon
as the match is found, the corresponding \fBbody\fR is evaluated.
Similarly to the
.BR switch (n)
@@ -279,22 +295,22 @@ as a name of a disk file. The hostgroup definition consists of one or
more files located in the directory \fB~/.rex/hostgroup/\fINAME\fR
(user-specific), or \fB\*(ET/rex/hostgroup/\fINAME\fR (system-wide), where
\fINAME\fR is the name of the group. User-specific directories are
-given preference over the system-wide. The only mandatory file is
+given preference over the system-wide ones. The only mandatory file is
\fBrc\fR. It is a \fBTCL\fR source, which will be loaded in a
separate namespace, to avoid the possibility of inadvertent
contamination of the main \fBrex\fR code.
.PP
-\fBRex\fR provides a set of basic commands for use in rc files, so
-normally there is no need to know \fBrex\fR internals in order to
-configure it. See the subsection
+The hostgroup \fBrc\fR file should use the \fBhost\fR and/or
+\fBhostgroup\fR commands
+(see the subsection
.B Configuration files
-for a detailed guide.
+above) to define the list of hosts in the hostgroup.
.SS Debugging
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. \fB\-ddd\fR).
+information is output. Currently, the most detailed information is
+obtained at level 3, i.e. using \fB\-ddd\fR.
.PP
Additional information is provided by the \fB\-l\fR
(\fB\-\-log\fR) option, which enables logging of the send/expect
@@ -683,7 +699,7 @@ if no command line prompt is seen within the predefined interval,
will try to disable \fBZLE\fR option, set \fBPS1\fR to
a dollar sign followed by space and will retry scanning. This allows for
properly recognizing command line prompts returned by \fBzsh\fR at the
-expense of certain slowdown. See the subsection \fBZSH\fR below for
+expense of a certain slowdown. See the subsection \fBZSH\fR below for
more efficient ways of handling \fBzsh\fR.
.SH REX COPY
.EX
@@ -773,6 +789,44 @@ Set default user name.
.TP
\fB\-h\fR, \fB\-\-help\fR
Display short help summary.
+.SH REX GROUP
+The \fBrex group\fR command manages host group stack.
+.TP
+\fBrex group push \fIGROUP\fR
+Pushes hostgroup \fIGROUP\fR on stack. The \fIGROUP\fR will be used
+by all subsequent \fBrex\fR commands, in the absence of the \fB\-g\fR option.
+.TP
+.B rex group pop
+Pops the hostgroup off the top of the stack.
+.TP
+\fBrex group swap \fIN\fR
+Exchanges top of the stack with the \fIN\fRth element (0-based).
+.TP
+\fBrex group drop \fIN\fR
+Removes the \fIN\fRth element from the stack.
+.TP
+\fBrex group select \fICOMMAND ARGS\fR...
+Using the current hostgroup, selects the hosts on which the supplied
+shell command gives success (exits with 0 status). On success, creates
+a new unnamed hostgroup consisting of the selected hosts and pushes it
+on stack.
+.TP
+\fBrex group show \fR[\fIOPTIONS\fR]
+Shows the hostgroup stack. Without options, displays only the topmost
+(current) entry. The following options are understood:
+.RS
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+Show all stack entries.
+.TP
+\fB\-H\fR, \fB\-\-hosts\fR
+Show hosts in the topmost (current) hostgroup.
+.PP
+All options are mutually exclusive.
+.RE
+.PP
+All the commands above accept also the \fB\-h\fR (\fB\-\-help\fR)
+option, which displays a short help summary.
.SH REX LOGIN
.EX
\fBrex login [\fIOPTIONS\fR] \fIHOST\fR
@@ -782,7 +836,7 @@ Logs in to the remote host \fIHOST\fR. It is basically equivalent to
using \fBssh\fR, except that it is convenient to use if the \fIHOST\fR
doesn't support passwordless authentication (see the section
.BR "Login credentials" ,
-above.
+above).
.SS REX LOGIN OPTIONS
.TP
.BR \-I ", " \-\-interactive
@@ -926,7 +980,10 @@ finished. See the \fB\-q\fR (\fB\-\-buffer\-output\fR) option.
\fB\-w\fR, \fB\-\-confirm\fR option.
.TP
.B option,editdb
-(boolean) Editdb mode. See the \fB\-\-editdb\fR option.
+(boolean) Editdb mode. This option is set by the
+.B rex edit
+command. See the section
+.BR "REX EDIT" .
.TP
.B option,encrypt
(boolean) String encrypt mode. See the \fBencrypt\fR option.
@@ -961,7 +1018,7 @@ See also the \fB\-q\fR (\fB\-\-no\-init\-file\fR) option.
.TP
.B option,noop
(boolean) Don't run \fICOMMAND\fR. This option is convenient when you
-have some side effects in your rc file (such as, e.g. launching a vpn
+have some side effects in your rc file (such as, e.g. launching a VPN
etc.) and wish to evaluate them without actually executing a command.
.TP
.B option,prefix
@@ -1065,8 +1122,8 @@ is:
shrc {set histfile=/dev/null}
.EE
.PP
-The drawback of this approach that the assignment itself, and all the
-built-in commands sent by \fBrex\fR itself are still retained in history.
+The drawback of this approach is that the assignment itself and all the
+built-in commands sent by \fBrex\fR are still retained in history.
.PP
A more sophisticated way, suitable for both \fBbash\fR and \fBzsh\fR
shells is:
@@ -1130,8 +1187,8 @@ If only some of your hosts run \fBzsh\fR, you can set the
.PP
The value of that option is a whitespace-separated list of TCL strings.
.PP
-For example, if the account on host \fBbaboo\fR runs \fBzsh\fR, start
-\fBrex --editdb\fR and add the following line:
+For example, if the account on host \fBbaboo\fR runs \fBzsh\fR, run
+\fBrex edit\fR and add the following line:
.PP
.EX
baboo:earlycmd {unsetopt ZLE} {PS1='$ '}
@@ -1241,7 +1298,7 @@ Sergey Poznyakoff
.SH "BUG REPORTS"
Report bugs to <gray+rex@gnu.org.ua>.
.SH COPYRIGHT
-Copyright \(co 2012\-2019 Sergey Poznyakoff
+Copyright \(co 2012\-2022 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.