test

Solaris Naming Administration Guide

Working With NIS Maps

The following sections describe how to administer NIS maps.

Obtaining Map Information

Users can obtain information from and about the maps at any time by using the ypcat, ypwhich, and ypmatch commands. In the examples that follow, mapname refers both to the official name of a map and to its nickname, if any.

To list all the values in a map, type:


% ypcat mapname

To list both the keys and the values (if any) in a map, type:


% ypcat -k mapname

To list all the map nicknames, type any of the following commands:


% ypcat -x
 

% ypwhich -x
 

% ypmatch -x

To list all the available maps and their master(s), type:


% ypwhich -m

To list the master server for a particular map, type:


% ypwhich -m mapname

To match a key with an entry in a map, type:


% ypmatch key mapname

If the item you are looking for is not a key in a map, type:


% ypcat mapname | grep item

Where item is the information you are searching for. To obtain information about other domains, use the -d domainname options of these commands.

If the machine requesting information for a domain other than its default does not have a binding for the requested domain, it causes ypbind to consult the /var/yp/binding/domainname/ypservers file for a list of servers for that domain. If this file doesn't exist it issues an RPC broadcast for a server. In this case, there must be a server for the requested domain on the same subnet as the requesting machine.

Changing a Map's Master Server

To change the master server for a selected map, you first have to build the map on the new NIS master. Since the old master server name occurs as a key-value pair in the existing map (this pair is inserted automatically by makedbm), copying the map to the new master or transferring a copy to the new master with ypxfr is insufficient. You have to reassociate the key with the new master server name. If the map has an ASCII source file, you should copy this file to the new master.

Here are instructions for remaking a sample NIS map called sites.byname.

  1. Log in to the new master as superuser and type:


    newmaster# cd /var/yp

  2. Makefile must have an entry for the new map before you specify the map to make. If this is not the case, edit the Makefile now.

  3. To update or remake the map, type:


    newmaster# make sites.byname

  4. If the old master remains an NIS server, remote log in (rlogin) to the old master and edit Makefile. Comment out the section of the Makefile that made sites.byname so that it is no longer made there.

  5. If sites.byname only exists as an ndbm file, remake it on the new master by disassembling a copy from any NIS server, then running the disassembled version through makedbm: 


    newmaster# cd /var/yp
newmaster# ypcat -k sites.byname | makedbm -domain/sites.byname

    After making the map on the new master, you must send a copy of the new map to the other slave servers. However, do not use yppush, because the other slaves will try to get new copies from the old master, rather than the new one. A typical method for circumventing this is to transfer a copy of the map from the new master back to the old master. To do this, become superuser on the old master server and type: 


    oldmaster# /usr/lib/netsvc/yp/ypxfr -h newmaster sites.byname

    Now it is safe to run yppush. The remaining slave servers still believe that the old master is the current master. They attempt to get the current version of the map from the old master. When they do so, they will get the new map, which names the new master as the current master.

    If this method fails, you can try this cumbersome but sure-fire option: log in as root on each NIS server and execute the ypxfr command shown above.

Modifying Configuration Files

NIS intelligently parses the setup files. Although this makes NIS administration easier, it does make the behavior of NIS more sensitive to changes in the setup and configuration files.

Use the procedures in this section when modifying any of the following:

To modify any of the listed files:

  1. Stop the NIS server by typing;


    # /etc/init.d/yp stop

  2. Make the necessary changes to your files.

  3. Restart the NIS server by typing:


    # /etc/init.d/yp start

You do not have to stop and start NIS when changing NIS maps or the map source files.

Keep in mind the following points:

Modifying and Using the Makefile

You can modify the Makefile provided by default in /var/yp to suit your needs. (Be sure to keep an unmodified copy of the original Makefile for future reference.) You can add or delete maps, and you can change the names of some of the directories.

