The SAF generalizes the procedures for service access so that login access on the local system and network access to local services are managed in similar ways. Under the SAF, systems may access services using a variety of port monitors, including ttymon, the listener, and port monitors written expressly for a user's application. The manner in which a port monitor observes and manages access ports is specific to the port monitor and not to any component of the SAF. Users may therefore extend their systems by developing and installing their own port monitors. One of the important features of the SAF is that it can be extended in this way by users.

Relative to the SAF, a service is a process that is started. There are no restrictions on the functions a service may provide. The SAF consists of a controlling process, the service access controller (SAC), and two administrative levels corresponding to two levels in the supporting directory structure. The top administrative level is concerned with port monitor administration, the lower level with service administration. The SAC is documented in the sac(1M) man page. The administrative levels and associated utilities are documented in the System Administration Guide - Volume II. The requirements for writing port monitors and the functions a port monitor must perform to run under the SAF and the SAC are documented here.

A port monitor is a process that is responsible for monitoring a set of homogeneous, incoming ports on a machine. A port monitor's major purpose is to detect incoming service requests and to dispatch them appropriately.

A port is an externally seen access point on a system. A port may be an address on a network (TSAP or PSAP), a hardwired terminal line, an incoming phone line, etc. The definition of what constitutes a port is strictly a function of the port monitor itself.

A port monitor performs certain basic functions. Some of these are required to conform to the SAF; others may be specified by the requirements and design of the port monitor itself. Port monitors have two main functions: managing ports and monitoring ports for indications of activity.

Port Management

Activity Monitoring

This section briefly describes other port monitor functions.

Restricting Access to the System

Creating utmpx Entries

Port Monitor Process IDs and Lock Files

Changing the Service Environment: Running

Terminating a Port Monitor

This section briefly covers the files used by the SAF.

The Port Monitor Administrative File

Per-Service Configuration Files

Private Port Monitor Files

The SAC creates two environment variables for each port monitor it starts:PMTAG and ISTATE.

This variable is set to a unique port monitor tag by the SAC. The port monitor uses this tag to identify itself in response to sac messages. ISTATE is used to indicate to the port monitor what its initial internal state should be. ISTATE is set to "enabled" or "disabled" to indicate that the port monitor is to start in the enabled or disabled state respectively.

The SAC performs a periodic sanity poll of the port monitors. The SAC communicates with port monitors through FIFOs. A port monitor should open _pmpipe, in the current directory, to receive messages from the SAC and ../_sacpipe to send return messages to the SAC.

This section describes the messages that may be sent from the SAC to a port monitor (sac messages), and from a port monitor to the SAC (port monitor messages). These messages are sent through FIFOs and are in the form of C structures.

sac Messages

struct sacmsg
{
 int sc_size; /* size of optional data portion */
 char sc_type; /* type of message */
};

The SAC may send four types of messages to port monitors. The type of message is indicated by setting the sc_type field of the sacmsg structure to one of the following:

SC_STATUS\|

SC_ENABLE\|

SC_DISABLE

SC_READDB\|

The sc_size field indicates the size of the optional data part of the message. See "Message Classes." For Solaris, sc_size should always be set to 0. A port monitor must respond to every message sent by the sac.

The format of messages from a port monitor to the SAC is defined by the structure pmmsg:

struct pmmsg {
 char pm_type; /* type of message */
 unchar_t pm_state; /* current state of port monitor */
 char pm_maxclass; /* maximum message class this port
 monitor understands */
 char pm_tag[PMTAGSIZE + 1]; /* port monitor's tag */
 int pm_size; /* size of optional data portion */
};

Port monitors may send two types of messages to the SAC. The type of message is indicated by setting the pm_type field of the pmmsg structure to one of the following:

PM_STATUS

PM_UNKNOWN

For both types of messages, the pm_tag field is set to the port monitor's tag and the pm_state field is set to the port monitor's current state. Valid states are:

PM_STARTING

PM_ENABLED

PM_DISABLED

PM_STOPPING

The current state reflects any changes caused by the last message from the SAC. The status message is the normal return message. The negative acknowledgment should be sent only when the message received is not understood. pm_size indicates the size of the optional data part of the message. pm_maxclass is used to specify a message class. Both are discussed under "Message Classes." In Solaris, always set pm_maxclass to 1 and sc_size to 0. Port monitors may never initiate messages; they may only respond to messages that they receive.

The concept of message class has been included to accommodate possible SAF extensions. The messages described above are all class 1 messages. None of these messages contains a variable data portion; all pertinent information is contained in the message header. If new messages are added to the protocol, they will be defined as new message classes (for example, class 2). The first message the SAC sends to a port monitor will always be a class 1 message. Since all port monitors, by definition, understand class 1 messages, the first message the SAC sends is guaranteed to be understood. In its response to the SAC, the port monitor sets the pm_maxclass field to the maximum message class number for that port monitor. The SAC will not send messages to a port monitor from a class with a larger number than the value of pm_maxclass. Requests that require messages of a higher class than the port monitor can understand will fail. For Solaris, always set pm_maxclass to 1.

