coshell \- network shell coprocess server
is a local network shell coprocess server for programs using
This server runs as a daemon on the user's home host,
and only processes running on the home host have access to the server.
The server controls a background
shell process, initiated by
on each of the connected hosts.
The environment of the local host shell is inherited from the server
whereas the environment of remote shells is initialized by
Job requests are accepted from user processes on the local host
and are executed on the connected hosts.
and the environment variables listed in
are set to match requesting user values.
does not directly support interactive jobs.
Job scheduling is based on load and idle time information generated by the
This information is updated every 60 seconds on average.
The server is started by running
The command exits after a child server process is forked in the background.
arguments name files containing local network host information
which may be generated from two shell scripts
under the subdirectory bin of the installation root directory.
If no files are specified then the default
The local network is comprised of hosts sharing the same file name space.
into two types, global and host-specific.
and are not associated with any particular host.
Attribute value pairs, not including readonly ones, may be specified in the
local network host information files,
and may be referenced in an expression in
Attribute names must match [a-zA-Z_][a-zA-Z_0-9]*.
In the following description on these attributes,
may be an actual host name or a comma separated list of attribute value pairs
adds the host to the automatic selection pool.
The host scheduling bias.
Hosts with a high bias are (linearly) least likely to be scheduled for job
The grace period for jobs running on busy hosts.
attribute is non-zero and its minimum logged in
user idle time is less than the value of
For a job running on an idle host,
is the maximum amount of time the job may run after the host becomes
busy. If the job does not finish within
the SIGSTOP signal is sent to the job and the job stops. When
the host idle time exceeds
the SIGCONT signal is sent to the job and the job resumes.
may be m(inute) and h(our).
The number of cpus on the host.
Names a file containing default attributes for machines on the local network.
If no directory components are specified then the subdirectory
of the installation root directory is searched.
The default attribute file for the local network is
The minimum logged in user idle time before jobs will be scheduled on the host.
may be m(inute) and h(our).
meaning no idle time restrictions.
for workstations and is not specified (
i.e., always
available) for compute servers.
labels either the current
Labels are displayed but are otherwise ignored.
A readonly attribute that evaluates to the host load average.
The maximum host load average. No job will be
scheduled on a host with load average >=
means no load average limit.
The host name in the local domain (
i.e., no .'s in the name).
In a host selection context:
A readonly attribute that evaluates to
if the host shell is closed,
if the host shell is being opened, and
if the host shell is open.
The maximum number of concurrent jobs on each cpu. The default is
The maximum number of concurrent jobs run by
has an upper limit that is silently enforced.
The limit is the half of the number of file descriptors allowed.
The maximum number of concurrent jobs per user connection to
The number of cpus in the processor pool.
The host cpu rating, usually in mips relative to the other hosts
on the local network. This is usually the observed rating rather than
the one in the vendor's advertisements.
The host type that differentiates different processor types, usually
related to the object and executable attributes.
A readonly attribute that evaluates to the number of seconds the host has
is less than 0 then it is the number of seconds the host has been down.
Other user-defined attributes may be specified.
They may be referenced in
expressions, but are otherwise ignored by
opens an interactive connection to the running server.
.BI a " host[,attributes ...]"
Set or add attributes for the named hosts.
Close the shell connections to the named hosts.
The hosts are also removed from the automatic selection pool.
is specified then the server debug trace level is set to
Higher debug levels produce more output on
This is a debugging option and may not be present in all
is specified then close the internal server file descriptor
otherwise list the status of all open file descriptors in the server.
List the status of all jobs.
The id assigned to the job by the server.
This number may be used as an argument to the
The id assigned to the requesting user by the server.
The id assigned to the job by the requesting user.
if the shell is in the process of opening,
if the PID has not been determined yet, and
if the job completed before its PID was determined.
The elapsed time since the job started.
follows the time if the job is about to terminate.
The host where the job is running.
The most recent signal sent to the job follows the host name.
The label assigned to the job by the requesting user.
\fBk\fP [ \fBc\fP | \fBk\fP | \fBs\fP | \fBt\fP ] \fIjob\fP
Kill the job with the server JOB id
If no argument is specified then the
signal is sent to the job.
List all host names matching the attribute expression
The names are sorted in scheduling rank order from best to worst.
names (after sorting) are listed.
Open a shell connection to the named hosts.
Quit the interactive connection.
Kill the server and quit the interactive connection.
\fBr\fP \fIhost\fP [ \fIcommand\fP ]
may be an attribute expression.
\fBs\fP [ \fBa\fP | \fBe\fP | \fBl\fP | \fBo\fP | \fBp\fP | \fBs\fP | \fBt\fP ]
List the shell connection status.
There is at most one shell connection per host.
If no argument is specified then only open connections are listed.
lists the attributes for all shells,
lists all shells in the processor pool,
lists the process id of all open shells,
lists the shell scheduling status (primarily for debugging),
lists all open shells sorted by the recent job activities running on each
The status fields for \fBse\fP and \fBsl\fP are:
The id assigned to the open shell by the server,
if the shell is not open and is not in the processor pool,
if the shell is not open, and
if an open is in progress.
The number of jobs currently running on the host.
follows the number if any of the jobs are queued pending the completion of an
The total number of jobs run on the host.
The accumulated user time
The elapsed time since the most recent logged in user activity.
follows the time if the host does not meet the processor pool
The number of cpus on the host.
The host rating, usually in network relative mips.
Hosts with lower bias are more likely to be scheduled.
The host type, usually related to object and executable attributes.
The status fields for \fBso\fP, \fBss\fP, and \fBst\fP are:
The id assigned to the open shell by the server,
if the shell is not open and is not in the processor pool,
if the shell is not open, and
if an open is in progress.
The accumulated number of times the server has connected to the host.
The current number of active users.
The amount of time the host has been up.
The amount of time the server has connected to the host.
The amount of time before the host status information is out-of-date.
The amount of time of keeping the host connection followed
by the host identification code, 1 for the local host, 0 for other
A measure of the recent job activities running on the host.
A measure of the desirability of the host. This takes idle time
restriction, load average, and the number of CPU into account.
Two digits after the decimal point are random numbers which are
used to break ties between different
servers. Hosts with lower
are more likely to be scheduled.
List the accumulated totals.
The number of active shell connections followed by the total number
of successful shell connections.
The number of active user connections followed by the total number
of successful user connections.
The number of active jobs followed by the total number
The number of server-user transactions.
The elapsed time since the server started.
The elapsed time during which the USER and SYS times were accumulated.
The accumulated user time for all jobs on all hosts.
The accumulated sys time for all jobs on all hosts.
The number of cpus available on all connected hosts followed by the
processor pool cpu limit plus the explicit host override count.
host is a connected host that does not meet the processor pool
The load average, averaged over all connected hosts.
The host rating, averaged over all connected hosts.
List connected user status.
The id assigned to the user connection by the server.
The number of jobs currently running on behalf of the user.
The total number of jobs requested by the user.
The label assigned to the connection by the requesting user.
List the server version stamp.
The interactive commands are useful in terms of tuning some global
variable values. For example, one could set
and control the number of jobs executed using the
coshell> a local,peruser=10,perserver=40
The interactive commands may be used as options for non-interactive
produces a long shell status listing and
closes the shell connection to the host
The following environment variables must be set if
is installed in a non-standard directory (not
root=<coshell-installation-root-directory>
is dynamically linked, the
environment variable needs to
export LD_LIBRARY_PATH=$
root/lib:$LD_LIBRARY_PATH
The following two commands are used to generate the local
network host information which is shared among all the
users and only needs to be generated once unless this information needs
If you run into permission problems, contact your system administrator.
command is run first to generate information on servers for the network.
Based on this information,
is run to generate the local host attribute file. By default,
command is not stored in the default path, you need to pass its path
command using the -f option.
You may also modify the generated files to meet your needs.
A sample local host attribute file follows:
local pool=8 bias=4 busy=1m
server type=sun4 rating=20
cruncher type=mips rating=30 cpu=20
station type=sun3 rating=6 idle=15m
token type=3b rating=0.1 idle=15m
entry sets the processor pool size to 8, the local host bias
to 4, and the busy host grace period to 1 minute.
Compute servers that are available to all users usually have no
attribute whereas personal workstations are given at least
out of courtesy to the workstation owner.
The processor pool size is taken from the local host attribute file.
The following instruct programs using
for command execution and sets the command execution concurrency level to 8.
provides a convenient interface for common coshell actions:
# start coshell, export COSHELL,NPROC, and set window title
\fIcoshell (AT&T Bell Laboratories) 10/11/93\fP [\fIfirst time only\fP]
# run hostname on best host
# interact with server ...
connect stream file is created in the
do not update the times on the connect stream file when it is accessed
automatically remove stale files from
event when the connect stream file is removed
do not handle mounted streams or sockets.
In any of these cases, the environment variable
needs to be set to another file system where
all the users have read and write permissions. For example:
export CS_MOUNT_LOCAL=<coshell-installation-root-directory>/tmp
On some systems the server may not detect that its connect stream
resulting in erroneous `server not running' errors.
To handle this situation the server checks and recreates the connect
stream file on receipt of a
NFS cache inconsistencies may arise for files generated via NFS on remote hosts
but serviced via the native file system on the local host.
from a diskless host avoids the problem.
Host load average and logged in user idle times are used
to schedule hosts and jobs.
Some terminal lock programs,
e.g.,
inflate the load average, usually doing complex graphics operations
on displays that have long since been blanked out by an independent
A simple lock program that blocks on a read request may open up idle cycles
Host attribute expression,
Non-numeric valued attributes may appear as the first operand of
where the second operand must be a \fB"..."\fP or \fB'...'\fP string
that is compared with the attribute value.
operators the second operand is taken to be a
For example, given the host definitions:
coot type=sun4 mem=8m rating=11.0 cad
dodo type=sun3 mem=4m rating=2.0
loon type=mips mem=16m rating=20.0
.L "(type=='sun*'&&mem>6m)"
matches the type of the host running the
A colon separated list of environment variables to export to each job.
This is to support the rare cases where some environment variables
For example, some commands use environment variables rather
than arguments or options to pass input data.
for the network shell service
Set to a different value for each shell command. It is used for
temporary file names. (see Engine Variables in
This variable may be referenced in
Set within each action to the name of the host executing
Set within each action to the name of the host executing the action.
This variable may be referenced in
Set within each action to the type
(from the local coshell host attribute file)
of the host executing the action.
This variable may be referenced in
Default command concurrency level
local network host attributes
3d(1), ksh(1), nmake(1), rsh(1), ss(1), coshell(3), cs(3)