To add a new NIS map, you must get copies of the ndbm files for the map into the /var/yp/domainname directory on each of the NIS servers in the domain. This is normally done for you by the Makefile. After deciding which NIS server is the master of the map, modify the Makefile on the master server so that you can conveniently rebuild the map. Different servers can be masters of different maps, but in most cases this leads to administrative confusion, and it is strongly recommended that you set only one server as the master of all maps.

Typically a human-readable text file is filtered through awk, sed, or grep to make it suitable for input to makedbm. Refer to the default Makefile for examples. See the make man page for general information about the make command.

Use the mechanisms already in place in the Makefile when deciding how to create dependencies that make will recognize. Be aware that make is very sensitive to the presence or absence of tabs at the beginning of lines within the dependency rules, and a missing tab can invalidate an entry that is otherwise well formed.

Adding Makefile Entries

To add an entry to the Makefile, do the following:

For example, in order for the Makefile to work on automounter input files, you would have to add the auto_direct.time and auto_home.time maps to the NIS database.

To add these maps to the NIS database:

  1. Modify the line that starts with the word all by adding the name(s) of the database you want to add:


    all: passwd group hosts ethers networks rpc services protocols \
	netgroup bootparams aliases netid netmasks \
	auto_direct auto_home auto_direct.time auto_home.time

    The order of the entries is not relevant, but the blank space at the beginning of the continuation lines must be a Tab, not spaces.

  2. Add the following lines at the end of the Makefile:


    auto_direct: auto_direct.time
auto_home: auto_home.time

  3. Add an entry for auto_direct.time in the middle of the file.

    

    

    


    

    auto_direct.time: $(DIR)/auto_direct
 @(while read L; do echo $$L; done < $(DIR)/auto_direct
 $(CHKPIPE)) | \ (sed -e "/^#/d" -e "s/#.*$$//" -e "/^ *$$/d"
 $(CHKPIPE)) | \ $(MAKEDBM) - $(YPDBDIR)/$(DOM)/auto_direct;
 @touch auto_direct.time;
 @echo "updated auto_direct";
 @if [ ! $(NOPUSH) ]; then $(YPPUSH) auto_direct; fi
 @if [ ! $(NOPUSH) ]; then echo "pushed auto_direct"; fi
    
    		

    

    

    Where:
    



      

    • 

      
CHKPIPE makes certain that the operations to the left of the pipe (|) are successfully completed before piping the results to next commands. If the operations to the left of the pipe do not successfully complete, the process is terminated with a "NIS make terminated" message. 

      


      • 

    • 

      NOPUSH prevents the makefile from calling yppush to transfer the new map to the slave servers. If NOPUSH is not set, the push is done automatically. 

      


      • 

    


    The while loop at the beginning is designed to eliminate any backslash-extended lines in the input file. The sed script eliminates comment and empty lines, and feeds the output to 

    


    The same procedure should be followed for all other automounter maps such as auto_home, or any other nondefault maps.
    


    4. 


  4. 

    Run make. 

    


    

    


    

    # make name
    
    		

    

    

    Where name is the name of the map you want to make. For example, auto_direct.
    


    5. 



Deleting Makefile Entries


If you do not want the Makefile to produce maps for a specific database, edit the Makefile as follows:



    


  1. 

    Delete the name of the database from the all rule.
    


    2. 


  2. 

    Delete or comment out the database rule for the database you want to delete.
    


    For example, to delete the hosts database, the hosts.time entry should be removed.

    


    3. 


  3. 

    Remove the time rule.
    


    For example, to delete the hosts database, the hosts: hosts.time entry should be removed.
    


    4. 


  4. 

    Remove the map from the master and slave servers.
    


    5. 



Changing Makefile Macros/Variables


You can change the settings of the variables defined at the top of the Makefile simply by changing the value to the right of the equal sign (=). For instance, if you do not want to use the files located in /etc as input for the maps, but you would rather use files located in another directory, such as /var/etc/domainname, you should change the value of DIR from DIR=/etc to DIR=/var/etc/domainname. You may also change the value of PWDIR from PWDIR=/etc to PWDIR=/var/etc/domainname.


The variables are:



