nlsadmin(8) CLIX nlsadmin(8)
NAME
nlsadmin - Administers the network listener service
SYNOPSIS
nlsadmin -x
nls [-qvimsk] [-z service_code] [-l addr] [-t addr] [-a service_code] [-p
modules]
[-w id] [-c cmd] [-y comment] [-r service_code] [-e service_code] [-d
service_code] [net_spec]
FLAGS
-x Reports the status of all the listener processes on this machine.
q net_spec
Queries the status of the listener process for the specified
network.
-v net_spec
Displays a verbose report on the servers associated with net_spec.
-z service_code
Executes the specified option for the network that has a service
code of service_code.
-l addr
Changes the address or sets the address on which the listener
listens.
-t addr
Changes the address or sets the address on which the listener
listens for requests for terminal service.
-i net_spec
Initializes or changes a listener process for the network specified
by net_spec.
-m Marks this entry as an administrative entry.
-a service_code
Adds a new service to the list of services available through the
indicated listener.
-p modules
The listener is to push these modules before starting service.
-w id Uses id to look in /etc/passwd to find the user ID, group ID, and
home directory for the listener to use. The default is listen.
2/94 - Intergraph Corporation 1
nlsadmin(8) CLIX nlsadmin(8)
-r service_code
Removes the entry for the service_code from the listener's list of
services.
-e service_code
Enables the service indicated by service_code.
-d service_code
Disables the service indicated by the service_code.
-s net_spec
Starts the listener for the indicated network.
-k net_spec
Kills the listener for the indicated network.
DESCRIPTION
The nlsadmin command administers the network listener process(es) on a
machine. Each network has a separate 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 spawns
servers in response to those service requests. The network listener
process will work with any network (more precisely, with any transport
provider) that conforms to the transport provider specification.
The listener supports two classes of service: a general listener service,
serving processes on remote machines, and a terminal login service, for
terminals connected directly to a network. The terminal login service
provides networked access to this machine in a form suitable for terminals
connected directly to the network. However, this direct terminal service
requires special associated software, and is only available with some
networks (for example, the AT&T STARLAN network).
The nlsadmin command 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. The nlsadmin command can also report
on the listener processes on a machine, either individually (per network)
or collectively.
EXAMPLES
The following list shows how to use nlsadmin. In this list, net_spec
represents a particular listener process. Specifically, net_spec is the
relative pathname of the entry under /dev for a given network (that is, a
transport provider). Changing the list of services provided by the
listener produces immediate changes, while changing an address on which
the listener listens has no effect until the listener is restarted. The
following combination of flags can be used.
2 Intergraph Corporation - 2/94
nlsadmin(8) CLIX nlsadmin(8)
nlsadmin
Gives a brief usage message.
nlsadmin -x
Reports the status of all of the listener processes installed on
this machine.
nlsadmin net_spec
Displays 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
Displays 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 that 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
Displays a report on the server associated with net_spec that has
service code service_code, giving the same information as with the
-v flag.
nlsadmin -q -z service_code net_spec
Queries the status of the service with service code service_code on
network net_spec, and will exit 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 addr net_spec
Changes or sets the address on which the listener listens (the
general listener service). This is the address generally used by
remote processes to access the servers available through this
listener (see the -a flag below). The addr argument is the
transport address on which to listen and is interpreted by using a
syntax that allows for a variety of address formats. By default,
addr is interpreted as the symbolic ASCII representation of the
transport address. An addr preceded by a \x will let you enter an
address in hexadecimal notation. Note that addr must appear as a
single word to the shell and must be quoted if it contains any
blanks. If addr is just a dash (-), nlsadmin will report the
address currently configured instead of changing it. A change of
address will not take effect until the next time the listener for
that network is started.
nlsadmin -t addr net_spec
2/94 - Intergraph Corporation 3
nlsadmin(8) CLIX nlsadmin(8)
Changes or sets the address on which the listener listens for
requests for terminal service, but is otherwise similar to the -l
flag. 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 flag
below).
nlsadmin -i net_spec
Initializes or changes a listener process for the network specified
by net_spec, that is, it will create and initialize the files
required by the listener. Note that the listener should only be
initialized once for a given network, and that doing so does not
actually invoke the listener for that network. The listener must
be initialized before the assignment of addressing or services.
net_spec
nlsadmin [-m] -a service_code [-p modules] [-w id] -c cmd -y comment
Adds a new service to the list of services available through the
indicated listener. The service_code argument is the code for the
service, cmd is the command to be invoked in response to that
service code (comprised of the full pathname 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, so if arguments are required the cmd and
its arguments must be surrounded by quotes. Similarly, 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 flags, below).
If the -m flag is specified, the entry will be marked as an
administrative entry. Service codes 1 through 100 are reserved for
administrative entries, which are those that require special
handling internally. In particular, code 1 is assigned to the
remote login service, which is the service automatically invoked
for connections to the terminal login address. The -m flag used
with the -a flag indicate that special handling internally is
required for those servers added with the -m set. This internal
handling is in the form of code embedded on the listener process.
If the -p flag 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. The modules argument should be a comma-separated
list of modules, with no white space included. If the -w flag is
specified, then id is interpreted as the username from /etc/passwd
that the listener should look up. From the username, the listener
should obtain the user ID, the group ID, and the home directory for
use by the server. If -w is not specified, the default is to use
the user ID 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.
4 Intergraph Corporation - 2/94
nlsadmin(8) CLIX nlsadmin(8)
nlsadmin -r service_code net_spec
Removes the entry for the service_code from that listener's list of
services. This will normally be performed only in conjunction with
the de-installation 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 network. The service must have
previously been added to the listener for that network (see the -a
flag, 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, and an address must be defined for the
general listener service (see the -i and -l flags, above). When a
listener is killed, processes that are still running as a result of
prior service requests will continue unaffected.
FILES
/usr/net/nls/net_spec The listener process' home directory
NOTES
The listener runs as user ID root, with group ID sys. Special IDs, user
ID listen and group ID adm, should be entered in the /etc/passwd file as
default IDs for servers. The listener always uses as its home directory
/usr/net/nls, which is concatenated with net_spec to determine the
location of the listener configuration information for each network. The
home directory specified in the /etc/passwd entry for listener will be
used by servers that run as ID listen.
The nlsadmin command may be invoked by any user to generate reports, but
all operations that affect a listener's status or configuration are
restricted to the superuser.
EXIT VALUES
Please see the various examples above for a discussion of the exit values
possible for this command.
RELATED INFORMATION
2/94 - Intergraph Corporation 5
nlsadmin(8) CLIX nlsadmin(8)
AT&T UNIX System V Network Programmer's Guide
6 Intergraph Corporation - 2/94