arrayd.conf(4) arrayd.conf(4) NAME 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 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 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. 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 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. %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. %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) 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) 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) 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. 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 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=value ARRAY_ATTRIBUTE litarg... 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. 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... or name=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. COMMAND DEFINITIONS 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... MERGE any-args... GROUP any-arg PROJECT any-arg USER any-arg OPTIONS litarg... 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. 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 "arraysvcs" 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. 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: 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... 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. 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 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 KEY num-arg HOSTNAME literal-arg 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" 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. 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. ROOT EXECUTION CONTROL A root execution control entry specifies whether Array Services will allow or prevent remote exec requests from executing as root on another host in the array. Use a root execution control entry of the form: ROOTEXECUTION NONE to prevent execution of a remote exec or arshell request as root on the target host. This setting helps to compartmentalize an array from a security standpoint. To allow appropriate root execution of remote exec requests, use a root execution control entry of the form: ROOTEXECUTION ALLOWED With this setting, root execution of remote exec requests is permitted only if the originating user is root, or if ~root/.rhost file is configured to allow a user on one system to run as root on a different system. By default, appropriately authenticated root execution of remote exec requests is allowed. SEE ALSO arrayd(1M), asgetattr(3X), aslistarrays(3X), aslistmachines(3X), array_services(5). Page 12