test

System Administration Guide: Naming and Directory Services (NIS+)

Chapter 20 NIS+ Server Use Customization

This chapter describes how to customize and control which servers NIS+ clients use.

Note –

NIS+ might not be supported in a future release. Tools to aid the migration from NIS+ to LDAP are available as of the Solaris 9 release. For more information, see System Administration Guide: Naming and Directory Services (DNS, NIS, and LDAP) and visit NIS+ End-of-Feature (EOF) Announcement FAQ.

NIS+ Servers and Clients

When client machines, users, applications, or processes need NIS+ information, they seek an active NIS+ server (master or replica) from which to get the needed data. On large networks, networks with many subnets, and networks that span wide-area links, you may be able to improve NIS+ performance by customizing server usage.

Default NIS+ Client Search Behavior

By default, if no server preferences have been set with the nisprefadm command, a client will first try to obtain the information it needs from an NIS+ server on the client's local subnet. If the client finds an active server on the local subnet, it obtains the information it needs from the first local server that responds. If no server is available on the local subnet, the client searches outside the local subnet, and obtains the NIS+ information it needs from the first remote server that responds.

On large, busy networks, this default search behavior may reduce NIS+ performance for one of two reasons:

Designating NIS+ Preferred Servers

The Solaris release contains a new feature – server-use customization – that allows you to control the order in which clients search for NIS+ servers.

With this new feature you can balance and customize server usage by:

The search criteria that you specify can be applied to all clients within a domain, all clients on a subnet, or to individual clients on a machine-by-machine basis.

Note –

When server-use preferences are set for a particular machine, those preferences apply to all users, applications, processes, or other clients running on that machine. You cannot set different server-use patterns for different clients on the same machine.

NIS+ Over Wide Area Networks

Server-use customization is particularly valuable for large networks with many subnets and networks that span multiple geographic sites connected by modems or leased lines. To maximize network performance, you want to minimize network traffic between subnets, and between sites linked by slower connections. You can do that by specifying which NIS+ servers the clients can use, and their order of server preference. In this way you confine as much NIS+ network traffic as possible to the local subnet.

Optimizing NIS+ Server Use

This section provides an overview of server-use customization.

nis_cachemgr Is Required

Server-use customization requires that a client be running nis_cachemgr. If a client machine is not running nis_cachemgr, it cannot make use of server-use customization. If there is no nis_cachemgr running on a client machine, that client will use the first server it identifies as described in Default NIS+ Client Search Behavior.

NIS+ Global Table or Local File

Depending on how you use the nisprefadm command, it creates either a local client_info file or a domain client_info table:

Caution – Caution –

Use only the nisprefadm command to make changes to client_info files and tables. Never use other NIS+ commands such as nistbladm.

When working with client_info tables or files, you must use either the -G or the -L option to specify that your command apply to either the global table (-G) or local file (-L) of the machine you are running the command on.

NIS+ Preference Rank Numbers

Server preferences are controlled by giving each server a preference rank number. Clients search for NIS+ servers in order of numeric preference, querying servers with lower preference rank numbers before seeking servers with higher numbers.

Thus, a client will first try to obtain namespace information from NIS+ servers with a preference of zero. If there are no preference=0 servers available, then the client will query servers whose preference=1. If no 1's are available, it will try to find a 2, and then a 3, and so on until it either gets the information it needs or runs out of servers.

Preference rank numbers are assigned to servers with the nisprefadm command as described in Specifying NIS+ Global Server Preferences.

Server preference numbers are stored in client_info tables and files. If a machine has its own /var/nis/client_info file, it uses the preference numbers stored in that file. If a machine does not have its own client_info file, it uses the preference numbers stored in the domain's client_info.org_dir table. These client_info tables and files are called “preferred server lists” or simply server lists.

You customize server usage by controlling the server preferences of each client. For example, suppose a domain has a client machine named mailer that makes heavy use of namespace information and the domain has both a master server (nismaster) and a replica server (replica1). You could assign a preference number of 1 to nismaster and a number of 0 to replica1 for the mailer machine. The mailer machine would then always try to obtain namespace information from replica1 before trying nismaster. You could then specify that for all the other machines on the subnet the nismaster server had a preference number of zero and replica1 the number 1. This would cause the other machine to always try nismaster first.

You can give the same preference number to more than one server in a domain. For example, you could assign both nismaster1 and replica2 a preference number of 0, and assign replica3, replica4, and replica5 a preference number of 1.

