.\" $HeadURL$ $LastChangedRevision$
.\"
.TH ROCON 1 "26 March 2005"
.\" If this man page will be released with aderel(1) then uncomment
.\" the following line and comment out the one above.
.\" .TH ROCON 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.SH NAME
rocon \- Run Or Copy On remote host
.br
.ne 5
.SH SYNOPSIS
.B rocon
[
.B \-V
|
.B \-\-version
] [
.B \-v
|
.B \-\-verbose
|
.B \-d
.I level
|
.B \-\-debug=\fIlevel\fR 
] 
[
.B \-h
|
.B \-\-help
] [
.B \-p
|
.B \-\-list\-paths
]
[
.B \-f
.I cfgfile
|
.B \-\-config\-file=\fIcfgfile\fR
]
[
.B \-S
.I separator
|
.B \-\-separator=\fIseparator\fR
]
[
.B \-l
.I login
|
.B \-\-login=\fIlogin\fR
]
{
.B \-c 
.I command
| 
.B \-s
.I source
.B \-t
.I target
|
.B \-m
|
.B \-u
|
.B \-e
} 
.I hostspec \fB...
.br
.ne 5
.SH DESCRIPTION
.B Rocon
is a 
.B remsh\fR(1)/\fBrsh\fR(1)
and 
.B rcp\fR(1) 
wrapper useful for performing the same simple action on
many machines. 
.B Rocon
accepts an ordered series 
.I hostspec\fRs
which specify a list of hosts which will be candidates for
.B rocon\fR's
action. Each
.I hostspec 
is described by:
.PP
.nf
.fam C
{\fB+\fR|\fB\-\fR}{\fIhost\fR|\fIhostgroup\fR}
.fam T
.fi
.PP
where 
.I host
is the name of a host, 
.I hostgroup
is the name of a hostgroup that is specified in the configuration file (see
CONFIGURATION below) and plus and minus signs are used to 
specify the inclusion of exclusion of that host or hostgroup.
.PP
.B Rocon
operates in one of five modes:
.PP
In 
.B
copy 
mode, 
.B rocon
takes a local file and copies it to the specified location
on the candidate hosts.
.PP 
In 
.B command 
mode,
.B rocon 
runs the specified command on the candidate hosts.
.PP
In 
.B match 
mode,
.B rocon
lists all matching hosts. 
.PP
In 
.B up 
mode,
.B rocon
lists matching hosts only if they are up.
.PP
In
.B edit
mode,
.B rocon 
invokes your favourite editor to edit the host information file.
.PP
.br
.ne 5
.SH CONFIGURATION
The default host information file is
.B \*[rocon_etc_prefix]/rocon.conf\fR.
This file is made up of hash-led comments, blank lines, and 
host information records. Each host information record is a
colon-separated series of fields according the following 
format:
.PP
.nf
.fam C
\fIhost\fR:\fIhostgroups\fR:\fIfreefield1\fR:\fIfreefield2\fR:\fIfreefield3\fR...
.fam T
.fi
.PP
where 
.I host
is the name of the host,
.I hostgroups
is a comma-separated list of one or more
.I hostgroup
names to which
.I host 
belongs,
.I hostgroup 
is any arbitrary word subject to the conditions that it may not
be a colon and must begin with an upper-case character,
and
.I freefield1\fR, ...
may be used to record such information as is locally
relevent, e.g.  serial number, floorbox id, user's name.
.PP 
It is suggested that all hosts are made members of the hostgroup
.B ALL\fR,
plus additional hostgroups specifying the host's hardware and operating
system with more and more specificity (see EXAMPLES below).
.br
.ne 5
.SH OPTIONS
.TP 25
.B \-c \fIcmd\fR
.B Rocon 
is to run in 
.B command
mode and the command it is to run on the candidate hosts is
.I cmd
(This is a single argument to the option, so quote it if 
necessary.)
.TP
.B \-d \fIlevel\fR, \fB\-\-debug=\fIlevel\fR
Determines how verbose
.B rocon
will be. The message types displayed for the different values of 
.I level
are as follows:
.RS 25
.TP 5
.B 0
internal errors only
.TP
.B 1
internal errors and normal errors 
.TP
.B 2
internal errors, normal errors and warnings
.TP 
.B 3
internal errors, normal errors, warnings and informational messages
.TP 
.B >3
all the above plus application-specific debug messages.
.RE
.TP
.B \-e
.B Rocon
is to run in
.B edit
mode.
.TP
.B \-f\fIcfgfile\fR, \fB \-\-config\-file=\fIcfgfile\fR
Host information should be read from
.I cfgfile 
instead of from the default location.
.TP
.B \-h\fR, \fB\-\-help
Displays a brief usage message.
.TP
.B \-l \fIlogin\fB
Specify an alternate remote login. The default is the same as on the local
machine.
.TP
.B \-m
.B Rocon 
is to run in
.B match
mode.
.TP
.B \-p\fR, \fB\-\-list\-paths
List the compiled-in paths of various files and directories that
.B rocon
uses.
.TP 
.B \-s \fIsource\fB \-t \fItarget\fB
.B Rocon 
is to run in 
.B copy
mode. The local file is specified by
.I source
and it will be copied to
.I target
on all candidate hosts.
.TP
.B \-u
.B Rocon 
is to run in
.B up
mode.
.TP
.B \-v\fR, \fB\-\-verbose
Equivalent to
.B \-d 3\fR.
.TP
.B \-V\fR, \fB\-\-version
Print the program's version number and exit.
.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 25
.B \*[rocon_etc_prefix]/rocon.conf
default host information file
.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).
.br
.ne 5
.SH EXAMPLES
Given a host information file in the default location containing:
.IP
.nf
.fam C
.B mickey:ALL,PC,Dell PC,Dell PC XPS T500,Linux,Debian Linux,Debian 3.1 Linux:::
.B pluto:ALL,HP,HP C110,HP-UX,HP-UX 11.00:::
.B donald:ALL,HP,HP C110,Linux,Debian Linux,Debian 3.1 Linux:::
.B goofey:ALL,Sun,Sun Ultra,Sun Ultra 1000,Linux,Debian Linux,Debian 3.1 Linux:::
.B dumbo:ALL,Sun,Sun Ultra,Sun Ultra 1000,Solaris,Solaris 8:::
.fam T
.fi
.PP
To get the uptime for all hosts in the
hostgroup HP except those running Linux
following command:
.IP
.nf
.fam C
.B rocon -c uptime +HP -Linux
.fam T
.fi
.PP
To remove a Sunday night reboot at 1 a.m. from root's crontab and
replace it with a reboot at 2 a.m. on all machines 
except dumbo:
.IP
.nf
.fam C
.B rocon -c 'mkdir /root/arc; crontab -l | grep -v shutdown > /root/arc/crontab.old' +ALL -dumbo
.B cat > /tmp/add_to_cron_tmp <<EOF
.B 0 2 * * 1 shutdown -r -y now
.B EOF
.B rocon -s /tmp/add_to_cron_tmp -d /tmp/add_to_cron +ALL -dumbo
.B rocon -c 'cat /root/arc/crontab.old /tmp/add_to_cron > /root/arc/crontab; crontab < /root/arc/crontab' +ALL -dumbo
.fam T
.fi
.PP
For those without a better way to control the system time,
don't use the following because
it is too slow and, depending on the number of hosts in 'ALL', can result
in a significant time difference between the first and last hosts on the list:
.IP
.nf
.fam C
.B rocon -c date 1227' +ALL
.fam T
.fi
.PP
Instead use the following:
.IP
.nf
.fam C
.B rocon -u +ALL | xargs -i sh -c 'rsh {} date 1227 &'
.fam T
.fi
.br
.ne 5
.SH CAVEATS
Beware of making the host on which 
.B rocon
is being run a candidate host for a copy operation.
In such cases the destination file name should differ 
from the source file name. (See EXAMPLES below.)
.PP
The order of 
.I hostspec\fRs
on the command is significant.
.PP
Since 
.B rocon
version 1.9, there is no longer a default for the
.B \-c
option.
.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
remsh(1), rsh(1), rcp(1), uptime(1), ping(1), rhosts(4), netgroup(4), vi(1),
date(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
.PP
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.
.PP
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
.PP
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.