array - execute an array command
SYNOPSIS
array [options...] command [args...]
DESCRIPTION
The array command is used to execute the array command
specifed by "command args..." on one or more machines in
an array and display the resulting output on stdout. An
array command is not necessarily the same thing as a UNIX
command. It is passed to arrayd(1M), the array services
daemon, which is responsible for translating it to an
actual UNIX command and executing it on the machines that
make up the array. Several array commands are available
by default; these are described below.
array takes several options. The first token on the com
mand line that does not constitute a valid option is
assumed to mark the beginning of the array command. None
of the remaining tokens will be examined by array, other
than to pass them along as arguments to the array command
itself.
The valid options include:
--aa arrayname or --aarrrraayy arrayname
Specifies the name of the array to which this command
should be directed. If not specified, the array ser
vices daemon's default destination will be used.
--DD or --ddiirreecctt
When used with --ss, indicates that the request should
be sent directly to the specified server, rather than
forwarded to that server by the local array services
daemon. This will fail on systems that use array
services authentication unless the -Kl and -Kr
options are also specified. --DD is the default behav
ior under normal circumstances (but see the descrip
tion of the AARRRRAAYYDD_FFOORRWWAARRDD variable, below).
--FF or --ffoorrwwaarrdd
When used with --ss, indicates that the request should
be forwarded to the specified server via the local
array services daemon, rather than sent directly to
it. --FF will become the default behavior if the value
of the AARRRRAAYYDD_FFOORRWWAARRDD environment variable begins
with the letter "Y" (as in "yes"; it may be in either
upper or lower case).
--gg or --gglloobbaall
Global command: indicates that the array command
should be run in a new global array session, that is,
global array session handle.
--KKll key or --llooccaallkkeeyy key
Use key for the local authentication key when commu
nicating directly with a remote array services dae
mon. key is an unsigned 64-bit value. The default
local key is obtained from the environment variable
AARRRRAAYYDD_LLOOCCAALLKKEEYY; if that does not exist, no key is
used. The actual role played by key depends on the
authentication method used by array services in a
particular configuration. In general, it is not used
when communicating with an array services daemon on
the local machine.
--KKrr key or --rreemmootteekkeeyy key
Use key for the remote authentication key when commu
nicating directly with a remote array services dae
mon. key is an unsigned 64-bit value. The default
remote key is obtained from the environment variable
AARRRRAAYYDD_RREEMMOOTTEEKKEEYY; if that does not exist, no key is
used. The actual role played by key depends on the
authentication method used by array services in a
particular configuration. In general, it is not used
when communicating with an array services daemon on
the local machine.
--ll or --llooccaall
Local request: indicates that the request should not
be propagated to other machines. This could be use
ful for testing a new array command.
--pp port or --ppoorrtt port
Specifies the port address of the array services dae
mon. Defaults to the value of the "ARRAYD_PORT"
environment variable if present, or the standard port
number of the "sgi-arrayd" service otherwise.
--qq or --qquuiieett
Quiet: discard the output of the array command rather
than sending it to stdout.
--ss server or --sseerrvveerr server
Specifies the hostname or IP address of the array
services daemon. Defaults to the value of the
"ARRAYD" environment variable if present, or "local
host" otherwise.
--tt value or --ttiimmeeoouutt value
Specifies the timeout value (in seconds) used for
waiting on a single array services request. Most
commands involve one array services daemon requesting
services from another array services daemon, so it
will typically take two times this many seconds
default is 15 seconds (so most array commands will
timeout if no response is received in 30 seconds).
--vv Verbose messages: display additional progress mes
sages. Repeated occurrences (either "-v -v ..." or
"-vv...") increases the verbosity, although this is
generally only useful for debugging arrayd itself.
USING A REMOTE ARRAY SERVICES DAEMON
Ordinarily, the array command uses the array services dae
mon running on the local machine for processing requests.
However, there are some circumstances where it is useful
to contact an array services daemon on another machine
instead, such as when a smaller machine, perhaps running
IRIX 5.3 and therefore not capable of running an array
services daemon, is used as a console interface for an
array. There are two ways to accomplish this. If it is
necessary to use a remote array services daemon only
infrequently, the -s server option can be specified on the
command line to indicate the hostname of the server that
should be contacted. However, if the remote daemon will
be used frequently or exclusively (such as in the case
where the local machine is being used as a console inter
face to an array, and not as a member of the array itself)
then an easier approach is to set the environment variable
ARRAYD to the hostname of the remote server. If the -s
option is not specified, then the array command will use
the value of that variable (if it is set) rather than try
ing to contact an array services daemon on the local
machine.
DEFAULT ARRAY COMMANDS
The default array services configuration includes several
simple array commands:
array kill ASH
Sends a SIGTERM signal to all of the processes in the
array that belong to the array session specified by
the handle ASH. By default, SIGTERM will kill most
processes, though shell programs are often a notable
exception.
array ps
Shows the array session handle, machine name, process
ID, owner, run time and command line for every pro
cess in the array that has a non-zero array session
handle.
array resume ASH
Resumes all processes in the array that belong to the
array session specified by the handle ASH by sending
them the SIGCONT signal. Presumably this array
pend.
array signal sig ASH
Sends signal sig to all processes in the array that
belong to the array session specified by the handle
ASH. This is simply a more general version of the
kill/suspend/resume commands.
array suspend ASH
Suspends all processes in the array that belong to
the array session specified by the handle ASH by
sending them the SIGTSTP signal.
array uptime
Equivalent to running the uptime(1) command on each
machine in the array.
array who
Shows the login name, current machine, origin machine
and current command for every logged-in user of the
array.
Note that the available array commands are controlled by the sys
tem administrator, so some or all of these commands may not be
present. Other array commands may also be available. Consult
your system adminstrator for more information.
NOTES
The array services daemon (arrayd(1M)) must be running on
all machines that are to execute an array command. It
does not necessarily have to be running on the machine
that executes array if an alternate server was specified
in some way.
SEE ALSO
arrayd(1M), arrayd.conf(4).
Man(1) output converted with
man2html