'\" te
.\"  Copyright 1989 AT&T Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved
.\" 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 pmadm 1M "10 Nov 1998" "SunOS 5.11" "System Administration Commands"
.SH NAME
pmadm \- port monitor administration
.SH SYNOPSIS
.LP
.nf
\fBpmadm\fR \fB-a\fR [\fB-p\fR \fIpmtag\fR | \fB-t\fR \fItype\fR] \fB-s\fR \fIsvctag\fR \fB-i\fR \fIid\fR \fB-m\fR \fIpmspecific\fR \fB-v\fR \fIver\fR 
     [\fB-f\fR xu] 
     [\fB-y\fR \fIcomment\fR] [\fB-z\fR \fI script\fR]
.fi

.LP
.nf
\fBpmadm\fR \fB-r\fR \fB-p\fR \fIpmtag\fR \fB-s\fR \fIsvctag\fR
.fi

.LP
.nf
\fBpmadm\fR \fB-e\fR \fB-p\fR \fIpmtag\fR \fB-s\fR \fIsvctag\fR
.fi

.LP
.nf
\fBpmadm\fR \fB-d\fR \fB-p\fR \fIpmtag\fR \fB-s\fR \fIsvctag\fR
.fi

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

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

.LP
.nf
\fBpmadm\fR \fB-g\fR \fB-p\fR \fIpmtag\fR \fB-s\fR \fIsvctag\fR [\fB-z\fR \fIscript\fR]
.fi

.LP
.nf
\fBpmadm\fR \fB-g\fR \fB-s\fR \fIsvctag\fR \fB-t\fR \fItype\fR \fB-z\fR \fIscript\fR
.fi

