1nisprefadm(1M)          System Administration Commands          nisprefadm(1M)
2
3
4

NAME

6       nisprefadm - NIS+ utility to set server preferences for NIS+ clients
7

SYNOPSIS

9       /usr/bin/nisprefadm -a {-L | -G} [-o opt-string]
10            [-d domain] [-C client] server...
11
12
13       /usr/bin/nisprefadm -m {-L | -G} [-o opt-string]
14            [-d domain] [-C client] oldserver=newserver...
15
16
17       /usr/bin/nisprefadm -r {-L | -G} [-o opt-string]
18            [-d domain] [-C client] server...
19
20
21       /usr/bin/nisprefadm -u {-L | -G} [-o opt-string]
22            [-d domain] [-C client] server...
23
24
25       /usr/bin/nisprefadm -x {-L | -G} [-d domain] [-C client]
26
27
28       /usr/bin/nisprefadm -l {-L | -G} [-d domain] [-C client]
29
30
31       /usr/bin/nisprefadm -F
32
33

DESCRIPTION

35       nisprefadm  defines  which servers are to be preferred by NIS+ clients.
36       This information is used by nis_cachemgr(1M) to control  the  order  in
37       which  it  selects  which  server  to use for a particular domain. On a
38       client system, the cache manager first  looks  for  a  local  preferred
39       server  list in /var/nis. If it doesn't find one, it looks for an entry
40       with its host name in the NIS+ table. Finally, if it  doesn't  find  it
41       there, it looks for an entry for its subnet.
42
43
44       By  default,  nis_cachemgr puts all servers that are on the same subnet
45       as the client system (that is, local  servers)  are  on  the  preferred
46       server list. In some cases this default preferred server list is inade‐
47       quate. For example, if all of the servers for a domain are remote,  but
48       some are closer than others, the cache manager should try to select the
49       closer one. Because the cache manager has no reliable way to  determine
50       the  distance  to  remote  servers,  nisprefadm is used to provide this
51       information.
52
53
54       The preferred server information is stored either globally  in  a  NIS+
55       table  (with  the -G option) or locally in a file, /var/nis/client_info
56       (with the -L option). It is preferable to store the  information  glob‐
57       ally  so  that  it  can  be  used  by  all  clients  on  a  subnet. The
58       nis_cachemgr process on a client machine reloads the  preferred  server
59       information  periodically,  depending  on  the  machine's setup. If the
60       local file is used, the information is reloaded every 12 hours. If  the
61       global  table  is  used,  the  information is reloaded based on the TTL
62       value of the client information table. This TTL value  can  be  changed
63       using   nischttl(1).  If  you  want your changes to take effect immedi‐
64       ately, use the nisprefadm -F command. When changing  local  information
65       (-L), nisprefadm automatically forces nis_cachemgr to reload the infor‐
66       mation.
67
68
69       The cache manager assigns weights to all of the  servers  on  the  pre‐
70       ferred  list.  By  default, local servers (that is, servers on the same
71       subnet) are given a weight of 0. Other servers are  given  the  weight,
72       "infinite".  This  can  be  changed by using the nisprefadm command and
73       giving a weight in parentheses after the server name. When selecting  a
74       server  for  a  domain,  the  cache  manager first tries to contact the
75       servers with the lowest weight. If it doesn't get a response, it  tries
76       the  servers with the next lowest weight, and so on. If it fails to get
77       a response from any of the preferred servers, it tries to  contact  the
78       non-preferred servers.
79
80
81       The  use  of  weights  gives  fine  control  over  the server selection
82       process, but care must be given to avoid assigning too  many  different
83       weights.  For  example,  if weights 0, 1, 2, and 3 are used, but all of
84       the servers with weight 0, 1, and 2, are unavailable, then  there  will
85       be  a noticeable delay in selecting a server. This is because the cache
86       manager waits 5 seconds for a response at each weight level before mov‐
87       ing  on  to  the  next one. As a general rule, one or two weight levels
88       provides a good balance of server selection control and performance.
89
90
91       When specifying a server name, it is not necessary to fully qualify the
92       name.  When the cache manager tries to access a domain, it compares the
93       list of servers for the domain with the list of preferred  servers.  It
94       will find a match if a preferred server name is a prefix of the name of
95       a server for the domain. If a domain is served by two servers with  the
96       same  prefix,  the  preferred  server  name  must include enough of the
97       domain name to distinguish the two.
98
99
100       The nis_cachemgr(1M) process automatically  adds  local  servers  (same
101       subnet  as the client) to the preferred server list with a weight of 0.
102       Thus, it is not necessary to specify them, though it does no harm.
103
104
105       If you specify a weight for a server, you  probably  should  quote  the
106       parentheses  to  avoid  having  the shell interpret them. The following
107       command illustrates this:
108
109         example% nisprefadm -G -a -C client1 "srv1(2)"
110
111
112
113
114       In general, nis_cachemgr does a fairly good job of selecting servers on
115       its  own.  Therefore,  the  use of nisprefadm is not usually necessary.
116       Some situations in which it is recommended are:
117
118       No local servers, many remote servers
119
120           In this case, nis_cachemgr  needs  to  choose  one  of  the  remote
121           servers.  Because  it doesn't have information on which is closest,
122           it sends a ping to all of  them  and  then  selects  the  one  that
123           responds  fastest.  This  may not always select the best server. If
124           some of the servers are closer to the client than the others,  they
125           should be listed as preferred servers so that nis_cachemgr will try
126           them first. This reduces the amount of network traffic for  select‐
127           ing a server.
128
129
130       Very remote servers
131
132           In  some  networks  there  are NIS+ servers that are only reachable
133           through very slow network connections. It is usually best to  avoid
134           unnecessary     traffic    over    that    connection.    If    the
135           pref_type=pref_only option is set  along  with  preferred  servers,
136           then  only  the  preferred  servers  are contacted for domains they
137           serve. The non-preferred servers are not tried at all; even if  all
138           of  the preferred servers are unavailable. For domains that are not
139           served by any of the preferred servers,  the  pref_only  option  is
140           ignored.
141
142