Updating Existing Maps


After you have installed NIS, you might discover that some maps require frequent updating while others never need to change. For example, the passwd.byname map can change frequently on a large company's network. On the other hand, the auto_master map changes little, if at all.


When you need to update a map, you can use one of two updating procedures, depending on whether it is a default map or not.



The following sections explain how to use various updating tools. In practice, you might decide to only use them if you add nondefault maps or change the set of NIS servers after the system is already up and running.


Modifying Default Maps


Use the following procedure for updating maps supplied with the default set.


    


  1. 

    Become root on the master server.
    


    Always modify NIS maps only on the master server.
    


    2. 


  2. 

    Edit the source file for the map you want to change, whether that file resides in /etc or in some other directory of your choice.
    


    3. 


  3. 

    Type the following:
    


    

    


    

    # cd /var/yp# make mapname

    
    		

    

    

    The make command then updates your map according to the changes you made in its corresponding file. It also propagates the changes among the other servers.

    


    4. 



Modifying Nondefault Maps


To update a nondefault map, you must:


    

  1. 

    Create or edit its corresponding text file.
    


    2. 

  2. 

    Build (or rebuild) the new or updated map. There are two ways to build a map:
    



      

    • 

      Use the Makefile. Using the Makefile is the preferred method of building a non-default map. If the map has an entry in the Makefile, simply run make name where name is the name of map you want to build. If the map does not have a Makefile entry, try to create one following the instructions in "Modifying and Using the Makefile".

      


      • 

    • 

       Use the /usr/sbin/makedbm program. (The makedbm man page fully describes this command.)
      


      • 

    


    3. 



Using makedbm to Modify a Non-Default Map
There are two different methods for using makedbm to modify maps if you do not have an input file:





Creating New Maps


To create new maps, you can use one of two possible procedures: the first method uses an existing text file as input; the second uses standard input.


Creating Maps From Text Files
Assume that a text file /var/yp/mymap.asc was created with an editor or a shell script on the master. You want to create an NIS map from this file and locate it in the homedomain subdirectory. To do this, type the following on the master server:










# cd /var/yp
# makedbm mymap.asc homedomain/mymap






The mymap map now exists on the master server in the directory homedomain. To distribute the new map to slave servers run ypxfr.




Adding Entries to a File-Based Map
Adding entries to mymap is simple. First, you must modify the text file /var/yp/mymap.asc. (If you modify the actual dbm files without modifying the corresponding text file, the modifications are lost.) Then run makedbm as shown above. 




Creating Maps From Standard Input
When no original text file exists, create the NIS map from the keyboard by typing input to makedbm, as shown below (end with Control-D):










ypmaster# cd /var/yp
ypmaster# makedbm - homedomain/mymapkey1 value1 key2 value2 key3 value3
ypmaster#







Modifying Maps Made From Standard Input
If you later need to modify the map, you can use makedbm to disassemble the map and create a temporary text intermediate file. To disassemble the map and create a temporary file, type the following:










% cd /var/yp
% makedbm -u homedomain/mymap > mymap.temp





The resulting temporary file mymap.temp has one entry per line. You can edit this file as needed, using any text editor.


To update the map, give the name of the modified temporary file to makedbm by typing the following:









% makedbm mymap.temp homedomain/mymap
% rm mymap.temp





Then propagate the map to the slave servers, by becoming root and typing:









# yppush mymap






The preceding paragraphs explained how to use makedbm to create maps; however, almost everything you actually have to do can be done by ypinit and Makefile unless you add nondefault maps to the database or change the set of NIS servers after the system is already up and running.


Whether you use the Makefile in /var/yp or some other procedure the goal is the same: a new pair of well-formed dbm files must end up in the maps directory on the master server.




Propagating an NIS Map


After a map is changed, the Makefile uses yppush to propagate a new map to the slave servers (unless NOPUSH is set in the Makefile). It does this by informing the ypserv daemon and sending a map transfer request. The ypserv daemon on the slave then starts a ypxfr process, which in turn contacts the ypxfrd daemon on the master server. Some basic checks are made (for example did the map really change?) and then the map is transferred. ypxfr on the slave then sends a response to the yppush process indicating whether the transfer succeeded.



