NLSADMIN(1M) (Networking Support Utilities) NLSADMIN(1M)
NAME
nlsadmin - network listener service administration
SYNOPSIS
nlsadmin -x
nlsadmin [ -q] [-v] [-z] [-l] [-t] [-i] [-m] [-p] [-w] [-c]
[-y] [r] [-e] [-d] [-s] [-k] net_spec
DESCRIPTION
nlsadmin 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).
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 following list shows how to use nlsadmin. In this list,
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
Page 1 May 1989
NLSADMIN(1M) (Networking Support Utilities) NLSADMIN(1M)
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
options can be used.
nlsadmin will give a brief usage message.
nlsadmin -x will report the status of all of the listener
processes installed on this machine.
nlsadmin net_spec
will print the status of the listener process
for net_spec.
nlsadmin -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.
nlsadmin -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.
nlsadmin -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.
nlsadmin -q -z service_code net_spec
Page 2 May 1989
NLSADMIN(1M) (Networking Support Utilities) NLSADMIN(1M)
will query 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
will change or set 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
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.
nlsadmin -t addr net_spec
will 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).
Page 3 May 1989
NLSADMIN(1M) (Networking Support Utilities) NLSADMIN(1M)
nlsadmin -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
actually invoke the listener for that network.
The listener must be initialized before
assigning addressing or services.
comment net_spec
nlsadmin [-m] -a service_code [-p modules] [-w id] -c cmd -y
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
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 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
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 option used with the -a option indicates
Page 4 May 1989
NLSADMIN(1M) (Networking Support Utilities) NLSADMIN(1M)
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 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 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
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
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.
nlsadmin -e service_code net_spec
nlsadmin -d service_code net_spec
will enable or disable (respectively) the
service indicated by service_code for the
specified network. The service must have
Page 5 May 1989
NLSADMIN(1M) (Networking Support Utilities) NLSADMIN(1M)
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 running will continue unaffected.
nlsadmin -s net_spec
nlsadmin -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
particular network, it must first have been
initialized, 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
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
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.
nlsadmin may be invoked by any user to generate reports, but
all operations that affect a listener's status or
configuration are restricted to the super-user.
FILES
/usr/net/nls/net_spec
SEE ALSO
Page 6 May 1989
NLSADMIN(1M) (Networking Support Utilities) NLSADMIN(1M)
Network Programmer's Guide, Vol. 1.
Page 7 May 1989