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