Chapter 15 Transitioning From NIS to LDAP (Overview/Tasks)

This chapter describes how to enable support of NIS clients that use naming information stored in the LDAP directory. By following the procedures in this chapter, you can transition from using an NIS naming service to using LDAP naming services.

To determine the benefits of transitioning to LDAP, see LDAP Naming Services Compared to Other Naming Services.

The following information is included in this chapter.

• NIS-to-LDAP Service Overview

• Transitioning From NIS to LDAP (Task Map)

• Prerequisites for the NIS-to-LDAP Transition

• Setting Up the NIS-to-LDAP Service

• NIS-to-LDAP Best Practices With Sun Java System Directory Server

• NIS-to-LDAP Restrictions

• NIS-to-LDAP Troubleshooting

• Reverting to NIS

NIS-to-LDAP Service Overview

The NIS–to–LDAP transition service (N2L service) replaces existing NIS daemons on the NIS master server with NIS–to–LDAP transition daemons. The N2L service also creates an NIS–to–LDAP mapping file on that server. The mapping file specifies the mapping between NIS map entries and equivalent Directory Information Tree (DIT) entries in LDAP. An NIS master server that has gone through this transition is referred to as an N2L server. The slave servers do not have an NISLDAPmapping file, so they continue to function in the usual manner. The slave servers periodically update their data from the N2L server as if it were a regular NIS master.

The behavior of the N2L service is controlled by the ypserv and NISLDAPmapping configuration files. A script, inityp2l, assists with the initial setup of these configuration files. Once the N2L server has been established, you can maintain N2L by directly editing the configuration files.

The N2L service supports the following:

• Import of NIS maps into the LDAP Directory Information Tree (DIT)

• Client access to DIT information with the speed and extensibility of NIS

In any naming system, only one source of information can be the authoritative source. In traditional NIS, NIS sources are the authoritative information. When using the N2L service, the source of authoritative data is the LDAP directory. The directory is managed by using directory management tools, as described in Chapter 9, LDAP Basic Components and Concepts (Overview).

NIS sources are retained for emergency backup or backout only. After using the N2L service, you can gradually phase out NIS clients. Eventually, all NIS clients can be replaced by Solaris LDAP naming services clients.

Additional overview information is provided in the following subsections:

• NIS-to-LDAP Audience Assumptions

• When Not to Use the NIS-to-LDAP Service

• Effects of the NIS-to-LDAP Service on Users

• NIS-to-LDAP Transition Terminology

• NIS-to-LDAP Commands, Files, and Maps

• Supported Standard Mappings

NIS-to-LDAP Tools and the Service Management Facility

The NIS and LDAP services are managed by the Service Management Facility. Administrative actions on these services, such as enabling, disabling, or restarting, can be performed by using the svcadm command. You can query the status of services by using the svcs command. For more information about using SMF with LDAP and NIS, see LDAP and the Service Management Facility and NIS and the Service Management Facility. For an overview of SMF, refer to Chapter 16, Managing Services (Overview), in System Administration Guide: Basic Administration. Also refer to the svcadm(1M) and svcs(1) man pages for more details.

NIS-to-LDAP Audience Assumptions

You need to be familiar with NIS and LDAP concepts, terminology, and IDs to perform the procedures in this chapter. For more information about the NIS and LDAP naming services, see the following sections of this book.

• Chapter 4, Network Information Service (NIS) (Overview), for an overview of NIS

• Chapter 8, Introduction to LDAP Naming Services (Overview/Reference), for an overview of LDAP

When Not to Use the NIS-to-LDAP Service

Do not use the N2L service in these situations:

• In an environment where there is no plan to share data between NIS and LDAP naming services clients

  In such an environment, an N2L server would serve as an excessively complex NIS master server.

• In an environment where NIS maps are managed by tools that modify the NIS source files (other than yppasswd)

  Regeneration of NIS sources from DIT maps is an imprecise task that requires manual checking of the resulting maps. Once the N2L service is used, regeneration of NIS sources is provided only for backout or reverting to NIS.

• In an environment with no NIS clients

  In such an environment, use Solaris LDAP naming services clients and their corresponding tools.

