Port Monitor Messages

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 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 can 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 values:

• PM_STATUS state information

• PM_UNKNOWN negative acknowledgement

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

• PM_STARTING starting

• PM_ENABLED enabled

• PM_DISABLED disabled

• PM_STOPPING 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 acknowledgement 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 fields are discussed in "Message Classes". In the Solaris environment, always set pm_maxclass to 1 and sc_size to 0.

Port monitors can never initiate messages; they can only respond to messages that they receive.

Message Classes

The concept of message class has been included to accommodate possible SAF extensions. The preceding messages 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 are defined as new message classes, for example, class 2. The first message that the SAC sends to a port monitor is always a class 1 message. Because all port monitors by definition understand class 1 messages, the first message that 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 does not send messages to a port monitor from a class with a larger number than the value of pm_maxclass. Requests fail if they require messages of a higher class than the port monitor can understand. For the Solaris environment, 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 cannot generate messages; they can only respond to messages. A port monitor's response must be of the same class as the originating message.

Because only the SAC can generate messages, this protocol function-- even if the port monitor is capable of dealing with messages of a higher class than the SAC can generate.

pm_size is an element of the pmmsg structure. sc_size is an element of the sacmsg structure. These elements 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 the Solaris environment, always set both sc_size and pm_size to 0.

Port Monitor Administrative Interface

This section discusses the administrative files available under the SAC.

SAC Administrative File _sactab

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, the file is empty except for a single comment line that contains the version number of the SAC. You add port monitors to the system by making entries in the SAC's administrative file. These entries should be made using the administrative command sacadm with a -a option. sacadm is also used to remove entries from the SAC's administrative file.

Each entry in the SAC's administrative file contains the information shown in the following table.

Table F-1 Service Access Controller _sactab File

Port Monitor Administrative File _pmtab

Each port monitor has two directories for its exclusive use. The current directory contains 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. Use the pmadm command to add, remove, or modify service entries in this file. Each time a change is made using pmadm, 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. You can use the same service tag 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 data includes 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 this data in a form suitable for storage in the file. The ttyadm command provides the formatting for ttymon, nlsadmin for listen. For a user-defined port monitor, you also must supply a similar administrative command.

Each service entry in the port monitor administrative file must have the following format and contain the following information:

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 can 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 in the following table.

Table F-2 SVCTAG Service Entries

Note - Port monitors might ignore the -u flag if creating a utmpx entry for the service is not appropriate to the manner in which the service is to be invoked. Some services might not start properly unless utmpx entries have been created for them, for example, login.

Each port monitor administrative file must contain one special comment of the form:

# VERSION=value 

In this case, value is an integer that represents the port monitor's version number. The version number defines the format of the port monitor administrative file. This comment line is created automatically when a port monitor is added to the system. It appears on a line by itself, before the service entries.

SAC Administrative Command sacadm

sacadm is the administrative command for the upper level of the SAF hierarchy, that is, for port monitor administration. See the sacadm(1M) man page. Under the SAF, port monitors are administered by using the sacadm command to make changes in the SAC's administrative file. sacadm performs the following functions:

• Prints requested port monitor information from the SAC administrative file

• Adds or removes a port monitor

• Enables or disables a port monitor

• Starts or stops a port monitor

• Installs or replaces a per-system configuration script

• Installs or replaces a per-port monitor configuration script

• Asks the SAC to reread its administrative file