2 .\" Copyright 1989 AT&T Copyright (c) 1997 Sun Microsystems, Inc. All Rights Reserved.
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH NLSADMIN 8 "Apr 3, 1997"
8 nlsadmin \- network listener service administration
12 \fB/usr/sbin/nlsadmin\fR \fB-x\fR
17 \fB/usr/sbin/nlsadmin\fR [\fIoptions\fR] \fInet_spec\fR
22 \fB/usr/sbin/nlsadmin\fR [\fIoptions\fR] \fB-N\fR \fIport_monitor_tag\fR
27 \fB/usr/sbin/nlsadmin\fR \fB-V\fR
32 \fB/usr/sbin/nlsadmin\fR \fB-c\fR \fIcmd\fR | \fB-o\fR \fIstreamname\fR [\fB-p\fR \fImodules\fR]
33 [\fB-A\fR \fIaddress\fR | \fB-D\fR] [\fB-R\fR \fIprognum\fR : \fIversnum\fR]
39 \fBnlsadmin\fR is the administrative command for the network listener
40 process(es) on a machine. Each network has at least one instance of the network
41 listener process associated with it; each instance (and thus, each network) is
42 configured separately. The listener process ``listens'' to the network for
43 service requests, accepts requests when they arrive, and invokes servers in
44 response to those service requests. The network listener process may be used
45 with any network (more precisely, with any connection-oriented transport
46 provider) that conforms to the transport provider specification.
49 \fBnlsadmin\fR can establish a listener process for a given network, configure
50 the specific attributes of that listener, and start and kill the listener
51 process for that network. \fBnlsadmin\fR can also report on the listener
52 processes on a machine, either individually (per network) or collectively.
55 \fInet_spec\fR represents a particular listener process. Specifically,
56 \fInet_spec\fR is the relative path name of the entry under \fB/dev\fR for a
57 given network (that is, a transport provider). \fIaddress\fR is a transport
58 address on which to listen and is interpreted using a syntax that allows for a
59 variety of address formats. By default, \fIaddress\fR is interpreted as the
60 symbolic ASCII representation of the transport address. An \fIaddress\fR
61 preceded by \fB\ex\fR will let you enter an address in hexadecimal notation.
62 Note that \fIaddress\fR must appear as a single word to the shell, thus it must
63 be quoted if it contains any blanks.
66 Changes to the list of services provided by the listener or the addresses of
67 those services are put into effect immediately.
71 \fBnlsadmin\fR may be used with the following combinations of options and
80 Report the status of all of the listener processes installed on this machine.
90 Print the status of the listener process for \fInet_spec\fR \fI\&.\fR
96 \fB\fB-q\fR \fInet_spec\fR\fR
100 Query the status of the listener process for the specified network, and
101 reflects the result of that query in its exit code. If a listener process is
102 active, \fBnlsadmin\fR will exit with a status of \fB0\fR; if no process is
103 active, the exit code will be \fB1\fR; the exit code will be greater than
104 \fB1\fR in case of error.
110 \fB\fB-v\fR \fInet_spec\fR\fR
114 Print a verbose report on the servers associated with \fInet_spec,\fR giving
115 the service code, status, command, and comment for each. It also specifies the
116 \fBuid\fR the server will run as and the list of modules to be pushed, if any,
117 before the server is started.
123 \fB\fB-z\fR \fIservice_code net_spec\fR\fR
127 Print a report on the server associated with \fInet_spec\fR that has service
128 code \fIservice_code,\fR giving the same information as in the \fB-v\fR option.
134 \fB\fB\fR\fB-q\fR\fB \fR\fB-z\fR \fIservice_code net_spec\fR\fR
138 Query the status of the service with service code \fIservice_code\fR on network
139 \fInet_spec,\fR and exits with a status of \fB0\fR if that service is enabled,
140 \fB1\fR if that service is disabled, and greater than \fB1\fR in case of error.
146 \fB\fB\fR\fB-l\fR \fIaddress net_spec\fR\fR
150 Change or set the transport address on which the listener listens (the general
151 listener service). This address can be used by remote processes to access the
152 servers available through this listener (see the \fB-a\fR option, below).
154 If \fIaddress\fR is just a dash (" \(mi "), \fBnlsadmin\fR reports the address
155 currently configured, instead of changing it.
157 A change of address takes effect immediately.
163 \fB\fB-t\fR \fIaddress net_spec\fR\fR
167 Change or set the address on which the listener listens for requests for
168 terminal service but is otherwise similar to the \fB-l\fR option above. A
169 terminal service address should not be defined unless the appropriate remote
170 login software is available; if such software is available, it must be
171 configured as service code 1 (see the \fB-a\fR option, below).
177 \fB\fB-i\fR \fInet_spec\fR\fR
181 Initialize an instance of the listener for the network specified by
182 \fInet_spec;\fR that is, create and initialize the files required by the
183 listener as well as starting that instance of the listener. Note that a
184 particular instance of the listener should be initialized only once. The
185 listener must be initialized before assigning addresses or services.
191 \fB\fB-a\fR \fIservice_code\fR\fR
195 [ \fB-p\fR \fImodules\fR ] [ \fB-w\fR \fIname\fR ] \fB-c\fR \fIcmd\fR \fB-y\fR
196 \fIcomment net_spec\fR
198 Add a new service to the list of services available through the indicated
199 listener. \fIservice_code\fR is the code for the service, \fIcmd\fR is the
200 command to be invoked in response to that service code, comprised of the full
201 path name of the server and its arguments, and \fIcomment\fR is a brief
202 (free-form) description of the service for use in various reports. Note that
203 \fIcmd\fR must appear as a single word to the shell; if arguments are required,
204 the \fIcmd\fR and its arguments must be enclosed in quotation marks. The
205 \fIcomment\fR must also appear as a single word to the shell. When a service is
206 added, it is initially enabled (see the \fB-e\fR and \fB-d\fR options, below).
208 Service codes are alphanumeric strings, and are administered by AT&T. The
209 numeric service codes 0 through 100 are reserved for internal use by the
210 listener. Service code 0 is assigned to the nlps server, which is the service
211 invoked on the general listening address. In particular, code 1 is assigned to
212 the remote login service, which is the service automatically invoked for
213 connections to the terminal login address.
215 If the \fB-p\fR option is specified, then \fImodules\fR will be interpreted as
216 a list of \fBSTREAMS\fR modules for the listener to push before starting the
217 service being added. The modules are pushed in the order they are specified.
218 \fImodules\fR should be a comma-separated list of modules, with no white space
221 If the \fB-w\fR option is specified, then \fIname\fR is interpreted as the user
222 name from \fB/etc/passwd\fR that the listener should look up. From the user
223 name, the listener obtains the user ID, the group ID(s), and the home directory
224 for use by the server. If \fB-w\fR is not specified, the default is to use the
225 user name \fBlisten.\fR
227 A service must explicitly be added to the listener for each network on which
228 that service is to be available. This operation will normally be performed only
229 when the service is installed on a machine, or when populating the list of
230 services for a new network.
236 \fB\fB\fR\fB-r\fR \fIservice_code net_spec\fR\fR
240 Remove the entry for the \fIservice_code\fR from that listener's list of
241 services. This is normally done only in conjunction with the de-installation of
242 a service from a machine.
248 \fB\fB\fR\fB-e\fR \fIservice_code net_spec\fR\fR
252 \fB\fB\fR\fB-d\fR \fIservice_code net_spec\fR\fR
256 Enable or disable (respectively) the service indicated by \fIservice_code\fR
257 for the specified network. The service must previously have been added to the
258 listener for that network (see the \fB-a\fR option, above). Disabling a service
259 will cause subsequent service requests for that service to be denied, but the
260 processes from any prior service requests that are still running will continue
267 \fB\fB\fR\fB-s\fR \fInet_spec\fR\fR
271 \fB\fB\fR\fB-k\fR \fInet_spec\fR\fR
275 Start and kill (respectively) the listener process for the indicated network.
276 These operations are normally performed as part of the system startup and
277 shutdown procedures. Before a listener can be started for a particular network,
278 it must first have been initialized (see the \fB-i\fR option, above). When a
279 listener is killed, processes that are still running as a result of prior
280 service requests will continue unaffected.
285 Under the Service Access Facility, it is possible to have multiple instances
286 of the listener on a single \fInet_spec\fR. In any of the above commands, the
287 option \fB\fR\fB-N\fR \fIport_monitor_tag\fR may be used in place of the
288 \fInet_spec\fR argument. This argument specifies the tag by which an instance
289 of the listener is identified by the Service Access Facility. If the \fB-N\fR
290 option is not specified (that is, the \fInet_spec\fR is specified in the
291 invocation), then it will be assumed that the last component of the
292 \fInet_spec\fR represents the tag of the listener for which the operation is
293 destined. In other words, it is assumed that there is at least one listener on
294 a designated \fInet_spec\fR, and that its tag is identical to the last
295 component of the \fInet_spec\fR. This listener may be thought of as the
296 primary, or default, listener for a particular \fInet_spec\fR.
299 \fBnlsadmin\fR is also used in conjunction with the Service Access Facility
300 commands. In that capacity, the following combinations of options can be used:
308 Write the current version number of the listener's administrative file to the
309 standard output. It is used as part of the \fBsacadm\fR command line when
310 \fBsacadm\fR adds a port monitor to the system.
316 \fB\fB-c\fR \fIcmd\fR | \fB-o\fR \fIstreamname\fR [ \fB-p\fR \fImodules\fR ] [
317 \fB-A\fR \fIaddress\fR | \fB-D\fR ] [ \fB-R\fR \fIprognum\fR : \fIversnum\fR
322 Format the port monitor-specific information to be used as an argument to
325 The \fB-c\fR option specifies the full path name of the server and its
326 arguments. \fIcmd\fR must appear as a single word to the shell, and its
327 arguments must therefore be surrounded by quotes.
329 The \fB-o\fR option specifies the full path name of a \fBFIFO\fR or named
330 stream through which a standing server is actually receiving the connection.
332 If the \fB-p\fR option is specified, then \fImodules\fR will be interpreted as
333 a list of \fBSTREAMS\fR modules for the listener to push before starting the
334 service being added. The modules are pushed in the order in which they are
335 specified. \fImodules\fR must be a comma-separated list, with no white space
338 If the \fB-A\fR option is specified, then \fIaddress\fR will be interpreted as
339 the server's private address. The listener will monitor this address on behalf
340 of the service and will dispatch all calls arriving on this address directly to
341 the designated service. This option may not be used in conjunction with the
344 If the \fB-D\fR option is specified, then the service is assigned a private
345 address dynamically, that is, the listener will have the transport provider
346 select the address each time the listener begins listening on behalf of this
347 service. For RPC services, this option will be often be used in conjunction
348 with the \fB-R\fR option to register the dynamically assigned address with the
349 rpcbinder. This option may not be used in conjunction with the \fB-A\fR option.
351 When the \fB-R\fR option is specified, the service is an RPC service whose
352 address, program number, and version number should be registered with the
353 rpcbinder for this transport provider. This registration is performed each time
354 the listener begins listening on behalf of the service. \fIprognum\fR and
355 \fIversnum\fR are the program number and version number, respectively, of the
361 \fBnlsadmin\fR may be invoked by any user to generate reports; all operations
362 that affect a listener's status or configuration may only be run by a
366 The options specific to the Service Access Facility may not be used together
367 with any other options.
371 If successful, \fBnlsadmin\fR exits with a status of 0. If \fBnlsadmin\fR
372 fails for any reason, it exits with a status greater than or equal to 2. See
373 \fB-q\fR option for a return status of 1.
377 \fBlisten\fR(8), \fBpmadm\fR(8), \fBrpcbind\fR(8), \fBsacadm\fR(8),
385 Dynamically assigned addresses are not displayed in reports as statically
386 assigned addresses are.