network listener service administration
nlsadmin [ options ] net_spec
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
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
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
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
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 options can be used.
Gives a brief usage message.
Reports the status of all of the listener processes installed on this
Prints the status of the listener process for 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.
Prints a verbose report on the servers associated with
net_spec, giving the service code, status, command, and comment
-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
-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.
-l addr net_spec
Changes or sets the address on which the listener listens (the general
This is the address generally used by remote processes to access
the servers available through this listener (see the -a option,
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
Changes or sets 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,
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
The listener must be initialized before assigning addressing or services.
[-m] -a service_code [-p modules] [-w id] -c cmd -y comment net_spec
Adds a new service to the list of services available through the
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 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
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
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 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
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
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
-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.
-e service_code net_spec
-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 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.
Starts and kills (respectively) the listener process for the
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
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
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.
If the command is not run under the proper ID, an error message
will be sent to standard error and the command will terminate.
Network Programming Interfaces
© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003