Port Management
The first function of a port monitor is to manage a port. The actual details of how a port is managed are defined by the person who defines the port monitor. A port monitor can handle multiple ports simultaneously.
Some examples of port management are setting the line speed on incoming phone connections, binding an appropriate network address, reinitializing the port when the service terminates, outputting a prompt, and so on.
Activity Monitoring
The second function of a port monitor is to monitor the port or ports for which it is responsible for indications of activity. Two types of activity can be detected.
The first activity is an indication to the port monitor to take some port monitor-specific action. Pressing the Break key to indicate that the line speed should be cycled is an example of a port monitor activity. Not all port monitors need to recognize and respond to the same indications. The indication used to attract the attention of the port monitor is defined by the person who defines the port monitor.
The second activity is an incoming service request. When a service request is received, a port monitor must be able to determine which service is being requested from the port on which the request is received. Note that the same service can be available on more than one port.
Other Port Monitor Functions
This section briefly describes other port monitor functions.
Restricting Access to the System
A port monitor must be able to restrict access to the system without disturbing services that are still running. In order to do so, a port monitor must maintain two internal states: enabled and disabled. The port monitor starts in the state indicated by the ISTATE environment variable provided by the SAC. See "SAC/Port Monitor Interface".
Enabling or disabling a port monitor affects all ports for which the port monitor is responsible. If a port monitor is responsible for a single port, only that port is affected. If a port monitor is responsible for multiple ports, the entire collection of ports is affected.
Enabling or disabling a port monitor is a dynamic operation. It causes the port monitor to change its internal state. The effect does not persist across new invocations of the port monitor.
Enabling or disabling an individual port is a static operation. It causes a change to an administrative file. The effect of this change persists across new invocations of the port monitor.
Creating utmpx Entries
Port monitors are responsible for creating utmpx entries with the type field set to USER_PROCESS for services they start, if this action has been specified, that is, if -fu was specified in the pmadm line that added the service. These utmpx entries can in turn be modified by the service. When the service terminates, the utmpx entry must be set to DEAD_PROCESS.
Port Monitor Process IDs and Lock Files
When a port monitor starts, it writes its process ID into a file named _pid in the current directory and places an advisory lock on the file.
Changing the Service Environment: Running doconfig()
Before invoking the service designated in the port monitor administrative file, _pmtab, a port monitor must arrange for the per-service configuration script to be run, if one exists, by calling the library function doconfig(). Because the per-service configuration script can specify the execution of restricted commands, as well as for other security reasons, port monitors are invoked with root permissions. The details of how services are invoked are specified by the person who defines the port monitor.
Terminating a Port Monitor
A port monitor must terminate itself gracefully on receipt of the signal SIGTERM. The termination sequence is as follows:
The port monitor enters the stopping state. No further service requests are accepted.
Any attempt to re-enable the port monitor is ignored.
The port monitor yields control of all ports for which it is responsible. A new instantiation of the port monitor must be able to start correctly while a previous instantiation is stopping.
The advisory lock on the process ID file is released. After this lock is released, the contents of the process ID file are undefined and a new invocation of the port monitor can be started.
SAF Files
This section briefly covers the files used by the SAF.
Port Monitor Administrative File
A port monitor's current directory contains an administrative file named _pmtab. _pmtab is maintained by the pmadm command in conjunction with a port monitor-specific administrative command.
The port monitor administrative command for a listen port monitor is nlsadmin(); the port monitor administrative command for ttymon is ttyadm(). Any port monitor written by a user must be provided with an administrative command specific to that port monitor to perform similar functions.
Per-Service Configuration Files
A port monitor's current directory also contains the per-service configuration scripts, if they exist. The names of the per-service configuration scripts correspond to the service tags in the _pmtab file.
Private Port Monitor Files
A port monitor can create private files in the directory /var/saf/tag, where tag is the name of the port monitor. Examples of private files are log files or temporary files.
SAC/Port Monitor Interface
The SAC creates two environment variables for each port monitor it starts:
-
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.
Message Formats
This section describes the messages that can 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. See Example F-2.
SAC Messages
The format of messages from the SAC is defined by the structure sacmsg:
struct sacmsg {
int sc_size; /* size of optional data portion */
char sc_type; /* type of message */
};
|
The SAC can 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 status request.
SC_ENABLE enable message.
SC_DISABLE disable message.
SC_READDB message indicating that the port monitor's _pmtab file should be read.
sc_size indicates the size of the optional data part of the message. See "Message Classes". For the Solaris environment, sc_size should always be set to 0.
A port monitor must respond to every message sent by the SAC.