ROCON(1) General Commands Manual ROCON(1)
NAME
rocon - run commands on clusters
SYNOPSIS
rocon [ -V | --version ] [ -v | --verbose | -d level | --debug=level ]
[ -h | --help ] [ -p | --paths ] [ -n | --simulate ] [ -F file ] -q |
--quiet ] [ --ssh=command ] [ -t secs | --timeout=secs ] [ -T count |
--threads=count ] { -c command host-selector-expression | -e | -g | -m
host-selector-expression | -r | -w | -A host | -D host | -M {+|-}host-
group[,...] host-selector-expression }
DESCRIPTION
Rocon runs a command-line-specified command on some hosts using ssh(1)
or lists those hosts. The hosts are determined by the contents of ro-
con's configuration file and by host-selector-expression, which is a
space-separated sequence of hostnames, hostgroup names and the combin-
ing tokens 'and', 'or', 'not', '(' and ')'.
Options are available for examining and modifying rocon's configuration
file.
CONFIGURATION
The configuration file consists of lines which are either hash-led com-
ments or host records. Host records are of the format:
hostname:[hostgroup1,...][:freefield1]...
where hostname is the name of a machine in the cluster and hostgroup1,
etc are arbitrarily named groups to which the specified host belongs.
The group names are strings conformant with the usual rules for host-
names (i.e. must consist of only letters, numbers, underscores and hy-
phens and must begin with a letter). Any number of fields after a sec-
ond colon may be present but are ignored by rocon; this is intended to
facilitate using the configuration file also for other purposes.
Some consideration should be given to naming hostgroups; however, some
guidelines can be applied:
+o create a group to which all hosts belong (e.g. AllHosts)
+o use CamelCase (e.g. SolarisHosts) in order to make it easy to
distinguish hostnames from hostgroup names on the command line
+o include hosts in a set of hostgroups with increasing specialisa-
tion, e.g.:
mickey:AllHosts,PcHosts,PcDellHostsLinuxHosts,DebianHosts,Debian31Hosts:::
OPTIONS
-d level, --debug=level Determines how verbose this program will be.
The message types displayed for the different
values of level are as follows: 0 displays no
messages; 1 displays only errors, 2 displays
errors and warnings; 3 displays errors, warn-
ings and informational messages; higher values
display errors, warnings, informational mes-
sages and various messages intended for debug-
ging. The default is 2.
-h, --help Displays a brief usage message.
-p, --paths Lists the compiled-in paths of various files
and directories that this program uses. -n,
--simulate Some external commands that this
program runs may be displayed rather than ac-
tually executed. BEWARE: different programs
implement different levels of simulation; so
this option may work perfectly; on the other
hand it may do nothing at all!
-v, --verbose Equivalent to -d 3.
-V, --version Prints the program's version number and exits.
-c command host-selector-expression
Runs command on the hosts matching host-selec-
tor-expression.
-e Edit the configuration file.
-F file Specify an alternate configuration file.
-g List known hostgroups.
-m host-selector-expression
List the hosts matching host-selector-expres-
sion.
-q, --quiet When using the -c option, suppress the host-
name: line prefix if there is no output from
the command.
-r Reads the config file to standard output.
--ssh=command Specify path to the ssh(1) command. The de-
fault is to rely on $PATH to find it.
-t secs, --timeout=secs Set the timeout for each ssh(1) command to
complete. By default, there is no timeout.
-R count, --threads=count
Set the maximum number of concurrent ssh(1)
commands that may be executed. The default
value is 200. Using --threads=1 makes the
ssh(1) commands run in series rather that in
parallel.
-w Writes the configuration file from standard
input.
-A host Add host to the configuration file. To add the
host to some hostgroups invoke rocon a second
time with the -M option. It is an error to
attempt to add a host that is already in the
configuration file.
-D host Delete host from the configuration file. It
is an error to attempt to delete a host that
is not in the configuration file.
-M {+|-}hostgroup[,...] host-selector-expression
Modify the hosts matching host-selector-ex-
pression, adding them ('+') or deleting them
('-') from the specified hostgroups. Several
modifications can be made at the same time,
e.g.: +AllHosts,-TestHosts,+DellHosts. It is
not an error to attempt to add a host to a
hostgroup of which it is already a member nor
to attempt to delete a host from a hostgroup
of which it is not a member.
EXIT STATUS
On success rocon returns zero. On failure it returns non-zero and dis-
plays a diagnostic message.
FILES
/etc/rocon.conf
Default configuration file; see also OPTIONS above.
ENVIRONMENT VARIABLES
EDITOR Command to be invoked when rocon called with
-e option. The default is vi(1).
PATH Used to find several commands.
ROCON_SSH_CMD Path to ssh(1). The default is ssh.
ROCON_CFG_FILE Path to the configuration file. For the de-
fault, see the FILES section above.
EXAMPLES
Given a host information file in the default location containing the
following:
mickey:AllHosts,DellHosts,DellLatitudeHosts,LinuxHosts,LinuxDebianHosts,LinuxDebian31Hosts:::
pluto:AllHosts,HpHosts,HpC110Hosts,HpuxHosts,Hpux11Hosts:::
donald:AllHosts,HpHosts,HpC110Hosts,LinuxHosts,LinuxDebianHosts,LinuxDebian31Hosts:::
goofey:AllHosts,SunHosts,SunUltraHosts,LinuxHosts,LinuxDebianHosts,LinuxDebian31Hosts:::
dumbo:AllHosts,SunHosts,SunUltraHosts,SolarisHosts,Solaris8Hosts:::
then get the uptime for all HP and Dell hosts except 'mickey' by run-
ning:
rocon -c uptime '(HpHosts or DellHosts) and not mickey'
CAVEATS
Due to the language of the host selector expression, host and hostgroup
names may not be 'and' or 'or' or 'not'.
Beware of local policies regarding the editing of the configuration
file (e.g. with the -e option); it may be that the configuration file
is generated from another database and that manual edits will be lost:
seek advice locally.
Any mathematical expression can be used to select hosts. For example,
the following command will add all hosts to the hostgroup AllHosts:
rocon -M +AllHosts 1
The mathematical expression here was simply '1', which will be true for
each considered host.
STANDARDS
This manual page documents version 5.0.4 of rocon.
SEE ALSO
rocon-config(1), ssh(1), vi(1)
AUTHOR
Alexis Huxley <alexishuxley@gmail.com>
COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 1995-2025 Alexis Huxley
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MER-
CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
675 Mass Ave, Cambridge, MA 02139, USA.
5 Feb 2025 ROCON(1)
