tclark@honir.cs.cornell.edu (Timothy Clark) (01/18/91)
.TH RESERVE 1 "14 December 1990" RESERVE "ISIS COMMANDS"
.SH NAME
reserve, net_exec, net_kill, net_stat, unreserve \- ISIS Network Manager C-shell interface
.SH SYNOPSIS
.B reserve [isis_portnumber] """name={specifications}"""
.br
.B net_exec [isis_portnumber] """name={specifications}"""
.br
.B net_kill [isis_portnumber] [-SIGxxxx] <reservation_name>
.br
.B net_stat [isis_portnumber]
.br
.B unreserve [isis_portnumber] <reservation_name>
.br
.SH DESCRIPTION
The
.IR reserve ,
.IR unreserve ,
.IR net_kill ,
.IR net_stat ,
and
.I net_exec
commands serve as a C-shell command interface to the ISIS Network
Manager program,
.IR nmgr (1).
When invoked, these commands
format their arguments into an ISIS message, which is
sent to the nmgr for execution.
.I reserve
is used to locate and reserve cpu cycles on lightly loaded
network machines which have been registered with the nmgr.
The program prints the names of the
selected machines. A machine is available if it
is running the nmgr remote stub program,
.IR netclient (1),
and satisfies the remote idleness criteria.
The
.I reserve
command includes a number of machine selection criteria that
can be used to obtain a very
flexible and powerful scheduling service; full details
of this are given in
.IR nmgr.rc(5) ,
and a summary appears below.
The
.I net_exec
command is identical to
.I reserve ,
but it executes a specified binary on each
selected cpu instead of merely returning the machine names.
The
.I net_kill
command can be used to send a signal to the remote programs
started using a
.I net_exec
or
.I reserve
command.
.I net_kill
command takes as an argument
the "name" parameter of a previous reservation,
as discussed below.
The signal to send may be specified; if not, SIGKILL will be used
by default.
The
.I net_stat
command can be used to start up an X-windows display for monitoring
the status of the nmgr. Presently,
.I net_stat
uses a scrollable text widget to display the nmgr's netclients
and services. This interface will be extended to allow the selection
of a machine name for a "ps-like" display of nmgr processes on the
specified netclient.
The
.I unreserve
command releases the resources reserved by a previous
.I reserve
command.
.I unreserve
is optional; if not used, reservations last for some period of time
and then are cancelled automatically.
.I unreserve
command takes as an argument
the "name" parameter of a previous reservation,
as discussed below.
The command explicitly clears the reservation for the
machine(s) allocated using the corresponding reserve request.
All three commands
accept an optional
.TP
isis_portnumber.
This provides the correct port number for the isis_init
call, in order to connect with ISIS. If not specified,
.I reserve
will use the appropriate default (if ISISPORT is specified
in the user's environment variable, it uses this; otherwise
it fetches the value to use from the system /etc/services file).
An error message is printed if it is impossible to connect to ISIS using
this port number.
The
.I reserve
and
.I net_exec
commands accept an additional
command consisting of a formatted string giving
a \fIname\fR and \fIselection criteria\fR for
picking the machine(s) to be reserved. The current format is not
very forgiving, and therefore must be followed closely in order
to get the desired results.
.SH "EXAMPLE USAGE"
.PP
Before we discuss the syntax of the reserve command
string and selection criteria, it may be helpful to look at an example:
Example\ 1.
.br
\ \ \ % reserve\ [portnumber]\ "res_01={mtype=sparc,n=3,mem=12,
.br
mounts={/usr/fsys/isis},interval=2,immediate=1,load=2}"
This command makes a reservation identified by the "name"
.IR res\_01 .
A globally unique name is provided by prepending the user name to
each reservation name. If the name is omitted, a unique name is
automatically generated by the system.
The above command will cause
reserve to allocate 3 machines,
of type sparc, all of which have a file system
mount point called /usr/fsys/isis in the mounted file system table,
and with physical memory greater than 10 MB.
It tells the network manager that
the command will impose a load of about 2 MIPS for an interval of 2 hours.
The selection criteria uses a format and a set of attributes
from the network manager command language, fully defined in
.I nmgr.rc(5).
It should be noted that although the order of the
attributes is arbitrary, the order shown here is the
standard method, i.e. by order of importance.
The
.I reserve
command would typically be
used in combination with a shell program, as in the example
below, which causes a csh variable to iterate over the
names of the selected cpus. The loop shown
starts a command called rxterm on each selected machine.
#!bin/csh
.br
foreach i (`reserve "res_01={mtype=sparc,n=3,mem>10,
.br
immediate=1,interval=0.1}"`)
.br
rxterm $i
.br
end
.PP
Example 2.
% unreserve res_01
This command will clear the reserved flag and the imposed load from the
machines reserved under the reservation
.IR res_01 .
Example\ 3.
.br
\ \ \ % net_exec\ "{binary={sparc=/usr/u/isis/tcisis/test},
.br
n=3,mem>10,immediate=1,interval=0.1}"
This command is similar to Example 1, except that it allows the
system to pick the reservation name, and instead of returning the
names of the three selected cpus,
.I net_exec
will automatically execute the
specified binary (/usr/u/isis/tcisis/test) on each cpu. This form has
several extended specification options, described below.
This particular command is risky in that it assumes that the
.I netclient
stub will actually be able to find the binary /usr/u/isis/tcisis/test
on all possible sparc systems, and that the binary can be run on
any machine with a sparc processor.
A safer way to perform the net_exec would be to specify the
NFS mount points needed to be able to get to the binary (if
this is an issue), or to actually copy the binary to the remote
site using the file copy out ability of the manager.
As for the use of "sparc", the major point here is that as
a user of the network manager, one needs to be aware of
the names by which machine types are known (which would normally
include sparc1, sparc1+, sparc2, etc. -- as well as the generic "sparc")
and to use the right one.
The basic format of the argument to
.I reserve
and
.I net_exec
is this "[name=]{selection_criteria}"
The basic specification criteria used in both the
.I reserve
and
.I net_exec
commands are as follows:
.TP
name.
is the name of the reservation you are registering.
The name may be omitted, but the curly braces around the selection criteria
are still required.
Used to unreserve a previous reservation.
.TP
binary={sparc=/usr/u/isis/sun4/test,mips=/usr/u/isis/mips/test}
This is used in the
.I net_exec
command to specify a list of processor types for which binaries
are available, and the absolute pathname for the corresponding binaries.
.TP
mtype={sparc,mips}
This form may only be used in the
.I reserve
command, and lists the cpu type or types that may be used to
satisfy the reservation.
You can list as many types
of processors as you wish, using the same format and separating entries
with a comma.
Processor types unknown to the Net Manager are ignored.
.TP
n=3
This option specifies the number of remote machines you wish to reserve.
.TP
mounts={filesys1,....}
This option allows you to specify a list of
filesystems that must be mounted on
a remote machine in order for it to meet the selection criteria.
.TP
mem>10
This option allows you to specify a minimum amount of physical memory
which must be present on a remote machine in order for it to meet the
selection criteria.
.TP
immediate=1
The immediate option is a boolean which specifies return immediately from
the request (TRUE=1) whether or not the reservation could be satisfied; or
do not return immediately (FALSE=0) if the request could not be satisfied,
but retry 5 times at 30 second intervals to meet the request.
.TP
interval=2
This option specifies the interval, in hours or fractions of hours,
to "hold" the reservation. When this interval expires, the reservation
is automatically released. (This means the reserved flag and the imposed
load are cleared from all the machines under the reservation name).
By default, a reservation is held for one hour.
.TP
load=1
This option specifies the simulated load to impose upon a reserved cpu, in
MIPS. Since the cpu selection algorithm examines a cpu's load, imposing a
high load will discourage the Network Manager from selecting the same cpu
for multiple reservations. NOTE: this load is not really imposed on the cpu,
but is only used to make an entry in the
the Network Managers database record for that cpu.
.PP
.SH EXTENDED NET_EXEC OPTIONS
.br
copyin=/usr/u/isis/tcisis/test.c
.TP
copyout={results.1,results.2}
The copyin option allows you to specify any necessary files which
need to be copied to the remote machines (i.e. for use by your application),
while the copyout option allows for the copying back to your host of any
output files (i.e. output results from your application). *NOTE: Presently
these options are implemented through the Network Manager, and therefore,
any copyin files (absolute pathnames) must be visible by the nmgr, and the
copyout files are copied to the directory in which the nmgr program is running.
This will be re-implemented in the future to remove these restrictions. Also
to avoid multiple copyout files overwriting each other, each copyout file
name is appended with ".<remote_host_name>", i.e. results.honir. Another
important point: the copyin and execution related to the specified binary
will take place in the
.I /tmp/nmgr
directory by default. This can be overridden in two ways: by specifying
the -D<exec_dir> option when starting the Remote Stub program, see
.IR netclient ,
or by using the
.I exec_dir
option described below.
.TP
exec_dir=/usr/u/my_name/home
This option allows you to specify where a particular service will execute
and copy files to/from.
.TP
leavefiles
A keyword used in conjunction with copyin/copyout. If you specify this
keyword, then the files copied in and produced will not be garbage collected,
but will be left for possible future use.
.TP
isis
The keyword
.I isis
is used to alert the Network Manager that the binary to be run is an ISIS
application, since this information results in slightly different treatment
by the nmgr program.
.TP
args={1683,1682}
Used to pass arguments to the binary to be executed.
.TP
env={"DISPLAY=honir:0","ISIS_MOTHER=honir"}
Used to establish environment variables for the binary to be executed,
IMPORTANT \- the quotes around the definition are mandatory here.
The problem is that '=' has a special meaning to the network manager,
and hence the above will not parse correctly unless the network
manager realizes that DISPLAY=honir:0 should be treated as a single string.
.TP
user=name.
Specifies a user account to run under. See nmgr.rc(5) before
using this option.
.TP
password=string.
Specifies a password for the user's account.
.TP
auto.
This keyword is used ONLY within nmgr.rc. It should never be used from
.I reserve
or
.I net_exec.
.TP
keyword.
Other keywords can be defined by the user, i.e. "mathlab" to
denote machines licensed to run a package called mathlab, etc.
See nmgr.rc for details.
Keywords can also have numeric values, in which case
comparisons are permitted, such as in mem>10.
.SH "SEE ALSO"
nmgr(1), netclient(1), nmgr_command(3), nmgr.rc(5), nmgr.sites(5), netclient.rc(5)tclark@honir.cs.cornell.edu (Timothy Clark) (01/18/91)
.TH NMGR 1 "14 December 1990" NMGR "ISIS COMMANDS" .SH NAME nmgr \- ISIS Network Manager Program. .SH SYNOPSIS .B nmgr [isis_portnumber] .SH DESCRIPTION The .I nmgr program is an ISIS server-based application which manages idle or lightly-loaded machines on the network. The application actually consists of three parts: the .I nmgr server application; the remote stub application, .IR netclient (1); and the user interface, .IR reserve (1). The .I nmgr server program manages a database of "registered" machines and services. Remote machines are registered by running the remote stub program, .IR netclient , which connects to the nmgr when the remote machine is available to run services (see .I netclient for details). Once connected (registered), the nmgr is free to send requests for remote execution to that machine. Requests for resources or services are generated via the user interface commands, .IR reserve and .IR net_exec . .PP As for most other ISIS utilities, the ISIS portnumber to use may be specified as an option; if not specified, the port number will be determined by first checking for the environment variable ISISPORT and, if that is not specified, by a lookup in the /etc/services file. .PP When the nmgr is run, it starts by reading an initialization file, .IR nmgr.sites (5), which contains the udp port number for the nmgr to use in it's communication with remote stubs. Lines in this file have the format hostname port-no where the hostname is normally the short-name for the host (the one returned by the gethostname(3) system call). The manager then reads in a second file, .IR nmgr.rc (5), which it uses to initialize an in-core database of machine and service types. .IR nmgr.rc is a command script that can be changed by the user to customize the network resource manager to the types of equipment and services that commonly run in your environment. The notion of a service is relevant primarily to ISIS programmers, and corresponds loosely to an ISIS process group. In an environment where a set of fault-tolerant services are needed (either at all times, or on demand), the network manager can be programmed to know how to pick machines on which to run server instances and when to do so. Users working through the UNIX commands .IR reserve(1) and .IR net_exec(1) would normally NOT be concerned with ISIS-based applications. From the perspective of these users, the nmgr is primarily a machine reservation service, scheduling a set of users onto a set of machines in a way that balances load as fairly as possible, and later providing interfaces for monitoring and (if necessary) stopping remote programs that exhibit undesired behaviors. A powerful feature of the network manager is that the attribute sets used to select processors are arbitrarily extensible. For example, an installation running a package called "mathlab" but only has licenses for certain machines might use this attribute as a machine selection criteria when running programs that depend on mathlab features. Even though the network manager doesn't have any built-in notion of mathlab or how its licenses work, the utility can easily be configured \fIby the user\fR to keep track of the machines which have this license and to assign these programs only to suitable machines. Similarly, new resource types and (for ISIS users) services can be defined dynamically, through the .IR netclient.rc file and .IR nmgr.rc file. The format used in these files is documented in nmgr.rc(5). .PP The nmgr program is normally replicated on several independent machines for fault\-tolerance. In such cases, work is shared among the machines in a uniform way. Any nmgr failures are completely masked from users, provided of course that at least one copy survives. .SH "SEE ALSO" netclient(1), reserve(1), nmgr_command(3), nmgr.rc(5), nmgr.sites(5)