NIS tools (Managing NFS and NIS, 2nd Edition)

13.4. NIS tools

Tools discussed to this point help to dissect the session and transport layers under an application such as NIS. The application and the utilities that analyze its behavior and performance all rely on a well-behaved network. Assuming that the lower layers are in place, NIS-oriented tools fine-tune the NIS system and help resolve problems that are caused by information in the NIS maps, rather than the way in which the maps are accessed. The tools described in this section alter client-server bindings, locate NIS servers and information for a particular map, and look up keys in maps.

13.4.1. Key lookup

ypmatch is a grep-like command for NIS maps. ypmatch finds a single key in an NIS map and prints the data associated with that key:

% ypmatch help-request aliases 
john.goodman
 
% ypmatch onaga hosts 
131.40.52.27   onaga

This procedure differs from using grep on the ASCII source file that produced the map in two ways:

ypmatch can be run from any client, while the NIS map source files may only exist on a server with limited user access. Therefore, users who need to parse maps such as the password, ipnodes, or hosts files must use NIS-oriented tools to gather their data.
The client may be bound to an NIS server with a corrupted map set or one that is out-of-date with the NIS master server. In this case, the output of ypmatch will not agree with the output of grep run on the ASCII source file.

Associated with ypmatch is ypcat, which is the equivalent of cat for NIS files. It writes the entire map file to the standard output:

% ypcat hosts 
131.40.52.121  vineyard         
131.40.52.54   hannah           
131.40.52.132  positive

NIS maps are stored as DBM databases, indexed files with fast access provided through a hash table. Standard utilities such as grep do not produce meaningful results when used on DBM data files. To peek into the contents of an NIS map, you must use ypmatch or ypcat. Output from NIS tools is colored by the underlying DBM index file organization, and presents several avenues of confusion:

By default, only the value paired with the key in the map is displayed, and not the key itself. Some maps retain the key as part of the data value because it is needed by applications that retrieve the map entry. Library routines that locate a password file entry based on UID, for example, return the user's login name as part of the password file structure. Other maps such as aliases simply store the value associated with the key, when applications (such as mail) that reference the NIS map already have the key value. The following excerpt from ypcat aliases is of little value because there are no alias names associated with the alias expansions:
```
% ypcat aliases
dan, lauri, paul, harry, bob
dave, michael
michael, jan, stewart, tom
```
Both ypcat and ypmatch use the -k option to print the data value with its associated key:
```
% ypcat -k aliases
south-sales     dan, lauri, paul, harry, bob
engin-managers  dave, michael
north-engin     michael, jan, stewart, tom
```

Some maps do not associate a data value with a key. The most common map of this variety is the ypservers map, which simply contains hostnames of NIS servers without any additional information. When using ypcat or ypmatch with value-less maps, blank lines are produced as output:
```
% ypcat ypservers
```
unless the -k option is specified:
```
% ypcat -k ypservers
>mahimahi
wahoo
thud
```

An NIS server implements separate procedures to get the "first" and each successive key in a map. ypcat uses the "get first key" and "get next key" procedures to locate the first key in the DBM file and to walk through all keys. The ordering of the keys is determined by a linear scan through the DBM index file, rather than the order in which the records appear in the plain text file. Because keys are encountered in the order in which they are hash chained together, ypcat produces a seemingly random ordering of the keys. In the hosts file example earlier, the original /etc/inet/hosts file was sorted by increasing host number in the IP addresses; but the process of hashing the keys into the DBM file produced the ordering seen with ypcat.

As a diagnostic tool, ypmatch can be used to identify NIS maps that are out of synchronization even after a map transfer has been requested or scheduled. It is often used to see if a change has taken place. After a new map is built, it is generally pushed to other servers using yppush. However, NIS map changes may not propagate as quickly as desired. A slave server may be down when a map transfer occurs, in which case it will not get an updated map until the next ypxfr transfer.

13.4.2. Displaying and analyzing client bindings

ypwhich provides information about a client's NIS domain binding, and the availability of master servers for various maps in the domain. With no arguments, it returns the name of the NIS server to which the client is currently bound by ypbind:

% ypwhich 
mahimahi

If a hostname is passed as a parameter, then ypwhich queries the named host for its current binding. If ypwhich cannot resolve the hostname into an IP address, it reports an error:

% ypwhich gonzo 
ypwhich: clnt_create error: RPC: Unknown host

An IP address may be used in place of a hostname if you are debugging NIS problems, since NIS itself is used to map the hostname into an IP address. If NIS operation is not reliable, then explicit IP addresses should be used with all of the NIS-oriented debugging tools. For example:

% ypwhich 131.40.52.34 
wahoo

Querying client bindings individually is useful for debugging client problems, but it doesn't provide much useful information about the use of NIS on the network. ypwhich is better suited for answering questions about NIS servers: Are there enough servers? Are the clients evenly distributed among the NIS servers? There is no client binding information kept by an NIS server -- the binding is something created by the client and known only to the client. The server simply answers requests that are sent to it. To determine the distribution of NIS clients to servers, you must poll the clients.

ypwhich, embedded in a shell script, collects NIS client demographics to perform a "census" of server usage:

#! /bin/sh 
#       ypcensus - poll for ypservers 
( for h in `ypcat hosts | awk '{print $2}'` 
  do 
        ypwhich $h 
  done ) | grep -v 'not running' | sort | uniq -c

The for expression dumps the hosts NIS file, and awk extracts the second field -- the hostname -- from each entry. The loop then queries each host for its NIS server, and then the output from the loop is sorted. The entire loop is executed in a subshell so that its output is treated as a single stream by the next stage of the command pipeline. The grep command filters out errors from ypwhich, produced when an NIS client has not found a server for its domain. At the end of the pipe, uniq -c counts the occurrences of each line, producing the census of NIS servers. Sample output from the script is:

% ypcensus 
 26 onaga 
  7 mahimahi 
  8 thud

You may find that the total number of bindings recorded is less than the number of clients -- some clients may not have formed a server binding when the script was run. Executing ypwhich causes the client to bind to a server, so if you "miss" some hosts on the first attempt, execute the script again after all clients have been forced to find servers.

What does the output indicate? With multiple NIS servers, it is possible for the client distribution to load one server more heavily than the others. In the previous example, the large number of clients bound to server onaga could be caused by several things:

The NIS server onaga is significantly faster than the other NIS servers, so it always replies to ypbind requests before other servers.
The servers have about the same CPU speed, so the lopsided binding indicates that onaga has the lightest CPU load. It generates replies faster than the other servers.
onaga may be "closer" to more NIS clients on the network, counting delays in network hardware. Network topology favors NIS servers that are physically close to the client if bridges or repeaters separate clients and potential NIS servers, adding packet transmission delays that can overshadow CPU scheduling delays on loaded servers.

The few clients bound to mahimahi and thud may experience NIS timeouts if these NIS servers are heavily loaded. The relatively small number of clients bound to these servers may indicate that they aren't the best candidates for NIS service because they have a higher CPU load.

Results of the binding poll should be compared to desired goals for balancing NIS server usage. If one NIS server is much faster than the others, you may improve the NIS binding distribution by shifting the fast machine's NIS service to one or two machines that are more similar to the other NIS servers.

To see if you have enough NIS servers, or if your choice of servers provides adequate NIS service, watch for broadcasts from NIS clients to the yserv port. You can observe network broadcasts using a tool like snoop or ethereal, both of which watch every packet on the network and print those that meet a defined criteria. ethereal and snoop are introduced in Section 13.5, "Network analyzers". To find all ypbind broadcasts, use the following snoop command line:

# snoop broadcast port sunrpc 
        aqua -> 131.40.52.255 NIS C DOMAIN_NONACK mydomain.com
   semaphore -> 131.40.52.255 NIS C DOMAIN_NONACK mydomain.com

ypbind sends its RPC broadcast to the portmapper on the sunrpc port (port 111), and the portmapper calls the ypserv process indirectly. If you see a large number of broadcast calls being made to the portmapper, then your NIS clients are rebinding frequently and you should add more NIS servers or choose servers that have a lighter load.

