'\" te
.\"  Copyright 1989 AT&T  Copyright (c) 1997 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 NLSADMIN 1M "Apr 3, 1997"
.SH NAME
nlsadmin \- network listener service administration
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/nlsadmin\fR \fB-x\fR
.fi

.LP
.nf
\fB/usr/sbin/nlsadmin\fR [\fIoptions\fR] \fInet_spec\fR
.fi

.LP
.nf
\fB/usr/sbin/nlsadmin\fR [\fIoptions\fR] \fB-N\fR \fIport_monitor_tag\fR
.fi

.LP
.nf
\fB/usr/sbin/nlsadmin\fR \fB-V\fR
.fi

.LP
.nf
\fB/usr/sbin/nlsadmin\fR \fB-c\fR \fIcmd\fR | \fB-o\fR \fIstreamname\fR [\fB-p\fR \fImodules\fR]
     [\fB-A\fR \fIaddress\fR | \fB-D\fR] [\fB-R\fR \fIprognum\fR : \fIversnum\fR]
.fi

.SH DESCRIPTION
.sp
.LP
\fBnlsadmin\fR is the administrative command for the network listener
process(es) on a machine. Each network has at least one instance of the network
listener process associated with it; each instance (and thus, each network) is
configured separately. The listener process ``listens'' to the network for
service requests, accepts requests when they arrive, and invokes servers in
response to those service requests. The network listener process may be used
with any network (more precisely, with any connection-oriented transport
provider) that conforms to the transport provider specification.
.sp
.LP
\fBnlsadmin\fR can establish a listener process for a given network, configure
the specific attributes of that listener, and start and kill the listener
process for that network. \fBnlsadmin\fR can also report on the listener
processes on a machine, either individually (per network) or collectively.
.sp
.LP
\fInet_spec\fR represents a particular listener process. Specifically,
\fInet_spec\fR is the relative path name of the entry under \fB/dev\fR for a
given network (that is, a transport provider). \fIaddress\fR is a transport
address on which to listen and is interpreted using a syntax that allows for a
variety of address formats. By default, \fIaddress\fR is interpreted as the
symbolic ASCII representation of the transport address. An \fIaddress\fR
preceded by \fB\ex\fR will let you enter an address in hexadecimal notation.
Note that \fIaddress\fR must appear as a single word to the shell, thus it must
be quoted if it contains any blanks.
.sp
.LP
Changes to the list of services provided by the listener or the addresses of
those services are put into effect immediately.
.SH OPTIONS
.sp
.LP
\fBnlsadmin\fR may be used with the following combinations of options and
arguments:
.sp
.ne 2
.na
\fB\fB-x\fR\fR
.ad
.sp .6
.RS 4n
Report the status of all of the listener processes installed on this machine.
.RE

.sp
.ne 2
.na
\fB\fInet_spec\fR\fR
.ad
.sp .6
.RS 4n
Print the status of the listener process for \fInet_spec\fR \fI\&.\fR
.RE

.sp
.ne 2
.na
\fB\fB-q\fR \fInet_spec\fR\fR
.ad
.sp .6
.RS 4n
Query the status of the listener process for the specified network, and
reflects the result of that query in its exit code. If a listener process is
active, \fBnlsadmin\fR will exit with a status of \fB0\fR; if no process is
active, the exit code will be \fB1\fR; the exit code will be greater than
\fB1\fR in case of error.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR \fInet_spec\fR\fR
.ad
.sp .6
.RS 4n
Print a verbose report on the servers associated with \fInet_spec,\fR giving
the service code, status, command, and comment for each. It also specifies the
\fBuid\fR the server will run as and the list of modules to be pushed, if any,
before the server is started.
.RE

.sp
.ne 2
.na
\fB\fB-z\fR \fIservice_code net_spec\fR\fR
.ad
.sp .6
.RS 4n
Print a report on the server associated with \fInet_spec\fR that has service
code \fIservice_code,\fR giving the same information as in the \fB-v\fR option.
.RE

.sp
.ne 2
.na
\fB\fB\fR\fB-q\fR\fB \fR\fB-z\fR \fIservice_code net_spec\fR\fR
.ad
.sp .6
.RS 4n
Query the status of the service with service code \fIservice_code\fR on network
\fInet_spec,\fR and exits with a status of \fB0\fR if that service is enabled,
\fB1\fR if that service is disabled, and greater than \fB1\fR in case of error.
.RE