OPTIONS

144       In  the  SYNOPSIS,  when several options are surrounded by braces (that
145       is, by `{' and `}') one of the options must be specified.
146
147       -a           Add the specified servers to the preferred server list.
148
149
150       -C client    Store the  preferred  server  information  with  the  key,
151                    client.  The  client  can be either a hostname or a subnet
152                    number. When a hostname is specified, the preferred server
153                    information  applies  to  that host only. When a subnet is
154                    specified, the preferred server information applies to all
155                    clients  on  that  subnet.  The cache manager searches for
156                    host specific entries first. It only searches  for  subnet
157                    entries  if  no host entry is found. If this option is not
158                    specified, then the hostname of the machine on  which  the
159                    command is run is used.
160
161
162       -d domain    Specify the domain to which the command is to apply.
163
164
165       -F           Tells  nis_cachemgr(1M)  to  refresh  its preferred server
166                    information. The program periodically  does  this  anyway,
167                    but  this  option forces it to do the refresh immediately.
168                    When updating the local information, nis_cachemgr automat‐
169                    ically refreshes the preferred server information.
170
171                    This option must be executed as root.
172
173
174       -l           List the current preferred server information.
175
176
177       -L | -G      Store  the  preferred  server  information  locally in the
178                    file, /var/nis/client_info (the -L option), or globally in
179                    a  NIS+  table client.info.org-dir.domain (the -G option).
180                    If the information is stored locally, then it only applies
181                    to the system on which the command is run. If it is stored
182                    globally then it can apply to  all  systems  on  a  subnet
183                    (depending on the value of the -C option).
184
185                    The -L option must be run as root.
186
187
188       -m           Modify  the preferred server list. The server specified by
189                    oldserver is replaced by newserver. This is typically used
190                    to change the weight for a server.
191
192
193       -o           Specify  additional  options  to control server selection.
194                    Currently the only valid option is  pref_type,  which  can
195                    have  a value of either all (the default) or pref_only. If
196                    the value is all, then the cache manager tries to  contact
197                    non-preferred servers if all of the preferred servers fail
198                    to respond. If pref_only is specified, then it  won't  try
199                    non-preferred  servers. The only exception to this is when
200                    a domain is not served by any of the preferred servers. In
201                    this  case,  the cache manager ignores the option. This is
202                    to avoid requiring that preferred servers be  defined  for
203                    every domain.
204
205
206       -r           Remove  the  specified  servers  from the preferred server
207                    list.
208
209
210       -u           Clear the list of preferred servers and then add the spec‐
211                    ified servers to the preferred server list.
212
213
214       -x           Remove the preferred server information completely.
215
216

RETURN VALUES

218       nisprefadm returns the following values:
219
220       0    On success.
221
222
223       1    On failure.
224
225

EXAMPLES

227       Example 1 Using nisprefadm
228
229
230       This  command sets the preferred server list for the system on which it
231       is run:
232
233
234         example% nisprefadm -L -a srv1 srv2
235
236
237
238
239       The information is stored in a file, /var/nis/client_info, so  it  will
240       only affect this one system.
241
242
243
244       The  following  command  has  the  same  effect, but the information is
245       stored in a NIS+ table in the default domain.
246
247
248         example% nisprefadm -G -a srv1 srv2
249
250
251
252
253       As a system administrator, you might want to set the  preferred  server
254       information  for a client system other than the one you are running the
255       command on. The following command sets the preferred server information
256       for a client system named client1:
257
258
259         example% nisprefadm -G -a -C client1 srv1 srv2
260
261
262
263
264       It  is common for all client systems on a subnet to use the same set of
265       preferred servers. The following command sets a preferred  server  list
266       that applies to all clients on subnet, 192.85.18.0:
267
268
269         example% nisprefadm -G -a -C 192.85.18.0 srv1 srv2
270
271
272

ATTRIBUTES

274       See attributes(5) for descriptions of the following attributes:
275
276
277
278
279       ┌─────────────────────────────┬─────────────────────────────┐
280       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
281       ├─────────────────────────────┼─────────────────────────────┤
282       │Availability                 │SUNWcsu                      │
283       └─────────────────────────────┴─────────────────────────────┘
284

SEE ALSO

286       nischttl(1), nis_cachemgr(1M), attributes(5)
287

NOTES

289       NIS+ might not be supported in future releases of the Solaris Operating
290       system. Tools to aid the migration from NIS+ to LDAP are  available  in
291       the    current   Solaris   release.   For   more   information,   visit
292       http://www.sun.com/directory/nisplus/transition.html.
293
294
295
296SunOS 5.11                        12 Dec 2001                   nisprefadm(1M)
Impressum