arrayd.conf, arrayd.auth - array services configuration
files
SYNOPSIS
/usr/lib/array/arrayd.conf
/usr/lib/array/arrayd.auth
DESCRIPTION
The arrayd.conf and arrayd.auth files are used to describe
the configuration of one or more arrays to the array ser
vices daemon. The default configuration files are
"/usr/lib/array/arrayd.conf" and
"/usr/lib/array/arrayd.auth", although the system adminis
trator can override this or specify additional files.
Every machine running an array services daemon (which
should be every machine that is part of an array) must
have its own configuration file or files. The configura
tion files contain information about which arrays are
known to the array services daemon and the machines in
each of them, the commands that can be executed by the
array services daemon, various local options, and informa
tion used for authenticating messages passed between array
services daemons on different machines.
The arrayd.conf file is typically readable by all users
while the arrayd.auth file is generally readable only by
root. Other than their initial access permissions upon
installation, there is no functional difference between
the two files; either may contain any sort of configura
tion information. However, because arrayd.auth is not
readable by most users it is most appropriate for secure
information such as authentication keys, while arrayd.conf
is intended to contain public information such as the
array and command definitions.
The initial configuration files that are installed with
array services are very minimal: they describe a single
array made up only of the local machine, several basic
"starter" commands (see array(1) for more information),
and no authentication. Every site installing array ser
vices will need to customize the configuration file to
describe their local arrangement.
GENERAL SYNTAX
The configuration file itself is made up of regular human-
readable ASCII text. Blank lines and comments (introduced
by a "#" character) are ignored. There are four types of
entries in the configuration file: array definitions, com
mand definitions, local options, and authentication infor
mation. A typical entry may consist of several suben
tries; by convention, each should be on a separate line.
Similarly, some subentries may have options, which proba
bly ought to be on separate lines as well. Leading
should) be indented for improved readability. The entries
in a configuration file and the subentries within an indi
vidual entry need not be in any particular order.
ARGUMENTS
Most of the various entries, subentries and options take
arguments. Arguments come in several varieties:
names These are simple identifiers, similar to variable
names. They can contain upper and lower case let
ters, the characters "-" and "_", and numeric dig
its (although the first character must not be a
digit).
numbers These are treated as signed 64-bit integers and
may be specified in hex, octal or decimal, with
hex values being preceded by "0x" and octal values
being preceded by "0".
environment variables
A name preceded by a "$" is presumed to refer to
an environment variable and will be substituted
accordingly.
strings Any arbitrary string of characters enclosed in
double quotes. Double quotes and backslashes can
be embedded within the string by preceding them
with a backslash. Newlines and tabs can be
included using "\n" and "\t", respectively. A
real newline may also be embedded by preceding it
with a backslash, thus allowing a string to span
several lines in a configuration file.
substitution variables
A name preceded by a "%" is referred to as a "sub
stitution variable" and will be replaced with some
other value. Recognized substitution variables
include:
%%11, %%22, ..., %%99
These represent the first nine arguments
specified for an array command. For exam
ple, if a user invokes an array command
with "aarrrraayy kkiilllljjoobb 11335544 ttookkeenn", then %1
would be replaced with "1354" (the first
argument to the command "killjob") and %2
would be replaced with "token". Arguments
that don't exist (%3 in this case, for
example) will be replaced with an empty
string.
%%AALLLLAARRGGSS
This will be replaced with all of the
command. When used with subentries that
take multiple arguments, each individual
command-line argument will be treated as
an individual argument in the subentry as
well. When used with subentries that take
only a single argument, only the first
command-line argument will actually be
substituted.
%%AARRRRAAYY This will be replaced with the name of the
array that is the target of the current
array command. This is primarily of use
when a machine belongs to two or more sep
arate arrays.
%%AASSHH This will be replaced with the array ses
sion handle of the program that invoked
the current array command. It will be in
hex and will be preceded with the string
"0x".
%%GGRROOUUPP This will be replaced with the name corre
sponding to the effective group ID of the
process that invoked the current array
command.
%%LLOOCCAALL This will be replaced with the name of the
local machine, as specified in a LOCAL
HOSTNAME entry. This could be useful if
several machines share a configuration
file containing commands.
%%OORRIIGGIINN This will be replaced with the primary
hostname of the network interface that
transmitted the request from the client
machine. If the client and server are the
same machine, then this will be "local
host". This is often not the same as the
client's machine name since it will typi
cally include the network name as well
(e.g. "machine.domain.com", not just
"machine").
%%OOUUTTFFIILLEE
This variable is valid only as part of a
MERGE command. This will be replaced with
a list of one or more temporary files.
Each file will contain the output from a
single machine of the related array com
mand. When the merge command is finished,
the temporary files will automatically be
removed. The files in the list are not in
any particular order; if the merge command
file came from, the original array command
should include that data in its output.
When used with subentries that take multi
ple arguments, each individual pathname
will be treated as an individual argument
in the subentry as well. When used with
subentries that take only a single argu
ment, only the first output file pathname
will actually be substituted.
%%PPRROOJJEECCTT
This will be replaced with the name corre
sponding to the project ID of the process
that invoked the current array command.
%%RREEAALLGGRROOUUPP
If the process that invoked the current
array command has different real and
effective group IDs, then this will be
replaced with the name corresponding to
the real group ID. If the real and effec
tive group IDs are the same, then "<same>"
will be substituted instead.
%%RREEAALLUUSSEERR
If the process that invoked the current
array command has different real and
effective user IDs, then this will be
replaced with the name corresponding to
the read user ID. If the real and effec
tive user IDs are the same, then "<same>"
will be substituted instead.
%%UUSSEERR This will be replaced with the name corre
sponding to the effective user ID of the
process that invoked the current array
command.
Note that the names of these substitution variables may be
in either upper or lower case. If an unrecognized vari
able name is specified, a warning will be issued and the
variable will be replaced with an empty string.
substitution functions
A substitution variable followed immediately by
one or more arguments enclosed in parentheses is a
"substitution function". The arguments of a sub
stitution function can generally be anything that
is valid as the argument of an entry or subentry,
except for another substitution function. Recog
nized substitution functions include:
This will be replaced with the command
argument specified by number, which obvi
ously should be a numeric value. If the
argument does not exist, a warning is gen
erated and an empty string is substituted.
%%OOPPTTAARRGG((number))
This is similar to %%AARRGG((...)) except that no
warning is generated if the specified argu
ment does not exist. This is useful for
specifying optional arguments.
%%PPIIDD((ash))
ash specifies an array session handle.
This will be replaced with a list of all
process IDs that belong to the specified
array session on the local machine. For
entries that take more than one argument,
each PID will be treated as a separate
argument (see %ALLARGS).
As with substitution variables, an unrecognized substitu
tion function will be replaced with an empty string and
will cause a warning to be generated.
literal arguments
A literal argument is any argument that can be
evaluated when the array services daemon is first
started. This includes names, strings, numbers,
and environment variables, but specifically does
NOT include substitution variables or functions.
numeric arguments
A numeric argument is an argument that can be
resolved to a numeric value when the array ser
vices daemon is first started. This includes
actual numbers, of course, as well as strings and
environment variables. An error will occur in
these latter cases if they cannot be converted to
proper numeric values.
ARRAY ENTRIES
As the name would imply, an array entry is a configuration
file entry that defines the machines and other details
that make up a particular array. The general format looks
like this:
AARRRRAAYY array-name
AARRRRAAYY_AATTTTRRIIBBUUTTEE name==value
AARRRRAAYY_AATTTTRRIIBBUUTTEE litarg......
IIDDEENNTT number
SSEEQQFFIILLEE pathname
machine options
......
MMAACCHHIINNEE machine-name-2
......
Keywords such as AARRRRAAYY, MMAACCHHIINNEE and IIDDEENNTT may be in either
upper or lower case; upper case is used here to distin
guish them from other fields. The various subentries do
not necessarily have to occur in any particular order.
However, they should not appear between options in a
MACHINE subentry.
array-name is the name that will be used to refer to the
array as a whole; it may be of any length. By default,
array name "me" is used to define the local host only.
The words "all" or "ALL" or "All" are reserved for inter
nal use, so please do not use these words for array name.
aarrrraayydd skips these words while reading the arrayd.conf
file. This is the name that would be used with the "-a"
option of the array(1) command.
The AARRRRAAYY_AATTTTRRIIBBUUTTEE subentry is used to specify one or
more arbitrary values that will be maintained in the con
figuration database but will otherwise be ignored by the
array services daemon. Programs that obtain array config
uration information (for example, using the aslistar
rays(3X) function) will be provided with a list of these
attributes. Thus, these could be useful for maintaining
miscellaneous configuration information that may be needed
by other programs. The AARRRRAAYY_AATTTTRRIIBBUUTTEE subentry may be
specified more than once. If the attribute starts with a
simple identifer followed by an equal sign, then the
remainder of the line (with multiple blanks and tabs con
verted to a single space) will be appended to form a sin
gle attribute. Such an attribute could be used along with
the asgetattr(3x) function in a manner similar to environ
ment variables. If the attribute is formed of any other
literal argument, then it is presumed to end as soon as
white space is encountered. In this case, multiple
attributes could be specified on a single line.
The SSEEQQFFIILLEE subentry specifies the pathname of a file used
to keep an array session sequence number for the array.
The default sequence file is located in the directory
specified by LLOOCCAALL DDIIRR (see below) and has a name formed
by appending the array name to the string ".seqfile.".
The IIDDEENNTT subentry specifies a numeric value that is used
when generating global array session handles for the
array. No other array should have the same IDENT value.
If an IDENT value is not specified, a random one will be
generated. The value should be in the range of 1-32767.
member of the array. Each AARRRRAAYY entry must have at least
one MMAACCHHIINNEE subentry. machine-name is the name that is
used to refer to this machine. Ordinarily this would be
the machine's hostname, though that is merely a convention
and not a requirement.
A MMAACCHHIINNEE subentry may have zero or more options. These
include:
MMAACCHHIINNEE_AATTTTRRIIBBUUTTEE litarg...... or name==value
The MMAACCHHIINNEE_AATTTTRRIIBBUUTTEE option is similar to the
AARRRRAAYY_AATTTTRRIIBBUUTTEE subentry in that it is used to
specify one or more arbitrary values that will be
maintained in the configuration database but will
otherwise be ignored by the array services daemon.
Programs that obtain machine configuration infor
mation (for example, using the aslistmachines(3X)
function) will be provided with a list of these
attributes. Thus, these could be useful for main
taining miscellaneous configuration information
that may be needed by other programs. The
MMAACCHHIINNEE_AATTTTRRIIBBUUTTEE option may be specified more
than once, and has the same syntax as
AARRRRAAYY_AATTTTRRIIBBUUTTEE.
[[SSEERRVVEERR]] HHOOSSTTNNAAMMEE string
to specify the full hostname or IP address of the
machine. The value should be enclosed in double
quotes. If a HHOOSSTTNNAAMMEE is not specified, the
machine name will be used. The string SSEERRVVEERR is
optional.
SSEERRVVEERR IIDDEENNTT number
to specify the numeric identifier of the array
services daemon on that machine. This value may
be used for generating global array session han
dles or uniquely identifying the machine. If a
SSEERRVVEERR IIDDEENNTT is specified for a machine, it should
match the LLOOCCAALL IIDDEENNTT that is specified in that
machine's local array services configuration file.
Note that unlike the HHOOSSTTNNAAMMEE and PPOORRTT options,
the string SSEERRVVEERR that comes before IIDDEENNTT is
required.
[[SSEERRVVEERR]] PPOORRTT number
to specify which port the array services daemon
for this machine is listening on. This would
override the default port number of 5434. The
string SSEERRVVEERR is optional.
COMMAND DEFINITIONS.
A command entry defines the actual program that is invoked
command. Its format is similar to an array entry, and
looks like this:
CCOOMMMMAANNDD cmd-name
IINNVVOOKKEE any-args......
MMEERRGGEE any-args......
GGRROOUUPP any-arg
PPRROOJJEECCTT any-arg
UUSSEERR any-arg
OOPPTTIIOONNSS litarg......
cmd-name specifies the actual command name. This is what
the user would use when invoking the command with
array(1).
The IINNVVOOKKEE subentry specifies the actual program to be
executed, plus any arguments that should be supplied to
it. Any number of arguments may be specified for the
IINNVVOOKKEE subentry. Groups of arguments that are not sepa
rated by white space will be concatenated to form single
values (white space embedded in a string is not considered
to be "white space" for these purposes). Each resulting
value will be passed to the program to be executed as a
single argument. Thus, if a user typed "array foo a b c",
and the IINNVVOOKKEE subentry for the command "foo" were:
IINNVVOOKKEE //uussrr//bbiinn//tteesstt%%11 %%22""tthhiiss iiss aa tteesstt"" %%33
the argument list for the program to be executed would
consist of:
aarrggvv[[00]] == ""//uussrr//bbiinn//tteessttaa""
aarrggvv[[11]] == ""bbtthhiiss iiss aa tteesstt""
aarrggvv[[22]] == ""cc""
Note that the first value in the argument list also speci
fies the actual pathname of the program to be executed
("/usr/bin/testa" in this case). The array services dae
mon does /f2not/f1 have a search path, so this must spec
ify either an absolute path to the file to be executed, or
a path relative to the array services daemon's current
directory (see the DIR local option).
The MMEERRGGEE subentry is used to specify a "merge command".
Ordinarily, when an array command is run on several
machines, the results and output from each machine are
returned as separate streams of data. However, if a merge
command is specified, it will be run after the array com
mand itself has been completed on all machines, and only
the results and output of the merge command will be
returned. When used with the %OUTFILES substitution vari
able, this could be a convenient way to consolidate or
summarize the results of the array command. The merge
command, except that it always runs on the same machine as
the array services daemon, even if that particular machine
is not a member of the array that the array command was
run on.
The GGRROOUUPP, PPRROOJJEECCTT and UUSSEERR subentries are all optional
and specify the name of the group, project and user that
the program should be run under. Each of these take a
single argument. To run with the ID's of the user that
invoked the array command, these could be specified as
%GROUP, %PROJECT and %USER, respectively. If these are
not specified for a particular command entry, they will
default first to the values set in the local options, or
if those are not present, to user and group "guest" and
project 0. By default, the GGRROOUUPP and UUSSEERR subentries only
affect the effective group and user IDs of the program;
the real group and user IDs will be the same as those of
the process that invoked the program. This behavior can
be changed using the SSEETTRRGGIIDD and SSEETTRRUUIIDD command options
(see below).
The OOPPTTIIOONNSS subentry is used to specify additional details
about how the command should be processed. It should be
followed by one or more arguments from the following list.
The arguments may be in either upper or lower case. They
may also be preceded by the string "NO" to negate their
effects.
LLOOCCAALL
Execute the command on the same machine as the array
services daemon only, even if a target array was
specified explicitly or by default.
NNEEWWSSEESSSSIIOONN
Execute the command in a new global array session.
Normally the command would be run in the same array
session as the process that invoked it.
QQUUIIEETT
Discard any output generated by the command. If a
merge command has been specified, QQUUIIEETT applies to
the merge command and not the invoke command. This
would allow a merge command to quietly act on the
output of the invoke commands.
SSEETTRRGGIIDD
Run the command with both its real and effective
group IDs set to the value specified by the GGRROOUUPP
subentry. Normally, only the effective group ID is
taken from the GGRROOUUPP subentry, while the real group
ID is taken from the process that invoked the com
mand.
Run the command with both its real and effective user
IDs set to the value specified by the UUSSEERR subentry.
Normally, only the effective user ID is taken from
the UUSSEERR subentry, while the real user ID is taken
from the process that invoked the command.
WWAAIITT Wait for each invoked program to complete execution
before returning control to the process that
requested the command. This is the default behavior.
If NNOOWWAAIITT is specified then control is returned to
the requestor immediately after starting the invoked
programs. NNOOWWAAIITT implies QQUUIIEETT and causes any merge
command to be ignored.
LOCAL OPTIONS.
A local options entry specifies options to be used by the
array services daemon itself. If more than one local
options entry is specified, settings in later entries will
silently override those in earlier entries. A local
options entry looks like this:
LLOOCCAALL
DDIIRR literal-arg
DDEESSTTIINNAATTIIOONN AARRRRAAYY literal-arg
GGRROOUUPP literal-arg
HHOOSSTTNNAAMMEE literal-arg
IIDDEENNTT num-arg
PPOORRTT num-arg
PPRROOJJEECCTT literal-arg
UUSSEERR literal-arg
OOPPTTIIOONNSS literal-arg......
All of the subentries in a local entry are optional.
The DDIIRR subentry specifies an absolute pathname for the
array services daemon's working directory. The default is
"/usr/lib/array".
The DDEESSTTIINNAATTIIOONN AARRRRAAYY subentry specifies the default tar
get array for array commands when one has not been speci
fied explicitly by the user. There is no default value
unless only one array is defined (in which case it becomes
the default); if a user omits the target array and there
is no default then an error will occur.
The GGRROOUUPP, PPRROOJJEECCTT and UUSSEERR subentries specify the names
of the group, project and user under which an array com
mand should be run. A GGRROOUUPP, PPRROOJJEECCTT or UUSSEERR specified in
a particular command entry will always override these val
ues. These default to the group, project and user that is
running the array services daemon.
by the "%LOCAL" substitution variable. The results of
array services commands initiated with ascommand(3X) will
also refer to this name. The default is the actual host
name of the local machine.
The IIDDEENNTT subentry specifies a numeric value that is
included in global array session handles generated by this
array services daemon. Some versions of IRIX may also
make use of this value to generate their own global array
session handles. No other array services daemon should
have the same IDENT value. If an IDENT value is not spec
ified, one will be generated from the hostid of the local
machine. The value must be in the range of 1-32767.
The PPOORRTT subentry specifies the network port on which this
array services daemon will listen for requests. The
default is the standard sgi-arrayd service, 5434.
The OOPPTTIIOONNSS subentry is used to specify additional details
about the operation of the array services daemon. It
should be followed by one or more arguments from the fol
lowing list. The arguments may be in either upper or
lower case. They may also be preceded by the string "NO"
to negate their effects.
SSEETTMMAACCHHIIDD
Some versions of IRIX permit setting a system
"machine identifier", which is used by the kernel for
generating global array session handles. If the cur
rent system has this facility and SSEETTMMAACCHHIIDD is speci
fied, arrayd will set the machine ID to the value
specified by a LOCAL IDENT statement in the configu
ration file or on the command line with the -m
option.
CCHHKKLLOOCCAALLIIDD
Instructs arrayd to make certain "paranoid" authenti
cation checks when accepting a connection from a
local user, such as ensuring that the user is for
mally authorized for their current group and project.
Note that these checks may fail on systems that have
mechanisms for changing the real group or project of
a user to a setting that is not in one of the "stan
dard" administrative files (e.g. /etc/group or its
corresponding NIS map).
SSVVRR44SSIIGGSS
Instructs arrayd to use SVR4 semantics for the SIGX
CPU and SIGXFSZ signals when starting a new process
to handle a remote execution request (such as those
issued by arshell(1)). In this mode, the new process
will ignore SIGXCPU and SIGXFSZ signals unless it
with a system call such as signal(2) or sigset(2).
This is different from the default behavior for pro
cesses started by arrayd to handle remote execution
requests, in which SIGXCPU and SIGXFSZ will cause the
process to abort with a core dump.
AUTHENTICATION INFORMATION.
An authentication information entry is used to describe
the type of authentication that should be done when pass
ing messages to and from another array services daemon.
Authentication information entries do not accumulate: if
more than one is encountered in the various configuration
files processed by an array services daemon, only the last
one will have any effect; all information from previous
entries will be discarded. There is currently only one
type of authentication provided, though more may be pro
vided in the future. Its entry looks like this:
AAUUTTHHEENNTTIICCAATTIIOONN SSIIMMPPLLEE
HHOOSSTTNNAAMMEE literal-arg KKEEYY num-arg
HHOOSSTTNNAAMMEE literal-arg KKEEYY num-arg
......
This entry contains one or more subentries consisting of
machine/key pairs. literal-arg is the network hostname of
a machine. Notice that the network hostname is not neces
sarily the same as the "machine name" used to identify a
machine in an array entry (see above). num-arg is a
64-bit unsigned integer that is to be used as the authen
tication key for all messages originating from that
machine. If a key of 0 is specified, authentication will
not be performed on messages originating from that
machine. Similarly, if a machine has no subentry at all,
no authentication will be performed on messages received
from it.
If a machine appears in more than one array entry, it
needs to have only one subentry in the authentication
information. Conversely, the machine in an authentication
information subentry does not need to appear in any array
entries.
With the SIMPLE scheme, a "digital signature" is calcu
lated for each message using the authentication key asso
ciated with the sending machine, then sent along with the
message. When an array services daemon receives a message
from another machine, it checks its private database for
the authentication key associated with the machine that
sent the message, recalculates the digital signature, and
ensures that it matches the one sent with the message.
This provides some basic protection against forged mes
sages, since a forger (presumably) would not have access
proper digital signature.
Because this approach depends on the secrecy of the
authentication keys, it is important to put this type of
authentication information entry in a configuration file
that is not accessible to general users (e.g. the
arrayd.auth file in the default installation). Because
both the sender and receiver need to have the same authen
tication key for a given machine, the administrator must
take special care to ensure that the authentication infor
mation in each machine's configuration files are consis
tent with each other.
There are some circumstances where array services may be
needed on an "array" of only one machine (for example,
systems that use the MPI message passing library). For
these systems, an alternative to using simple authentica
tion is to simply disallow any requests from remote sys
tems. This can be done by specifying an authentication
information entry of the form:
AAUUTTHHEENNTTIICCAATTIIOONN NNOORREEMMOOTTEE
This is the default setting when the array services are
first installed. Note that for the purposes of array ser
vices, any request to an IP address other than 127.0.0.1
is considered to be "remote". Therefore, the HOSTNAME
entry for the local machine in any array should be either
"127.0.0.1" or "localhost" if NOREMOTE is being used.
Also note that while this will block any incoming array
services requests from remote machines, it will not pre
vent outgoing array services requests originating on the
local machine from being sent to remote machines.
If an array is on a private network with trusted peers, or
perhaps is carefully hidden behind a good firewall,
authentication may be unnecessary. It is possible to dis
able authentication entirely by using an authentication
information entry of the form:
AAUUTTHHEENNTTIICCAATTIIOONN NNOONNEE
However, unless the environment is reasonably secure, this
should be changed the one of the other authentication set
tings as soon as possible.
SEE ALSO
arrayd(1M), asgetattr(3X), aslistarrays(3X), aslistma
chines(3X), array_services(5).
Man(1) output converted with
man2html