Effects of the NIS-to-LDAP Service on Users

Simply installing the files that are related to the N2L service does not change the NIS server's default behavior. At installation, the administrator will see some changes to NIS man pages and the addition of N2L helper scripts, inityp2l and ypmap2src, on the servers. But as long as inityp2l is not run or the N2L configuration files are not created manually on the NIS server, the NIS components continue to start in traditional NIS mode and function as usual.

After inityp2l is run, users see some changes in server and client behavior. Following is a list of NIS and LDAP user types and a description of what each type of user should notice after the N2L service is deployed.

NIS-to-LDAP Transition Terminology

The following terms are related to the implementation of the N2L service.

NIS-to-LDAP Commands, Files, and Maps

There are two utilities, two configuration files, and a mapping that are associated with the N2L transition.

Supported Standard Mappings

By default, the N2L service supports mappings between the following list of maps and RFC 2307, or its successors', LDAP entries. These standard maps do not require manual modification to the mapping file. Any maps on your system that are not in the following list are considered custom maps and require manual modification.

The N2L service also supports automatic mapping of the auto.* maps. However, since most auto.* file names and contents are specific to each network configuration, those files are not specified in this list. The exceptions to this are the auto.home and auto.master maps, which are supported as standard maps.

audit_user
auth_attr
auto.home
auto.master
bootparams
ethers.byaddr ethers.byname
exec_attr
group.bygid group.byname group.adjunct.byname
hosts.byaddr hosts.byname
ipnodes.byaddr ipnodes.byname
mail.byaddr mail.aliases
netgroup netgroup.byprojid netgroup.byuser netgroup.byhost
netid.byname
netmasks.byaddr
networks.byaddr networks.byname
passwd.byname passwd.byuid passwd.adjunct.byname
printers.conf.byname
prof_attr
project.byname project.byprojectid
protocols.byname protocols.bynumber
publickey.byname
rpc.bynumber
services.byname services.byservicename
timezone.byname
user_attr

During the NIS-to-LDAP transition, the yppasswdd daemon uses the N2L-specific map, ageing.byname, to read and write password aging information to the DIT. If you are not using password aging, then the ageing.byname mapping is ignored.

Transitioning From NIS to LDAP (Task Map)

The following table identifies the procedures needed to install and manage the N2L service with standard and with custom NIS–to–LDAP mappings.

Prerequisites for the NIS-to-LDAP Transition

Before implementing the N2L service, you must check or complete the following items.

• Make sure that the system is set up as a working traditional NIS server before running the inityp2l script to enable N2L mode.

• Configure the LDAP directory server on your system.

  Sun Java System Directory Server (formerly Sun ONE Directory Server) and compatible versions of directory servers offered by Sun Microsystems, Inc., are supported with the NIS-to-LDAP migration tools. If you use Sun Java System Directory Server, configure the server by using the idsconfig command before you set up the N2L service. For more information about idsconfig, see Chapter 11, Setting Up Sun Java System Directory Server With LDAP Clients (Tasks) and the idsconfig(1M) man page.

  Other (third party) LDAP servers might work with the N2L service, but they are not supported by Sun. If you are using an LDAP server other than the Sun Java System Directory Server or compatible Sun servers, you must manually configure the server to support RFC 2307, or its successors', schemas before you set up the N2L service.

• Make sure that the nsswitch.conf file lists files before nis for the lookup order, at least for the hosts and ipnodes entries.

• Ensure that the addresses of the N2L master server and the LDAP server are present in the hosts or ipnodes files on the N2L master server. Whether the server addresses must be listed in hosts, ipnodes, or both files depends on how your system is configured to resolve local host names.

  An alternative solution is to list the LDAP server address, not its host name, in ypserv. This means that the LDAP server address is listed in another place, so changing the address of either the LDAP server or the N2L master server requires additional file modifications.

Setting Up the NIS-to-LDAP Service

You can set up the N2L service either by using standard mappings or by using custom mappings, as described in the next two procedures.

As part of the NIS-to -LDAP conversion, you need to run the inityp2l command. This command runs an interactive script for which you must provide configuration information. The following list shows the type of information you need to provide. See the ypserv(1M) man page for explanations of these attributes.

