NAME

nlsadmin - network listener service administration

SYNOPSIS

/usr/sbin/nlsadmin -x
/usr/sbin/nlsadmin [ options ] net_spec
/usr/sbin/nlsadmin [ options ] -N port_monitor_tag
/usr/sbin/nlsadmin -V
/usr/sbin/nlsadmin -c cmd | -o streamname [ -p modules ] \
   [ -A address | -D ] [ -R prognum:versnum ]

DESCRIPTION

nlsadmin is the administrative command for the network listener process(es) on a machine. Each network has at least one 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 invokes servers in response to those service requests. The network listener process may be used with any network (more precisely, with any connection-oriented transport provider) that conforms to the transport provider specification.

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 list below 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 provider). address is a transport address on which to listen and is interpreted using a syntax that allows for a variety of address formats. By default, address is interpreted as the symbolic ASCII representation of the transport address. An address preceded by a \x will let you enter an address in hexadecimal notation. Note that address must appear as a single word to the shell and thus must be quoted if it contains any blanks.

Changes to the list of services provided by the listener or the addresses of those services are put into effect immediately.

nlsadmin may be used with the following combinations of options and arguments:

nlsadmingives a brief usage message.

nlsadmin -x

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

nlsadmin net_spec

prints the status of the listener process for net_spec.

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

nlsadmin -v net_spec

prints 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

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.

nlsadmin -q -z service_code net_spec

queries the status of the service with service code service_code on network net_spec, and exits 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 address net_spec

changes or set the transport address on which the listener listens (the general listener service). This address can be used by remote processes to access the servers available through this listener (see the -a option, below).

If address is just a dash ("-"), nlsadmin will report the address currently configured, instead of changing it.

A change of address takes effect immediately.

nlsadmin -t address 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).

nlsadmin -i net_spec

initializes an instance of the listener for the network specified by net_spec; that is, creates and initializes the files required by the listener as well as starting that instance of the listener. Note that a particular instance of the listener should be initialized only once. The listener must be initialized before assigning addresses or services.

net_spec
     nlsadmin -a service_code [-p modules] [-w name] -c cmd -y comment
             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  path name of the server and its argu-
             ments, and comment is a brief  (free-form)  descrip-
             tion  of  the  service  for  use in various reports.
             Note that cmd must appear as a single  word  to  the
             shell;  if  arguments  are  required the cmd and its
             arguments must be enclosed in quotation marks.   The
             comment                   must                  also
             appear as a single word to the shell.  When  a  ser-
             vice  is  added, it is initially enabled (see the -e
             and -d options, below).

Service codes are alphanumeric strings, and are administered by AT&T. The numeric service codes 0 through 100 are reserved for internal use by the listener. Service code 0 is assigned to the nlps server, which is the service invoked on the general listening address. In particular, code 1 is assigned to the remote login service, which is the service automatically invoked for connections to the terminal login address.

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 name is interpreted as the user name from /etc/passwd that the listener should look up. From the user name, the listener obtains the user ID, the group ID(s), and the home directory for use by the server. If -w is not specified, the default is to use the user name 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

removes the entry for the service_code from that listener's list of services. This is normally done only in conjunction with the deinstallation of a service from a machine.

nlsadmin -e service_code net_spec
nlsadmin -d service_code net_spec
        enables or disables (respectively) the service indi-
        cated  by  service_code  for  the specified network.
        The service must previously have 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
        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 (see the -i option, above).  When a
        listener is killed, processes that are still running
        as  a result of prior service requests will continue
        unaffected.

Under the Service Access Facility, it is possible to have multiple instances of the listener on a single net_spec. In any of the above commands, the option -N port_monitor_tag may be used in place of the net_spec argument. This argument specifies the tag by which an instance of the listener is identified by the Service Access Facility. If the -N option is not specified (i.e., the net_spec is specified in the invocation), then it will be assumed that the last component of the net_spec represents the tag of the listener for which the operation is destined. In other words, it is assumed that there is at least one listener on a designated net_spec, and that its tag is identical to the last component of the net_spec. This listener may be thought of as the primary, or default, listener for a particular net_spec. nlsadmin is also used in conjunction with the Service Access Facility commands. In that capacity, the following combinations of options can be used:

nlsadmin -V

writes the current version number of the listener's administrative file to the standard output. It is used as part of the sacadm command line when sacadm add a port monitor to the system.

nlsadmin -c cmd | -o streamname [-p modules] [-A  address  |
-D ] \
   [ -R prognum:versnum ]
     formats the port  monitor-specific  information  to  be
     used as an argument to pmadm(1M).

The -c option specifies the full path name of the server and its arguments. cmd must appear as a single word to the shell, and its arguments must therefor be surrounded by quotes.

The -o option specifies the full path name of a FIFO or named STREAM through which a standing server is actually receiving the connection.

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 in which they are specified. modules must be a comma-separated list, with no white space included.

If the -A option is specified, then address will be interpreted as the server's private address. The listener will monitor this address on behalf of the service and will dispatch all calls arriving on this address directly to the designated service. This option may not be used in conjunction with the -D option.

If the -D option is specified, then the service is assigned a private address dynamically, that is, the listener will have the transport provider select the address each time the listener begins listening on behalf of this service. For RPC services, this option will be often be used in conjunction with the -R option to register the dynamically assigned address with the rpcbinder. This option may not be used in conjunction with the -A option.

When the -R option is specified, the service is an RPC service whose address, program number, and version number should be registered with the rpcbinder for this transport provider. This registration is performed each time the listener begins listening on behalf of ththe service. prognum and versnum are the program number and version number, respectively, of the RPC service.

nlsadmin may be invoked by any user to generate reports but all operations that affect a listener's status or configuration are restricted to privileged users. The options specific to the Service Access Facility may not be mixed with any other options.

SEE ALSO

listen(1M), pmadm(1M), rpcbind(1M), sacadm(1M)
Network Programmer's Guide

NOTES

Dynamically assigned addresses are not displayed in reports as statically assigned addresses are.