arrayd.conf(4) arrayd.conf(4)
arrayd.conf, arrayd.auth - array services configuration files
/usr/lib/array/arrayd.conf
/usr/lib/array/arrayd.auth
The arrayd.conf and arrayd.auth files are used to describe the
configuration of one or more arrays to the array services daemon. The
default configuration files are "/usr/lib/array/arrayd.conf" and
"/usr/lib/array/arrayd.auth", although the system administrator 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 configuration
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
information 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
configuration 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
services will need to customize the configuration file to describe their
local arrangement.
GENERAL SYNTAX [Toc] [Back]
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, command definitions, local options, and authentication
information. A typical entry may consist of several subentries; by
convention, each should be on a separate line. Similarly, some
subentries may have options, which probably ought to be on separate lines
as well. Leading whitespace is ignored, so subentries and options can
(and should) be indented for improved readability. The entries in a
configuration file and the subentries within an individual entry need not
be in any particular order.
Page 1
arrayd.conf(4) arrayd.conf(4)
ARGUMENTS [Toc] [Back]
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 letters, the characters "-" and
"_", and numeric digits (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 "substitution
variable" and will be replaced with some other value. Recognized
substitution variables include:
%1, %2, ..., %9
These represent the first nine arguments specified for an
array command. For example, if a user invokes an array
command with "array killjob 1354 token", 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.
%ALLARGS
This will be replaced with all of the arguments that were
specified for an array 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.
%ARRAY 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
separate arrays.
Page 2
arrayd.conf(4) arrayd.conf(4)
%ASH This will be replaced with the array session handle of
the program that invoked the current array command. It
will be in hex and will be preceded with the string "0x".
%GROUP This will be replaced with the name corresponding to the
effective group ID of the process that invoked the
current array command.
%LOCAL 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.
%ORIGIN 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 "localhost". This is often
not the same as the client's machine name since it will
typically include the network name as well (e.g.
"machine.domain.com", not just "machine").
%OUTFILE
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 command. 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 needs to
know which machine a specific file came from, the
original array command should include that data in its
output. When used with subentries that take multiple
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 argument, only
the first output file pathname will actually be
substituted.
%PROJECT
This will be replaced with the name corresponding to the
project ID of the process that invoked the current array
command.
%REALGROUP
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 effective group IDs are the same,
then "<same>" will be substituted instead.
Page 3
arrayd.conf(4) arrayd.conf(4)
%REALUSER
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 effective user IDs are the same, then
"<same>" will be substituted instead.
%USER This will be replaced with the name corresponding 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 variable 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 substitution function can generally be
anything that is valid as the argument of an entry or subentry,
except for another substitution function. Recognized
substitution functions include:
%ARG(number<b>)
This will be replaced with the command argument specified by
number, which obviously should be a numeric value. If the
argument does not exist, a warning is generated and an empty
string is substituted.
%OPTARG(number<b>)
This is similar to %ARG(...) except that no warning is
generated if the specified argument does not exist. This is
useful for specifying optional arguments.
%PID(ash<b>)
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 substitution 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.
Page 4
arrayd.conf(4) arrayd.conf(4)
numeric arguments
A numeric argument is an argument that can be resolved to a
numeric value when the array services 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 [Toc] [Back]
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:
ARRAY array-name
ARRAY_ATTRIBUTE name<b>=value
ARRAY_ATTRIBUTE litarg<b>...
IDENT number
SEQFILE pathname
MACHINE machine-name-1
machine options
...
MACHINE machine-name-2
...
Keywords such as ARRAY, MACHINE and IDENT may be in either upper or lower
case; upper case is used here to distinguish 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 internal use, so please do not use these words for array
name. arrayd 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 ARRAY_ATTRIBUTE subentry 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
array configuration information (for example, using the aslistarrays(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 ARRAY_ATTRIBUTE 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 converted to a single space) will be appended to
form a single attribute. Such an attribute could be used along with the
asgetattr(3x) function in a manner similar to environment 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.
Page 5
arrayd.conf(4) arrayd.conf(4)
The SEQFILE 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 LOCAL DIR (see below) and has a
name formed by appending the array name to the string ".seqfile.".
The IDENT 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.
Each MACHINE subentry specifies a single machine that is a member of the
array. Each ARRAY entry must have at least one MACHINE 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 MACHINE subentry may have zero or more options. These include:
MACHINE_ATTRIBUTE litarg<b>... or name<b>=value
The MACHINE_ATTRIBUTE option is similar to the ARRAY_ATTRIBUTE
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 information (for example, using
the aslistmachines(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 MACHINE_ATTRIBUTE option may be specified
more than once, and has the same syntax as ARRAY_ATTRIBUTE.
[SERVER] HOSTNAME string
to specify the full hostname or IP address of the machine. The
value should be enclosed in double quotes. If a HOSTNAME is not
specified, the machine name will be used. The string SERVER is
optional.
SERVER IDENT number
to specify the numeric identifier of the array services daemon on
that machine. This value may be used for generating global array
session handles or uniquely identifying the machine. If a SERVER
IDENT is specified for a machine, it should match the LOCAL IDENT
that is specified in that machine's local array services
configuration file. Note that unlike the HOSTNAME and PORT
options, the string SERVER that comes before IDENT is required.
[SERVER] PORT 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 SERVER is optional.
Page 6
arrayd.conf(4) arrayd.conf(4)
COMMAND DEFINITIONS. [Toc] [Back]
A command entry defines the actual program that is invoked by the array
services daemon when it receives an array command. Its format is similar
to an array entry, and looks like this:
COMMAND cmd-name
INVOKE any-args<b>...
MERGE any-args<b>...
GROUP any-arg
PROJECT any-arg
USER any-arg
OPTIONS litarg<b>...
cmd-name specifies the actual command name. This is what the user would
use when invoking the command with array(1).
The INVOKE 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 INVOKE subentry. Groups of arguments that are not
separated 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 INVOKE subentry for the command "foo" were:
INVOKE /usr/bin/test%1 %2"this is a test" %3
the argument list for the program to be executed would consist of:
argv[0] = "/usr/bin/testa"
argv[1] = "bthis is a test"
argv[2] = "c"
Note that the first value in the argument list also specifies the actual
pathname of the program to be executed ("/usr/bin/testa" in this case).
The array services daemon does /f2not/f1 have a search path, so this must
specify 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 MERGE 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 command
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 variable, this could be a convenient way to
consolidate or summarize the results of the array command. The merge
command is executed in the same was as a normal INVOKE 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.
Page 7
arrayd.conf(4) arrayd.conf(4)
The GROUP, PROJECT and USER 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 GROUP and USER 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 SETRGID and SETRUID command options
(see below).
The OPTIONS 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.
LOCAL
Execute the command on the same machine as the array services daemon
only, even if a target array was specified explicitly or by default.
NEWSESSION
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.
QUIET
Discard any output generated by the command. If a merge command has
been specified, QUIET 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.
SETRGID
Run the command with both its real and effective group IDs set to
the value specified by the GROUP subentry. Normally, only the
effective group ID is taken from the GROUP subentry, while the real
group ID is taken from the process that invoked the command.
SETRUID
Run the command with both its real and effective user IDs set to the
value specified by the USER subentry. Normally, only the effective
user ID is taken from the USER subentry, while the real user ID is
taken from the process that invoked the command.
WAIT Wait for each invoked program to complete execution before returning
control to the process that requested the command. This is the
default behavior. If NOWAIT is specified then control is returned
to the requestor immediately after starting the invoked programs.
NOWAIT implies QUIET and causes any merge command to be ignored.
Page 8
arrayd.conf(4) arrayd.conf(4)
LOCAL OPTIONS. [Toc] [Back]
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:
LOCAL
DIR literal-arg
DESTINATION ARRAY literal-arg
GROUP literal-arg
HOSTNAME literal-arg
IDENT num-arg
PORT num-arg
PROJECT literal-arg
USER literal-arg
OPTIONS literal-arg<b>...
All of the subentries in a local entry are optional.
The DIR subentry specifies an absolute pathname for the array services
daemon's working directory. The default is "/usr/lib/array".
The DESTINATION ARRAY subentry specifies the default target array for
array commands when one has not been specified 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 GROUP, PROJECT and USER subentries specify the names of the group,
project and user under which an array command should be run. A GROUP,
PROJECT or USER specified in a particular command entry will always
override these values. These default to the group, project and user that
is running the array services daemon.
The HOSTNAME subentry specifies the value that is returned 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 hostname of the local machine.
The IDENT 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 specified, one will be
generated from the hostid of the local machine. The value must be in the
range of 1-32767.
The PORT subentry specifies the network port on which this array services
daemon will listen for requests. The default is the standard sgi-arrayd
service, 5434.
Page 9
arrayd.conf(4) arrayd.conf(4)
The OPTIONS 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 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.
SETMACHID
Some versions of IRIX permit setting a system "machine identifier",
which is used by the kernel for generating global array session
handles. If the current system has this facility and SETMACHID is
specified, arrayd will set the machine ID to the value specified by
a LOCAL IDENT statement in the configuration file or on the command
line with the -m option.
CHKLOCALID
Instructs arrayd to make certain "paranoid" authentication checks
when accepting a connection from a local user, such as ensuring that
the user is formally 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 "standard" administrative files (e.g. /etc/group
or its corresponding NIS map).
SVR4SIGS
Instructs arrayd to use SVR4 semantics for the SIGXCPU 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
specifically alters the behavior for those signals with a system
call such as signal(2) or sigset(2). This is different from the
default behavior for processes 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. [Toc] [Back]
An authentication information entry is used to describe the type of
authentication that should be done when passing 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 provided in the future. Its entry looks like this:
AUTHENTICATION SIMPLE
HOSTNAME literal-arg <b>KEY num-arg
HOSTNAME literal-arg <b>KEY 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 necessarily the same as the "machine name"
Page 10
arrayd.conf(4) arrayd.conf(4)
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 authentication 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 calculated for each
message using the authentication key associated 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 messages, since a forger (presumably) would not have access to the
authentication key that is required to calculate a 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 authentication key for a given
machine, the administrator must take special care to ensure that the
authentication information in each machine's configuration files are
consistent 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 authentication is to simply disallow any requests from remote
systems. This can be done by specifying an authentication information
entry of the form:
AUTHENTICATION NOREMOTE
This is the default setting when the array services are first installed.
Note that for the purposes of array services, 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 prevent outgoing array services requests
originating on the local machine from being sent to remote machines.
Page 11
arrayd.conf(4) arrayd.conf(4)
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 disable authentication entirely by using
an authentication information entry of the form:
AUTHENTICATION NONE
However, unless the environment is reasonably secure, this should be
changed the one of the other authentication settings as soon as possible.
arrayd(1M), asgetattr(3X), aslistarrays(3X), aslistmachines(3X),
array_services(5).
PPPPaaaaggggeeee 11112222 [ Back ]
|
