Chapter 12 Managing Serial Ports With the Service Access Facility (Tasks)
This chapter describes how to manage serial port services with the Service Access Facility (SAF).
This is a list of the step-by-step instructions in this chapter.
This is a list of the overview information in this chapter.
For reference information about the SAF, see Service Access Facility Administration (Reference).
Using the Service Access Facility
You can set up terminals and modems with the Solaris Management Console's Serial Ports Tool, admintool, or the SAF commands.
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 can differ from network to network, the SAC and its administrative commands, sacadm and pmadm, are network independent.
The following table describes 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 the pmadm command. One instance of ttymon can service multiple ports and one instance of listen can provide multiple services on a network interface.
Table 12–1 SAF Control Hierarchy|
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 |
|
Console Administration |
console login |
The console is automatically set up via an entry in the /etc/inittab file using ttymon-express mode. Do not use the pmadm or sacadm to manage the console directly. For more information, see ttymon and the Console Port. |
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 might 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:
-
The SAC program is spawned by init at run level two.
-
The SAC program reads /etc/saf/_safconfig, the per-system configuration script.
-
The SAC program reads /etc/saf/_sactab, the SAC administrative file.
-
The SAC program forks a child process for each port monitor it starts.
-
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 by using a directly connected modem or alphanumeric terminal, ttymon goes to work, as follows.
As shown in the following figure, the init process is the first process to be started at boot time. Consulting its administrative file (/etc/inittab), the init process starts other processes as they are needed. Listed among those processes is the SAC.
SAC, in turn, automatically starts the port monitors designated in its administrative file (/etc/saf/_sactab). The following figure shows only a single ttymon port monitor.
After the ttymon port monitor has been started, it monitors the serial port lines for service requests.
Figure 12–1 How ttymon Helps Process a Login Request
When someone attempts to log in by using 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. The ttymon port monitor 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, the ttymon port monitor passes these parameters to the login program and transfers control to it.
Port Initialization Process
When an instance of the ttymon port monitor is invoked by SAC, ttymon starts to monitor its ports. For each port, the ttymon port monitor 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 the /etc/ttydefs file.
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, the ttymon port monitor tries the next speed and writes the prompt again.
If autobaud is enabled for a port, the ttymon port monitor tries to determine the baud rate on the port automatically. Users must press Return before the ttymon port monitor can recognize the baud rate and print the prompt.
When valid input is received, the ttymon port monitor interprets the per-service configuration file for the port, creates an /etc/utmpx entry if required, establishes the service environment, and invokes the service associated with the port.
After the service terminates, the ttymon port monitor cleans up the /etc/utmpx entry, if one exists, and returns the port to its initial state.
Bidirectional Service
If a port is configured for bidirectional service, the ttymon port monitor will:
-
Allow users to connect to a service
-
Allow the uucico, cu, or ct commands 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 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 users the same services that getty did under previous versions of SunOS 4.1 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.
ttymon and the Console Port
Console services are not managed by the Service Access Controller nor any explicit ttymon administration file. An entry in the /etc/inittab file is used to manage the console port using ttymon in express mode, which is a special ttymon mode that is invoked directly by a command that requires login service.
The default console entry in the /etc/inittab file looks like this:
co:234:respawn:/usr/lib/saf/ttymon -g -h -p "`uname -n` console login: " -T terminal_type -d /dev/console -l console -m ldterm,ttcompat |
|
co:234:respawn: |
co identifies the entry as the console; 234 identifies the run levels for the action, respawn, which means the console entry should be restarted if it fails or doesn't exist at run levels 2, 3, and 4. |
|
/usr/lib/saf/ttymon -g -h |
The -g option is used so the correct baud rate and terminal setting can be set on a port and connect to a login service without being preconfigured by the SAC. The -h option forces a line hangup by setting the line speed to zero before setting the default or specified speed. |
|
-p "`uname -n` console login: |
Identifies the prompt string for the console port. |
|
-t terminal_type |
Identifies the terminal type of the console. |
|
-d /dev/console -l console -m ldterm,ttcompat |
The -d option identifies the console device; the -l option identifies the ttylabel in the /etc/ttydefs file. The -m option identifies the STREAMS modules to be pushed. |
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. For more information, see ttyadm(1M).
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 can be used with any connection-oriented transport provider that conforms to the Transport Layer Interface (TLI) specification. In the Solaris environment, listen port monitors can provide additional network services not provided by the inetd 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.
Each network can have 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.
For more information, see nlsadmin(1M).
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 the following:
# sacadm -a -p mbmon -t ttymon -c /usr/lib/saf/ttymon -v `ttyadm -V` -y "TTY Ports a & b" |
|
-a |
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 the following:
# sacadm -l -p mbmon |
|
-l |
The list port monitor status flag. |
|
-p |
Specifies the pmtag mbmon as the port monitor tag. |
Example—Viewing ttymon Port Monitor Status
# sacadm -l -p mbmon PMTAG PMTYPE FLGS RCNT STATUS COMMAND mbmon ttymon - 0 STARTING /usr/lib/saf/ttymon #TTY Ports a & b |
|
PMTAG mbmon |
Identifies the port monitor name, mbmon. |
|
PMTYPE ttymon |
Identifies the port monitor type, ttymon. |
|
FLGS - |
Indicates whether the following two flags are set: d, do not enable the new port monitor, or x, do not start the new port monitor. There are no flags set in this example. |
|
RCNT 0 |
Indicates the return count value. A return count of 0 indicates that the port monitor is not to be restarted if it fails. |
|
STATUS STARTING |
Indicates the current status of the port monitor. |
|
COMMAND /usr/lib/saf ... |
Identifies the command used to start the port monitor. |
|
#TTY Ports a & b |
Identifies any comment used to describe the port monitor. |
How to Stop a ttymon Port Monitor
To kill a ttymon port monitor, type the following:
# sacadm -k -p mbmon |
|
-k |
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 the following:
# sacadm -s -p mbmon |
|
-s |
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 the following:
# sacadm -d -p mbmon |
|
-d |
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 the following:
# sacadm -e -p mbmon |
|
-e |
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 the following:
# sacadm -r -p mbmon |
|
-r |
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 the following:
# 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.
|
-a |
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. The options in this embedded command are as follows:
|
-b |
The bidirectional port flag. |
|
-i |
Specifies the inactive (disabled) response message. |
|
-l |
Specifies which TTY label in the /etc/ttydefs file 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.
To list one service of a port monitor, type the following:
# pmadm -l -p mbmon -s a |
|
-l |
Lists service information. |
|
-p |
Specifies the pmtag mbmon as the port monitor tag. |
|
-s |
Specifies the svctag a as the port monitor service tag. |
To list all services of all port monitors, type the following:
# pmadm -l |
|
-l |
Lists service information |
To list all services of a port monitor, type the following:
# pmadm -l -p mbmon |
|
-l |
Lists service information |
|
-p |
Specifies the pmtag mbmon as the port monitor tag |
Example—Viewing the Status of a TTY Port Monitor Service
# pmadm -l -p mbmon PMTAG PMTYPE SVCTAG FLAGS ID <PMSPECIFIC> mbmon ttymon a - root /dev/term/a - - /usr/bin/login - contty ldterm,ttcompat login: Terminal disabled - y # |
|
mbmon |
Identifies the port monitor name, mbmon, set by using the pmadm -p command. |
|
ttymon |
Identifies the port monitor type, ttymon. |
|
a |
Indicates the service tag value set by using the pmadm -s command. |
|
- |
Identifies whether the following flags are set by using the pmadm -f command: x, which means do not enable the service; u, which means create a utmpx entry for the service. No flags are set in this example. |
|
root |
Identifies the ID assigned to the service when its started. This value is set by using the pmadm -i command. |
|
<PMSPECIFIC> Information |
|
|
/dev/term/a |
Indicates the TTY port pathname set by using the ttyadm -d command. |
|
- |
Indicates whether the following flags are set by using the ttyadm -c -b -h -I -r command: c, sets the connect on carrier flag for the port b, sets the port as bidirectional, allowing both incoming and outgoing traffic h, suppresses an automatic hangup immediately after an incoming call is received I, initializes the port r, forces ttymon to wait until it receives a character from the port before it prints the login: message. |
|
- |
Indicates a value set by using the ttyadm -r option. This option determines when ttymon displays a prompt after receiving data from a port. If count is 0, ttymon will wait until it receives any character. If count is greater than 0, ttymon will wait until count new lines have been received. No value is set in this example. |
|
/usr/bin/login |
Identifies the full pathname of the service to be invoked when a connected is received. This value is set by using ttyadm -s command. |
|
- |
Identifies the ttyadm -t command's (timeout) value. This option specifies that ttymon should close a port if the open on the port succeeds, and no input data is received in timeout seconds. There is no timeout value in this example. |
|
contty |
Identifies the TTY label in the /etc/ttydefs file. This value is set by using the ttyadm -l command. |
|
ldterm,ttcompat |
Identifies the STREAMS modules to be pushed. These modules are set by using the ttyadmin -m command. |
|
login: Terminal disabled |
Identifies an inactive message to be displayed when the port is disabled. This message is set by using the ttyadm -i command. |
|
tvi925 |
Identifies the terminal type, if set, by using the ttyadm -Tcommand. The terminal type is tvi925 in this example. |
|
y |
Identifies the software carrier value set by using the ttyadm -S command; n will turn software carrier off, y will turn software carrier on. Software carrier is turned on in this example. |
|
# |
Identifies any comment specified with the pmadm -y command. (There is no comment in this example). |
How to Enable a Port Monitor Service
To enable a disabled port monitor service, type the following:
# pmadm -e -p mbmon -s a |
|
-e |
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 the following:
# pmadm -d -p mbmon -s a |
|
-d |
The disable flag. |
|
-p |
Specifies the pmtag mbmon as the port monitor tag. |
|
-s |
Specifies the svctag a as the port monitor service tag. |
Service Access Facility Administration (Reference)
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 that 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 that contains port monitor-specific configuration data for the services pmtag provides. |
|
/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. |
The /etc/saf/_sactab File
The /etc/saf/_sactab looks like this:
# VERSION=1 zsmon:ttymon::0:/usr/lib/saf/ttymon # |
|
# VERSION=1 |
Indicates the Service Access Facility version number. |
|
zsmon |
Is the name of the port monitor. |
|
ttymon |
Is the type of port monitor. |
|
:: |
Indicates whether the following two flags are set: d, do not enable the port monitor x, do not start the port monitor. No flags are set in this example. |
|
0 |
Indicates the return code value. A return count of 0 indicates that the port monitor is not be restarted if it fails. |
|
/usr/lib/saf/ttymon |
Indicates the port monitor pathname. |
The /etc/saf/pmtab/_pmtab File
The /etc/saf/pmtab/_pmtab file, such as /etc/saf/zsmon/_pmtab, looks similar to the following:
# VERSION=1 ttya:u:root:reserved:reserved:reserved:/dev/term/a:I::/usr/bin/login::9600: ldterm,ttcompat:ttya login\: ::tvi925:y:# |
|
# VERSION=1 |
Indicates the Service Access Facility version number. |
|
ttya |
Indicates the service tag. |
|
x,u |
Identifies whether the following flags are set: x, which means do not enable the service. u, which means create a utmpx entry for the service. |
|
root |
Indicates the identity assigned to the service tag. |
|
reserved |
This field is reserved. |
|
reserved |
This field is reserved. |
|
reserved |
This field is reserved. |
|
/dev/term/a |
Indicates the TTY port pathname. |
|
/usr/bin/login |
Identifies the full pathname of the service to be invoked when a connection is received. |
|
:c,b,h,I,r: |
Indicates whether the following flags are set: c, sets the connect on carrier flag for the port b, sets the port as bidirectional, allowing both incoming and outgoing traffic h, suppresses an automatic hangup immediately after an incoming call is received I, initializes the port r, forces ttymon to wait until it receives a character from the port before it prints the login: message. |
|
9600 |
Identifies the TTY label defined in /etc/ttydefs file. |
|
ldterm,ttcompat |
Identifies the STREAMS modules to be pushed. |
|
ttya login\: |
Identifies the prompt to be displayed. |
|
:y/n: |
|
|
message |
Identifies any inactive (disabled) response message. |
|
tvi925 |
Identifies the terminal type. |
|
y |
Indicates whether software carrier is set (y/n). |
Service States
The sacadm command controls the states of services. The following table describes the possible states of services.
|
State |
Description |
|---|---|
|
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 -ssvctag |
Port Monitor States
The sacadm command controls the states of ttymon and listen port monitors. The following table describes the possible port monitor states.
|
State |
Description |
|---|---|
|
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. |
|
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 can be enabled or disabled depending on the state of the port monitor that controls them.
|
State |
Description |
|
|---|---|---|
|
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. |
- © 2010, Oracle Corporation and/or its affiliates