NLSADMIN(8) Maintenance Procedures NLSADMIN(8)

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.


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 \x will
let you enter an address in hexadecimal notation. Note that address must
appear as a single word to the shell, thus it 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.

OPTIONS

nlsadmin may be used with the following combinations of options and
arguments:

-x

Report the status of all of the listener processes installed on this
machine.


net_spec

Print the status of the listener process for net_spec .


-q net_spec

Query 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.


-v net_spec

Print 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.


-z service_code net_spec

Print a report on the server associated with net_spec that has
service code service_code, giving the same information as in the -v
option.


-q -z service_code net_spec

Query 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.


-l address net_spec

Change 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 reports the address
currently configured, instead of changing it.

A change of address takes effect immediately.


-t address net_spec

Change or set 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).


-i net_spec

Initialize an instance of the listener for the network specified by
net_spec; that is, create and initialize 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.


-a service_code

[ -p modules ] [ -w name ] -c cmd -y comment net_spec

Add 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 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 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.


-r service_code net_spec

Remove the entry for the service_code from that listener's list of
services. This is normally done only in conjunction with the de-
installation of a service from a machine.


-e service_code net_spec
-d service_code net_spec

Enable or disable (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.


-s net_spec
-k net_spec

Start and kill (respectively) the listener process for the indicated
network. These operations are normally 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, 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:

-V

Write 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 adds a port monitor to the system.


-c cmd | -o streamname [ -p modules ] [ -A address | -D ] [ -R prognum :
versnum ]

Format the port monitor-specific information to be used as an
argument to pmadm(8)

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.

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 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; all operations
that affect a listener's status or configuration may only be run by a
super-user.


The options specific to the Service Access Facility may not be used
together with any other options.

ERRORS

If successful, nlsadmin exits with a status of 0. If nlsadmin fails
for any reason, it exits with a status greater than or equal to 2. See
-q option for a return status of 1.

SEE ALSO

attributes(7), listen(8), pmadm(8), rpcbind(8), sacadm(8)

NOTES

Dynamically assigned addresses are not displayed in reports as
statically assigned addresses are.


April 3, 1997 NLSADMIN(8)