Using the Service Access Facility

The SAF is the tool used for administering terminals, modems, and other network devices. The top-level SAF program is the Service Access Controller (SAC). The SAC controls port monitors which you administer through the sacadm command. Each port monitor can manage one or more ports.

You administer the services associated with ports through the pmadm command. While services provided through SAC may differ from network to network, SAC and the administrative programs sacadm and pmadm are network independent.

Table 56-1 illustrates the SAF control hierarchy. The sacadm command is used to administer the SAC which controls the ttymon and listen port monitors.

The services of ttymon and listen are in turn controlled by pmadm. One instance of ttymon can service multiple ports and one instance of listen can provide multiple services on a network interface.

Table 56-1

Function	Program	Description
Overall Administration	sacadm	Command for adding and removing port monitors
Service Access Controller	sac	SAF's master program
Port Monitors	ttymon listen	Monitors serial port login requests Monitors requests for network services
Port Monitor Service Administrator	pmadm	Command for controlling port monitors' services
Services	logins; remote procedure calls; other	Services to which SAF provides access

Overall Administration: sacadm Command

The sacadm command is the top level of the SAF. The sacadm command primarily is used to add and remove port monitors such as ttymon and listen. Other sacadm functions include listing the current status of port monitors and administering port monitor configuration scripts.

Service Access Controller: SAC Program

The Service Access Controller program (SAC) oversees all port monitors. A system automatically starts SAC upon entering multiuser mode.

When SAC is invoked, it first looks for, and interprets, each system's configuration script, by which SAC customizes its environment. The modifications made to the SAC environment are inherited by all the "children" of the SAC. This inherited environment may be modified by the children.

After it has interpreted the per-system configuration script, the SAC program reads its administrative file and starts the specified port monitors. For each port monitor, SAC runs a copy of itself (SAC forks a child process). Each child then interprets its per-port monitor configuration script, if such a script exists.

Any modifications to the environment specified in the per-port monitor configuration script affect the port monitor and will be inherited by all its children. Finally, the child process runs the port monitor program using the command found in the SAC administrative file.

SAC Initialization Process

The following steps summarize what happens when SAC is first started:

1. The SAC program is spawned by init at run level two.

2. The SAC program reads /etc/saf/_safconfig, the per-system configuration script.

3. The SAC program reads /etc/saf/_sactab, the SAC administrative file.

4. The SAC program forks a child process for each port monitor it starts.

5. Each port monitor reads /etc/saf/pmtag/_config, the per-port monitor configuration script.

Port Monitor Service Administrator: pmadm Command

The pmadm command enables you to administer port monitors' services. In particular, you use the pmadm command to add or remove a service and to enable or disable a service. You can also install or replace per-service configuration scripts, or print information about a service.

Each instance of a service must be uniquely identified by a port monitor and a port. When you use the pmadm command to administer a service, you specify a particular port monitor via the pmtag argument, and a particular port via the svctag argument.

For each port monitor type, the SAF requires a specialized command to format port monitor-specific configuration data. This data is used by the pmadm command. For ttymon and listen type port monitors, these specialized commands are ttyadm and nlsadmin, respectively.

A Port Monitor at Work: ttymon

Whenever you attempt to log in via a directly connected modem or alphanumeric terminal, ttymon goes to work, as follows.

As shown in Figure 56-1 on page 1133, the init program is the first process to be started at boot time. Consulting its administrative file (/etc/inittab), init starts other processes as they are needed. Listed among those processes is the SAC.

SAC, in turn, automatically starts up the port monitors designated in its administrative file (/etc/saf/_sactab). Figure 56-1 shows only a single ttymon port monitor.

After ttymon has been started, it monitors the serial port lines for service requests.

Figure 56-1 ttymon

When someone attempts to log in via an alphanumeric terminal or a modem, the serial port driver passes the activity to the operating system. The ttymon port monitor notes the serial port activity, and attempts to establish a communications link. ttymon determines what data transfer rate, line discipline, and handshaking protocol are required to communicate with the device.

