Chapter 20 Server-Use Customization

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

NIS+ might not be supported in a future release. Tools to aid the migration from NIS+ to LDAP are available in the Solaris 9 operating environment (see System Administration Guide: Naming and Directory Services (DNS, NIS, and LDAP)). For more information, visit http://www.sun.com/directory/nisplus/transition.html.

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 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:

• When multiple servers on a subnet are serving a large number of clients, the random nature of the client's default search pattern may result in some servers being over worked while others are under used.

• When a client has to seek an NIS+ server beyond the local subnet, it will obtain its information from the first server that responds even if that server is overworked, or linked to the client's subnet by a slower Wide Area Network connection such as a modem or a dedicated line that is already carrying heavy traffic.

Designating Preferred Servers

The Solaris operating environment 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:

• Specifying that clients prefer (search for) certain servers over others.

• Specify whether or not clients are permitted to use remote servers if no local servers are available.

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.

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 Server-Use—Overview

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 Client Search Behavior.

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:

• File. You can use nisprefadm to create a local, machine-specific client_info file that is stored in the machine's /var/nis directory. A local file specifies server preferences for that machine only. When a machine has a local /var/nis/client_info file, it ignores any server preferences contained in a domain client_info.org_dir table. To create a local client_info file, you run nisprefadm with the -L option.

• Table. You can use nisprefadm to create an NIS+ client_info table which is stored in each domain's org_dir NIS+ directory object. This table can specify server preferences for:

  • Individual machines. (If a machine has a local /var/nis/client_info file, any preferences for that machine that happen to be in the domain client_info table are ignored.)

  • All the machines on a particular subnet. (If a machine on the subnet has a local /var/nis/client_info file or individual preferences set for it in the table it ignores subnet preferences.)

  To create a global client_info table that applies to all machine on a subnet, you run nisprefadm with the -G and -C options as described in Specifying Global Server Preferences.

  Note that if a machine has its own local client_info file as described below, it will ignore all server preferences set for it in a global client_info table. If a machine has either a local client_info file or a machine-specific entry for it in the global client_info table, it will ignore preferences set for its subnet.

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.

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 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 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 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 Servers Versus 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 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 for details.

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

Viewing 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 Current Server Preferences.

Server and Client Names

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

• Server and client names do not need to be fully qualified so long as they are in the same NIS+ domain and uniquely identify the object. You can simply use the machine name by itself.

• If a server or subnet is in another NIS+ domain, you need to include enough of the domain name to uniquely identify that machine. For example, if you are in the sales.doc.com domain and you need to specify the nismaster2 machine in the manf.doc.com domain, you need only enter nismaster2.manf.

Server Preferences

To specify a server preference for:

• Individual client machine, use the -L option to create a local client_info file for the machine you are running the nisprefadm on. Use the -G -C machine options to create machine-specific preferences in the global client_info table.

• All machines on a subnet, use the -G -C subnetnumber option.

• All machines in the current domain that do not have machine-specific or subnet-specific preferences, use the -G option.

When 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 Global Table or Local File).

• Global table. The cache managers of machines obtaining their server preferences from global tables update their server preferences whenever the machine is booted or whenever the Time-to-live (TTL) value expires for the client_info table. By default, this TTL value is 12 hours, but you can change that as described in Changing the Time-to-Live of an Object.

• Local file. The cache managers of machines obtaining their server preferences from local files update their server preferences every 12 hours or whenever you run nisprefadm to change a server preference. (Rebooting the machine does not update the cache manager's server preference information.)

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 How to Immediately Implement Preference Changes 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

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 Current Server Preferences

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

How to View Preferences for a Machine

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.

How to View Global Preferences for Single Machine

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.

How to View Global Preferences for a Subnet

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.

How to Specify 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)

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

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

Specifying 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.

• See Specifying Local Server Preference for information on how to create a local client_info file on an individual machine.

• See Global Table or Local File for an explanation of the difference between a global client_info table and a local client_info file.

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

• -a option to add new or additional preferred servers.

• -u option to delete existing server preferences and create new ones.

How to Set Global Preferences for a Subnet

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

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 123.123.123.123 use the nismaster and replica3 servers with default preference number s of zero and the manf.replica6 server with a preference number of 1:

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

How to Set Global Preferences for an Individual Machine

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:

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

How to Set Global Preferences for a Remote Domain

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

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 111.11.111.11 subnet in the remote sales.doc.com domain:

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

Specifying Local 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.

• See Specifying Global Server Preferences for information on how to create a global client_info tables for NIS+ servers.

• See Global Table or Local File for an explanation of the difference between a global client_info table and a local client_info file.

To assign server preferences, run nisprefadm with either the:

• -a option to add new or additional preferred servers.

• -u option to delete existing server preferences and create new ones.

How to Set Preferences on a Local Machine

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

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 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.

How to Change a Server's Preference Number

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)

How to Replace One Server With Another in a Preference List

To change one server for another in a preference list:

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 123.12.123.12 in the domain's global client_info table and assign replica6 a preference number of 1:

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

How to Remove Servers From Preference Lists

To remove one or more servers from a preference list:

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

How to Replace an Entire Preferred Server List

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 Machine for an example using the -u option.

Specifying Preferred-Only Servers

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 Servers Versus 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.

How to Specify Preferred-Only Servers

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

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.

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

How to Revert to Using Non-Preferred Servers

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:

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.

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

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

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

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

How to Eliminate Global Server Preferences

Run nisprefadm with the -G and -x options.

#nisprefadm -G -x

This eliminates global server preferences.

• Client machines that do not have local server preferences will obtain NIS+ information as described in Default Client Search Behavior.

• Client machines that do have local server preferences set by a local /var/nis/client_info file will continue to use servers as specified in that file.

How to Eliminate Local Server Preferences

Ending local preferences can mean one of three different things:

• That you want the machine to stop using its local client_info file for its server preferences and start using the preferences set for its subnet in the domain's global client_info table.

• That you want this machine to stop using its local client_info file for its server preferences and start using the preferences set for it specifically in the domain's global client_info table.

• That you do not want the machine to use server preferences at all. When a machine does not use server preferences, it obtains NIS+ information as described in Default Client Search Behavior.

How to Switch From Local to Global Subnet Preferences

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.

How to Switch From Local to Machine-Specific Global Preferences

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 Machine.

How to Stop a Machine From Using Any Server Preferences

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 Client Search Behavior.

Putting 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

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 nisprefadm -F on it will have no effect.)

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.

How to Immediately Implement Preference Changes

To force a newly created or modified server list into immediate effect on a given machine:

Run nisprefadm with the -F option on that machine.

# nisprefadm -F

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

vega# nisprefadm -F