Interpreting Configuration Scripts With `doconfig()`

The library routine doconfig(), defined in libnsl.so, interprets the configuration scripts contained in the files /etc/saf/_sysconfig, the per-system configuration file, /etc/saf/pmtag/_config, the per-port monitor configuration files, and /etc/saf/pmtag/svctag, the per-service configuration files. Its syntax is:

# include <sac.h>
int doconfig (int fd, char *script, long rflag);

script is the name of the configuration script.
fd is a file descriptor that designates the stream to which stream manipulation operations are to be applied.
rflag is a bitmask that indicates the mode in which script is to be interpreted.

rflag takes two values, NORUN and NOASSIGN, which may be OR'd. If rflag is zero, all commands in the configuration script are eligible to be interpreted. If rflag has the NOASSIGN bit set, the assign command is considered illegal and generates an error return. If rflag has the NORUN bit set, the run and runwait commands are considered illegal and generates error returns.

If a command in the script fails, the interpretation of the script ceases at that point and a positive integer is returned. This number indicates which line in the script failed. If a system error occurs, a value of -1 is returned.

If a script fails, the process with the environment being established should not be started.

In the following example, doconfig() is used to interpret a per-service configuration script.

. . .
 	if ((i = doconfig (fd, svctag, 0)) != 0){
 	error ("doconfig failed online %d of script %s",i,svctag);
}

Per-System Configuration File

The per-system configuration file, /etc/saf/_sysconfig, is delivered empty. You can use it to customize the environment for all services on the system by writing a command script in the interpreted language. This language is described in this chapter and on the doconfig(3NSL) man page. When the SAC is started, it calls the doconfig() function to interpret the per-system configuration script. The SAC is started when the system enters multiuser mode.

Per-Port Monitor Configuration Files

Per-port monitor configuration scripts (/etc/saf/pmtag/_config) are optional. They enable you to customize the environment for any given port monitor and for the services that are available through the ports for which that port monitor is responsible. Per-port monitor configuration scripts are written in the same language that is used for per-system configuration scripts.

The per-port monitor configuration script is interpreted when the port monitor is started. The port monitor is started by the SAC after the SAC has itself been started and after it has run its own configuration script, /etc/saf/_sysconfig.

The per-port monitor configuration script might override defaults provided by the per-system configuration script.

Per-Service Configuration Files

Per-service configuration files enable you to customize the environment for a specific service. For example, a service might require special privileges that are not available to the general user. Using the language described in the doconfig(3NSL) man page, you can write a script that grants or limits such special privileges to a particular service offered through a particular port monitor.

The per-service configuration might override defaults provided by higher-level configuration scripts. For example, the per-service configuration script might specify a set of STREAMS modules other than the default set.

Configuration Language

The language in which configuration scripts are written consists of a sequence of commands, each of which is interpreted separately. The following reserved keywords are defined: assign, push, pop, runwait, and run. The comment character is #. Blank lines are not significant. No line in a command script can exceed 1024 characters.

`assign` Keyword

The assign keyword is used to define environment variables.

assign variable=value

variable is the name of the environment variable and value is the value to be assigned to it. The value assigned must be a string constant. No form of parameter substitution is available. value can be quoted. The quoting rules are those that the shell uses for defining environment variables. assign fails if space cannot be allocated for the new variable or if any part of the specification is invalid.

`push` Keyword

The push keyword is used to push STREAMS modules onto the stream designated by fd. See the doconfig(3NSL) man page.

push module1[, module2, module3, ...]

module1 is the name of the first module to be pushed, module2 is the name of the second module to be pushed, and so on. The command fails if any of the named modules cannot be pushed. If a module cannot be pushed, the subsequent modules on the same command line are ignored and modules that have already been pushed are popped.

`pop` Keyword

The pop keyword is used to pop STREAMS modules off the designated stream.

pop [module]

If pop is invoked with no arguments, the top module on the stream is popped. If an argument is given, modules are popped one at a time until the named module is at the top of the stream. If the named module is not on the designated stream, the stream is left as it was and the command fails. If module is the special keyword ALL, then all modules on the stream are popped. Note that only modules above the topmost driver are affected.

`runwait` Keyword

The runwait keyword runs a command and waits for it to complete.

runwait command

command is the path name of the command to be run. The command is run with /bin/sh -c prepended to it. Shell scripts can thus be executed from configuration scripts. The runwait command fails if command cannot be found or cannot be executed, or if command exits with a nonzero status.

