NLSADMIN(8)

NAME
listen, nlsadmin - network listener service administration for RFS

SYNOPSIS
nlsadmin [ -mx ] [ -edr service_code net_spec ] [ -ikqsv net_spec ] [ -lt addr net_spec ] [ -a service_code [ -p modules ] -c command -y comment net_spec ] [ -qz code net_spec ] [ -z code net_spec ] [ net_spec ]

/usr/etc/listen

AVAILABILITY

This program is available with the RFS software installation option. Refer to for information on how to install optional software.

DESCRIPTION

nlsadmin configures, initiates and terminates network listener (listen) servers for the local host. Each network (transport provider) has an associated listen daemon to service it locally. The listen daemon for each is configured separately. A listen daemon accepts network service requests when they arrive, and spawns servers in response to those requests. It can be used on any network (transport provider) that conforms to the transport provider specification.

nlsadmin can also report on the listener processes on a machine, either individually (per network) or collectively.

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.

nlsadmin without any options gives a brief usage message.

OPTIONS
The net_spec argument to nlsadmin refers to a particular listen daemon. Specifically, net_spec is the relative path name of the entry under /dev for a given network.

-x  Report the status of all of the listener processes installed on this 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 have previously been added to the listener for that network (see the -a option). When a listener is disabled, processes serving prior requests continue until they complete.

-r service_code net_spec
    Remove the entry for the service_code from that listener's list of services.

-i net_spec
    Initialize or change a listener process for the network specified by net_spec. That is, create and initialize the files required by the listener. Initializing a listener with this option does not start it running. The listener must be initialized before assigning addressing or services. Note: the listener should only be initialized once for a given network.

-q net_spec
    Query the status of the listener process for the specified network. If the listener process is active, nlsadmin exits with a status of 0. If no such process is active, the exit code is 1. The exit code will be greater than 1 if there is an error.

-s net_spec
-k net_spec
    Start or kill, respectively, the listener process for the indicated network. When a listener is killed, processes that are still running as a result of prior service requests will continue unaffected. The listener runs under its own ID of listen with group ID (GID) adm. This GID appear in the system password file /etc/passwd; the HOME directory listed for the GID is concatenated with net_spec to determine the location of the listener configuration information for each network.

    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.

-v net_spec
    Verbose. Report on the servers associated with net_spec, giving the service code, status, command, and comment for each.

-l addr net_spec Change or set the address for the general listener service. This is the address generally used by remote processes to access the servers available through the 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' (BACKSLASH-X) lets you enter an address in hexadecimal notation. Note: addr must be quoted if it contains any blanks. If addr is just a dash (`—'), nlsadmin merely reports the currently configured address.

    A change of address does not take effect until the next time the listener for that network is started.

-t addr net_spec
    Change or set the address on which the listener listens for requests for terminal service. Otherwise, this is similar to -l. 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).

[-m] -a service_code -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: cmd must be quoted if it contains arguments for the server. Similarly, comment must also be quoted, so as to appear to be a single word to the shell. When a service is added, it is initially enabled (see the -e and -d options).

    If the -m option is specified, the entry is 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.

    A service must explicitly be added to the listener for each network on which that service is to be available. This operation is normally performed only when the service is installed on a machine, or when populating the list of services for a new network.

-qz code net_spec
    Query the status of the service with service code code on network net_spec, Exit with a status of 0 if the service is enabled, 1 if the service is disabled, or greater than 1 on error.

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

net_spec
    Print the status of the listener process for net_spec.

DIAGNOSTICS
If the command is not run under the proper ID, an error message is sent to the standard error, and the command terminates.

FILES
/usr/etc/listen
/usr/net/nls/net_spec

SEE ALSO