nlsadmin(1M) nlsadmin(1M)
NAME
nlsadmin - network listener service administration
SYNOPSIS
/usr/sbin/nlsadmin -x
/usr/sbin/nlsadmin [ options ] net_spec
/usr/sbin/nlsadmin [ options ] -N port_monitor_tag
/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,
configure 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, net_spec
represents a particular listener process. Specifically, net_spec 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.
nlsadmin may be used with the following combinations of options and
arguments:
nlsadmin
gives a brief usage message.
nlsadmin -x
reports the status of all of the listener processes installed
on this machine.
7/91 Page 1
nlsadmin(1M) nlsadmin(1M)
nlsadmin net_spec
prints the status of the listener process for net_spec.
nlsadmin -q net_spec
queries 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, 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 net_spec
prints a verbose report on the servers associated with
net_spec, 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 service_code net_spec
prints a report on the server associated with net_spec that
has service code service_code, giving the same information as
in the -v option.
nlsadmin -q -z service_code net_spec
queries the status of the service with service code
service_code on network net_spec, 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 net_spec
changes 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 -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 net_spec
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).
nlsadmin -i net_spec
initializes an instance of the listener for the network
specified by net_spec; that is, creates and initializes the
Page 2 7/91
nlsadmin(1M) nlsadmin(1M)
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 service_code [-p modules] [-w name] -c cmd -y comment net_spec
adds a new service to the list of services available through
the indicated listener. service_code 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 Motorola. 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.
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 specified, the default is to use the user name
listen.
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.
nlsadmin -r service_code net_spec
removes the entry for the service_code from that listener's
list of services. This is normally done only in conjunction
with the deinstallation of a service from a machine.
7/91 Page 3
nlsadmin(1M) nlsadmin(1M)
nlsadmin -e service_code net_spec
nlsadmin -d service_code net_spec
enables or disables (respectively) the service indicated by
service_code for the specified network. The service must
previously have been added to the listener for that network
(see the -a 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.
nlsadmin -s net_spec
nlsadmin -k net_spec
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.
nlsadmin [ options ] -N port_monitor_tag
Under the Service Access Facility, it is possible to have
multiple instances of the listener on a single net_spec. In
any of the above commands, the option -N port_monitor_tag may
be used in place of the net_spec 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 net_spec is specified in the
invocation), then it will be assumed that the last component
of the net_spec 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 net_spec,
and that its tag is identical to the last component of the
net_spec. This listener may be thought of as the primary, or
default, listener for a particular net_spec.
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
administrative 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 ]
Page 4 7/91
nlsadmin(1M) nlsadmin(1M)
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 therefor be surrounded by
quotes.
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, 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 ththe 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
operations 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.
7/91 Page 5
nlsadmin(1M) nlsadmin(1M)
SEE ALSO
listen(1M), pmadm(1M), rpcbind(1M), sacadm(1M)
Programmer's Guide: Networking Interfaces
NOTES
Dynamically assigned addresses are not displayed in reports as
statically assigned addresses are.
The -m option of the SVR3.2 nlsadmin command is now ignored.
Page 6 7/91