`run` Keyword

The run keyword is identical to runwait except that it does not wait for command to complete.

run command

command is the path name of the command to be run. run does not fail unless it is unable to create a child process to execute the command.

Although they are syntactically indistinguishable, some of the commands available to run and runwait are interpreter built-in commands. Interpreter built-ins are used when it is necessary to alter the state of a process within the context of that process. The doconfig() interpreter built-in commands are similar to the shell special commands and, like these commands, they do not spawn another process for execution. See the sh(1) man page. The initial set of built-in commands is:

cd ulimit umask

Printing, Installing, and Replacing Configuration Scripts

This section describes the form of the SAC and port monitor administrative commands used to install the three types of configuration scripts. Per-system and per-port monitor configuration scripts are administered using the sacadm command. Per-service configuration scripts are administered using the pmadm command.

Per-System Configuration Scripts

Per-system configuration scripts are administered by using the sacadm command.

sacadm -G  [ -z script ]

The -G option is used to print or replace the per-system configuration script. The -G option by itself prints the per-system configuration script. The -G option in combination with a -z option replaces /etc/saf/_sysconfig with the contents of the file script. Other combinations of options with a -G option are invalid.

The _sysconfig file in the following example sets the time zone variable, TZ.

assign TZ=EST5EDT # set TZ
runwait echo SAC is starting > /dev/console

Per-Port Monitor Configuration Scripts

Per-port monitor configuration scripts are administered by using the sacadm command.

sacadm -g -p pmtag [ -z script ]

The -g option is used to print, install, or replace the per-port monitor configuration script. A -g option requires a -p option. The -g option with only a -p option prints the per-port monitor configuration script for port monitor pmtag. The -g option with a -p option and a -z option installs the file script as the per-port monitor configuration script for port monitor pmtag. Or, if /etc/saf/pmtag/_config exists, these options replace _config with the contents of script. Other combinations of options with -g are invalid.

In the _config file, the command /usr/bin/daemon is assumed to start a daemon process that builds and holds together a STREAMS multiplexor. By installing this configuration script, the command can be executed just before starting the port monitor that requires it.

# build a STREAMS multiplexor
run /usr/bin/daemon
runwait echo $PMTAG is starting > /dev/console

Per-Service Configuration Scripts

Per-service configuration scripts are interpreted by the port monitor before the service is invoked.

pmadm -g -p pmtag -s svctag [ -z script ]
 pmadm -g -s svctag -t type -z script

Note - The SAC interprets both its own configuration file, _sysconfig, and the port monitor configuration files. Only the per-service configuration files are interpreted by the port monitors.

The -g option is used to print, install, or replace a per-service configuration script. The -g option with a -p option and a -s option prints the per-service configuration script for service svctag available through port monitor pmtag. The -g option with a -p option, a -s option, and a -z option installs the per-service configuration script contained in the file script as the per-service configuration script for service svctag available through port monitor pmtag. The -g option with a -s option, a -t option, and a -z option installs the file script as the per-service configuration script for service svctag available through any port monitor of type type. Other combinations of options with -g are invalid.

The following per-service configuration script controls two settings: It specifies the maximum file size for files created by a process by setting the process's ulimit to 4096. It also specifies the protection mask to be applied to files created by the process by setting umask to 077.

runwait ulimit 4096
runwait umask 077

Sample Port Monitor Code

The following code example is a "null" port monitor that simply responds to messages from the SAC.

Example F-1 Sample Port Monitor

# include <stdlib.h>
# include <stdio.h>
# include <unistd.h>
# include <fcntl.h>
# include <signal.h>
# include <sac.h>

char Scratch[BUFSIZ]; /* scratch buffer */
char Tag[PMTAGSIZE + 1]; /* port monitor's tag */
FILE *Fp; /* file pointer for log file */
FILE *Tfp; /* file pointer for pid file */
char State; /* port monitor's current state*/

