muxmon(1M) muxmon(1M)
NAME
muxmon - DPTG2 monitor
SYNOPSIS
/usr/lib/saf/muxmon [-d level] [-f file] [-t sec] [-r retry]
/usr/lib/saf/muxmon -?
DESCRIPTION
muxmon is a port monitor based on TTY-STREAMS, as prescribed by System
V Release 4 through SAF (Service Access Facility). muxmon's job is to
monitor links to the terminals, which are operated using the DPTG2
protocol. muxmon is designed such that it usually only runs under the
control of the SAC (Service Access Controller) [see sac(1M)]. muxmon
can be operated using the sacadm(1M) and pmadm(1M) commands. DPTG2-
specific commands and formats can be executed using the muxadm(1M)
command.
The basic functions of muxmon are:
1) General control of monitor processes
This function controls the actual selection of the monitor. Under
SAF, the monitor has 2 internal statuses: ENABLED and DISABLED.
The monitor is started in either of the two statuses from SAC.
The status taken when the monitor is started defines the sactab
entry. If DISABLED, none of the ports is monitored. If ENABLED,
all terminals listed in the pmtab file are monitored. The moni-
tor is terminated using a SIGTERM(15) signal.
2) Monitoring of links
Each entry in the monitor pmtab file describes a link to a DPTG2
terminal. In accordance with this entry, the monitor opens the
link to the terminal and monitors its status. The multiplexer is
activated when the terminal is switched on (ILINK) [see
termio(7)]. The multiplexer is disconnected when the terminal is
switched off (IUNLINK) [see termio(7)]. When the monitor status
is DISABLED or the pmtab entry reads x=disable, the multiplexer
administrator channel is closed.
3) Execution of tasks
A load service can be specified in the terminal pmtab entry. If
required (e.g. when operating a 9766 terminal), the program to be
loaded can be indicated using the name of a workstation program
(e.g. xb4D). If N is selected, the load service is switched off.
If Y is selected, the terminal can specify with which program it
is to to be loaded. Loading is always completed prior to activa-
tion of the multiplexer (ILINK). Until loading is completed, an
open system call is blocked on the user channels.
Page 1 Reliant UNIX 5.44 Printed 11/98
muxmon(1M) muxmon(1M)
OPTIONS
If muxmon is invoked and options have not been specified, the follow-
ing default values apply:
-d level
This option sets the trace level to a value of level. If the
value is greater than 2, it is reduced to 2. The default value is
0.
-f file
This option can be used to select the file trace file instead of
the /var/saf/pmtag/trace default file.
-t sec
This option sets the timeout for repetitions to sec. If sec is
less than 60 seconds, it is increased to 60. The default value is
90 seconds.
-r retry
In all error situations, the links are reset to the corresponding
connecting terminals (service ID) for a timeout [see option -t].
When the timeout has expired, an attempt is made to reestablish
the link. In the event of a further error, the entire process is
repeated. The process is repeated MAXRETRY times. If all attempts
fail, the service ID is DISABLED. The default for MAXRETRY is 12.
This option can be used to change the default value when the mon-
itor is started.
The retry argument can have any integer value. However, values
lower than 5 are increased to 5. In the case of negative values,
the absolute value applies. If -1 is selected, continuous
attempts are made to reestablish the link. Only the first and
last attempts are recorded in the /var/saf/pmtag/log logging
interface. Thus, in the case of a -1 value, only the first
attempt is recorded.
-? Command syntax is displayed on stderr.
DIAGNOSTICS/MAINTENANCE
For diagnostic purposes, the monitor keeps a private logging file
called log in the /var/saf/pmtag directory. This file can only be
edited by the monitor. This log file records the SAC commands, status
changes and error situations.
As a Reliant UNIX system component, the DPTG2 monitor also writes all
of these log records to the Reliant UNIX logbook. They are filed under
component number 36 and error number 6. As the muxmon files all of its
messages under this error number, the repetition counter in the log-
ging system for the component group should generally be switched off.
Page 2 Reliant UNIX 5.44 Printed 11/98
muxmon(1M) muxmon(1M)
To facilitate the search for errors, it is possible to operate the
monitor in a trace (debugging) mode. To do this, a file is specified
under option -f which contains the trace information. If the -f is not
used, the monitor writes this trace information to trace in the
/var/saf/pmtag directory. The trace mode is activated by the -d option
when the monitor is started. It can also be activated dynamically by
signals later at runtime. Trace mode can be operated at 3 levels:
0 No trace output.
1 Output only in the case of error.
2 Full trace output, which can be used to trace the operational
course of the monitor.
These traces are intended only for diagnostic use by developers. Trace
mode should only be activated when required.
The SIGUSR1(16) signal increases the trace level by one. SIGUSR2(17)
sets the trace level to 0. Trace level can also be set using the -d
option at monitor start. There is no administration of the trace file.
This means that trace mode should not be activated under normal
operating conditions (level 0), otherwise the trace file could over-
flow.
The status of the links to be monitored are written to a status file
called state by the SIGHUP(1) signal, which is located in the
/var/saf/pmtag directory. Previous status entries in the file are
overwritten.
The state file has the following format:
DPTG-monitor 'pmtag' (pid=number) state: pmstate
whereby pmtag denotes the name of the monitor incarnation. The PID
number is the current process ID, pmstate can accept both PMDISABLED
and PMENABLED.
The entry for each link to be monitored occupies one line. There are
different formats according to the type of entry.
A remote link looks like this:
no. svrtag: admin path, [state] host 'name' port portno => status
and a direct link:
no. svrtag: admin path, local device 'name' => status
Page 3 Reliant UNIX 5.44 Printed 11/98
muxmon(1M) muxmon(1M)
The format fields are as follows:
no The serial number of an entry.
svrtag The symbolical tag name for the link (service ID).
path Path name of administrator channel to multiplexer.
state For remote links, the availability of the host is tested from
time to time. The result of the most recent check is
displayed here.
name For direct links, the path name of the serial terminal con-
nection is displayed here. For remote links, the host name is
displayed here as entered in the pmtab file.
portno For remote links, the port number for the remote host is
displayed here.
status This field shows the status of the terminal connection as
read by the monitor. The options are:
SUSPENDED An error occurred in establishing the link. The
reason for the suspension is always indicated
after the keyword reason:
DISABLED This status is registered when an attempt to re-
establish a connection MAXRETRY has failed once.
The reason for the most recent failure is indi-
cated after the keyword reason:
ACTIVATED This indicates that a connection establishment
sequence has begun. The administrator channel is
already open, and the monitor is waiting for con-
firmation of an "Open" or acceptance of a "Con-
nect".
CONNECTED This status indicates that a link has been esta-
blished with the terminal.
LOADING Contact has been established with the terminal and
loading is in process.
LINKED The terminal is available and loaded. It is ready
for DPTG2 operation.
WARNING
Trace mode should only be switched on for a short period of time, so
that the trace file does not overflow.
Page 4 Reliant UNIX 5.44 Printed 11/98
muxmon(1M) muxmon(1M)
DIAGNOSTICS
If no error occurs, muxmon terminates with a return value of 0. In the
event of an error, the return values have the following meanings.
1 = An illegal option was used (EILLOPT)
2 = The pid file could not be opened (EPID)
3 = The log file could not be opened (ELOG)
4 = No exclusive access to the pid file (EPLOCK)
5 = No exclusive access to the log file (ELLOCK)
6 = An internal pipe could not be opened (EPIPE)
7 = Illegal monitor start status (EISTATE)
8 = pmpipe file not available (EPIPE)
9 = sacpipe file not available (ESACPIPE)
10 = Error reading pmpipe file (EERROR)
11 = Error reading sacpipe file (ESACMSG)
12 = Wrong format version in pmtab file (EVERSION)
FILES
/etc/saf/sactab
/etc/saf/sacpipe
/etc/saf/pmtag/pmtab
/etc/saf/pmtag/pmpipe
/var/saf/pmtag/state
/var/saf/pmtag/log
/var/saf/pmtag/trace
SEE ALSO
muxadm(1M), sac(1M), sacadm(1M), dptg2(7), termio(7).
Page 5 Reliant UNIX 5.44 Printed 11/98