nlsadmin(1M) SYSTEM ADMINISTRATION COMMANDS 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 associ-
ated with it; each instance (and thus, each network) is con-
figured 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 tran-
sport provider) that conforms to the transport provider
specification.
nlsadmin can establish a listener process for a given net-
work, 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. Specifi-
cally, 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 con-
tains any blanks.
Changes to the list of services provided by the listener or
the addresses of those services are put into effect immedi-
ately.
nlsadmin may be used with the following combinations of
options and arguments:
nlsadmin gives a brief usage message.
1
nlsadmin(1M) SYSTEM ADMINISTRATION COMMANDS nlsadmin(1M)
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 associ-
ated 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 ser-
vice). 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
2
nlsadmin(1M) SYSTEM ADMINISTRATION COMMANDS nlsadmin(1M)
listener listens for requests for terminal ser-
vice 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 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 assign-
ing 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 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 argu-
ments are required the cmd and its arguments
must be enclosed in quotation marks. The com-
ment 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 listening address. In particular, code
1 is assigned to the remote login service, which
is the service automatically invoked for connec-
tions 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.
3
nlsadmin(1M) SYSTEM ADMINISTRATION COMMANDS nlsadmin(1M)
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 nor-
mally 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.
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 net-
work. 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 ser-
vice 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 opera-
tions will normally be performed as part of the
system startup and shutdown procedures. Before
a listener can be started for a particular net-
work, 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, 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 argu-
ment specifies the tag by which an instance of the listener
is identified by the Service Access Facility. If the -N
4
nlsadmin(1M) SYSTEM ADMINISTRATION COMMANDS nlsadmin(1M)
option is not specified (i.e., the net_spec is specified in
the invocation), then it will be assumed that the last com-
ponent 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 com-
ponent 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 combina-
tions 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 ]
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 actu-
ally 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
5
nlsadmin(1M) SYSTEM ADMINISTRATION COMMANDS nlsadmin(1M)
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 configura-
tion are restricted to privileged users. The options
specific to the Service Access Facility may not be mixed
with any other options.
SEE ALSO
listen(1M), pmadm(1M), rpcbind(1M), sacadm(1M)
Network Programmer's Guide
NOTES
Dynamically assigned addresses are not displayed in reports
as statically assigned addresses are.
6