.sp
.ne 2
.na
\fB\fB\fR\fB-l\fR \fIaddress net_spec\fR\fR
.ad
.sp .6
.RS 4n
Change or set the transport address on which the listener listens (the general
listener service). This address can be used by remote processes to access the
servers available through this listener (see the \fB-a\fR option, below).
.sp
If \fIaddress\fR is just a dash (" \(mi "), \fBnlsadmin\fR reports the address
currently configured, instead of changing it.
.sp
A change of address takes effect immediately.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR \fIaddress net_spec\fR\fR
.ad
.sp .6
.RS 4n
Change or set the address on which the listener listens for requests for
terminal service but is otherwise similar to the \fB-l\fR option above. A
terminal service address should not be defined unless the appropriate remote
login software is available; if such software is available, it must be
configured as service code 1 (see the \fB-a\fR option, below).
.RE

.sp
.ne 2
.na
\fB\fB-i\fR \fInet_spec\fR\fR
.ad
.sp .6
.RS 4n
Initialize an instance of the listener for the network specified by
\fInet_spec;\fR that is, create and initialize the files required by the
listener as well as starting that instance of the listener. Note that a
particular instance of the listener should be initialized only once. The
listener must be initialized before assigning addresses or services.
.RE

.sp
.ne 2
.na
\fB\fB-a\fR \fIservice_code\fR\fR
.ad
.sp .6
.RS 4n
[ \fB-p\fR \fImodules\fR ] [  \fB-w\fR \fIname\fR ] \fB-c\fR \fIcmd\fR \fB-y\fR
\fIcomment net_spec\fR
.sp
Add a new service to the list of services available through the indicated
listener. \fIservice_code\fR is the code for the service, \fIcmd\fR is the
command to be invoked in response to that service code, comprised of the full
path name of the server and its arguments, and \fIcomment\fR is a brief
(free-form) description of the service for use in various reports. Note that
\fIcmd\fR must appear as a single word to the shell; if arguments are required,
the \fIcmd\fR and its arguments must be enclosed in quotation marks. The
\fIcomment\fR must also appear as a single word to the shell. When a service is
added, it is initially enabled (see the \fB-e\fR and \fB-d\fR options, below).
.sp
Service codes are alphanumeric strings, and are administered by AT&T. The
numeric service codes 0 through 100 are reserved for internal use by the
listener. Service code 0 is assigned to the nlps server, which is the service
invoked on the general listening address. In particular, code 1 is assigned to
the remote login service, which is the service automatically invoked for
connections to the terminal login address.
.sp
If the \fB-p\fR option is specified, then \fImodules\fR will be interpreted as
a list of \fBSTREAMS\fR modules for the listener to push before starting the
service being added. The modules are pushed in the order they are specified.
\fImodules\fR should be a comma-separated list of modules, with no white space
included.
.sp
If the \fB-w\fR option is specified, then \fIname\fR is interpreted as the user
name from \fB/etc/passwd\fR that the listener should look up. From the user
name, the listener obtains the user ID, the group ID(s), and the home directory
for use by the server. If \fB-w\fR is not specified, the default is to use the
user name \fBlisten.\fR
.sp
A service must explicitly be added to the listener for each network on which
that service is to be available. This operation will normally be performed only
when the service is installed on a machine, or when populating the list of
services for a new network.
.RE

.sp
.ne 2
.na
\fB\fB\fR\fB-r\fR \fIservice_code net_spec\fR\fR
.ad
.sp .6
.RS 4n
Remove the entry for the \fIservice_code\fR from that listener's list of
services. This is normally done only in conjunction with the de-installation of
a service from a machine.
.RE

.sp
.ne 2
.na
\fB\fB\fR\fB-e\fR \fIservice_code net_spec\fR\fR
.ad
.br
.na
\fB\fB\fR\fB-d\fR \fIservice_code net_spec\fR\fR
.ad
.sp .6
.RS 4n
Enable or disable (respectively) the service indicated by \fIservice_code\fR
for the specified network. The service must previously have been added to the
listener for that network (see the \fB-a\fR option, above). Disabling a service
will cause subsequent service requests for that service to be denied, but the
processes from any prior service requests that are still running will continue
unaffected.
.RE