Note - 
The above procedure will not work for newly created maps that do not yet exist on the slave servers. New maps must be sent to the slave servers by running ypxfr on the slaves.




Occasionally, maps fail to propagate and you must to use ypxfr manually to send new map information. You can choose to use ypxfr in two different ways: periodically through the root crontab file, or interactively on the command line. These approaches are discussed in the following sections. 



Using cron for Map Transfers


Maps have different rates of change. For instance, some might not change for months at a time, such as protocols.byname among the default maps and auto_master among the nondefault maps; but passwd.byname can change several times a day. Scheduling map transfer using the crontab command allows you to set specific propagation times for individual maps.



To periodically run ypxfr at a rate appropriate for the map, the root crontab file on each slave server should contain the appropriate ypxfr entries. ypxfr contacts the master server and transfers the map only if the copy on the master server is more recent than the local copy. 



Note - 
If your master server runs rpc.yppasswdd with the default -m option, then each time someone changes their yp password, the passwd daemon runs make, which rebuilds the passwd maps. 





Using Shell Scripts With cron and ypxfr



As an alternative to creating separate crontab entries for each map, you might prefer to have the root crontab command run a shell script that periodically updates all maps. Sample map-updating shell scripts are n the /usr/lib/netsvc/yp directory. The script names are ypxfr_1perday, ypxfr_1perhour, and ypxfr_2perday. You can modify or replace these shell scripts to fit your site requirements. Example 19-1 shows the default ypxfr_1perday shell script. 



Example 19-1  ypxfr_1perday Shell Script








#! /bin/sh
#
# ypxfr_1perday.sh - Do daily yp map check/updates
PATH=/bin:/usr/bin:/usr/lib/netsvc/yp:$PATH
export PATH
# set -xv
ypxfr group.byname
ypxfr group.bygid
ypxfr protocols.byname
ypxfr protocols.bynumber
ypxfr networks.byname
ypxfr networks.byaddr
ypxfr services.byname
ypxfr ypservers







This shell script updates the maps once per day, if the root crontab is executed daily. You can also have scripts that update maps once a week, once a month, once every hour, and so forth, but be aware of the performance degradation implied in frequently propagating the maps.


Run the same shell scripts as root on each slave server configured for the NIS domain. Alter the exact time of execution from one server to another to avoid bogging down the master.


If you want to transfer the map from a particular slave server, use the -h machine option of ypxfr within the shell script. Here is the syntax of the commands you put in the script:










/usr/lib/netsvc/yp/ypxfr -h machine [ -c ] mapname






Where machine is the name of the server with the maps you want to transfer, and mapname is the name of the requested map. If you use the -h option without specifying a machine, ypxfr tries to get the map from the master server. If ypserv is not running locally at the time ypxfr is executed, you must use the -c flag so that ypxfr does not send a clear current map request to the local ypserver.


You can use the -s domain option to transfer maps from another domain to your local domain. These maps should be the same across domains. For example, two domains might share the same services.byname and services.byaddr maps. Alternatively, you can use rcp, or rdist for more control, to transfer files across domains.



Directly Invoking ypxfr



The second method of invoking ypxfr is to run it as a command. Typically, you do this only in exceptional situations--for example, when setting up a temporary NIS server to create a test environment or when trying to quickly get an NIS server that has been out of service consistent with the other servers.


Logging ypxfr Activity


The transfer attempts and results of ypxfr can be captured in a log file. If a file called /var/yp/ypxfr.log exists, results are appended to it. No attempt to limit the size of the log file is made. To prevent it from growing indefinitely, empty it from time to time by typing:










# cd /var/yp
# cp ypxfr.log ypxfr.log.old
# cat /dev/null > /var/yp/ypxfr.log





You can have crontab execute these commands once a week. To turn off logging, remove the log file.