13.4.3. Other NIS map information

In addition to providing NIS server binding information, ypwhich examines the NIS map information: the master server for a map, the list of all maps, and map nickname translations. Map nicknames are more mnemonic forms of map names used in place of the actual DBM filenames in NIS-related utilities; the nickname usually has the .byaddr or .byname suffix removed. Nicknames exist only within the ypmatch, ypcat, and ypwhich utilities; they are not part of the maps and are not part of the NIS servers. No application will ever perform a key lookup in map passwd; it has to use passwd.byname or passwd.byuid.

ypwhich -x prints the table of nicknames:

% ypwhich -x 
Use "passwd"           for map "passwd.byname"
Use "group"            for map "group.byname"
Use "networks"         for map "networks.byaddr"
Use "hosts"            for map "hosts.byname"
Use "protocols"        for map "protocols.bynumber"
Use "services"         for map "services.byname"
Use "aliases"          for map "mail.aliases"
Use "ethers"           for map "ethers.byname"
Use "ipnodes"          for map "ipnodes.byname"
Use "project"          for map "project.byname"

While map nicknames provide a shorter command-line option for tools that take a map name as a parameter, they can also create name conflicts with non-standard maps that share commonly used map names. For example, a daemon that maps popular internal resource server names to IP ports might create an NIS map called services advertising its default mappings. This map name will not conflict with the NIS map created from /etc/inet/services because the latter is converted into the map services.byname. Users of ypcat and ypmatch may be surprised by output that appears to confuse the map names.

The following example doesn't work at first because the ypmatch utility turns the map name services into services.byname, using the standard nickname translation. NIS completely ignores the map you want. If you use ypmatch -t, nickname translation is suppressed and you locate the desired map:

% ypmatch cullinet services 
Can't match key cullinet in map services.byname.  Reason: no such key in map. 
% ypmatch -t cullinet services 
cullinet        6667

If you create your own maps, it's best to pick names that do not conflict with the standard map nicknames. Finally, ypwhich finds the master server for a map, or prints the list of all known maps if passed the -m option:

% ypwhich -m passwd 
mahimahi 
% ypwhich -m 
excerpt follows 
protocols.byname mahimahi
passwd.byuid mahimahi
passwd.byname mahimahi
hosts.byname mahimahi
rpc.bynumber mahimahi
group.bygid mahimahi
netmasks.byaddr mahimahi
hosts.byaddr mahimahi
netgroup mahimahi
group.byname mahimahi
mail.aliases mahimahi
services.byname mahimahi
netgroup.byhost mahimahi
protocols.bynumber mahimahi
ethers.byname mahimahi
bootparams mahimahi
ypservers mahimahi

ypwhich -m examines the NIS master server name embedded in the NIS map DBM file.

You can also explode an NIS map using makedbm -u, which "undoes" a DBM file. You see the data records as well as the two additional records added by DBM containing the NIS master name and the map's timestamp. If you have concerns about data disappearing from NIS maps, dump the entire map (including keys) using makedbm -u:

[wahoo]% cd /var/yp/nesales 
[wahoo]% /usr/etc/yp/makedbm -u  ypservers 
YP_LAST_MODIFIED 0649548751 
YP_MASTER_NAME wahoo 
wahoo wahoo 
redsox redsox 
thud thud

The map master information is useful if you have changed NIS master servers and need to verify that client maps are built correctly and synchronized with the new master server.

13.4.4. Setting initial client bindings

The ypinit command is used to preconfigure a list of NIS servers to contact at startup time. ypinit stores the list of NIS servers in the file /var/yp/binding/domainname/ypservers, where domainname resolves to your NIS domain name. Normally, ypinit is run only once after installing the system, though it may also be run whenever a new NIS server is added to the network or an existing one is decommissioned:

# ypinit -c

In order for NIS to operate sucessfully, we have to construct a list of the 
NIS servers.  Please continue to add the names for YP servers in order of
preference, one per line.  When you are done with the list, type a <control D>
or a return on a line by itself.
	next host to add:  onaga
	next host to add:  mahimahi
	next host to add:  131.40.52.126
	next host to add:  ^D