• The name of the configuration file being created (default = /etc/default/ypserv)

• The DN that stores configuration information in LDAP (default = ypserv)

• Preferred server list for mapping data to/from LDAP

• Authentication method for mapping data to/from LDAP

• Transport Layer Security (TLS) method for mapping data to/from LDAP

• Proxy user bind DN to read/write data from/to LDAP

• Proxy user password to read/write data from/to LDAP

• Timeout value (in seconds) for LDAP bind operation

• Timeout value (in seconds) for LDAP search operation

• Timeout value (in seconds) for LDAP modify operation

• Timeout value (in seconds) for LDAP add operation

• Timeout value (in seconds) for LDAP delete operation

• Time limit (in seconds) for search operation on LDAP server

• Size limit (in bytes) for search operation on LDAP server

• Whether N2L should follow LDAP referrals

• LDAP retrieval error action, number of retrieval attempts, and timeout (in seconds) between each attempt

• Store error action, number of attempts, and timeout (in seconds) between each attempt

• Mapping file name

• Whether to generate mapping information for auto_direct map

  The script places relevant information regarding custom maps at appropriate places in the mapping file.

• The naming context

• Whether to enable password changes

• Whether to change the default TTL values for any map

sasl/cram-md5 authentication is not supported by most LDAP servers, including Sun Java System Directory Server.

How to Set Up the N2L Service With Standard Mappings

Use this procedure if you are transitioning the maps listed in Supported Standard Mappings. If you are using custom or nonstandard maps, see How to Set Up the N2L Service With Custom or Nonstandard Mappings.

When the LDAP server has been set up, run the inityp2l script and supply configuration information when prompted. inityp2l sets up the configuration and mapping files for standard and auto.* maps.

1. Complete the prerequisite steps that are listed in Prerequisites for the NIS-to-LDAP Transition.

2. On the NIS master server, become superuser or assume an equivalent role.

   Roles contain authorizations and privileged commands. For more information about roles, see Chapter 9, Using Role-Based Access Control (Tasks), in System Administration Guide: Security Services.

3. Convert the NIS master server into an N2L server.

   # inityp2l

   Run the inityp2l script on the NIS master server and follow the prompts. See Setting Up the NIS-to-LDAP Service for a list of the information you need to provide.

   See the inityp2l(1M) man page for more details.

4. Determine if the LDAP Directory Information Tree (DIT) is fully initialized.

   The DIT is fully initialized if it already contains the information necessary to populate all the maps that are listed in the NISLDAPmapping file.

   • If no, continue with Step 5 and skip Step 6.

   • If yes, skip Step 5 and go to Step 6.

5. Initialize the DIT for the transition from the NIS source files.

   Perform these steps only if the DIT has not been fully initialized.

   1. Make sure that the old NIS maps are up-to-date.

      # cd /var/yp # make

      For more information, see the ypmake(1M) man page.

   2. Stop the NIS daemons.

      # svcadm disable network/nis/server:default

   3. Copy the old maps to the DIT, then initialize N2L support for the maps.

      # ypserv -Ir

      Wait for ypserv to exit.

      ---

      Tip –

      The original NIS dbm files are not overwritten. You can recover these files, if needed.

      ---

   4. Start the NIS daemons to ensure that they use the new maps.

      # svcadm enable network/nis/server:default

      This completes the set up of the N2L service with standard maps. You do not need to complete Step 6.

6. Initialize the NIS maps.

   Perform these steps only if the DIT is fully initialized and you skipped Step 5.

   1. Stop the NIS daemons.

      # svcadm disable network/nis/server:default

   2. Initialize the NIS maps from information in the DIT.

      # ypserv -r

      Wait for ypserv to exit.

      ---

      Tip –

      The original NIS dbm files are not overwritten. You can recover these files, if needed.

      ---

   3. Start the NIS daemons to ensure that they use the new maps.

      # svcadm enable network/nis/server:default

How to Set Up the N2L Service With Custom or Nonstandard Mappings

Use this procedure if the following circumstances apply:

• You have maps that are not listed in Supported Standard Mappings.

• You have standard NIS maps that you want to map to non-RFC 2307 LDAP mappings.

