System Administration Commands nlsadmin(1M)
NAME
nlsadmin - network listener service administration
SYNOPSIS
/usr/sbin/nlsadmin -x
/usr/sbin/nlsadmin [options] netspec
/usr/sbin/nlsadmin [options] -N portmonitortag
/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 net-
work, 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.
netspec represents a particular listener process. Specifi-
cally, netspec 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 ASCI representation of the transport address. An
address preceded by \x will let you enter an address in hex-
adecimal notation. Note that address must appear as a single
word to the shell, thus it must be quoted if it contains any
blanks.
SunOS 5.11 Last change: 3 Apr 1997 1
System Administration Commands nlsadmin(1M)
Changes to the list of services provided by the listener or
the addresses of those services are put into effect immedi-
ately.
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.
netspec
Print the status of the listener process for netspec .
-q netspec
Query 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
Print a verbose report on the servers associated with
netspec, 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 servicecode netspec
Print a report on the server associated with netspec
that has service code servicecode, giving the same
information as in the -v option.
-q -z servicecode netspec
Query the status of the service with service code
servicecode on network netspec, and exits with a
status of 0 if that service is enabled, 1 if that ser-
vice is disabled, and greater than 1 in case of error.
SunOS 5.11 Last change: 3 Apr 1997 2
System Administration Commands nlsadmin(1M)
-l address netspec
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 netspec
Change or set the address on which the listener listens
for requests for terminal service but is otherwise simi-
lar 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 avail-
able, it must be configured as service code 1 (see the
-a option, below).
-i netspec
Initialize an instance of the listener for the network
specified by netspec; that is, create and initialize
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.
-a servicecode
[ -p modules ] [ -w name ] -c cmd -y comment netspec
Add a new service to the list of services available
through the indicated 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
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 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).
SunOS 5.11 Last change: 3 Apr 1997 3
System Administration Commands nlsadmin(1M)
Service codes are alphanumeric strings, and are admin-
istered 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 ser-
vice invoked on the general listening address. In par-
ticular, code 1 is assigned to the remote login service,
which is the service automatically invoked for connec-
tions 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.
-r servicecode netspec
Remove the entry for the servicecode 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 servicecode netspec
-d servicecode netspec
Enable or disable (respectively) the service indicated
by servicecode 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 unaf-
fected.
SunOS 5.11 Last change: 3 Apr 1997 4
System Administration Commands nlsadmin(1M)
-s netspec
-k netspec
Start and kill (respectively) the listener process for
the indicated network. These operations are normally
performed as part of the system startup and shutdown
procedures. Before a listener can be started for a par-
ticular 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 netspec. In
any of the above commands, the option -N portmonitortag
may be used in place of the netspec 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 netspec is specified in the
invocation), then it will be assumed that the last component
of the netspec 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
netspec, and that its tag is identical to the last com-
ponent of the netspec. This listener may be thought of as
the primary, or default, listener for a particular netspec.
nlsadmin is also used in conjunction with the Service Access
Facility commands. In that capacity, the following combina-
tions 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 command 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 sur-
rounded by quotes.
SunOS 5.11 Last change: 3 Apr 1997 5
System Administration Commands nlsadmin(1M)
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 ser-
vice 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 the ser-
vice. 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.
ERORS
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.
SunOS 5.11 Last change: 3 Apr 1997 6
System Administration Commands nlsadmin(1M)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcsu
SEE ALSO
listen(1M), pmadm(1M), rpcbind(1M), sacadm(1M), attri-
butes(5)
NOTES
Dynamically assigned addresses are not displayed in reports
as statically assigned addresses are.
SunOS 5.11 Last change: 3 Apr 1997 7
|