.SH DESCRIPTION
.sp
.LP
\fBpmadm\fR is the administrative command for the lower level of the Service
Access Facility hierarchy, that is, for service administration. A port may have
only one service associated with it although the same service may be available
through more than one port. In order to uniquely identify an instance of a
service, the \fBpmadm\fR command must identify both the port monitor or port
monitors through which the service is available (\fB-p\fR or \fB-t\fR) and the
service (\fB-s\fR). See .
.sp
.LP
\fBpmadm\fR performs the following functions:
.RS +4
.TP
.ie t \(bu
.el o
adds or removes a service
.RE
.RS +4
.TP
.ie t \(bu
.el o
enables or disables a service
.RE
.RS +4
.TP
.ie t \(bu
.el o
installs or replaces a per-service configuration script
.RE
.RS +4
.TP
.ie t \(bu
.el o
prints requested service information
.RE
.sp
.LP
Any user on the system may invoke \fBpmadm\fR to request service status
(\fB-l\fR or \fB-L\fR) or to print per-service configuration scripts (\fB-g\fR
without the \fB-z\fR option). \fBpmadm\fR with other options may be executed
only by a privileged user.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.na
\fB\fB-a\fR\fR
.ad
.RS 17n
.rt  
Add a service. \fBpmadm\fR adds an entry for the new service to the port
monitor's administrative file. 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 services.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-d\fR\fR
.ad
.RS 17n
.rt  
Disable a service. Add \fBx\fR to the flag field in the entry for the service
\fIsvctag\fR in the port monitor's administrative file. This is the entry used
by port monitor \fIpmtag\fR. See the \fB-f\fR option, below, for a description
of the flags available.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-e\fR\fR
.ad
.RS 17n
.rt  
Enable a service. Remove \fBx\fR from the flag field in the entry for the
service \fIsvctag\fR in the port monitor administrative file. This is the entry
used by port monitor \fIpmtag\fR. See the \fB-f\fR option, below, for a
description of the flags available.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-f\fR \fBxu\fR\fR
.ad
.RS 17n
.rt  
The \fB-f\fR option specifies one or both of the following two flags which are
then included in the flag field of the entry for the new service in the port
monitor's administrative file. If the \fB-f\fR option is not included, no flags
are set and the default conditions prevail. By default, a new service is
enabled and no \fButmpx\fR entry is created for it. An \fB-f\fR option without
a following argument is illegal.
.sp
.ne 2
.mk
.na
\fB\fBx\fR\fR
.ad
.RS 5n
.rt  
Do not enable the service \fIsvctag\fR available through port monitor
\fIpmtag\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBu\fR\fR
.ad
.RS 5n
.rt  
Create a \fButmpx\fR entry for service \fIsvctag\fR available through port
monitor \fIpmtag\fR.
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fB-g\fR\fR
.ad
.RS 17n
.rt  
Print, install, or replace a per-service configuration script. The \fB-g\fR
option with a \fB-p\fR option and a \fB-s\fR option prints the per-service
configuration script for service \fIsvctag\fR available through port monitor
\fIpmtag\fR. The \fB-g\fR option with a \fB-p\fR option, a \fB-s\fR option, and
a \fB-z\fR option installs the per-service configuration script contained in
the file \fBscript\fR as the per-service configuration script for service
\fIsvctag\fR available through port monitor \fIpmtag\fR. The \fB-g\fR option
with a \fB- s\fR option, a \fB-t\fR option, and a \fB-z\fR option installs the
file \fBscript\fR as the per-service configuration script for service
\fIsvctag\fR available through any port monitor of type \fBtype\fR. Other
combinations of options with \fB-g\fR are invalid.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-i\fR\fI id\fR\fR
.ad
.RS 17n
.rt  
\fBid\fR is the identity that is to be assigned to service \fIsvctag\fR when it
is started. \fBid\fR must be an entry in \fB/etc/passwd\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-l\fR\fR
.ad
.RS 17n
.rt  
The \fB-l\fR option requests service information. Used by itself and with the
options described below, it provides a filter for extracting information in
several different groupings.
.sp
.ne 2
.mk
.na
\fB\fB-l\fR\fR
.ad
.RS 23n
.rt  
By itself, the \fB-l\fR option lists all services on the system.
.RE

.sp
.ne 2
.mk
.na
\fB\fB\fR\fB-l\fR\fB \fR\fB-p\fR\fB \fR\fIpmtag\fR\fR
.ad
.RS 23n
.rt  
Lists all services available through port monitor \fIpmtag\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB\fR\fB-l\fR\fB \fR\fB-s\fR\fB \fR\fIsvctag\fR\fR
.ad
.RS 23n
.rt  
Lists all services with tag \fIsvctag\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB\fR\fB-l\fR\fB \fR\fB-p\fR\fB \fR\fIpmtag\fR\fB-s\fR\fIsvctag\fR\fR
.ad
.RS 23n
.rt  
Lists service \fIsvctag\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB\fR\fB-l\fR\fB \fR\fB-t\fR\fB \fR\fItype\fR\fR
.ad
.RS 23n
.rt  
Lists all services available through port monitors of type \fBtype\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fB\fR\fB-l\fR\fB \fR\fB-t\fR\fB \fR\fItype\fR\fB-s\fR\fIsvctag\fR\fR
.ad
.RS 23n
.rt  
Lists all services with tag \fIsvctag\fR available through a port monitor of
type \fBtype\fR.
.RE

Other combinations of options with \fB-l\fR are invalid.
.RE

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

.sp
.ne 2
.mk
.na
\fB\fB-m\fR\fI pmspecific\fR\fR
.ad
.RS 17n
.rt  
\fIpmspecific\fR is the port monitor-specific portion of the port monitor
administrative file entry for the service.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-p\fR\fI pmtag\fR\fR
.ad
.RS 17n
.rt  
Specifies the tag associated with the port monitor through which a service
(specified as \fB\fR\fB-s\fR\fB \fR\fIsvctag\fR) is available.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-r\fR\fR
.ad
.RS 17n
.rt  
Remove a service. When \fBpmadm\fR removes a service, the entry for the service
is removed from the port monitor's administrative file.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-s\fR\fI svctag\fR\fR
.ad
.RS 17n
.rt  
Specifies the service tag associated with a given service. The service tag is
assigned by the system administrator and is part of the entry for the service
in the port monitor's administrative file.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-t\fR\fI type\fR\fR
.ad
.RS 17n
.rt  
Specifies the port monitor type.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-v\fR\fI ver\fR\fR
.ad
.RS 17n
.rt  
Specifies the version number of the port monitor administrative file. The
version number may be given as
.sp
.in +2
.nf
\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
.mk
.na
\fB\fB-y\fR\fI comment\fR\fR
.ad
.RS 17n
.rt  
Associate \fIcomment\fR with the service entry in the port monitor
administrative file.
.RE

.sp
.ne 2
.mk
.na
\fB\fB-z\fR\fI script\fR\fR
.ad
.RS 17n
.rt  
Used with the \fB-g\fR option to specify the name of the file that contains the
per-service configuration script. Modifying a configuration script is a
three-step procedure. First a copy of the existing script is made (\fB-g\fR
alone). Then the copy is edited. Finally, the copy is put in place over the
existing script (\fB-g\fR with \fB-z\fR).
.RE

.sp
.LP
Options that request information write the requested information to the
standard output. A request for information using the \fB-l\fR option prints
column headers and aligns the information under the appropriate headings. In
this format, a missing field is indicated by a hyphen. A request for
information in the condensed format using the \fB-L\fR option prints the
information in colon-separated fields; missing fields are indicated by two
successive colons. \fB#\fR is the comment character.
.SH EXAMPLES
.LP
\fBExample 1 \fRAdding a Service to a Port Monitor with the Tag \fBpmtag\fR
.sp
.LP
The following command adds a service to a port monitor with tag \fBpmtag\fR and
gives the service the tag \fBsvctag\fR. The port monitor-specific information
is generated by \fBspecpm\fR. The service defined by \fBsvctag\fR will be
invoked with identity \fBroot\fR.

.sp
.in +2
.nf
pmadm -a -p pmtag -s svctag -i root -m `specpm -a arg1 -b arg2`-v `specpm -V`
.fi
.in -2
.sp

.LP
\fBExample 2 \fRAdding a Service with Service Tab \fBsvctag\fR
.sp
.LP
The following command adds a service with service tag \fBsvctag\fR, identity
\fBguest\fR, and port monitor-specific information generated by \fBspecpm\fR to
all port monitors of type \fBtype\fR:

.sp
.in +2
.nf
pmadm -a -s svctag -i guest -t type -m `specpm -a arg1 -b arg2`-v `specpm -V`
.fi
.in -2
.sp

.LP
\fBExample 3 \fRRemoving a Service
.sp
.LP
The following command removes the service \fBsvctag\fR from port monitor
\fBpmtag\fR:

.sp
.in +2
.nf
pmadm -r -p pmtag -s svctag
.fi
.in -2
.sp

.LP
\fBExample 4 \fREnabling a Service
.sp
.LP
The following command enables the service \fBsvctag\fR available through port
monitor \fBpmtag\fR:

.sp
.in +2
.nf
pmadm -e -p pmtag -s svctag
.fi
.in -2
.sp

.LP
\fBExample 5 \fRDisabling a Service
.sp
.LP
The following command disables the service \fBsvctag\fR available through port
monitor \fBpmtag\fR:

.sp
.in +2
.nf
pmadm -d -p pmtag -s svctag
.fi
.in -2
.sp

.LP
\fBExample 6 \fRListing Status Information
.sp
.LP
The following command lists status information for all services:

.sp
.in +2
.nf
pmadm -l
.fi
.in -2
.sp

.LP
\fBExample 7 \fRListing Status Information
.sp
.LP
The following command lists status information for all services available
through the port monitor with tag \fBports\fR:

.sp
.in +2
.nf
pmadm -l -p ports
.fi
.in -2
.sp

.LP
\fBExample 8 \fRListing Status Information in Condensed Format
.sp
.LP
The following command lists the status information for all services available
through the port monitor with tag \fBports\fR in condensed format:

.sp
.in +2
.nf
pmadm -L -p ports
.fi
.in -2
.sp

.LP
\fBExample 9 \fRListing Status Information for All Services
.sp
.LP
List status information for all services available through port monitors of
type \fBlisten\fR:

.sp
.in +2
.nf
pmadm -l -t listen
.fi
.in -2
.sp

.LP
\fBExample 10 \fRPrinting the per-service Configuration
.sp
.LP
The following command prints the per-service configuration script associated
with the service \fBsvctag\fR available through port monitor \fBpmtag\fR:

.sp
.in +2
.nf
pmadm -g -p pmtag -s svctag
.fi
.in -2
.sp

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.mk
.na
\fB\fB0\fR\fR
.ad
.RS 6n
.rt  
Successful operation.
.RE

.sp
.ne 2
.mk
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
.rt  
Operation failed.
.RE

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

.RE

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

.RE

.sp
.ne 2
.mk
.na
\fB\fB/var/saf/\fR\fIpmtag\fR\fB/*\fR\fR
.ad
.RS 26n
.rt  

.RE

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