1. Complete the prerequisite steps that are listed in Prerequisites for the NIS-to-LDAP Transition.

2. On the NIS master server, become superuser or assume an equivalent role.

   Roles contain authorizations and privileged commands. For more information about roles, see Chapter 9, Using Role-Based Access Control (Tasks), in System Administration Guide: Security Services.

3. Configure the NIS master server into the N2L server.

   # inityp2l

   Run the inityp2l script on the NIS master server and follow the prompts. See Setting Up the NIS-to-LDAP Service for a list of the information you need to provide.

   See the inityp2l(1M) man page for more details.

4. Modify the /var/yp/NISLDAPmapping file.

   See Examples of Custom Maps for examples of how to modify the mapping file.

5. Determine if the LDAP Directory Information Tree (DIT) is fully initialized.

   The DIT is fully initialized if it already contains the information necessary to populate all the maps that are listed in the NISLDAPmapping file.

   • If no, complete Step 6, Step 8, and Step 9.

   • If yes, skip Step 6 and complete Step 7, Step 8, and Step 9.

6. Initialize the DIT for the transition from the NIS source files.

   1. Make sure that the old NIS maps are up-to-date.

      # cd /var/yp # make

      For more information, see the ypmake(1M) man page.

   2. Stop the NIS daemons.

      # svcadm disable network/nis/server:default

   3. Copy the old maps to the DIT, then initialize N2L support for the maps.

      # ypserv -Ir

      Wait for ypserv to exit.

      ---

      Tip –

      The original NIS dbm files are not overwritten. You can recover these files, if needed.

      ---

   4. Start the NIS daemons to ensure that they use the new maps.

      # svcadm enable network/nis/server:default

   5. Skip Step 7 and continue with Step 8.

7. Initialize the NIS maps.

   Perform this step only if the DIT is fully initialized.

   1. Stop the NIS daemons.

      # svcadm disable network/nis/server:default

   2. Initialize the NIS maps from information in the DIT.

      # ypserv -r

      Wait for ypserv to exit.

      ---

      Tip –

      The original NIS dbm files are not overwritten. You can recover these files, if needed.

      ---

   3. Start the NIS daemons to ensure that they use the new maps.

      # svcadm enable network/nis/server:default

8. Verify that the LDAP entries are correct.

   If the entries are not correct, then the entries can not be found by LDAP naming services clients.

   # ldapsearch -h server -s sub -b "ou=servdates, dc=..." \ "objectclass=servDates"

9. Verify the contents of the LDAP_ maps.

   The following sample output shows how to use makedm to verify the contents of the hosts.byaddr map.

   # makedbm -u LDAP_servdate.bynumber plato: 1/3/2001 johnson: 2/4/2003,1/3/2001 yeats: 4/4/2002 poe: 3/3/2002,3/4/2000

   If the contents are as expected, the transition from NIS to LDAP was successful.

   Note that the original NIS dbm files are not overwritten, so you can always recover those files. See Reverting to NIS for more information.

Examples of Custom Maps

The following two examples show how you might customize maps. Use your preferred text editor to modify the /var/yp/NISLDAPmapping file as needed. For more information about file attributes and syntax, see the NISLDAPmapping(4) man page and the LDAP naming services information in Chapter 9, LDAP Basic Components and Concepts (Overview).

Example 1–Moving Host Entries

This example shows how to move host entries from the default location to another (nonstandard) location in the DIT.

Change the nisLDAPobjectDN attribute in the NISLDAPmapping file to the new base LDAP distinguished name (DN). For this example, the internal structure of the LDAP objects is unchanged, so objectClass entries are unchanged.

Change:

nisLDAPobjectDN hosts: \
                        ou=hosts,?one?, \
                        objectClass=device, \
                        objectClass=ipHost

To:

nisLDAPobjectDN hosts: \
                        ou=newHosts,?one?, \
                        objectClass=device, \
                        objectClass=ipHost

This change causes entries to be mapped under

   dn: ou=newHosts, dom=domain1, dc=sun, dc=com

instead of under

   dn: ou=hosts, dom=domain1, dc=sun, dc=com.

Example 2–Implementing a Custom Map

