JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
ONC+ Developer's Guide
search filter icon
search icon

Document Information

Preface

1.  Introduction to ONC+ Technologies

2.  Introduction to TI-RPC

3.  rpcgen Programming Guide

4.  Programmer's Interface to RPC

5.  Advanced RPC Programming Techniques

6.  Porting From TS-RPC to TI-RPC

7.  Multithreaded RPC Programming

8.  Extensions to the Sun RPC Library

9.  NIS+ Programming Guide

A.  XDR Technical Note

B.  RPC Protocol and Language Specification

C.  XDR Protocol Specification

D.  RPC Code Examples

E.  portmap Utility

F.  Writing a Port Monitor With the Service Access Facility (SAF)

What Is the SAF?

What Is the SAC?

Basic Port Monitor Functions

Port Management

Activity Monitoring

Other Port Monitor Functions

Restricting Access to the System

Creating utmpx Entries

Port Monitor Process IDs and Lock Files

Changing the Service Environment: Running doconfig()

Terminating a Port Monitor

SAF Files

Port Monitor Administrative File

Per-Service Configuration Files

Private Port Monitor Files

SAC/Port Monitor Interface

Message Formats

SAC Messages

Port Monitor Messages

Message Classes

Port Monitor Administrative Interface

SAC Administrative File _sactab

Port Monitor Administrative File _pmtab

SAC Administrative Command sacadm

Port Monitor Administrative Command pmadm

Monitor-Specific Administrative Command

Port Monitor/Service Interface

New Service Invocations

Standing Service Invocations

Port Monitor Requirements

Initial Environment

Important Files

Port Monitor Responsibilities

Configuration Files and Scripts

Interpreting Configuration Scripts With doconfig()

Per-System Configuration File

Per-Port Monitor Configuration Files

Per-Service Configuration Files

Configuration Language

assign Keyword

push Keyword

pop Keyword

runwait Keyword

run Keyword

Printing, Installing, and Replacing Configuration Scripts

Per-System Configuration Scripts

Per-Port Monitor Configuration Scripts

Per-Service Configuration Scripts

Sample Port Monitor Code

Logic Diagram and Directory Structure

Glossary

Index

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

Fields
Description
PMTAG
A unique tag that identifies a particular port monitor. The system administrator is responsible for naming a port monitor. This tag is then used by the SAC to identify the port monitor for all administrative purposes. PMTAG can consist of up to 14 alphanumeric characters.
PMTYPE
The type of the port monitor. In addition to its unique tag, each port monitor has a type designator. The type designator identifies a group of port monitors that are different invocations of the same entity. ttymon and listen are examples of valid port monitor types. The type designator is used to facilitate the administration of groups of related port monitors. Without a type designator, the system administrator has no way of knowing which port monitor tags correspond to port monitors of the same type. PMTYPE can consist of up to 14 alphanumeric characters.
FLGS
The flags that are currently defined are:

-d When it is started, do not enable the port monitor.

-x Do not start the port monitor.

If no flag is specified, the default action is taken. By default, a port monitor is started and enabled.

RCNT
The number of times a port monitor can fail before being placed in a failed state. After a port monitor enters the failed state, the SAC does not try to restart it. If a count is not specified when the entry is created, this field is set to 0. A restart count of 0 indicates that the port monitor is not to be restarted when it fails.
COMMAND
A string representing the command that starts the port monitor. The first component of the string, the command itself, must be a full path name.

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

Service Entries
Description
FLGS
Flags with the following meanings might currently be included in this field:

-x Do not enable this port. By default, the port is enabled.

-u Create a utmpx entry for this service. By default, no utmpx entry is created for the service.

ID
The identity under which the service is to be started. The identity has the form of a login name as it appears in /etc/passwd.
PMSPECIFIC
Examples of port monitor information are addresses, the name of a process to execute, or the name of a STREAMS pipe through which to pass a connection. This information varies to meet the needs of each different type of port monitor.
COMMENT
A comment associated with the service entry.

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:

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:

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:

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
_config
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.
_pid
The file into which the port monitor writes its process ID.
_pmtab
The port monitor's administrative file. This file contains information about the ports and services for which the port monitor is responsible.
_pmpipe
The FIFO through which the port monitor receives messages from the SAC.
svctag
The per-service configuration script for the service with the tag svctag.
../_sacpipe
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:

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


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.