Default NIS+ Server Preferences

If there is no client_info file or table, the cache manager automatically assigns all servers on the local subnet a default preference number of zero (0) and all servers outside the local subnet a preference of infinite. The purpose of nisprefadm is to change these default preference numbers to what you want them to be.

Efficiency and NIS+ Server Preference Numbers

A client must seek all servers with a given preference number before searching for servers with the next higher number. It requires 5 or more seconds for a client to search for all the servers with a given preference number. This means that if you have a master server and 4 replicas in a domain, and you give each one a different preference number from 0 to 4, it could take a client more than 25 seconds to run through all of those preference levels.

To maximize performance, you should not use more than two or three levels of server preference. For example, in the case described above, it is better to give one of those five servers a preference=0 and all the others a preference of 1, or give two of them a preference of 1 and the remaining three a preference of 2.

Preferred-Only NIS+ Servers and All Servers

Server lists also specify what a client does if it cannot find any preferred servers. A preferred server is any server with a preference of zero, or any server that you have assigned a preference number with nisprefadm.

By default, if a client fails to reach a preferred server, it will then seek out any server it can find anywhere on the network using the search mode described in Default NIS+ Client Search Behavior. You can change this default behavior with the nisprefadm -o option to specify that a client can only use preferred servers and if no servers are available it cannot go to non-preferred servers. See Specifying Preferred-Only Servers in NIS+ for details.

Note –

This option is ignored when the machine's domain is not served by any preferred servers.

Viewing NIS+ Preferences

To view the server preferences currently in effect for a particular client machine, you run nisprefadm with the -l option as described in Viewing NIS+ Machine Preferences.

NIS+ Server and Client Names

When specifying server or client machines, keep in mind the following points:

NIS+ Server Preferences

To specify a server preference for:

When NIS+ Server Preferences Take Effect

Changes you make to a machine or subnet's server preferences normally do not take effect on a given machine until that machine updates it nis_cachemgr data. When the nis_cachemgr of a machine updates its server-use information depends on whether the machine is obtaining its server preferences from a global client_info table or a local /var/nis/client_info file (see NIS+ Global Table or Local File).

However, you can force server preference changes to take effect immediately by running nisprefadm with the -F option. The -F option forces nis_cachemgr to immediately update its information. See Putting NIS+ Server Preferences Into Immediate Effect for details.

Using the nisprefadm Command

The following sections describe how to use the nisprefadm command to set, modify, and delete server preferences.

The nisprefadm command is used to specify the servers that clients are to prefer. The nisprefadm command has the following syntax:


nisprefadm -a|-m|-r|-u|-x|-l -L|-G [-o type] \
 [-d domain]  [-C machine] \
 servers
nisprefadm -F
Table 20–1 nisprefadm Command Options

Option 

Description 

-G

Create a global client_info table stored in the domain's org_dir directory. In other words, create a global preferred server list. This option must be used with either -C subnet to specify preferences for all the machines on a given subnet, or -C machine to specify preferences for an individual machine.

-L

Create a local client_info file stored in the local machine's /var/nis directory. In other words, create a preferred server list that applies only to the machine you are running the command on.

-o type

Specify an option. The valid options are: pref_type=all, which specifies that clients can use non-preferred servers if no preferred servers can be contacted, and pref_type=pref_only, which specifies that clients may only use the designated preferred servers.

-d domain

Create a global preferred server client_info table for the specified domain or subdomain. 

-C subnet

The number of a subnet to which the preferences will apply. 

-C machine

The name of a client machine. 

servers

One or more NIS+ servers. These are the servers that are to be preferred. 

-a

Add the specified servers to the server list. 

-m

Modify the server list. For example, you can use the -m option to change the preference number given to one or more servers.

-r

Remove the specified servers from the server list. 

-u

Clear the server list, and then add the specified servers. (In other words, replace the current server list with a new list of preferred servers.) 

-x

Remove the server list completely. 

-l

List (display) the current preferred server information. 

-F

Force changes to a preferred server list to take effect immediately. 

Note –

The -C machine option should not be used with the -L (local) flag because it has no effect. For example, suppose you are running nisprefadm on the altair machine. You use the -L flag to specify that the preferences you are specifying be written into altair's local client_info file. You also use a -C vega option to specify that the preferences you are creating be applied to the vega machine. The nisprefadmcommand then write your preferences for vega into altair's file. But vega will never see them because vega will always get its server preferences from either its own local client_info file or the domain's global client_info table. Thus, it only makes sense to use the -C option when running nisprefadm with the -G (global) flag.