For any given port monitor, messages of class pm_maxclass and messages of all classes with values lower than pm_maxclass are valid. Thus, if the pm_maxclass field is set to 3, the port monitor understands messages of classes 1, 2, and 3. Port monitors may not generate messages; they may only respond to messages. A port monitor's response must be of the same class as the originating message. Since only the SAC can generate messages, this protocol will function even if the port monitor is capable of dealing with messages of a higher class than the SAC can generate. pm_size (an element of the pmmsg structure) and sc_size (an element of the sacmsg structure) indicate the size of the optional data part of the message. The format of this part of the message is undefined. Its definition is inherent in the type of message. For Solaris, always set both sc_size and pm_size to 0.

This section discusses the port monitor administrative files available under the SAC.

The service access controller's administrative file contains information about all the port monitors for which the SAC is responsible. This file exists on the delivered system. Initially, it is empty except for a single comment line that contains the version number of the SAC. Port monitors are added to the system by making entries in the SAC's administrative file. These entries should be made using the administrative command sacadm(1M) with a -a option. sacadm(1M) is also used to remove entries from the SAC's administrative file. Each entry in the SAC's administrative file contains the following information.

PMTAG

PMTYPE

FLGS

RCNT

COMMAND

Each port monitor will have two directories for its exclusive use. The current directory will contain files defined by the SAF (_pmtab, _pid) and the per-service configuration scripts, if they exist. The directory /var/saf/pmtag, where pmtag is the tag of the port monitor, is available for the port monitor's private files. Each port monitor has its own administrative file. The pmadm(1M) command should be used to add, remove, or modify service entries in this file. Each time a change is made using pmadm(1M), the corresponding port monitor rereads its administrative file. Each entry in a port monitor's administrative file defines how the port monitor treats a specific port and what service is to be invoked on that port. Some fields must be present for all types of port monitors. Each entry must include a service tag to identify the service uniquely and an identity to be assigned to the service when it is started (for example, root).

The combination of a service tag and a port monitor tag uniquely define an instance of a service. The same service tag may be used to identify a service under a different port monitor. The record must also contain port monitor specific data (for example, for a ttymon port monitor, this will include the prompt string which is meaningful to ttymon). Each type of port monitor must provide a command that takes the necessary port monitor-specific data as arguments and outputs these data in a form suitable for storage in the file. The ttyadm(1M) command does this for ttymon and nlsadmin(1M) does it for listen. For a user-defined port monitor, a similar administrative command must also be supplied. Each service entry in the port monitor administrative file must have the following format and contain the information listed below:

svctag:flgs:id:reserved:reserved:reserved:pmspecific# comment

SVCTAG is a unique tag that identifies a service. This tag is unique only for the port monitor through which the service is available. Other port monitors may offer the same or other services with the same tag. A service requires both a port monitor tag and a service tag to identify it uniquely. SVCTAG may consist of up to 14 alphanumeric characters. The service entries are defined as:

FLGS

ID

PMSPECIFIC

COMMENT

Previously, two pieces of information included in the _pmtab file were described: the port monitor's version number and the port monitor part of the service entries in the port monitor's _pmtab file. When a new port monitor is added, the version number must be known so that the _pmtab file can be correctly initialized. When a new service is added, the port monitor part of the _pmtab entry must be formatted correctly. Each port monitor must have an administrative command to perform these two tasks. The person who defines the port monitor must also define such an administrative command and its input options. When the command is invoked with these options, the information required for the port monitor part of the service entry must be correctly formatted for inclusion in the port monitor's _pmtab file and must be written to the standard output. To request the version number the command must be invoked with a -V option; when it is invoked in this way, the port monitor's current version number must be written to the standard output. If the command fails for any reason during the execution of either of these tasks, no data should be written to standard output.

The interface between a port monitor and a service is determined solely by the service. Two mechanisms for invoking a service are presented here as examples.

New Service Invocations

Standing Service Invocations

To implement a port monitor, several generic requirements must be met. This section summarizes these requirements. In addition to the port monitor itself, an administrative command must be supplied.

Initial Environment

Important Files

A port monitor is responsible for performing the following tasks in addition to its port monitor function:

A port monitor must perform the following tasks during service invocation:

The library routine doconfig(3NSL), defined in libnsl.so, interprets the configuration scripts contained in the files /etc/saf/_sysconfig (the per-system configuration file), and /etc/saf/pmtag/_config (per-port monitor configuration files); and in /etc/saf/pmtag/svctag (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 may take 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 will generate an error return. If rflag has the NORUN bit set, the run and runwait commands are considered illegal and will generate 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 whose environment was being established should not be started. In the example, doconfig(3NSL) is used to interpret a per-service configuration script.

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

The Per-System Configuration File

Per-Port Monitor Configuration Files

Per-Service Configuration Files

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 may exceed 1024 characters.

assign variable=value

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

pop [module]

runwait command

run command

This example shows an example of a "null" port monitor that simply responds to messages from the SAC.

># 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; /* portmonitor'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);
 }

 log(Fp, "locking file");
 if (lockf(fileno(Tfp), F_LOCK, 0) < 0) {
 log(Fp, "lock failed");
 exit(1);
 }
 fprintf(Tfp, "%d", getpid());
 fflush(Tfp);

/*
 * 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:
 /*note internal state change below*/
 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\en", getpid(), msg);
 fflush(fp);
}

The following example shows the sac.h header file.

/* length in bytes of a utmpx id */
# define IDLEN 4
/* wild character for utmpx ids */
# define SC_WILDC 0xff
/* max len in bytes for port monitor tag */
# define PMTAGSIZE 14
/*
 * values for rflag in doconfig()
 */
/* don't allow assign operations */
# define NOASSIGN 0x1
/* don't allow run or runwait operations */
# define NORUN 0x2
/*
 * message to SAC (header only). This header is forever fixed. The
 * size field (pm_size) defines the size of the data portion of the
 * message, which follows the header. The form of this optional data
 * portion is defined strictly by the message type (pm_type).
 */
struct pmmsg {
 char pm_type; /* type of message */
 unchar_t pm_state; /* current state of pm */
 char pm_maxclass; /* max message class this port monitor
 understands */
 char pm_tag[PMTAGSIZE + 1]; /* pm's tag */
 int pm_size; /* size of opt data portion */
};
/*
 * pm_type values
 */
# define PM_STATUS 1 /* status response */
# define PM_UNKNOWN 2 /* unknown message was received */
/*
 * pm_state values
 */
/*
 * Class 1 responses
 */
# define PM_STARTING 1 /* monitor in starting state */
# define PM_ENABLED 2 /* monitor in enabled state */
# define PM_DISABLED 3 /* monitor in disabled state */
# define PM_STOPPING 4 /* monitor in stopping state */
/*
 * message to port monitor
 */
struct sacmsg {
 int sc_size; /* size of optional data portion */
 char sc_type; /* type of message */
};
/*
 * sc_type values
 * These represent commands that the SAC sends to a port monitor.
 * These commands are divided into "classes" for extensibility. Each
 * subsequent "class" is a superset of the previous "classes" plus
 * the new commands defined within that "class". The header for all
 * commands is identical; however, a command may be defined such that
 * an optional data portion may be sent in addition to the header.
 * The format of this optional data piece is self-defining based on
 * the command. The first message sent by the SAC
 * will always be a class 1 message. The port monitor response
 * indicates the maximum class that it is able to understand. Another
 * note is that port monitors should only respond to a message with
 * an equivalent class response (i.e. a class 1 command causes a
 * class 1 response).
 */
/*
 * Class 1 commands (currently, there are only class 1 commands)
 */
# define SC_STATUS 1 /* status request *
# define SC_ENABLE 2 /* enable request */
# define SC_DISABLE 3 /* disable request */
# define SC_READDB 4 /* read pmtab request */
/*
 * `errno' values for Saferrno, note that Saferrno is used by both
 * pmadm and sacadm and these values are shared between them
 */
# define E_BADARGS 1 /* bad args/ill-formed cmd line */
# define E_NOPRIV 2 /* user not priv for operation */
# define E_SAFERR 3 /* generic SAF error */
# define E_SYSERR 4 /* system error */
# define E_NOEXIST 5 /* invalid specification */
# define E_DUP 6 /* entry already exists */
# define E_PMRUN 7 /* port monitor is running */
# define E_PMNOTRUN 8 /* port monitor is not running */
# define E_RECOVER 9
 /* in recovery */

This section gives a description of the SAF files and directories.

/etc/saf/_sysconfig

/etc/saf/_sactab

/etc/saf/pmtag

/etc/saf/pmtag/_config

/etc/saf/pmtag/_pmtab

/etc/saf/pmtag/svctag

/etc/saf/pmtag/_pid

/etc/saf/ pmtag /_pmpipe

/var/saf/_log

/var/saf/pmtag

The following administrative commands relate to SAF.

sacadm(1M)

pmadm(1M)

exec(1), sh(1), init(1M), nlsadmin(1M), pmadm(1M), sac(1M), sacadm(1M), ttyadm(1M), fork(2), doconfig(3NSL), attributes(5)