nlsadmin(ADM)

Syntax

nlsadmin [ options ] net_spec

Description

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 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.

no options

Gives a brief usage message.

-x

Reports the status of all of the listener processes installed on this machine.

net_spec

Prints the status of the listener process for net_spec.

-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.

-v net_spec

Prints a verbose report on the servers associated with net_spec, giving the service code, status, command, and comment for each.

-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 -v option.

-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 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.

-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, below).

-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 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 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 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 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 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.

-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.

-s net_spec

-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 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.

Diagnostics

Files

See also