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 pipename [-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.
USAGE
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 Options section below shows how to use nlsadmin. In this
section, 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); net_spec must be specified in ASCII characters.
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.
Copyright 1994 Novell, Inc. Page 1
nlsadmin(1M) nlsadmin(1M)
nlsadmin processes supplementary code set characters in the
cmd given to the -c option and the comment given to the -y
option (see below) according to the locale specified in the
LC_CTYPE environment variable [see LANG on environ(5)].
Changes to the list of services provided by the listener or
the addresses of those services are put into effect
immediately.
Options
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.
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, the authentication scheme, 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.
Copyright 1994 Novell, Inc. Page 2
nlsadmin(1M) nlsadmin(1M)
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 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 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. The
terminal service 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 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.
net_spec
nlsadmin -a service_code [-p modules] [-w name] -c cmd -
y comment
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
Copyright 1994 Novell, Inc. Page 3
nlsadmin(1M) nlsadmin(1M)
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). cmd and comment may contain
supplementary code set characters.
Service codes are alphanumeric strings. 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. modules
must be specified in ASCII characters.
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
Copyright 1994 Novell, Inc. Page 4
nlsadmin(1M) nlsadmin(1M)
service from a machine.
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.
Service Access Facility Options
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 (that is, 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:
Copyright 1994 Novell, Inc. Page 5
nlsadmin(1M) nlsadmin(1M)
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(1M) command line when
sacadm adds a listener to the system.
nlsadmin -c cmd | -o pipename [-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; its arguments must be surrounded by
quotes. cmd may contain supplementary code set
characters.
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.
Copyright 1994 Novell, Inc. Page 6
nlsadmin(1M) nlsadmin(1M)
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.
The options specific to the Service Access Facility may not be
mixed with any other options.
Warnings
Only statically assigned addresses are displayed in reports.
Dynamically assigned addresses are not displayed.
REFERENCES
listen(1M), pmadm(1M), rpcbind(1M), sacadm(1M)
Copyright 1994 Novell, Inc. Page 7