Port Monitor Administrative Command pmadm
pmadm is the administrative command for the lower level of the SAF hierarchy, that is, for service administration. See the pmadm(1M) man page. A port can have only one service associated with it, although the same service might be available through more than one port. pmadm performs the following functions:
Prints service status information from the port monitor's administrative file
Adds or removes a service
Enables or disables a service
Installs or replaces a per-service configuration script
In order to identify an instance of a service uniquely, the pmadm command must identify both the service (-s) and the port monitor or port monitors through which the service is available (-p or -t).
Monitor-Specific Administrative Command
In the previous section, 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 you add a new port monitor, the version number must be known so that the _pmtab file can be correctly initialized. When you add a new service, 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.
Port Monitor/Service Interface
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
The first interface is for services that are started anew with each request. This interface requires the port monitor to first fork() a child process. The child eventually becomes the designated service by performing an exec(). Before the exec() happens, the port monitor might take some port monitor-specific action. However, one action that must occur is the interpretation of the per-service configuration script, if one is present. This interpretation is done by calling the library routine doconfig().
Standing Service Invocations
The second interface is for invocations of services that are actively running. To use this interface, a service must have one end of a stream pipe open and be prepared to receive connections through it.
Port Monitor Requirements
To implement a port monitor, several generic requirements must be met. This section summarizes these requirements. In addition to the port monitor itself, you must supply an administrative command.
Initial Environment
When a port monitor is started, it expects an initial execution environment in which:
It has no file descriptors open.
It cannot be a process group leader.
It has an entry in /var/adm/utmpx of type LOGIN_PROCESS.
An environment variable, ISTATE, is set to enabled or disabled to indicate the port monitor's correct initial state .
An environment variable, PMTAG, is set to the port monitor's assigned tag.
The directory that contains the port monitor's administrative files is its current directory.
The port monitor is able to create private files in the directory /var/saf/tag, where tag is the port monitor's tag.
Important Files
Relative to its current directory, the key files listed in the following table exist for a port monitor.
Table F-3 Key Port Monitor Files
File | Description |
|---|---|
The port monitor's configuration script. The port monitor configuration script is run by the SAC. The SAC is started by init() as a result of an entry in /etc/inittab that calls the SAC. | |
The port monitor's administrative file. This file contains information about the ports and services for which the port monitor is responsible. | |
The FIFO through which the port monitor receives messages from the SAC. | |
The per-service configuration script for the service with the tag svctag. | |
The FIFO through which the port monitor sends messages to the SAC. |
Port Monitor Responsibilities
A port monitor is responsible for performing the following tasks in addition to its port monitor function:
Writing its process ID into the file _pid and place an advisory lock on the file
Following the protocol for message exchange with the SAC
A port monitor must perform the following tasks during service invocation:
Creating a utmp entry if the requested service has the "-u" flag set in _pmtab
Note - Port monitors might ignore this flag if creating a utmp entry for the service does not make sense because of the manner in which the service is to be invoked. On the other hand, some services might not start properly unless utmp entries have been created for them.
Interpreting the per-service configuration script for the requested service, if it exists, by calling the doconfig() library routine
Configuration Files and Scripts
This section describes configuration files and scripts.