Network services

Port monitor functions

A port monitor is a process that is responsible for monitoring a set of homogeneous, incoming ports on a machine. A port monitor's main 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, and so on. 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 Service Access Facility (SAF); others may be specified by the requirements and design of the port monitor itself.

Port monitors have two main functions:

managing ports
monitoring ports for indications of activity

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 is not restricted to handling a single port; it may handle multiple ports simultaneously.

NOTE: 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 may be detected:

The first is an indication to the port monitor to take some port monitor-specific action. Pressing the <Break> key to show that the line speed should be cycled is an example of a port monitor-specific 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 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 may be available on more than one port.

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 this, 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 ``The Service Access Controller''.)

Enabling and disabling a port monitor

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 will be affected. If a port monitor is responsible for multiple ports, the entire collection of ports will be 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 and disabling a port

Enabling or disabling an individual port, however, is a static operation: it causes a change to an administrative file. The effect of this change will persist across new invocations of the port monitor.

Creating utmp entries

Port monitors are responsible for creating utmp 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 on the pmadm command line that added the service). These utmp entries may in turn be modified by the service. When the service terminates, the utmp 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: 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(3iac). Because the per-service configuration script may 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.

Files: the 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. Port monitor-specific commands are discussed below.

NOTE: The port monitor-specific administrative command for a listen port monitor is nlsadmin(1M); the port monitor-specific 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.

Files: 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 may create private files in the directory /var/saf/pmtag, where pmtag is the name of the port monitor. Examples of private files are log files or temporary files.

Terminating a port monitor

A port monitor must terminate itself gracefully on receipt of the signal SIGTERM. The termination sequence is:

The port monitor enters the stopping state; no further service requests are accepted.
Any attempt to re-enable the port monitor will be ignored.
The port monitor yields control of all ports for which it is responsible. It must be possible for a new instantiation of the port monitor to start correctly while a previous instantiation is stopping.
The advisory lock on the process ID file is released. Once this lock is released, the contents of the process ID file are undefined and a new invocation of the port monitor may be started.