The current list of yp servers looks like this:

onaga
mahimahi
131.40.52.126

Is this correct?  [y/n: y]  y

Make sure to include the necessary hostname to IP address mappings in /etc/inet/ipnodes or /etc/inet/hosts before running the ypinit command, otherwise ypinit will fail. The resulting ypservers file:

% cat ypservers
onaga
mahimahi
131.40.52.126

Note that it is not necessary to preconfigure an initial list of NIS servers, since ypbind will broadcast a request on the network to find the available servers if the initial list does not exist. ypbind is started by /usr/lib/netsvc/yp/ypstart which in turn is invoked by the /etc/init.d/rpc startup script:

Excerpt from /usr/lib/netsvc/yp/ypstart:
if [ -d /var/yp/binding/$domain -a -f /var/yp/binding/$domain/ypservers ]; then
        /usr/lib/netsvc/yp/ypbind > /dev/null 2>&1
        echo " ypbind\c"
elif [ -d /var/yp/binding/$domain ]; then
        /usr/lib/netsvc/yp/ypbind -broadcast > /dev/null 2>&1
        echo " ypbind\c"
fi

The next section will explain in more detail when and why you may want to bind to specific NIS servers, and how you can modify the binding once ypbind has been started.

13.4.5. Modifying client bindings

The ypset utility forcefully changes the server binding. It is mostly used to dissect tangles of intertwined NIS servers and to point a client at a server that is not hearing its broadcasts. The normal NIS server search is conducted by ypbind through a broadcast request. The first server answering the request is bound to the domain, and is probably the most lightly loaded or closest server to the requesting host. As shown in the previous rpcinfo examples, a server's response time, relative to other NIS servers, varies over time as its load fluctuates.

If the server's load increases so that NIS requests are not serviced before the RPC call times out on the client machine, then the client's ypbind daemon dissolves the current binding and rebroadcasts a request for NIS service. With varying server loads and local network traffic conditions, the timeout/rebroadcast system effects a dynamic load balancing scheme between NIS clients and servers.

Neither ypset nor ypinit should be used to implement a static load balancing scheme for two reasons:

The initial ypinit or ypset may implement your chosen server allocation, but poor response time from this server causes the client to break the binding and perform a broadcast-based search. This dynamic rebinding will undo the attempts to effect a preferred binding.
Extreme disparity in NIS server usage is indicative of other network problems or of excessive server loading imposed by NFS service, interactive use, or print spooling.

There are four valid uses of ypinit and ypset:

Point a client at an NIS server that is isolated from it by a router or gateway that does not forward broadcast packets.
Test the services provided by a particular server, if you have recently installed or rebuilt the maps on that server.
Force servers to rebind to themselves instead of cross-binding.
Point a client to use a known and trusted server for security reasons, instead of using any NIS server on the network.

Again, ypinit is used to set the initial static binding at boot time, ypset is used to change this binding after boot time. It is recommended to use an IP address as the argument to ypset to avoid using the very same NIS service that ypbind is having trouble starting.

# ypset 131.40.52.28 
# ypwhich 
mahimahi

Alternatively, you can verify that the /etc/inet/ipnodes or /etc/inet/hosts file lists the IP address for the new NIS server, and that /etc/nsswitch.conf is configured to use files before it uses NIS.

In some NIS implementations (Solaris and others), ypbind no longer allows ypset to change its binding unless this functionality is explicitly enabled. If the -ypset option is used when ypbind is started, then ypbind accepts requests from any remote machine to rebind to a specified server:

ypbind -ypset

The use of -ypset is a security risk as it allows a third party to change the binding to a potentially hostile server. Without the -ypset parameter, attempts to change the server binding will fail:

wahoo# ypset thud 
ypset: Sorry, ypbind on host localhost has rejected your request.

A more restrictive form is:

ypbind -ypsetme

which only allows root on the local machine to invoke ypset to alter the binding. To discourage manually changing the binding, the startup script does not specify either of these options when it invokes ypbind.