Viewing NIS+ Machine Preferences

ProcedureHow to View Preferences for an NIS+ Server

To view current server preferences, run nisprefadm with the -l option.

  1. Run nisprefadm with the -l option.


    sirius# nisprefadm -l

ProcedureHow to View Preferences for an NIS+ Machine

  1. Run nisprefadm with the -L and -l options on the machine.


    sirius# nisprefadm -L -l

    This displays any server preferences defined in the machine's local /var/nis/client_info file. If there is no local file, no information is displayed and you are returned to your shell prompt.

ProcedureHow to View Global Preferences for an NIS+ Machine

  1. Run nisprefadm with the -l, -G and -C machinename options.


    sirius# nisprefadm -G -l -C machinename

    Where machinename is the IP address (number) of the machine.

    This displays the preferences set in the domain's global client_info table for that machine.

ProcedureHow to View Global Preferences for an NIS+ Subnet

  1. Run nisprefadm with the -l, -G and -C subnet options.


    sirius# nisprefadm -G -l -C subnet

    Where subnet is the IP address (number) of the subnet.

    This displays the preferences set in the domain's global client_info table for that machine.

Specifying NIS+ Preference Rank Numbers

By default, all servers listed after the -a option are given a preference number of zero. To specify a different preference number, enclose the number in parentheses immediately after the server name like this: -a name(n). Where name is the name of the server and n is the preference number.

For example, assign the replica2 server a preference number of 3:


# nisprefadm -G -a replica2(3)
Note –

With some shells you may have to enclose the element in quotes like this: "name(n)".

See NIS+ Preference Rank Numbers for background information on the server preference rank numbers.

Specifying NIS+ Global Server Preferences

You can set global server preferences for a local or remote domain. Preferences may be set for individual machines and all the machines on a subnet.

The procedures in this section describe how to specify server preferences in a global client_info table residing on the NIS+ domain's master server. Once the table exists on the master server, NIS+ replicates it on to any existing replica servers for the domain.

To assign server preference numbers, run nisprefadm with either the:

ProcedureHow to Set Global Preferences for an NIS+ Subnet

To assign server preferences in the global table for all the machines on a subnet:

  1. Run nisprefadm with the -G and -C subnet options.


    #nisprefadm -G -a -C subnet servers (preferences)

    Where:

    • -C subnet identifies the IP number of the subnet the preferences will apply to.

    • servers(preferences) are one or more servers with optional preference ranking numbers.

      For example, to specify that the subnet 172.22.123.123 uses the nismaster and replica3 servers with a default preference number of zero and the manf.replica6 server with a preference number of 1, type the following.


      polaris# nisprefadm -a -G -C 172.22.123.123 nismaster1 \
replica3 "manf.replica6(1)"

ProcedureHow to Set Global Preferences for an Individual NIS+ Machine

  1. Run nisprefadm with the -G, and -C machine options.


    #nisprefadm -G -a -C machine servers (preferences)

    Where:

    • -C machine identifies the machine the preferences will apply to. (Depending on the shell you are using, you may need to enclose machine in quotes.)

    • servers(preferences) are one or more servers with optional preference ranking numbers.

      For example, to replace the current preferences for the machine cygnus with replica7 and replica9 both with a default preference number of zero, type the following.


    polaris# nisprefadm -u -G -C cygnus replica7 replica9

ProcedureHow to Set Global Preferences for a Remote NIS+ Domain

To assign server preferences for an individual machine in a remote domain or all the machines on a subnet in a remote domain:

  1. Run nisprefadm with the -C, -G, and -d options.


    #nisprefadm -a -G -C name \
 -d domain servers(preferences)

    Where:

    • name is the IP number of a subnet or the name of a machine. The modifications you make with this command apply to the subnet or machine that you name.

    • domainname is the name of the remote domain.

    • servers(preferences) are one or more servers with optional preference ranking numbers.

    For example, to add the nismaster2 server with a default preference number of zero to the preferred server list of the 10.10.111.11 subnet in the remote sales.doc.com domain:


    polaris# nisprefadm -a -G -C 10.10.111.11 -d sales.doc.com. nismaster2

Specifying Local NIS+ Server Preference

These procedures explain how to create or change a local client_info file that specifies server preferences for the machine on which it resides.

