\" $HeadURL$ $LastChangedRevision$
.\"
.pso ade-config --format=man
.so \*[ade_include_prefix]/ade.man
.pso rocon-config --format=man
.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 \-\-refresh
]
[
.B \-q
|
.B \-\-quiet
]
[
.B \-\-ssh=\fIcommand\fR
]
[
.B \-t
.I secs
|
.B \-\-timeout=\fIsecs\fR
]
[
.B \-s
.I command
|
.B \-\-sqlite=\fIcommand\fR
]
[
.B \-u
]
{
.B \-c 
.I command
|
.B \-e
|
.B \-g
|
.B \-m
|
.B \-r
|
.B \-w
}
.I host\-selector\-expression
.br
.ne 5
.SH DESCRIPTION
.B Rocon
runs a specified command on a set of remote machines 
using
.B ssh\fR(1)
or lists that set of machines.
The set of machines is determined by the contents of a configuration file and by
.I host\-selector\-expression\fR.
.PP
.I host\-selector\-expression
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
In addition, 
.B rocon 
can invoke an editor to edit the configuration file, write the contents of the
configuration file to standard output and display a list of known hostgroups.
.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,\fIhostgroup2\fR,...:\fIfreefield1\fR:\fIfreefield2\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 caps-led names or suffix the group names with 
.B Hosts
(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
.RE
.PP
.B Rocon
creates a database with as many columns as there are hosts and hostgroups; if you have 
large number of hosts then this can be a problem. To address this you need to 
compile 
.B sqlite\fR(1) 
with support for a larger number of columns, which you can do with something like
this:
.RS 5
.IP
.nf
.fam C
.B wget --no-check-certificate https://www.sqlite.org/2015/sqlite-autoconf-3090200.tar.gz
.B tar xzf sqlite-autoconf-3090200.tar.gz 
.B cd sqlite-autoconf-3090200
.B SQLITE_MAX_COLUMN=32768 ./configure
.B SQLITE_MAX_COLUMN=32768 make
.B cp sqlite3 ~/.sqlite3-with-support-for-32768-columns
.fam T
.fi
.br
.br
.RE
.PP
and then telling 
.B rocon
to use this version of
.B sqlite\fR(1)
by adding something like:
.RS 5
.IP
.nf
.fam C
.B ROCON_SQLITE_CMD=~/.sqlite3-with-support-for-32768-columns
.B export ROCON_SQLITE_CMD
.fam T
.fi
.br
.br
.RE
.PP
to your startup files (e.g.
.B .profile
(see 
.B bash\fR(1)).
.ne 5
.SH OPTIONS
\*[ade_standard_options_component]
.TP 
.B \-c \fI command
Runs the specified command on the set of remote machines specified by
.I host\-selector\-expression\fR
using
.B ssh\fR(1).
.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
Display the set of machines specified by 
.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 from standard input and write it to the configuration file.
.TP
.B \-\-refresh
Force refresh of the cache. Ordinarily 
.B rocon
manages the cached compiled configuration data itself and this option is not needed. However if old versions
of the configuration are restored then it may be impossible for 
.B rocon
to determine that its cache is stale and needs refreshing. In such circumstances this option will force
the cache to be refreshed.
.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
When using the 
.B \-c
option, wait a maximum of 
.I secs
seconds for
.I command
to complete; the default is 0, which means no timeout is applied.
.TP
.B \-s \fIcommand\fR,\fB \-\-sqlite=\fIcommand\fR
Set the name of the
.B sqlite\fR(1)
command. The default is 
.B sqlite3\fR.
.TP
.B \-u
Further limits
.B rocon\fR's
activities to apply only to hosts which are up.
.TP
.B \-w
Writes the config file to standard output.
.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. 
.B vi\fR(1).
.TP
.B PATH
used to find several commands. See also
.TP
.B ROCON_CHECKSQLITE_FLAG
If set to 
.B false\fR
and 
.B sqlite\fR(1)
does not support a large number of columns then no warning about this limitation will be given.
It is expected that sysadmins at 'small' sites will set this in their startup files to avoid
the annoyance of the warning message.
.TP
.B ROCON_SQLITE_CMD
Path to 
.B sqlite\fR(1). 
The default is 
.B sqlite3\fR.
.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:
.IP
.nf
.fam C
.B mickey:AllHosts,PcHosts,PcDellHostsLinuxHosts,DebianHosts,Debian31Hosts:::
.B pluto:AllHosts,HpHosts,HpC110Hosts,HpuxHosts,Hpux11Hosts:::
.B donald:AllHosts,HpHosts,HpC110Hosts,LinuxHosts,DebianHosts,Debian31Hosts:::
.B goofey:AllHosts,SunHosts,SunUltraHosts,LinuxHosts,DebianHosts,Debian31Hosts:::
.B dumbo:AllHosts,SunHosts,SunUltraHosts,SolarisHosts,Solaris8Hosts:::
.fam T
.fi
.PP
To get the uptime for all hosts in the
hostgroup 'HpHosts' except those running Linux run:
.IP
.nf
.fam C
.B rocon -c uptime HpHosts and not Linux
.fam T
.fi
.PP
To remove any existing reboot from root's crontab and replace it with a reboot at 02:00
every Sunday morning on all machines except dumbo run:
.IP
.nf
.fam C
.B rocon -c '{ crontab -l | grep -v shutdown; echo \[dq]0 2 * * 1 shutdown -r -y now\[dq]; } > /tmp/newcrontab; crontab - < /tmp/newcrontab' AllHosts and not dumbo
.fam T
.fi
.PP
For those without a better way to control the system time,
don't run the following because
it is too slow and, depending on the number of hosts in 'AllHosts', can result
in a significant time difference between the first and last hosts on the list:
.IP
.nf
.fam C
.B rocon -u -c 'date 1227' AllHosts
.fam T
.fi
.PP
Instead run the following:
.IP
.nf
.fam C
.B rocon -u -m AllHosts | xargs -i sh -c 'ssh {} date 1227 &'
.fam T
.fi
.br
.ne 5
.ne 5
.SH CAVEATS
Because of the format in which the configuration is cached, hostnames and
hostgroup names may not be SQL keywords; see http://www.sqlite.org/lang.html
for a list of these. This restriction is considered a bug.
.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.
.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), sqlite(1), vi(1), http://www.sqlite.org, RFC952
.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]