path: root/usr/src/man/man1m/sacadm.1m

'\" te
.\" Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 1989 AT&T
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH SACADM 1M "Sep 14, 1992"
.SH NAME
sacadm \- service access controller administration
.SH SYNOPSIS
.LP
.nf
\fBsacadm\fR \fB-a\fR \fB-p\fR \fIpmtag\fR \fB-t\fR \fItype\fR \fB-c\fR \fIcmd\fR \fB-v\fR \fIver\fR [\fB-f\fR dx] [\fB-n\fR \fIcount\fR]
     [\fB-y\fR \fIcomment\fR] [\fB-z\fR \fIscript\fR]
.fi

.LP
.nf
\fBsacadm\fR \fB-r\fR \fB-p\fR \fIpmtag\fR
.fi

.LP
.nf
\fBsacadm\fR \fB-s\fR \fB-p\fR \fIpmtag\fR
.fi

.LP
.nf
\fBsacadm\fR \fB-k\fR \fB-p\fR \fIpmtag\fR
.fi

.LP
.nf
\fBsacadm\fR \fB-e\fR \fB-p\fR \fIpmtag\fR
.fi

.LP
.nf
\fBsacadm\fR \fB-d\fR \fB-p\fR \fIpmtag\fR
.fi

.LP
.nf
\fBsacadm\fR \fB-l\fR [\fB-p\fR \fIpmtag\fR | \fB-t\fR \fItype\fR]
.fi

.LP
.nf
\fBsacadm\fR \fB-L\fR [\fB-p\fR \fIpmtag\fR | \fB-t\fR \fItype\fR]
.fi

.LP
.nf
\fBsacadm\fR \fB-g\fR \fB-p\fR \fIpmtag\fR [\fB-z\fR \fIscript\fR]
.fi

.LP
.nf
\fBsacadm\fR \fB-G\fR [\fB-z\fR \fIscript\fR]
.fi

.LP
.nf
\fBsacadm\fR \fB-x\fR [\fB-p\fR \fIpmtag\fR]
.fi