If a machine has a local /var/nis/client_info file, that machine takes its server preferences from its local file rather than the global client_info tables on NIS+ servers. In other words, a local file overrides any global table.

To assign server preferences, run nisprefadm with either the:

ProcedureHow to Set Preferences on a Local NIS+ Machine

To assign server preferences for the local machine that you are running the nisprefadm command on:

  1. Run nisprefadm with the -L option and either the -a or -u options.


    #nisprefadm -a -L servers(preferences)

    Where servers(preferences) are one or more servers with optional preference ranking numbers.

    For example, to specify that the deneb machine first seek NIS+ information from the replica3 server with a default preference number of zero and then from the replica6 server (with a preference number of 1) in the manf.doc.com domain:


    deneb# nisprefadm -a -L replica3 replica6.manf(1)

Modifying NIS+ Server Preferences

You can change a server's preference number and switch (replace) the preference numbers assigned to different servers.

To change preferred servers or the preference number assigned to a server, run nisprefadm with the -m oldserver-=newserver(n) option.

ProcedureHow to Change an NIS+ Server's Preference Number

  1. Run nisprefadm with the -m server=server(new) option.


    #nisprefadm -L|-G -C name -m oldserver=newserver(n)

    Where:

    • -L|-G determines whether you are modifying a local file or a global table.

    • -C name is the IP number of a subnet or the name of a machine. This option is only used when you are also using the -G option. The modifications you make with this command apply to the subnet or machine that you name.

    • -m is the modify server list option.

    • old server is the name of the server whose preference number you want to change.

    • new server(n) is the server name and its new preference number.

    For example, on the deneb machine, to change the number given to the replica6.manf server to 2 in deneb's local client_info file:


    deneb# nisprefadm -L -m replica6.manf=replica6.manf(2)

ProcedureHow to Replace One NIS+ Server With Another in a Preference List

To change one server for another in a preference list:

  1. Run nisprefadm with the -m oldserver=newserver option.


    #nisprefadm -L|-G -C name -m \
 oldserver=newserver(prefnumber)

    Where:

    • -L|-G determine whether you are modifying a local or a domain-wide server list.

    • -C name is the IP number of a subnet or the name of a machine. This option is only used in when you are also using the -G option. The modifications you make with this command apply to the subnet or machine that you name.

    • -m is the modify-server-list option.

    • oldserver is the old server you are replacing.

    • newserver(prefnumber) is the new server (with an optional preference number) that is taking the old server's place in the preferred server list.

    Keep in mind that when you replace a server in a global client_info table using the -G option, the replacement only applies to the subnet or machine identified by the -C option. Other listings of the replaced server are not affected.

    For example, suppose you have a domain with three subnets, and the replica1 server is listed as a preferred server for two of those subnets. If replica1 is obsolete and you take it out of service, you then run nisprefadm -m to replace it with the new server for the first subnet. Until you do the same for the second subnet, replica1 is still listed as a preferred server for that subnet. The same principle applies to preferred servers for individual machines.

    For example, to replace the replica3 server with the replica6 server for subnet 172.21.123.12 in the domain's global client_info table and assign replica6 a preference number of 1:


    nismaster# nisprefadm -G -C 172.21.123.12 -m replica3 replica6(1)

ProcedureHow to Remove NIS+ Servers From Preference Lists

To remove one or more servers from a preference list:

  1. Run nisprefadm with the -r option.


    #nisprefadm -L|-G -C name -r servers

    Where:

    • -L|-G determines whether you are modifying a local or a domain-wide server list.

    • -C name is the IP number of a subnet or the name of a machine. This option is only used when you are also using the -G option. The preferred servers you remove with this command apply to the subnet or machine that you name.

    • -r removes the named servers from the list.

    For example, in the domain's global client_info table, to remove the replica3 and replica6.manf servers for the machine polaris:


    polaris# nisprefadm -G -C polaris -r replica3 replica6.manf

Replacing an Entire Preferred Server List in NIS+

To replace an entire list of preferred servers for a subnet or machine in either a global client_info table or a machine in its local client_info file, run nisprefadm with the -u option.

The -u option operates the same way as the -a option, except that -u first deletes any existing server preferences for the machine or subnet before adding the new ones that you specify. (If there are existing preferences, the -a option adds the new ones to the old list.)

See How to Set Global Preferences for an Individual NIS+ Machine for an example using the -u option.

Specifying Preferred-Only Servers in NIS+

You can specify what clients do when no preferred servers are available.

