NLSADMIN(1M) RISC/os Reference Manual 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 associ-
ated with it; each instance (and thus, each network) is con-
figured 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 tran-
sport 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.
The list below shows how to use nlsadmin. In this list,
net_spec represents a particular listener process. Specifi-
cally, 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 con-
tains any blanks.
Changes to the list of services provided by the listener or
the addresses of those services are put into effect immedi-
ately.
nlsadmin may be used with the following combinations of
options and arguments:
nlsadmingives a brief usage message.
Printed 11/19/92 Page 1
NLSADMIN(1M) RISC/os Reference Manual NLSADMIN(1M)
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, com-
mand, 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
Page 2 Printed 11/19/92
NLSADMIN(1M) RISC/os Reference Manual NLSADMIN(1M)
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 net-
work 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 ser-
vices.
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 service is added, it is initially
enabled (see the -e and -d options, below).
Service codes are alphanumeric strings. The numeric
service codes 0 through 100 are reserved for inter-
nal 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 inter-
preted 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
Printed 11/19/92 Page 3
NLSADMIN(1M) RISC/os Reference Manual NLSADMIN(1M)
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 per-
formed 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 argu-
ment 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 com-
ponent 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
Page 4 Printed 11/19/92
NLSADMIN(1M) RISC/os Reference Manual NLSADMIN(1M)
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 combina-
tions 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 actu-
ally 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
Printed 11/19/92 Page 5
NLSADMIN(1M) RISC/os Reference Manual NLSADMIN(1M)
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 configura-
tion 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).
NOTES
Dynamically assigned addresses are not displayed in reports
as statically assigned addresses are.
Page 6 Printed 11/19/92