Having established the proper parameters for communication with the modem or terminal, ttymon passes these parameters to the login program and transfers control to it.

Port Initialization Process

When an instance of ttymon is invoked by SAC, ttymon starts to monitor its ports. For each port, ttymon first initializes the line disciplines, if they are specified, and the speed and terminal settings. The values used for initialization are taken from the appropriate entry in /etc/ttydefs.

The ttymon port monitor then writes the prompt and waits for user input. If the user indicates that the speed is inappropriate by pressing the Break key, ttymon tries the next speed and writes the prompt again.

If autobaud is enabled for a port, ttymon will try to determine the baud rate on the port automatically. Users must press Return before ttymon can recognize the baud rate and print the prompt.

When valid input is received, ttymon interprets the per-service configuration file for the port, creates a /etc/utmp entry if required, establishes the service environment, and invokes the service associated with the port.

After the service terminates, ttymon cleans up the /etc/utmp entry, if one exists, and returns the port to its initial state.

Bidirectional Service

If a port is configured for bidirectional service, ttymon will:

• Allow users to connect to a service
• Allow uucico, cu, or ct to use the port for dialing out (if the port's free)
• Wait to read a character before printing a prompt
• Invoke the port's associated service--without sending the prompt message--when a connection is requested (if the connect-on-carrier flag is set)

Port Monitors: TTY Monitor and Network Listener

Though SAF provides a generic means for administering any future or third-party port monitors, only two are implemented in the Solaris 2.x environment--ttymon and listen.

TTY Port Monitor: ttymon

The ttymon port monitor is STREAMS-based. It monitors ports; sets terminal modes, baud rates, and line disciplines; and invokes the login process. (It provides Solaris 2.x users the same services that getty did under previous versions of Solaris software.)

The ttymon port monitor runs under the SAC program. It is configured using the sacadm command. Each instance of ttymon can monitor multiple ports. These ports are specified in the port monitor's administrative file. The administrative file is configured using the pmadm and ttyadm commands.

Special ttymon-Specific Administrative Command: ttyadm

The ttymon administrative file is updated by sacadm and pmadm, as well as by the ttyadm command. The ttyadm command formats ttymon-specific information and writes it to the standard output, providing a means for presenting formatted ttymon-specific data to the sacadm and pmadm commands.

Thus, ttyadm does not administer ttymon directly; rather, it complements the generic administrative commands, sacadm and pmadm. See the ttyadm(1M) for more details.

Network Listener Service: listen

The listen port monitor runs under SAC. It monitors the network for service requests, accepts requests when they arrive, and invokes servers in response to those service requests.

The listen port monitor is configured using the sacadm command. Each instance of listen can provide multiple services. These services are specified in the port monitor's administrative file. This administrative file is configured using the pmadm and nlsadmin commands.

The network listener process may be used with any connection-oriented transport provider that conforms to the Transport Layer Interface (TLI) specification. In the Solaris 2.x environment, listen port monitors provide additional network services not provided by inetd, such as print service.

Special listen-Specific Administrative Command: nlsadmin

The listen port monitor's administrative file is updated by sacadm and pmadm, as well as by the nlsadmin command. The nlsadmin command formats listen-specific information and writes it to the standard output, providing a means of presenting formatted listen-specific data to the sacadm and pmadm commands.

Thus, nlsadmin does not administer listen directly; rather, it complements the generic administrative commands, sacadm and pmadm. See nlsadmin(1M) for more details.

Each network has at least one instance of the network listener process associated with it. Each network is configured separately. The nlsadmin command controls the operational states of listen port monitors.

The nlsadmin command can establish a listen port monitor for a given network, configure the specific attributes of that port monitor, and start and kill the monitor. The nlsadmin command can also report on the listen port monitors on a machine. See nlsadmin(1M) for a detailed description.

Administering ttymon Port Monitors

Use the sacadm command to add, list, remove, kill, start, enable, disable, enable, and remove a ttymon port monitor.

---

Note - You must be superuser to perform the following procedures.

---

· How to Add a ttymon Port Monitor

To add a ttymon port monitor, type:

# sacadm -a -p mbmon -t ttymon -c /usr/lib/saf/ttymon -v 'ttyadm -V' -y "TTY Ports a & b"

In this command,

-a	is the add port monitor flag
-p	specifies the pmtag mbmon as the port monitor tag
-t	specifies the port monitor type as ttymon
-c	defines the command string used to start the port monitor
-v	specifies the version number of the port monitor
-y	defines a comment to describe this instance of the port monitor

· How to View ttymon Port Monitor Status

To see the status of a ttymon port monitor, type:

# sacadm -l -p mbmon

In this command,

-l	is the list port monitor status flag
-p	specifies the pmtag mbmon as the port monitor tag

· How to Stop a ttymon Port Monitor

To kill a ttymon port monitor, type:

# sacadm -k -p mbmon

In this command,

-k	is the kill port monitor status flag
-p	specifies the pmtag mbmon as the port monitor tag

· How to Start a ttymon Port Monitor

To start a killed ttymon port monitor, type:

# sacadm -s -p mbmon

In this command,

-s	is the start port monitor status flag
-p	specifies the pmtag mbmon as the port monitor tag

· How to Disable a ttymon Port Monitor

Disabling a port monitor prevents new services from starting, without affecting existing services.

To disable a ttymon port monitor, type:

# sacadm -d -p mbmon

In this command,

-d	is the disable port monitor status flag
-p	specifies the pmtag mbmon as the port monitor tag

· How to Enable a ttymon Port Monitor

Enabling a ttymon port monitor allows it to service new requests.

To enable a ttymon port monitor, type:

# sacadm -e -p mbmon

In this command,

-e	is the enable port monitor status flag
-p	specifies the pmtag mbmon as the port monitor tag

· How to Remove a ttymon Port Monitor

To remove a ttymon port monitor, type:

# sacadm -r -p mbmon

In this command,

-r	is the remove port monitor status flag
-p	specifies the pmtag mbmon as the port monitor tag

---

Note - Removing a port monitor deletes all the configuration files associated with it. Port monitor configuration files cannot be updated or changed using sacadm. To reconfigure a port monitor, remove it and add a new one.

---

Administering ttymon Services

Use pmadm to add services, list the services of one or more ports associated with a port monitor, and enable or disable a service.

---

Note - You must be superuser to perform the following procedures.

---

· How to Add a Service

To add a standard terminal service to the mbmon port monitor, type:

# pmadm -a -p mbmon -s a -i root -v 'ttyadm -V' -m "'ttyadm -i ´Terminal disabled.´ -l contty -m ldterm,ttcompat -S y -d /dev/term/a -s /usr/bin/login'"

---

Note - In this example, the input wraps to the next line. Do not put a Return or line feed after contty.

---

In this command,

-a	is the add port monitor status flag
-p	specifies the pmtag mbmon as the port monitor tag
-s	specifies the svctag a as the port monitor service tag
-i	specifies the identity to be assigned to svctag when it runs
-v	specifies the version number of the port monitor

-m      specifies the ttymon-specific configuration data formatted by ttyadm

The above pmadm command contains an embedded ttyadm command. In that embedded command:

-b	is the bidirectional port flag
-i	specifies the inactive (disabled) response message

-l      specifies which TTY label in /etc/ttydefs to use

-m	specifies the STREAMS modules to push before invoking this service
-d	specifies the full path name to the device to use for the TTY port
-s	specifies the full path name of the service to invoke when a connection request is received; if arguments are required, enclose the command and its arguments in quotation marks (")

· How to View the Status of a TTY Port Service

Use the pmadm command as shown to list the status of a TTY port, or all the ports associated with a port monitor.

Listing One Service

To list one service of a port monitor, type:

# pmadm -l -p mbmon -s a

In this command,

-l	is the flag for a list of service information
-p	specifies the pmtag mbmon as the port monitor tag
-s	specifies the svctag a as the port monitor service tag

Listing All Services of All Port Monitors

To list all services of all port monitors, type:

# pmadm -l

In this command,

-l is the flag for a list of service information

Listing All Services of a Port Monitor

To list all services of a port monitor, type:

# pmadm -l -p mbmon

In this command,

-l	is the flag for a list of service information
-p	specifies the pmtag mbmon as the port monitor tag

· How to Enable a Port Monitor Service

To enable a disabled port monitor service, type:

# pmadm -e -p mbmon -s a

In this command,

-e	is the enable flag
-p	specifies the pmtag mbmon as the port monitor tag
-s	specifies the svctag a as the port monitor service tag

· How to Disable a Port Monitor Service

To disable a port monitor service, type:

# pmadm -d -p mbmon -s a

In this command,

-d	is the disable flag
-p	specifies the pmtag mbmon as the port monitor tag
-s	specifies the svctag a as the port monitor service tag

Administering listen Port Monitors

Use the sacadm command to add, list, kill, start, enable, disable, or remove a listen port monitor.

---

Note - You must be superuser to perform the following procedures.

---

· How to Add a listen Port Monitor

To add a listen port monitor, type:

# sacadm -a -p tcp -t listen -c /usr/lib/saf/listen -v 'nlsadmin -V' -y "le0 ethernet"

In this command,

-a	is the add port monitor flag
-p	specifies the pmtag tcp as the port monitor tag
-t	specifies the port monitor type as listen
-c	defines the command string used to start the port monitor

-v	specifies the version number of the port monitor
-y	defines a comment to describe this instance of the port monitor

· How to View listen Port Monitor Status

To list the status of a listen port monitor, type:

# sacadm -l -p tcp

In this command,

-l	is the list port monitor status flag
-p	specifies the pmtag tcp as the port monitor tag

· How to Stop a listen Port Monitor

To kill a listen port monitor, type:

# sacadm -k -p tcp

In this command,

-k	is the kill port monitor flag
-p	specifies the pmtag tcp as the port monitor tag

· How to Start a listen Port Monitor

To start a listen port monitor, type:

# sacadm -s -p tcp

In this command,

-s	is the start port monitor flag
-p	specifies the pmtag tcp as the port monitor tag

· How to Enable a listen Port Monitor

To enable a listen port monitor, type:

# sacadm -e -p tcp

In this command,

-e	is the enable port monitor flag
-p	specifies the pmtag tcp as the port monitor tag

· How to Disable a listen Port Monitor

To disable a listen port monitor, type:

# sacadm -d -p tcp

In this command,

-e	is the disable port monitor flag
-p	specifies the pmtag tcp as the port monitor tag

· How to Remove a listen Port Monitor

To remove a listen port monitor, type:

# sacadm -r -p tcp

In this command,

-r	is the remove port monitor flag
-p	specifies the pmtag tcp as the port monitor tag

Administering listen Port Monitor Services

Use the pmadm command to add, enable, disable, and list the services associated with a listen port monitor.

---

Note - You must be superuser to perform the following procedures.

---

· How to Add a listen Port Monitor Service

To add a listen port monitor service, type:

# pmadm -a -p tcp -s lp -i root -v 'nlsadmin -V' -m "'nlsadmin -o /var/spool/lp/fifos/listenS5'"

In this example, a listen service is added for print requests from remote SunOS 5.x machines. This service does not listen for requests from SunOS 4.x machines.

---

Note - In this example, the input wraps to the next line. Do not put a Return or line feed after the -o.

---

In this command,

-a	is the add port monitor service flag
-p	specifies the pmtag tcp as the port monitor tag
-s	specifies the svctag lp as the port monitor service tag
-i	specifies the identity to be assigned to svctag when it runs
-v	specifies the version number of the port monitor

-m      specifies the listen-specific configuration data formatted by nlsadmin

The above pmadm command contains an embedded nlsadmin command. In that embedded command -o specifies the full path name of a first-in first-out (FIFO) or named STREAM through which a standing server will receive the connection.

· How to List listen Port Monitor Services

To list the services associated with a listen port monitor, type:

# pmadm -l -p tcp

In this command,

-l	is the list port monitor service flag
-p	specifies the pmtag tcp as the port monitor tag

· How to Enable a listen Port Monitor Service

To enable a listen port monitor service, type:

# pmadm -e -p tcp -s lp

In this command,

-e	is the enable flag
-p	specifies the pmtag tcp as the port monitor tag
-s	specifies the svctag lp as the port monitor service tag

· How to Disable a listen Port Monitor Service

To disable a listen port monitor service, type:

# pmadm -d -p tcp -s lp

In this command,

-d	is the disable flag
-p	specifies the pmtag tcp as the port monitor tag
-s	specifies the svctag lp as the port monitor service tag

Troubleshooting the Network Listener: listen Port Monitor

Use the following tips to remedy listen port monitor difficulties.

1. Begin with the network.

   The network listener is suspect when users report that they cannot print to a network printer. Begin by issuing the /usr/sbin/ping command from the print server to the client and back to determine if the network is up.

2. Check the listen port monitor.

   Use sacadm to check that the listener is starting. Use pmadm to check that the print service is configured correctly and that the service is enabled.

3. Check the print server's configuration.

   See Chapter 52, "Troubleshooting Printing Problems," for more information.

Reference Material for Service Access Facility Administration

Files Associated With SAF

SAF uses configuration files which can be modified by using the sacadm and pmadm commands. You should not need to edit them manually.

File Name	Description
/etc/saf/_sysconfig	Per-system configuration script
/etc/saf/_sactab	SAC's administrative file; contains configuration data for the port monitors that the SAC controls
/etc/saf/pmtag	Home directory for port monitor pmtag
/etc/saf/pmtag/_config	Per-port monitor configuration script for port monitor pmtag if it exists
/etc/saf/pmtag/_pmtab	Port monitor pmtag's administrative file; contains port monitor-specific configuration data for the services pmtag provides

File Name	Description
/etc/saf/pmtag/svctag	Per-service configuration script for service svctag
/var/saf/log	SAC's log file
/var/saf/pmtag	Directory for files created by pmtag, for example, log files

Service States

The sacadm command controls the states of services. The possible states are shown below.

State	Notes
Enabled	Default state - When the port monitor is added, the service operates.
Disabled	Default state - When the port monitor is removed, the service stops.

To determine the state of any particular service, use the following:

pmadm -l -p portmon_name -s svctag

Port Monitor States

The sacadm command controls the states of ttymon and listen port monitors. The possible states are shown below.

State	Notes
Started	Default state - When the port monitor is added, it is automatically started.
Enabled	Default state - When the port monitor is added, it is automatically ready to accept requests for service.
Stopped	Default state - When the port monitor is removed, it is automatically stopped.
Disabled	Default state - When the port monitor is removed, it automatically continues existing services and refuses to add new services.
Starting	Intermediate state - The port monitor is in the process of starting.

State	Notes
Stopping	Intermediate state - The port monitor has been manually terminated, but it has not completed its shutdown procedure. It is on the way to becoming stopped.
Notrunning	Inactive state - The port monitor has been killed. All ports previously monitored are inaccessible. An external user cannot tell whether a port is disabled or notrunning.
Failed	Inactive state - The port monitor is unable to start and remain running.

To determine the state of any particular port monitor, use the following:

# sacadm -l -p portmon_name

Port States

Ports may be enabled or disabled depending on the state of the port monitor that controls them.

State	Notes
Serial (ttymon) Port States Enabled	The ttymon port monitor sends a prompt message to the port and provides login service to it.
Disabled	Default state of all ports if ttymon is killed or disabled. If you specify this state, ttymon will send out the "disabled" message when it receives a connection request.
Network (listen) Port States Enabled	The listen port monitor scans the network for service requests and invokes services in response to those requests.
Disabled	If the listen port monitor is killed or disabled, the ports it controls are automatically disabled. If you specify this state, listen will send out the "disabled" message when it receives a connection request.