.SH DESCRIPTION
.sp
.LP
\fBsacadm\fR is the administrative command for the upper level of the Service
Access Facility hierarchy (port monitor administration). \fBsacadm\fR performs
the following functions:
.RS +4
.TP
.ie t \(bu
.el o
adds or removes a port monitor
.RE
.RS +4
.TP
.ie t \(bu
.el o
starts or stops a port monitor
.RE
.RS +4
.TP
.ie t \(bu
.el o
enables or disables a port monitor
.RE
.RS +4
.TP
.ie t \(bu
.el o
installs or replaces a per-system configuration script
.RE
.RS +4
.TP
.ie t \(bu
.el o
installs or replaces a per-port monitor configuration script
.RE
.RS +4
.TP
.ie t \(bu
.el o
prints requested port monitor information
.RE
.sp
.LP
Requests about the status of port monitors (\fB-l\fR and \fB-L\fR) and requests
to print per-port monitor and per-system configuration scripts (\fB-g\fR and
\fB-G\fR without the \fB-z\fR option) may be executed by any user on the
system. Other \fBsacadm\fR commands may be executed only by the super-user.
.SH OPTIONS
.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.RS 14n
Add a port monitor. When adding a port monitor, \fBsacadm\fR creates the
supporting directory structure in \fB/etc/saf\fR and \fB/var/saf\fR and adds an
entry for the new port monitor to \fB/etc/saf/_sactab\fR. The file
\fB_sactab\fR already exists on the delivered system. Initially, it is empty
except for a single line, which contains the version number of the Service
Access Controller. Unless the command line that adds the new port monitor
includes the \fB-f\fR option with the \fB-x\fR argument, the new port monitor
will be started. Because of the complexity of the options and arguments that
follow the \fB- a\fR option, it may be convenient to use a command script or
the menu system to add port monitors.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR \fIcmd\fR\fR
.ad
.RS 14n
Execute the command string \fIcmd\fR to start a port monitor. The \fB-c\fR
option may be used only with a \fB-a\fR. A \fB-a\fR option requires a \fB-c\fR.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR\fR
.ad
.RS 14n
Disable the port monitor \fIpmtag\fR.
.RE

.sp
.ne 2
.na
\fB\fB-e\fR\fR
.ad
.RS 14n
Enable the port monitor \fIpmtag\fR.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR \fBdx\fR\fR
.ad
.RS 14n
The \fB-f\fR option  specifies one or both of the following two flags which are
then included in the flags field of the \fB_sactab\fR entry for the new port
monitor. If the \fB-f\fR option is not included on the command line, no flags
are set and the default conditions prevail. By default, a port monitor is
started. A \fB-f\fR option with no following argument is illegal.
.sp
.ne 2
.na
\fBd\fR
.ad
.RS 5n
Do not enable the new port monitor.
.RE

.sp
.ne 2
.na
\fBx\fR
.ad
.RS 5n
Do not start the new port monitor.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-g\fR\fR
.ad
.RS 14n
The \fB-g\fR option is used to request output or to install or replace the
per-port monitor configuration script \fB/etc/saf/\fR\fIpmtag\fR\fB/_config\fR.
\fB-g\fR requires a \fB-p\fR option. The \fB-g\fR option with only a \fB-p\fR
option prints the per-port monitor configuration script for port monitor
\fIpmtag\fR. The \fB-g\fR option with a \fB-p\fR option and a \fB-z\fR option
installs  the file \fBscript\fR as the per-port monitor configuration script
for port monitor \fIpmtag\fR. Other combinations of options with \fB-g\fR are
invalid.
.RE

.sp
.ne 2
.na
\fB\fB-G\fR\fR
.ad
.RS 14n
The \fB-G\fR option is used to request output or to install or replace the
per-system configuration script \fB/etc/saf/_sysconfig\fR. The \fB-G\fR option
by itself prints the per-system configuration script. The \fB-G\fR option in
combination with a \fB-z\fR option  installs the file \fBscript\fR as the
per-system configuration script. Other combinations of options with a \fB-G\fR
option are invalid.
.RE

.sp
.ne 2
.na
\fB\fB-k\fR\fR
.ad
.RS 14n
Stop port monitor \fIpmtag\fR.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.RS 14n
The \fB-l\fR option is used to request port monitor information. The \fB-l\fR
by itself lists all port monitors on the system. The \fB-l\fR option in
combination with the \fB-p\fR option lists only the port monitor specified by
\fIpmtag\fR. A \fB-l\fR in combination with the \fB-t\fR option lists all port
monitors of type \fBtype\fR. Any other combination of options with the \fB-l\fR
option is invalid.
.RE

.sp
.ne 2
.na
\fB\fB-L\fR\fR
.ad
.RS 14n
The \fB-L\fR option is identical to the \fB-l\fR option except that the output
appears in a condensed format.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR \fIcount\fR\fR
.ad
.RS 14n
Set the restart count to \fIcount\fR. If a restart count is not specified,
count is set to \fB0\fR. A count of \fB0\fR indicates that the port monitor is
not to be restarted if it fails.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR \fIpmtag\fR\fR
.ad
.RS 14n
Specifies the tag associated with a port monitor.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR\fR
.ad
.RS 14n
Remove port monitor \fIpmtag\fR. \fBsacadm\fR removes the port monitor entry
from \fB/etc/saf/_sactab\fR. If the removed port monitor is not running, then
no further action is taken. If the removed port monitor is running, the Service
Access Controller (SAC) sends it \fBSIGTERM\fR to indicate that it should shut
down. Note that the port monitor's directory structure remains intact.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.RS 14n
Start a port monitor. The SAC starts the port monitor \fIpmtag\fR.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR \fBtype\fR\fR
.ad
.RS 14n
Specifies the port monitor type.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR \fBver\fR\fR
.ad
.RS 14n
Specifies the version number of the port monitor. This version number may be
given as
.sp
.in +2
.nf
\fB\fR\fB-v\fR\fB `\fR\fIpmspec\fR \fB-V\fR`
.fi
.in -2
.sp

where \fIpmspec\fR is the special administrative command for port monitor
\fIpmtag\fR. This special command is \fBttyadm\fR for \fBttymon\fR and
\fBnlsadmin\fR for \fBlisten\fR. The version stamp of the port monitor is known
by the command and is returned when \fIpmspec\fR is invoked with a \fB-V\fR
option.
.RE

.sp
.ne 2
.na
\fB\fB-x\fR\fR
.ad
.RS 14n
The \fB-x\fR option by itself  tells the SAC to read its database file
(\fB_sactab\fR). The \fB-x\fR option with the \fB-p\fR option tells port
monitor \fIpmtag\fR to read its administrative file.
.RE

.sp
.ne 2
.na
\fB\fB-y\fR \fIcomment\fR\fR
.ad
.RS 14n
Include \fIcomment\fR in the \fB_sactab\fR entry for port monitor \fIpmtag\fR.
.RE

.sp
.ne 2
.na
\fB\fB-z\fR \fBscript\fR\fR
.ad
.RS 14n
Used with the \fB-g\fR and \fB-G\fR options to specify the name of a file that
contains a configuration script. With the \fB-g\fR option, \fBscript\fR is a
per-port monitor configuration script; with \fB-G\fR it is a per-system
configuration script. Modifying a configuration script is a three-step
procedure. First a copy of the existing script is made (\fB-g\fR or \fB-G\fR).
Then the copy is edited. Finally, the copy is put in place over the existing
script (\fB-g\fR or \fB-G\fR with \fB-z\fR).
.RE

.SH OUTPUT
.sp
.LP
If successful, \fBsacadm\fR will exit with a status of \fB0\fR. If \fBsacadm\fR
fails for any reason, it will exit with a nonzero status. Options that request
information will write the information on the standard output. In the condensed
format (\fB-L\fR), port monitor information is printed as a sequence of
colon-separated fields; empty fields are indicated by two successive colons.
The standard format (\fB-l\fR) prints a header identifying the columns, and
port monitor information is aligned under the appropriate headings. In this
format, an empty field is indicated by a hyphen. The comment character is
\fB#\fR.
.SH EXAMPLES
.LP
\fBExample 1 \fRA sample output of the \fBsacadm\fR command.
.sp
.LP
The following command line adds a port monitor. The port monitor tag is
\fBnpack\fR; its type is \fBlisten\fR; if necessary, it will restart three
times before failing; its administrative command is \fBnlsadmin\fR; and the
configuration script to be read is in the file \fBscript\fR:

.sp
.in +2
.nf
\fBsacadm \fR\fB-a\fR\fB \fR\fB-p\fR\fB npack \fR\fB-t\fR\fB listen \fR\fB-c\fR\fB /usr/lib/saf/listen npack\fR
\fB\fR\fB-v\fR\fB `nlsadmin \fR\fB-V\fR\fB` \fR\fB-n\fR\fB 3 \fR\fB-z\fR\fB script\fR
.fi
.in -2
.sp

.sp
.LP
Remove a port monitor whose tag is \fBpmtag\fR:

.sp
.in +2
.nf
\fBsacadm\fR \fB-r\fR \fB-p\fR \fBpmtag\fR
.fi
.in -2
.sp

.sp
.LP
Start the port monitor whose tag is \fBpmtag\fR:

.sp
.in +2
.nf
\fBsacadm\fR \fB-s\fR \fB-p\fR \fBpmtag\fR
.fi
.in -2
.sp

.sp
.LP
Stop the port monitor whose tag is \fBpmtag\fR:

.sp
.in +2
.nf
\fBsacadm\fR \fB-k\fR \fB-p\fR \fBpmtag\fR
.fi
.in -2
.sp

.sp
.LP
Enable the port monitor whose tag is \fBpmtag\fR:

.sp
.in +2
.nf
\fBsacadm\fR \fB-e\fR \fB-p\fR \fBpmtag\fR
.fi
.in -2
.sp

.sp
.LP
Disable the port monitor whose tag is \fBpmtag\fR:

.sp
.in +2
.nf
\fBsacadm\fR \fB-d\fR \fB-p\fR \fBpmtag\fR
.fi
.in -2
.sp

.sp
.LP
List status information for all port monitors:

.sp
.in +2
.nf
\fBsacadm\fR \fB-l\fR
.fi
.in -2
.sp

.sp
.LP
List status information for the port monitor whose tag is \fBpmtag\fR:

.sp
.in +2
.nf
\fBsacadm\fR \fB-l\fR \fB-p\fR \fBpmtag\fR
.fi
.in -2
.sp

.sp
.LP
List the same information in condensed format:

.sp
.in +2
.nf
\fBsacadm\fR \fB-L\fR \fB-p\fR \fBpmtag\fR
.fi
.in -2
.sp

.sp
.LP
List status information for all port monitors whose type is \fBlisten\fR:

.sp
.in +2
.nf
\fBsacadm\fR \fB-l\fR \fB-t\fR \fBlisten\fR
.fi
.in -2
.sp

.sp
.LP
Replace the per-port monitor configuration script associated with the port
monitor whose tag is \fBpmtag\fR with the contents of the file
\fBfile.config\fR:

.sp
.in +2
.nf
\fBsacadm\fR \fB-g\fR \fB-p\fR \fBpmtag\fR \fB-z\fR \fBfile.config\fR
.fi
.in -2
.sp

.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/saf/_sactab\fR\fR
.ad
.RS 26n

.RE

.sp
.ne 2
.na
\fB\fB/etc/saf/_sysconfig\fR\fR
.ad
.RS 26n

.RE

.sp
.ne 2
.na
\fB\fB/etc/saf/\fIpmtag\fR\fR\fB/_config\fR\fR
.ad
.RS 26n

.RE

.SH SEE ALSO
.sp
.LP
\fBpmadm\fR(1M), \fBsac\fR(1M), \fBdoconfig\fR(3NSL), \fBattributes\fR(5)