nlsadmin(1M)						  System Administration Commands					      nlsadmin(1M)

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  ``lis-
       tens''  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.

       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 x will let you enter an address in hexadecimal notation. Note that address must appear as a single word to the  shell,
       thus it 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.

OPTIONS

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

       -x			       Report the status of all of the listener processes installed on this machine.

       net_spec 		       Print the status of the listener process for net_spec .

       -q net_spec		       Query  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		       Print  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.

       -z service_code net_spec        Print  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     Query 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.

       -l address net_spec	       Change  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 reports the address currently configured, instead of changing
				       it.

				       A change of address takes effect immediately.

       -t address net_spec	       Change or set 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		       Initialize  an instance of the listener for the network specified by net_spec; that is, create and initial-
				       ize the files required by the listener as well as starting that instance of the listener. Note that a  par-
				       ticular	instance  of the listener should be initialized only once. The listener must be initialized before
				       assigning addresses or services.

       -a service_code		       [ -p modules ] [  -w name ] -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  ser-
				       vice  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 service 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 lis-
				       tener to push before starting the service being added. The modules are pushed in the order they are  speci-
				       fied. 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  direc-
				       tory 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 avail-
				       able. 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        Remove  the entry for the service_code from that listener's list of services. This is normally done only in
				       conjunction with the de-installation of a service from a machine.

       -e service_code net_spec        Enable or disable (respectively) the service indicated by service_code for the specified network. The  ser-
       -d service_code net_spec        vice 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.

       -s net_spec		       Start and kill (respectively) the listener process for the indicated network. These operations are normally
       -k net_spec		       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 (that is, the net_spec	is  speci-
       fied  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:

       -V

	   Write  the  current version number of the listener's administrative file to the standard output.  It is used as part of the sacadm com-
	   mand line when sacadm adds a  port monitor to the system.

       -c cmd | -o streamname [ -p modules ] [ -A address | -D ] [ -R prognum : versnum ]

	   Format 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 therefore 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 connec-
	   tion.

	   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  trans-
	   port  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
	   the 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; all operations that affect a listener's status or configuration may only be run by
       a super-user.

       The options specific to the Service Access Facility may not be used together with any other options.

ERRORS

       If successful,  nlsadmin exits with a status of 0.  If  nlsadmin fails for any reason, it exits with a status greater than or equal  to	2.
       See  -q option for a return status of 1.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsu			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       listen(1M), pmadm(1M), rpcbind(1M), sacadm(1M), attributes(5)

       System Administration Guide: Basic Administration

NOTES

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

SunOS 5.10							    3 Apr 1997							      nlsadmin(1M)