nisprefadm(1M)
NAME
nisprefadm - NIS+ utility to set server preferences for NIS+
clients
SYNOPSIS
/usr/bin/nisprefadm -a {-L | -G} [-o opt-string] [-
d domain] [-C client] server...
/usr/bin/nisprefadm -m {-L | -G} [-o opt-string] [-
d domain] [-C client] oldserver=newserver...
/usr/bin/nisprefadm -r {-L | -G} [-o opt-string] [-
d domain] [-C client] server...
/usr/bin/nisprefadm -u {-L | -G} [-o opt-string] [-
d domain] [-C client] server...
/usr/bin/nisprefadm -x {-L | -G} [-d domain] [-C client]
/usr/bin/nisprefadm -l {-L | -G} [-d domain] [-C client]
/usr/bin/nisprefadm -F
DESCRIPTION
nisprefadm defines which servers are to be preferred by NIS+
clients. This information is used by nis_cachemgr(1M) to
control the order in which it selects which server to use
for a particular domain. On a client system, the cache
manager first looks for a local preferred server list in
/var/nis. If it doesn't find one, it looks for an entry with
its host name in the NIS+ table. Finally, if it doesn't
find it there, it looks for an entry for its subnet.
By default, nis_cachemgr puts all servers that are on the
same subnet as the client system (that is, local servers)
are on the preferred server list. In some cases this default
preferred server list is inadequate. For example, if all of
the servers for a domain are remote, but some are closer
than others, the cache manager should try to select the
closer one. Because the cache manager has no reliable way to
determine the distance to remote servers, nisprefadm is used
to provide this information.
The preferred server information is stored either globally
in a NIS+ table (with the -G option) or locally in a file,
/var/nis/client_info (with the -L option). It is preferable
to store the information globally so that it can be used by
all clients on a subnet. The nis_cachemgr process on a
client machine reloads the preferred server information
periodically, depending on the machine's setup. If the local
file is used, the information is reloaded every 12 hours. If
the global table is used, the information is reloaded based
on the TTL value of the client information table. This TTL
value can be changed using nischttl(1). If you want your
changes to take effect immediately, use the nisprefadm -F
command. When changing local information (-L), nisprefadm
automatically forces nis_cachemgr to reload the informa-
tion.
The cache manager assigns weights to all of the servers on
the preferred list. By default, local servers (that is,
servers on the same subnet) are given a weight of 0. Other
servers are given the weight, "infinite". This can be
changed by using the nisprefadm command and giving a weight
in parentheses after the server name. When selecting a
server for a domain, the cache manager first tries to con-
tact the servers with the lowest weight. If it doesn't get a
response, it tries the servers with the next lowest weight,
and so on. If it fails to get a response from any of the
preferred servers, it tries to contact the non-preferred
servers.
The use of weights gives fine control over the server selec-
tion process, but care must be given to avoid assigning too
many different weights. For example, if weights 0, 1, 2, and
3 are used, but all of the servers with weight 0, 1, and 2,
are unavailable, then there will be a noticeable delay in
selecting a server. This is because the cache manager waits
5 seconds for a response at each weight level before moving
on to the next one. As a general rule, one or two weight
levels provides a good balance of server selection control
and performance.
When specifying a server name, it is not necessary to fully
qualify the name. When the cache manager tries to access a
domain, it compares the list of servers for the domain with
the list of preferred servers. It will find a match if a
preferred server name is a prefix of the name of a server
for the domain. If a domain is served by two servers with
the same prefix, the preferred server name must include
enough of the domain name to distinguish the two.
The nis_cachemgr(1M) process automatically adds local
servers (same subnet as the client) to the preferred server
list with a weight of 0. Thus, it is not necessary to
specify them, though it does no harm.
If you specify a weight for a server, you probably should
quote the parentheses to avoid having the shell interpret
them. The following command illustrates this:
example% nisprefadm -G -a -C client1 "srv1(2)"
In general, nis_cachemgr does a fairly good job of selecting
servers on its own. Therefore, the use of nisprefadm is not
usually necessary. Some situations in which it is recom-
mended are:
No local servers, many remote servers
In this case, nis_cachemgr needs to choose one of the
remote servers. Because it doesn't have information on
which is closest, it sends a ping to all of them and
then selects the one that responds fastest. This may
not always select the best server. If some of the
servers are closer to the client than the others, they
should be listed as preferred servers so that
nis_cachemgr will try them first. This reduces the
amount of network traffic for selecting a server.
Very remote servers
In some networks there are NIS+ servers that are only
reachable through very slow network connections. It is
usually best to avoid unnecessary traffic over that
connection. If the pref_type=pref_only option is set
along with preferred servers, then only the preferred
servers are contacted for domains they serve. The
non-preferred servers are not tried at all; even if
all of the preferred servers are unavailable. For
domains that are not served by any of the preferred
servers, the pref_only option is ignored.
OPTIONS
In the SYNOPSIS, when several options are surrounded by
braces (that is, by `{' and `}') one of the options must be
specified.
-a Add the specified servers to the preferred server
list.
-C client
Store the preferred server information with the key,
client. The client can be either a hostname or a sub-
net number. When a hostname is specified, the pre-
ferred server information applies to that host only.
When a subnet is specified, the preferred server
information applies to all clients on that subnet. The
cache manager searches for host specific entries
first. It only searches for subnet entries if no host
entry is found. If this option is not specified, then
the hostname of the machine on which the command is
run is used.
-d domain
Specify the domain to which the command is to apply.
-F Tells nis_cachemgr(1M) to refresh its preferred
server information. The program periodically does this
anyway, but this option forces it to do the refresh
immediately. When updating the local information,
nis_cachemgr automatically refreshes the preferred
server information.
This option must be executed as root.
-l List the current preferred server information.
-L | -G
Store the preferred server information locally in the
file, /var/nis/client_info (the -L option), or glo-
bally in a NIS+ table client.info.org-dir.domain (the
-G option). If the information is stored locally, then
it only applies to the system on which the command is
run. If it is stored globally then it can apply to all
systems on a subnet (depending on the value of the -C
option).
The -L option must be run as root.
-m Modify the preferred server list. The server specified
by oldserver is replaced by newserver. This is typi-
cally used to change the weight for a server.
-o Specify additional options to control server selec-
tion. Currently the only valid option is pref_type,
which can have a value of either all (the default) or
pref_only. If the value is all, then the cache manager
tries to contact non-preferred servers if all of the
preferred servers fail to respond. If pref_only is
specified, then it won't try non-preferred servers.
The only exception to this is when a domain is not
served by any of the preferred servers. In this case,
the cache manager ignores the option. This is to avoid
requiring that preferred servers be defined for every
domain.
-r Remove the specified servers from the preferred server
list.
-u Clear the list of preferred servers and then add the
specified servers to the preferred server list.
-x Remove the preferred server information completely.
RETURN VALUES
nisprefadm returns the following values:
0 On success.
1 On failure.
EXAMPLES
Example 1: Using nisprefadm
This command sets the preferred server list for the system
on which it is run:
example% nisprefadm -L -a srv1 srv2
The information is stored in a file, /var/nis/client_info,
so it will only affect this one system.
The following command has the same effect, but the informa-
tion is stored in a NIS+ table in the default domain.
example% nisprefadm -G -a srv1 srv2
As a system administrator, you might want to set the pre-
ferred server information for a client system other than the
one you are running the command on. The following command
sets the preferred server information for a client system
named client1:
example% nisprefadm -G -a -C client1 srv1 srv2
It is common for all client systems on a subnet to use the
same set of preferred servers. The following command sets a
preferred server list that applies to all clients on subnet,
192.85.18.0:
example% nisprefadm -G -a -C 192.85.18.0 srv1 srv2
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWcsu |
|_____________________________|_____________________________|
SEE ALSO
nischttl(1), nis_cachemgr(1M), attributes(5)
NOTES
NIS+ might not be supported in future releases of the
SolarisTM Operating Environment. Tools to aid the migration
from NIS+ to LDAP are available in the Solaris 9 operating
environment. For more information, visit
http://www.sun.com/directory/nisplus/transition.html.
Man(1) output converted with
man2html