This example shows how to implement a custom map.

A hypothetical map, servdate.bynumber, contains information about the servicing dates for systems. This map is indexed by the machine's serial number which, in this example, is 123. Each entry consists of the machine owner's name, a colon, and a comma-separated list of service dates, such as John Smith:1/3/2001,4/5/2003.

The old map structure is to be mapped onto LDAP entries of the following form:

dn: number=123,ou=servdates,dc=... \
                 number: 123 \
                 userName: John Smith \
                 date: 1/3/2001 \
                 date: 4/5/2003 \
                  .
                  .
                  .
                 objectClass: servDates

By examining the NISLDAPmapping file, you can see that the mapping closest to the required pattern is group. The custom mappings can be modeled on the group mapping. Since there is only one map, no nisLDAPdatabaseIdMapping attribute is required. The attributes to be added to NISLDAPmapping are the following:

nisLDAPentryTtl servdate.bynumber:1800:5400:3600

nisLDAPnameFields servdate.bynumber: \
                        ("%s:%s", uname, dates)

nisLDAPobjectDN servdate.bynumber: \
                        ou=servdates, ?one? \
                        objectClass=servDates:

nisLDAPattributeFromField servdate.bynumber: \
                        dn=("number=%s,", rf_key), \
                        number=rf_key, \
                        userName=uname, \
                        (date)=(dates, ",")

nisLDAPfieldFromAttribute servdate.bynumber: \
                        rf_key=number, \
                        uname=userName, \
                        dates=("%s,", (date), ",")  

NIS-to-LDAP Best Practices With Sun Java System Directory Server

The N2L service supports Sun Java System Directory Server (formerly Sun ONE Directory Server) and compatible versions of directory servers offered by Sun Microsystems, Inc. Other (third party) LDAP servers might work with the N2L service, but they are not supported by Sun. If you are using an LDAP server other than the Sun Java System Directory Server or compatible Sun servers, you must manually configure the server to support RFC 2307, or its successors', schemas.

If you are using the Sun Java System Directory Server, you can enhance the directory server to improve performance. To make these enhancements, you must have LDAP administrator privileges on the Sun Java System Directory Server. In addition, the directory server might need to be rebooted, a task that must be coordinated with the server's LDAP clients. The Sun Java System Directory Server (and Sun ONE and iPlanet Directory Server) documentation is available on the Sun Java System Directory Server Enterprise Edition 6.2 web site.

Creating Virtual List View Indexes With Sun Java System Directory Server

For large maps, LDAP virtual list view (VLV) indexes must be used to ensure LDAP searches return complete results. For information about setting up VLV indexes on the Sun Java System Directory Server, see the Sun Java System Directory Server Enterprise Edition 6.2 documentation.

VLV search results use a fixed page size of 50000. If VLVs are used with Sun Java System Directory Server, both the LDAP server and N2L server must be able to handle transfers of this size. If all of your maps are known to be smaller than this limit, you do not need to use VLV indexes. However, if your maps are larger than the size limit, or you are unsure of the size of all maps, use VLV indexes to avoid incomplete returns.

If you are using VLV indexes, set up the appropriate size limits as follows.

• On the Sun Java System Directory Server: nsslapd-sizelimit attribute must be set greater than or equal to 50000 or -1. See the idsconfig(1M) man page.

• On the N2L server: nisLDAPsearchSizelimit attribute must be set greater than or equal to 50000 or zero. For more information, see the NISLDAPmapping(4) man page.

Once VLV indexes have been created, activate them by running directoryserver with the vlvindex option on the Sun Java System Directory Server. See the directoryserver(1M) man page for more information.

VLVs for Standard Maps

Use the Sun Java System Directory Server idsconfig command to set up VLVs if the following conditions apply:

• You are using the Sun Java System Directory Server.

• You are mapping standard maps to RFC 2307 LDAP entries.

VLVs are domain specific, so each time idsconfig is run, VLVs are created for one NIS domain. Therefore, during the NIS–to–LDAP transition, you must run idsconfig once for each nisLDAPdomainContext attribute included in the NISLDAPmapping file.

VLVs for Custom and Nonstandard Maps

