\" $HeadURL$ $LastChangedRevision$
.\" vim: filetype=nroff
.\"
.TH ROCON 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.SH NAME
rocon \- run commands on clusters
.br
.ne 5
.SH SYNOPSIS
.B rocon
\*[ade_standard_synopsis_component]
[
.B \-F
.I file
]
.B \-q
|
.B \-\-quiet
]
[
.B \-\-ssh=\fIcommand\fR
]
[
.B \-t
.I secs
|
.B \-\-timeout=\fIsecs\fR
]
[
.B \-T
.I count
|
.B \-\-threads=\fIcount\fR
]
{
.B \-c 
.I command
.I host\-selector\-expression
|
.B \-e
|
.B \-g
|
.B \-m
.I host\-selector\-expression
|
.B \-r
|
.B \-w
|
.B \-A
.I host
|
.B \-D
.I host
|
.B \-M
{\fB+\fR|\fB-\fR}\fIhostgroup\fR[,...]
.I host\-selector\-expression
}
.br
.ne 5
.SH DESCRIPTION
.B Rocon
runs a command-line-specified command on some hosts 
using
.B ssh\fR(1)
or lists those hosts.
The hosts are determined by the contents of 
.B rocon\fR's
configuration file and by
.I host\-selector\-expression\fR,
which is a space-separated sequence of hostnames, hostgroup names
and the combining tokens 
.B \fR'\fBand\fR', '\fBor\fR', '\fBnot\fR', '\fB(\fR' and '\fB)\fR'.
.PP
Options are available for examining and modifying 
.B rocon\fR's
configuration file.
.br
.ne 5
.SH CONFIGURATION
The configuration file consists of lines which are either
hash-led comments or host records. Host records are of the format:
.PP
.nf
.fam C
\fIhostname\fR:[\fIhostgroup1\fR,...][:\fIfreefield1\fR]...
.fam T
.fi
.PP
where
.I hostname
is the name of a machine in the cluster and 
.I hostgroup1\fR,
etc are arbitrarily named groups to which the specified host belongs. The group
names are strings conformant with the usual rules for hostnames (i.e. must consist
of only letters, numbers, underscores and hyphens and must begin with a letter).
Any number of fields after a second colon may be present but are ignored by 
.B rocon\fR;
this is intended to facilitate using the configuration file also for other purposes.
.PP
Some consideration should be given to naming hostgroups; however, some guidelines can
be applied:
.TP
\(bu
create a group to which all hosts belong (e.g. 
.B AllHosts\fR)
.TP
\(bu
use CamelCase (e.g. 
.B SolarisHosts\fR)
in order to make it easy to distinguish hostnames from hostgroup names on the command line
.TP
\(bu
include hosts in a set of hostgroups with increasing specialisation, e.g.:
.RS 5
.IP
.nf
.fam C
.B mickey:AllHosts,PcHosts,PcDellHostsLinuxHosts,DebianHosts,Debian31Hosts:::
.fam T
.fi
.br
.ne 5
.SH OPTIONS
\*[ade_standard_options_component]
.TP 
.B \-c \fIcommand host\-selector\-expression\fR
Runs 
.I command 
on the hosts matching
.I host\-selector\-expression\fR.
.TP
.B \-e
Edit the configuration file.
.TP
.B \-F \fIfile\fR
Specify an alternate configuration file.
.TP
.B \-g
List known hostgroups.
.TP
.B \-m \fIhost\-selector\-expression\fR
List the hosts matching
.I host\-selector\-expression\fR.
.TP
.B \-q\fR, \fB\-\-quiet\fR
When using the 
.B \-c 
option, suppress the 
.I hostname\fB:\fR
line prefix if there is no output from the command.
.TP
.B \-r
Reads the config file to standard output. 
.TP
.B \-\-ssh=\fIcommand\fR
Specify path to the 
.B ssh\fR(1)
command. The default is to rely on
.B $PATH
to find it.
.TP
.B \-t \fIsecs\fR, \fB\-\-timeout=\fIsecs\fR
Set the timeout for each
.B ssh\fR(1)
command to complete.
By default, there is no timeout.
.TP
.B \-R \fIcount\fR, \fB\-\-threads=\fIcount\fR
Set the maximum number of concurrent 
.B ssh\fR(1)
commands that may be executed.
The default value is
.B 200\fR.
Using
.B \-\-threads=1
makes the
.B ssh\fR(1)
commands run in series rather that in parallel.
.TP
.B \-w
Writes the configuration file from standard input.
.TP
.B \-A \fIhost\fR
Add 
.I host
to the configuration file. To add the host to some hostgroups invoke 
.B rocon
a second time with the 
.B \-M
option.
It is an error to attempt to add a host that is already in the configuration file.
.TP
.B \-D \fIhost\fR
Delete
.I host
from the configuration file. 
It is an error to attempt to delete a host that is not in the configuration file.
.TP
.B \-M \fR{\fB+\fR|\fB-\fR}\fIhostgroup\fR[,...] \fIhost\-selector\-expression\fR
Modify the hosts matching
.I host\-selector\-expression\fR,
adding them ('\fB+\fR') or deleting them ('\fB-\fR') from the specified hostgroups. 
Several modifications can be made at the same time, e.g.:
.B +AllHosts,-TestHosts,+DellHosts\fR.
It is 
.I 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.
.br
.ne 5
.SH EXIT STATUS
On success
.B rocon
returns zero. On failure it returns non-zero and displays a diagnostic
message.
.br
.ne 5
.SH FILES
.TP 
.B \*[rocon_etc_prefix]/rocon.conf
Default configuration file; see also 
.B OPTIONS
above.
.br
.ne 5
.SH ENVIRONMENT VARIABLES
.TP 25
.B EDITOR
Command to be invoked when 
.B rocon
called with 
.B \-e
option. 
The default is
.B vi\fR(1).
.TP
.B PATH
Used to find several commands.
.TP
.B ROCON_SSH_CMD
Path to
.B ssh\fR(1).
The default is
.B ssh\fR.
.TP
.B ROCON_CFG_FILE
Path to the configuration file. For the default, see the 
.B FILES
section above.
.br
.ne 5
.SH EXAMPLES
Given a host information file in the default location containing the following:
.IP
.nf
.fam C
.B mickey:AllHosts,DellHosts,DellLatitudeHosts,LinuxHosts,LinuxDebianHosts,LinuxDebian31Hosts:::
.B pluto:AllHosts,HpHosts,HpC110Hosts,HpuxHosts,Hpux11Hosts:::
.B donald:AllHosts,HpHosts,HpC110Hosts,LinuxHosts,LinuxDebianHosts,LinuxDebian31Hosts:::
.B goofey:AllHosts,SunHosts,SunUltraHosts,LinuxHosts,LinuxDebianHosts,LinuxDebian31Hosts:::
.B dumbo:AllHosts,SunHosts,SunUltraHosts,SolarisHosts,Solaris8Hosts:::
.fam T
.fi
.PP
then get the uptime for all HP and Dell hosts except 'mickey' by running:
.IP
.nf
.fam C
.B rocon -c uptime '(HpHosts or DellHosts) and not mickey'
.fam T
.fi
.br
.ne 5
.SH CAVEATS
Due to the language of the host selector expression, host and hostgroup names 
may not be '\fBand\fR' or '\fBor\fR' or '\fBnot\fR'.
.PP
Beware of local policies regarding the editing of the configuration file (e.g.
with the
.B \-e
option); it may be that the configuration file is generated from another database
and that manual edits will be lost: seek advice locally.
.PP
.I Any
mathematical expression can be used to select hosts. For example, the following
command will add
.I all
hosts to the hostgroup
.B AllHosts\fR:
.IP
.nf
.fam C
.B rocon -M +AllHosts 1
.fam T
.fi
.PP
The mathematical expression here was simply '\fB1\fR', which will be true for
each considered host.
.br
.ne 5
.SH STANDARDS
This manual page documents version ADE_APP_TOKEN_RELEASE_ID of
.B rocon\fR.
.br
.ne 5
.SH SEE ALSO
rocon-config(1), ssh(1), vi(1)
.br
.ne 5
.SH AUTHOR
ADE_APP_TOKEN_AUTHOR_NAME <ADE_APP_TOKEN_AUTHOR_EMAIL>
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 1995-ADE_APP_TOKEN_RELEASE_YEAR ADE_APP_TOKEN_AUTHOR_NAME
\*[ade_standard_copyright_component]