nlsadmin(ADM) 19 June 1992 nlsadmin(ADM) Name nlsadmin - network listener service administration Syntax nlsadmin -x nlsadmin [ options ] netspec Description nlsadmin administers the network listener process(es) on a machine. Each network has a separate instance of the network listener process associ- ated 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 ser- vice, 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 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 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 pro- cesses on a machine, either individually (per network) or collectively. The following list shows how to use nlsadmin. In this list, netspec represents a particular listener process. Specifically, netspec 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 netspec Prints the status of the listener process for netspec -q netspec Queries the status of the listener process for the speci- fied 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 netspec Prints a verbose report on the servers associated with netspec, giv- ing the service code, status, command, and comment for each. -z servicecode netspec Prints a report on the server associated with netspec that has ser- vice code servicecode, giving the same information as in the -v option. -q -z servicecode netspec Queries the status of the service with service code servicecode on network netspec, 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 netspec Changes or sets the address on which the listener listens (the general listener service). This is the address generally used by remote pro- cesses 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 netspec 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 appropri- ate remote login software is available; if such software is available, it must be configured as service code 1 (see the -a option, below). -i netspec Initializes or changes a listener process for the network specified by netspec; 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 servicecode [-p modules] [-w id] -c cmd -y comment netspec Adds a new service to the list of services available through the indi- cated listener. servicecode 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 sur- rounded by quotes. Similarly, the comment must also appear as a sin- gle 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 adminis- trative entry. Service codes 1 through 100 are reserved for adminis- trative entries, which are those that require special handling inter- nally. In particular, code 1 is assigned to the remote login service, which is the service automatically invoked for connections to the ter- minal 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 pro- cess. 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 servicecode netspec Removes the entry for the servicecode 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 servicecode netspec -d servicecode netspec Enables or disables (respectively) the service indicated by servicecode for the specified network. The service must have previ- ously 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 ser- vice requests that are still running will continue unaffected. -s netspec -k netspec 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 con- tinue 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 netspec to determine the loca- tion 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 opera- tions that affect a listener's status or configuration are restricted to the super user. Diagnostics If the command is not run under the proper ID, an error message will be sent to standard error and the command will terminate. File /usr/net/nls/netspec See also Network Programmer's Guide