You must manually create new Sun Java System Directory Server VLVs for maps, or copy and modify existing VLV indexes, if the following conditions apply:

• You are using the Sun Java System Directory Server.

• You have large custom maps or have standard maps that are mapped to nonstandard DIT locations.

To view existing VLV indexes, type the following:

# ldapsearch -h hostname -s sub -b "cn=ldbm database,cn=plugins,cn=config" \
"objectClass=vlvSearch"

Avoiding Server Timeouts With Sun Java System Directory Server

When the N2L server refreshes a map, the result might be a large LDAP directory access. If the Sun Java System Directory Server is not correctly configured, the refresh operation might time out before completion. To avoid directory server timeouts, modify the following Sun Java System Directory Server attributes manually or by running the idsconfig command.

For example, to increase the minimum amount of time in seconds that the server should spend performing the search request, modify these attributes:

dn: cn=config
nsslapd-timelimit: -1

For testing purposes, you can use an attribute value of -1, which indicates no limit. When you have determined the optimum limit value, change the attribute value. Do not maintain any attribute settings at -1 on a production server. With no limits, the server might be vulnerable to Denial of Service attacks.

For more information about configuring Sun Java System Directory Server with LDAP, see Chapter 11, Setting Up Sun Java System Directory Server With LDAP Clients (Tasks) of this book.

Avoiding Buffer Overruns With Sun Java System Directory Server

To avoid buffer overruns, modify the Sun Java System Directory Server attributes manually or by running the idsconfig command.

1. For example, to increase the maximum number of entries that are returned for a client search query, modify these attributes:

   dn: cn=config nsslapd-sizelimit: -1

2. To increase the maximum number of entries that are verified for a client search query, modify these attributes:

   dn: cn=config, cn=ldbm database, cn=plugins, cn=config nsslapd-lookthroughlimit: -1

For testing purposes, you can use an attribute value of -1, which indicates no limit. When you have determined the optimum limit value, change the attribute value. Do not maintain any attribute settings at -1 on a production server. With no limits, the server might be vulnerable to Denial of Service attacks.

If VLVs are being used, the sizelimit attribute values should be set as defined in Creating Virtual List View Indexes With Sun Java System Directory Server. If VLVs are not being used, the size limit should be set large enough to accommodate the largest container.

For more information about configuring Sun Java System Directory Server with LDAP, see Chapter 11, Setting Up Sun Java System Directory Server With LDAP Clients (Tasks).

NIS-to-LDAP Restrictions

When the N2L server has been set up, the NIS source files are no longer used. Therefore, do not run ypmake on an N2L server. If ypmake is accidentally run, such as for an existing cron job, the N2L service is unaffected. However, a warning is logged suggesting that yppush should be called explicitly.

NIS-to-LDAP Troubleshooting

This section covers two areas of troubleshooting:

• Common LDAP Error Messages

• NIS-to-LDAP Issues

Common LDAP Error Messages

Sometimes the N2L server logs errors that relate to internal LDAP problems, resulting in LDAP-related error messages. Although the errors are nonfatal, they indicate problems to investigate. For example, the N2L server might continue to operate, but provide out-of-date or incomplete results.

The following list includes some of the common LDAP error messages that you might encounter when implementing the N2L service. Error descriptions, and possible causes and solutions for the errors, are included.

Administrative limit exceeded

Error Number: 11




Cause: An LDAP search was made that was larger than allowed by the directory server's nsslapd-sizelimit attribute. Only partial information will be returned.




Solution: Increase the value of the nsslapd-sizelimit attribute, or implement a VLV index for the failing search.

Invalid DN Syntax

Error Number: 34




Cause: An attempt has been made to write an LDAP entry with a DN that contains illegal characters. The N2L server attempts to escape illegal characters, such as the + symbol, that are generated in DNs.




Solution: Check the LDAP server error log to find out which illegal DNs were written, then modify the NISLDAPmapping file that generated the illegal DNs.

Object class violation

Error Number: 65




Cause: An attempt has been made to write an LDAP entry that is invalid. Generally, this error is due to missing MUST attributes that can be caused by either of the following circumstances.

• Bugs in the NISLDAPmapping file that create entries with missing attributes