main(argc, argv)
	int argc;
	char *argv[];
{
	char *istate;
	strcpy(Tag, getenv("PMTAG"));
/*
 * open up a log file in port monitor's private directory
 */
	sprintf(Scratch, "/var/saf/%s/log", Tag);
	Fp = fopen(Scratch, "a+");
	if (Fp == (FILE *)NULL)
		exit(1);
	log(Fp, "starting");
/*
 * retrieve initial state (either "enabled" or "disabled") and set
 * State accordingly
 */
	istate = getenv("ISTATE");
	sprintf(Scratch, "ISTATE is %s", istate);
	log(Fp, Scratch);
	if (!strcmp(istate, "enabled"))
		State = PM_ENABLED;
	else if (!strcmp(istate, "disabled"))
		State = PM_DISABLED;
	else {
		log(Fp, "invalid initial state");
		exit(1);
	}
	sprintf(Scratch, "PMTAG is %s", Tag);
	log(Fp, Scratch);
/*
 * set up pid file and lock it to indicate that we are active
 */
	Tfp = fopen("_pid", "w");
	if (Tfp == (FILE *)NULL) {
		log(Fp, "couldn't open pid file");
		exit(1);
	}
	if (lockf(fileno(Tfp), F_TEST, 0) < 0) {
		log(Fp, "pid file already locked");
		exit(1);
	}
	fprintf(Tfp, "%d", getpid());
	fflush(Tfp);
	log(Fp, "locking file");
	if (lockf(fileno(Tfp), F_LOCK, 0) < 0) {
		log(Fp, "lock failed");
		exit(1);
	}
/*
 * handle poll messages from the sac ... this function never
returns
 */
	handlepoll();
	pause();
	fclose(Tfp);
	fclose(Fp);
}

handlepoll()
{
	int pfd; /* file descriptor for incoming pipe */
	int sfd; /* file descriptor for outgoing pipe */
	struct sacmsg sacmsg; /* incoming message */
	struct pmmsg pmmsg; /* outgoing message */
/*
 * open pipe for incoming messages from the sac
 */
	pfd = open("_pmpipe", O_RDONLY|O_NONBLOCK);
	if (pfd < 0) {
		log(Fp, "_pmpipe open failed");
		exit(1);
	}
/*
 * open pipe for outgoing messages to the sac
 */
	sfd = open("../_sacpipe", O_WRONLY);
	if (sfd < 0) {
		log(Fp, "_sacpipe open failed");
		exit(1);
	}
/*
 * start to build a return message; we only support class 1
messages
 */
	strcpy(pmmsg.pm_tag, Tag);
	pmmsg.pm_size = 0;
	pmmsg.pm_maxclass = 1;
/*
 * keep responding to messages from the sac
 */
 	for (;;) {
 		if (read(pfd, &sacmsg, sizeof(sacmsg)) != sizeof(sacmsg)) {
 			log(Fp, "_pmpipe read failed");
 			exit(1);
 		}
/*
 * determine the message type and respond appropriately
 */
 		switch (sacmsg.sc_type) {
 			case SC_STATUS:
 				log(Fp, "Got SC_STATUS message");
 				pmmsg.pm_type = PM_STATUS;
 				pmmsg.pm_state = State;
 				break;
 			case SC_ENABLE:
 				/*note internal state change below*/
 				log(Fp, "Got SC_ENABLE message");
 				pmmsg.pm_type = PM_STATUS;
 				State = PM_ENABLED;
 				pmmsg.pm_state = State;
 				break;
 			case SC_DISABLE:
 				/*noteinternalstatechangebelow*/
 				log(Fp, "Got SC_DISABLE message");
 				pmmsg.pm_type = PM_STATUS;
 				State = PM_DISABLED;
 				pmmsg.pm_state = State;
 				break;
 			case SC_READDB:
 				/*
				 * if this were a fully functional port monitor it
				 * would read _pmtab here and take appropriate action
				 */
 				log(Fp, "Got SC_READDB message");
 				pmmsg.pm_type = PM_STATUS;
 				pmmsg.pm_state = State;
 				break;
 			default:
 				sprintf(Scratch, "Got unknown message <%d>",
 				sacmsg.sc_type);
 				log(Fp, Scratch);
 				pmmsg.pm_type = PM_UNKNOWN;
 				pmmsg.pm_state = State;
 				break;
 		}
/*
 * send back a response to the poll
 * indicating current state
 */
 		if (write(sfd, &pmmsg, sizeof(pmmsg)) != sizeof(pmmsg))
 			log(Fp, "sanity response failed");
 	}
}
/*
 * general logging function
 */
log(fp, msg)
	FILE *fp;
	char *msg;
{
	fprintf(fp, "%d; %s\n", getpid(), msg);
	fflush(fp);
}


F. Writing a Port Monitor With the Service Access Facility (SAF) Configuration Files and Scripts

Interpreting Configuration Scripts With doconfig()