nlsadmin(1M) nlsadmin(1M)
NAME
nlsadmin - network listener service administration
SYNOPSIS
/usr/sbin/nlsadmin -x
/usr/sbin/nlsadmin [options] netspec
/usr/sbin/nlsadmin [options] -N portmonitortag
/usr/sbin/nlsadmin -V
/usr/sbin/nlsadmin -c cmd | -o streamname [-p modules] [-A address | -D]
[-R prognum:versnum]
DESCRIPTION
nlsadmin 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.
nlsadmin can establish a listener process for a given network, config-
ure the specific attributes of that listener, and start and kill the
listener process for that network. nlsadmin can also report on the
listener processes on a machine, either individually (per network) or
collectively.
The list below shows how to use nlsadmin. In this list, netspec rep-
resents a particular listener process. Specifically, netspec is the
relative path name of the entry under /dev for a given network (that
is, a transport provider). address is a transport address on which to
listen and is interpreted using a syntax that allows for a variety of
address formats. By default, address is interpreted as the symbolic
ASCII representation of the transport address. An address preceded by
a \x will let you enter an address in hexadecimal notation. Note that
address must appear as a single word to the shell and thus must be
quoted if it contains any blanks.
Changes to the list of services provided by the listener or the
addresses of those services are put into effect immediately.
Page 1 Reliant UNIX 5.44 Printed 11/98
nlsadmin(1M) nlsadmin(1M)
OPTIONS
nlsadmin
gives a brief usage message.
nlsadmin -x
reports the status of all of the listener processes installed on
this machine.
nlsadmin netspec
prints the status of the listener process for netspec.
nlsadmin -q netspec
queries the status of the listener process for the specified net-
work, and reflects the result of that query in its exit code. If
a listener process is active, nlsadmin will exit with a status of
0; if no process is active, the exit code will be 1; the exit
code will be greater than 1 in case of error.
nlsadmin -v netspec
prints a verbose report on the servers associated with netspec,
giving the service code, status, command, and comment for each.
It also specifies the uid the server will run as and the list of
modules to be pushed, if any, before the server is started.
nlsadmin -z servicecode netspec
prints a report on the server associated with netspec that has
service code servicecode, giving the same information as in the
-v option.
nlsadmin -q -z servicecode netspec
queries the status of the service with service code servicecode
on network netspec, and exits with a status of 0 if that service
is enabled, 1 if that service is disabled, and greater than 1 in
case of error.
nlsadmin -l address netspec
changes or sets 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 -a option, below).
If address is just a dash ("-"), nlsadmin will report the address
currently configured, instead of changing it. A change of address
takes effect immediately.
nlsadmin -t address netspec
changes or sets the address on which the listener listens for
requests for terminal service but is otherwise similar to the -l
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 -a option, below).
Page 2 Reliant UNIX 5.44 Printed 11/98
nlsadmin(1M) nlsadmin(1M)
nlsadmin -i netspec
initializes an instance of the listener for the network specified
by netspec; that is, creates and initializes 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.
nlsadmin -a servicecode [-p modules] [-w name] -c cmd -y comment netspec
adds a new service to the list of services available through the
indicated listener. servicecode is the code for the service, cmd
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 comment is a brief (free-form) description of the service for
use in various reports. Note that cmd must appear as a single
word to the shell; if arguments are required the cmd and its
arguments must be enclosed in quotation marks. The comment must
also appear as a single word to the shell. When a service is
added, it is initially enabled (see the -e and -d options,
below).
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 listen-
ing 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.
If the -p option is specified, then modules will be interpreted
as a list of STREAMS modules for the listener to push before
starting the service being added. The modules are pushed in the
order they are specified. modules should be a comma-separated
list of modules, with no white space included.
If the -w option is specified, then name is interpreted as the
user name from /etc/passwd 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 -w is not speci-
fied, the default is to use the user name listen.
A service must explicitly be added to the listener for each net-
work 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 net-
work.
nlsadmin -r servicecode netspec
removes the entry for the servicecode from that listener's list
of services. This is normally done only in conjunction with the
deinstallation of a service from a machine.
Page 3 Reliant UNIX 5.44 Printed 11/98
nlsadmin(1M) nlsadmin(1M)
nlsadmin -e servicecode netspec
nlsadmin -d servicecode netspec
enables or disables (respectively) the service indicated by
servicecode for the specified network. The service must previ-
ously have been added to the listener for that network (see the
-a option, above). Disabling a service will cause subsequent ser-
vice requests for that service to be denied, but the processes
from any prior service requests that are still running will con-
tinue unaffected.
nlsadmin -s netspec
nlsadmin -k netspec
starts and kills (respectively) the listener process for the
indicated network. These operations will normally be 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 -i option, above). When a listener
is killed, processes that are still running as a result of prior
service requests will continue unaffected.
Under the Service Access Facility (SAF), it is possible to have multi-
ple instances of the listener on a single netspec. In any of the
above commands, the option -N portmonitortag may be used in place of
the netspec argument. This argument specifies the tag by which an
instance of the listener is identified by the Service Access Facility.
If the -N option is not specified (i.e., the netspec is specified in
the invocation), then it will be assumed that the last component of
the netspec represents the tag of the listener for which the opera-
tion is destined. In other words, it is assumed that there is at least
one listener on a designated netspec, and that its tag is identical
to the last component of the netspec. This listener may be thought of
as the primary, or default, listener for a particular netspec.
nlsadmin is also used in conjunction with the Service Access Facility
commands. In that capacity, the following combinations of options can
be used:
nlsadmin -V
writes the current version number of the listener's administra-
tive file to the standard output. It is used as part of the
sacadm command line when sacadm add a port monitor to the system.
nlsadmin -c cmd | -o streamname [-p modules] [-A address | -D]
[-R prognum:versnum]
formats the port monitor-specific information to be used as an
argument to pmadm(1M).
The -c option specifies the full path name of the server and its
arguments. cmd must appear as a single word to the shell, and its
arguments must therefore be surrounded by quotes.
Page 4 Reliant UNIX 5.44 Printed 11/98
nlsadmin(1M) nlsadmin(1M)
The -o option specifies the full path name of a FIFO or named
STREAM through which a standing server is actually receiving the
connection.
If the -p option is specified, then modules will be interpreted
as a list of STREAMS modules for the listener to push before
starting the service being added. The modules are pushed in the
order in which they are specified. modules must be a comma-
separated list, with no white space included.
If the -A option is specified, then address 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 -D option.
If the -D 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
(Remote Procedure Call), this option will be often be used in
conjunction with the -R option to register the dynamically
assigned address with the rpcbinder. This option may not be used
in conjunction with the -A option.
When the -R 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. prognum and versnum are the program
number and version number, respectively, of the RPC service.
nlsadmin may be invoked by any user to generate reports but all opera-
tions that affect a listener's status or configuration are restricted
to privileged users.
The options specific to the Service Access Facility may not be mixed
with any other options.
NOTE
Dynamically assigned addresses are not displayed in reports as stati-
cally assigned addresses are.
SEE ALSO
listen(1M), pmadm(1M), rpcbind(1M), sacadm(1M).
Page 5 Reliant UNIX 5.44 Printed 11/98