• Attempts to add an AUXILIARY attribute to an object that does not exist

  For example, if a user name has not yet been created from the passwd.byxxx map, an attempt to add auxiliary information to that user will fail.




Solution: For bugs in the NISLDAPmapping file, check what was written in the server error log to determine the nature of the problem.

Can't contact LDAP server

Error Number: 81




Cause: The ypserv file might be incorrectly configured to point to the wrong LDAP directory server. Alternatively, the directory server might not be running.




Solution:

• Reconfigure the ypserv file to point to the correct LDAP directory server.

• To confirm that the LDAP server is running, become superuser, or assume an equivalent role, on the directory server and type:

  # pgrep -l slapd

Timeout

Error Number: 85




Cause: An LDAP operation timed out, typically while updating a map from the DIT. The map might now contain out-of-date information.




Solution: Increase the nisLDAPxxxTimeout attributes in the ypserv configuration file.

NIS-to-LDAP Issues

The following problems could occur while running the N2L server. Possible causes and solutions are provided.

Debugging the NISLDAPmapping File

The mapping file, NISLDAPmapping, is complex. Many potential errors might cause the mapping to behave in unexpected ways. Use the following techniques to resolve such problems.

Console Message Displays When ypserv -ir (or -Ir) Runs

Problem: A simple message is displayed on the console and the server exits (a detailed description is written to syslog).




Cause: The syntax of the mapping file might be incorrect.




Solution: Check and correct the syntax in the NISLDAPmapping file.

NIS Daemon Exits at Startup

Problem: When ypserv or other NIS daemons run, an LDAP-related error message is logged and the daemon exits.




Cause: The cause might be one of the following:

• The LDAP server cannot be contacted.

• An entry found in an NIS map or in the DIT is incompatible with the mapping specified.

• An attempt to read or write to the LDAP server returns an error.




Solution: Examine the error log on the LDAP server. See the LDAP errors that are listed in Common LDAP Error Messages.

Unexpected Results From NIS Operations

Problem: NIS operations do not return the expected results, but no errors are logged.




Cause: Incorrect entries might exist in the LDAP or NIS maps, which results in mappings not completing as intended.




Solution: Check and correct entries in the LDAP DIT and in the N2L versions of the NIS maps.

1. Check that the correct entries exist in the LDAP DIT, and correct the entries as needed.

   If you are using the Sun Java System Directory Server, start the management console by running directoryserver startconsole.

2. Check that the N2L versions of the NIS maps in the /var/yp directory contain the expected entries by comparing the newly generated map to the original map. Correct entries as needed.

   # cd /var/yp/domainname # makedbm -u test.byname # makedbm -u LDAP_test.byname

   Be aware of the following when checking the output for the maps:

   • The order of entries might not be the same in both files.

     Use the sort command before comparing output.

   • The use of white space might not be the same in both files.

     Use the diff -b command when comparing output.

Processing Order of NIS Maps

Problem: Object class violations occur.




Cause: When the ypserv -i command is run, each NIS map is read and its contents are written into the DIT. Several maps might contribute attributes to the same DIT object. Generally, one map creates most of the object, including all the object's MUST attributes. Other maps contribute additional MAY attributes.

Maps are processed in the same order that nisLDAPobjectDN attributes appear in the NISLDAPmapping file. If maps containing MAY attributes get processed before maps containing MUST attributes, then object class violations occur. See Error 65 in Common LDAP Error Messages for more information about this error.




Solution: Reorder the nisLDAPobjectDN attributes so that maps are processed in the correct order.

As a temporary fix, rerun the ypserv -i command several times. Each time the command is executed, more of the LDAP entry is built up.

Mapping in such a way that all of an object's MUST attributes cannot be created from at least one map is not supported.

N2L Server Timeout Issue

Problem: The server times out.




Cause: When the N2L server refreshes a map, the result might be a large LDAP directory access. If the Sun Java System Directory Server is not correctly configured, this operation might time out before completion.




Solution: To avoid directory server timeouts, modify the Sun Java System Directory Server attributes manually or by running the idsconfig command. See Common LDAP Error Messages and NIS-to-LDAP Best Practices With Sun Java System Directory Server for details.