By default, if a client cannot reach a preferred server, it uses whatever other server it can find. You can specify that clients may only use preferred servers by setting the preferred-only option. See Preferred-Only NIS+ Servers and All Servers for background information on the preferred-only and all servers options.

To specify what clients do when no preferred servers are available, run nisprefadm with the -o value option.

ProcedureHow to Specify Preferred-Only Servers in NIS+

To specify that clients using a server list may only obtain NIS+ information from servers named in the list:

  1. Run nisprefadm with the -o pref_only option.


    #nisprefadm -L|-G -o pref_only

    Where:

    • -L|-G determines whether you are modifying a local or a domain-wide server list.

    • -o -pref_only specifies that clients can only obtain NIS+ information from servers on the list.

    Note –

    This option is ignored for domains that are not served by any preferred servers.

    For example, to specify in altair's local client_info file that altair must always use preferred servers and cannot use any server not on altair's preferred server list:


    altair# nisprefadm -L -o pref_only

ProcedureHow to Revert to Using Non-Preferred Servers in NIS+

To specify that clients using a server list may obtain NIS+ information from servers not named in the list if no preferred servers are available:

  1. Run nisprefadm with the -o all option.


    #nisprefadm -L|-G -o all

    Where:

    • -L|-G determines whether you are modifying a local or a domain-wide server list.

    • -o -all specifies that clients may obtain NIS+ information from servers not on the list if no preferred servers are available.

    Note –

    This is the default behavior. You only need to use the -o all option if you have previously specified preferred-only servers with the -o pref_only option.

    For example, to specify in altair's local client_info file that altair can now use non-preferred servers if no preferred servers can be reached:


    altair# nisprefadm -L -o all

Ending Use of Server Preferences in NIS+

You can stop using server-use customization and revert to the obtaining NIS+ information as described in Default NIS+ Client Search Behavior.

To end server preferences, run nisprefadm with the -x option.


# nisprefadm -G -x
Note –

When you end server preferences, clients do not stop using server preferences until the normal course of events as described When NIS+ Server Preferences Take Effect. You can force an immediate end to server preferences as described in Putting NIS+ Server Preferences Into Immediate Effect.

Eliminating Local Server Preferences in NIS+

Ending local preferences can mean one of three different things:

ProcedureHow to Switch From Local to Global Subnet Preferences in NIS+

  1. Remove the machine's /var/nis/client_info file.


    # rm /var/nis/client_info

    This causes the machine to use the preferences specified for the machine's subnet in the domain's global client_info table.

ProcedureHow to Switch From Local to Machine-Specific Global Preferences in NIS+

  1. Remove the machine's /var/nis/client_info file.


    # rm /var/nis/client_info

  2. Specify preferences for the machine in the global table using the -G and -C options.

    See How to Set Global Preferences for an Individual NIS+ Machine.

ProcedureHow to Stop a Machine From Using Any Server Preferences in NIS+

  1. Remove the machine's /var/nis/client_info file.


    # rm /var/nis/client_info

    If the machine's domain does not have a global client_info table, this step is all you have to do. If the domain does have a client_info table, continue on to the next step.

  2. Create an empty /var/nis/client_info file.


    # touch /var/nis/client_info

    When a machine has its own /var/nis/client_info file, it does not use global preferences from any client_info table. If the machine has an empty /var/nis/client_info file, it will not use any preferences at all and will obtain NIS+ information, as described in Default NIS+ Client Search Behavior.

Putting NIS+ Server Preferences Into Immediate Effect

Server-use changes normally go into effect whenever the client machine is rebooted or updates its cache manager.

When you use nisprefadm to set or change server preferences on a local machine using a local client_info file (the -L option), your changes go into effect immediately.

For machines obtaining their server preferences from a global client_info table (the -G option) you can force server preference changes into immediate effect by running nisprefadm a particular with the -F option.


# nisprefadm -F

For example, to force immediate implementation of changes to vega's preferred server list (whether local or global):


vega# nisprefadm -F

The -F option forces the machine's cache manager to immediately update its server preference information from the domain's global client_info table. If the machine on which you run nisprefadm -F has its own local client_info file in /var/nis, running this command will have no effect.

Note –

You cannot use the -F option with any other nisprefadm options. The nisprefadm -F command must always be run by itself on the machine you want it to apply to. You cannot use the -G option to update the cache managers of all machines in a domain. The nisprefadm -F command must be run on each machine individually.