NLSADMIN(1M) INTERACTIVE UNIX System NLSADMIN(1M)
NAME
nlsadmin - network listener service administration
SYNOPSIS
nlsadmin -x
nlsadmin [ options ] net_spec
DESCRIPTION
nlsadmin administers the network listener process(es) on a
machine. Each network has a separate instance of the net-
work 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 con-
nected directly to the network. However, this direct termi-
nal service requires special associated software, and is
only available with some networks (for example, the AT&T
STARLAN network).
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 following list 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).
Changing the list of services provided by the listener pro-
duces immediate changes, while changing an address on which
the listener listens has no effect until the listener is
restarted. The following combination of options can be
used.
no options will give a brief usage message.
-x will report the status of all of the listener
processes installed on this machine.
net_spec will print the status of the listener process
for net_spec.
Rev. Networking Support Utilities Page 1
NLSADMIN(1M) INTERACTIVE UNIX System NLSADMIN(1M)
-q net_spec will query the status of the listener process
for the specified network, and will reflect 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 will 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
will 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
will query the status of the service with ser-
vice 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.
-l addr net_spec
will change or set the address on which the
listener listens (the general listener ser-
vice). This is the address generally used by
remote processes to access the servers avail-
able through this listener (see the -a option,
below). addr is the transport address on which
to listen and is interpreted 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.
-t addr net_spec
Rev. Networking Support Utilities Page 2
NLSADMIN(1M) INTERACTIVE UNIX System NLSADMIN(1M)
will change or set the address on which the
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).
-i net_spec will initialize or change 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 actu-
ally invoke the listener for that network. The
listener must be initialized before assigning
addressing or services.
net_spec
[-m] -a service_code [-p modules] [-w id] -c cmd -y comment
will 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 com-
ment 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. Simi-
larly, 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).
If the -m option is specified, the entry will
be marked as an administrative entry. Service
codes 1 through 100 are reserved for adminis-
trative 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 option used with the -a option indicates
that special handling internally is required
for those servers added with the -m set. This
internal handling is in the form of code embed-
ded on the listener process.
If the -p option is specified, then modules
Rev. Networking Support Utilities Page 3
NLSADMIN(1M) INTERACTIVE UNIX System NLSADMIN(1M)
will be interpreted as a list of STREAMS
modules for the listener to push before start-
ing 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 id is
interpreted as the user name from /etc/passwd
that the listener should look up. From the
user name, 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 nor-
mally 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
will remove 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.
-e service_code net_spec
-d service_code net_spec
will enable or disable (respectively) the ser-
vice indicated by service_code for the speci-
fied network. The service must have previously
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 run-
ning will continue unaffected.
-s net_spec
-k net_spec will start and kill (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 particu-
lar network, it must first have been initial-
ized, and an address must be defined for the
general listener service (see the -i and -l
options, above). When a listener is killed,
processes that are still running as a result of
prior service requests will continue
Rev. Networking Support Utilities Page 4
NLSADMIN(1M) INTERACTIVE UNIX System NLSADMIN(1M)
unaffected.
The listener runs as user ID root, with group ID sys. A
special ID, user ID listen and group ID adm, should be
entered in the /etc/passwd file as a default ID for servers.
The listener always uses as its home directory /usr/net/nls,
which is concatenated with net_spec to determine the loca-
tion of the listener configuration information for each net-
work. The home directory specified in the /etc/passwd entry
for listener will used by servers that run as ID listen.
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 the super-user.
FILES
/usr/net/nls/net_spec
SEE ALSO
Network Programmer's Guide.
Rev. Networking Support Utilities Page 5