N2L Lock File Issue

Problem: The ypserv command starts but does not respond to NIS requests.




Cause: The N2L server lock files are not correctly synchronizing access to the NIS maps. This should never happen.




Solution: Type the following commands on the N2L server.

# svcadm disable network/nis/server:default # rm /var/run/yp_maplock /var/run/yp_mapupdate # svcadm enable network/nis/server:default

N2L Deadlock Issue

Problem: The N2L server deadlocks.




Cause: If the addresses of the N2L master server and the LDAP server are not listed properly in the hosts, ipnodes, or ypserv files, a deadlock might result. See Prerequisites for the NIS-to-LDAP Transition for details about proper address configuration for N2L.

For an example of a deadlock scenario, consider the following sequence of events:

1. An NIS client tries to look up an IP address.

2. The N2L server finds that the hosts entry is out-of-date.

3. The N2L server tries to update the hosts entry from LDAP.

4. The N2L server gets the name of its LDAP server from ypserv, then does a search by using libldap.

5. libldap tries to convert the LDAP server's name to an IP address by making a call to the name service switch.

6. The name service switch might make an NIS call to the N2L server, which deadlocks.




Solution: List the addresses of the N2L master server and the LDAP server in the hosts or ipnodes files on the N2L master server. Whether the server addresses must be listed in hosts, ipnodes, or both files depends on how these files are configured to resolve local host names. Also, check that the hosts and ipnodes entries in the nsswitch.conf file list files before nis in the lookup order.

An alternative solution to this deadlock problem is to list the LDAP server address, not its host name, in the ypserv file. This means that the LDAP server address would be listed in another place. Therefore, changing the address of either the LDAP server or the N2L server would require slightly more effort.

Reverting to NIS

A site that has transitioned from NIS to LDAP using the N2L service is expected to gradually replace all NIS clients with Solaris LDAP naming services clients. Support for NIS clients eventually becomes redundant. However, if required, the N2L service provides two ways to return to traditional NIS, as explained in the next two procedures.

Traditional NIS ignores the N2L versions of the NIS maps if those maps are present. After reverting to NIS, if you leave the N2L versions of the maps on the server, the N2L maps do not cause problems. Therefore, it might be useful to keep the N2L maps in case you later decide to re-enable N2L. However, the maps do take up disk space.

How to Revert to Maps Based on Old Source Files

1. Become superuser or assume an equivalent role.

   Roles contain authorizations and privileged commands. For more information about roles, see Chapter 9, Using Role-Based Access Control (Tasks), in System Administration Guide: Security Services.

2. Stop the NIS daemons.

   # svcadm disable network/nis/server:default

3. Disable N2L.

   This command backs up and moves the N2L mapping file.

   # mv /var/yp/NISLDAPmapping backup_filename

4. Set the NOPUSH environment variable so the new maps are not pushed by ypmake.

   # NOPUSH=1

5. Make a new set of NIS maps that are based on the old sources.

   # cd /var/yp # make

6. (Optional) Remove N2L versions of the NIS maps.

   # rm /var/yp/domainname/LDAP_*

7. Start the NIS daemons.

   # svcadm enable network/nis/server:default

How to Revert to Maps Based on Current DIT Contents

Back up the old NIS source files before performing this procedure.

1. Become superuser or assume an equivalent role.

   Roles contain authorizations and privileged commands. For more information about roles, see Chapter 9, Using Role-Based Access Control (Tasks), in System Administration Guide: Security Services.

2. Stop the NIS daemons.

   # svcadm disable network/nis/server:default

3. Update the maps from the DIT.

   # ypserv -r

   Wait for ypserv to exit.

4. Disable N2L.

   This command backs up and moves the N2L mapping file.

   # mv /var/yp/NISLDAPmapping backup_filename

5. Regenerate the NIS source files.

   # ypmap2src

6. Manually check that regenerated NIS source files have the correct content and structure.

7. Move the regenerated NIS source files to the appropriate directories.

8. (Optional) Remove the N2L versions of the mapping files.

   # rm /var/yp/domainname/LDAP_*

9. Start the NIS daemons.

   # svcadm enable network/nis/server:default