.sp
.ne 2
.na
\fB\fB\fR\fB-s\fR \fInet_spec\fR\fR
.ad
.br
.na
\fB\fB\fR\fB-k\fR \fInet_spec\fR\fR
.ad
.sp .6
.RS 4n
Start and kill (respectively) the listener process for the indicated network.
These operations are normally performed as part of the system startup and
shutdown procedures. Before a listener can be started for a particular network,
it must first have been initialized (see the \fB-i\fR option, above). When a
listener is killed, processes that are still running as a result of prior
service requests will continue unaffected.
.RE

.sp
.LP
Under the Service Access Facility, it is possible to have multiple  instances
of the listener on a single \fInet_spec\fR. In any of the above commands, the
option \fB\fR\fB-N\fR \fIport_monitor_tag\fR may be used in place of the
\fInet_spec\fR argument. This argument specifies the tag by which  an instance
of the listener is identified by the Service Access Facility. If the \fB-N\fR
option is not specified (that is, the \fInet_spec\fR is specified in the
invocation), then it will be assumed that the last component of the
\fInet_spec\fR represents the tag of the listener for which the operation is
destined. In other words, it is assumed that there is at least one listener on
a designated \fInet_spec\fR, and that its tag is identical to the last
component of the \fInet_spec\fR. This listener may be thought of as the
primary, or default, listener for a particular \fInet_spec\fR.
.sp
.LP
\fBnlsadmin\fR is also used in conjunction with the Service Access Facility
commands. In that capacity, the following combinations of options can be used:
.sp
.ne 2
.na
\fB\fB-V\fR\fR
.ad
.sp .6
.RS 4n
Write the current version number of the listener's administrative file to the
standard output. It is used as part of the \fBsacadm\fR command line when
\fBsacadm\fR adds a  port monitor to the system.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR \fIcmd\fR | \fB-o\fR \fIstreamname\fR [ \fB-p\fR \fImodules\fR ] [
\fB-A\fR \fIaddress\fR | \fB-D\fR ] [ \fB-R\fR \fIprognum\fR : \fIversnum\fR
]\fR
.ad
.sp .6
.RS 4n
Format the port monitor-specific information to be used as an argument to
\fBpmadm\fR(1M)
.sp
The \fB-c\fR option specifies the full path name of the server and its
arguments. \fIcmd\fR must appear as a single word to the shell, and its
arguments must therefore be surrounded by quotes.
.sp
The \fB-o\fR option specifies the full path name of a \fBFIFO\fR or named
stream through which a standing server is actually receiving the connection.
.sp
If the \fB-p\fR option is specified, then \fImodules\fR will be interpreted as
a list of \fBSTREAMS\fR modules for the listener to push before starting the
service being added. The modules are pushed in the order in which they are
specified. \fImodules\fR must be a comma-separated list, with no white space
included.
.sp
If the \fB-A\fR option is specified, then \fIaddress\fR will be interpreted as
the server's private address. The listener will monitor this address on behalf
of the service and will dispatch all calls arriving on this address directly to
the designated service. This option may not be used in conjunction with the
\fB-D\fR option.
.sp
If the \fB-D\fR option is specified, then the service is assigned a private
address dynamically, that is, the listener will have the transport provider
select the address each time the listener begins listening on behalf of this
service. For RPC services, this option will be often be used in conjunction
with the \fB-R\fR option to register the dynamically assigned address with the
rpcbinder. This option may not be used in conjunction with the \fB-A\fR option.
.sp
When the \fB-R\fR option is specified, the service is an RPC service whose
address, program number, and version number should be registered with the
rpcbinder for this transport provider. This registration is performed each time
the listener begins listening on behalf of the service. \fIprognum\fR and
\fIversnum\fR are the program number and version number, respectively, of the
RPC service.
.RE

.sp
.LP
\fBnlsadmin\fR may be invoked by any user to generate reports; all operations
that affect a listener's status or configuration may only be run by a
super-user.
.sp
.LP
The options specific to the Service Access Facility may not be used together
with any other options.
.SH ERRORS
.sp
.LP
If successful,  \fBnlsadmin\fR exits with a status of 0.  If  \fBnlsadmin\fR
fails for any reason, it exits with a status greater than or equal to 2.  See
\fB-q\fR option for a return status of 1.
.SH SEE ALSO
.sp
.LP
\fBlisten\fR(1M), \fBpmadm\fR(1M), \fBrpcbind\fR(1M), \fBsacadm\fR(1M),
\fBattributes\fR(5)
.sp
.LP
\fI\fR
.SH NOTES
.sp
.LP
Dynamically assigned addresses are not displayed in  reports as statically
assigned addresses are.