openSolaris 2008 - Getting Started With the NIS+ to LDAP Transition - System Administration Guide: Naming and Directory Services (DNS, NIS, and LDAP)

Getting Started With the NIS+ to LDAP Transition

For an introduction to the configuration needed to start using an LDAP repository for NIS+ data, see NIS+LDAPmapping(4). The remainder of this section goes into more detail about the organization of the configuration files.

`/etc/default/rpc.nisd` File

All assignments in the /etc/default/rpc.nisd file are of the attributeName=value type.

General Configuration

The following attributes control general configuration of the rpc.nisd, and are active whether or not LDAP mapping is in effect. They should generally be left at their default values. See rpc.nisd(4) for more information.

nisplusNumberOfServiceThreads
nisplusThreadCreationErrorAction
nisplusThreadCreationErrorAttempts
nisplusThreadCreationErrorTimeout
nisplusDumpErrorAction
nisplusDumpErrorAttempts
nisplusDumpErrorTimeout
nisplusResyncService
nisplusUpdateBatching
nisplusUpdateBatchingTimeout

Configuration Data From LDAP

The following attributes control the reading of other configuration attributes from LDAP. These attributes cannot themselves reside in LDAP. They are read only from the command line or the configuration file. See rpc.nisd(4) for more information.

nisplusLDAPconfigDN
nisplusLDAPconfigPreferredServerList
nisplusLDAPconfigAuthenticationMethod
nisplusLDAPconfigTLS
nisplusLDAPconfigTLSCertificateDBPath
nisplusLDAPconfigProxyUser
nisplusLDAPconfigProxyPassword

Server Selection

preferredServerList

Specify the LDAP server and port number.

# LDAP server can be found at port 389
# LDAP server can be found at port 389
on the local machine
# preferredServerList=127.0.0.1
# Could also be written
# preferredServerList=127.0.0.0.1:389
LDAP server on the machine at IP
# address "1.2.3.4", at port 65042
# preferredServerList=1.2.3.4:65042

Authentication and Security

authenticationMethod
nisplusLDAPproxyUser
nisplusLDAPproxyPassword

The authentication method and, if appropriate for the method selected, the proxy user (bind distinguished name [DN]) and password (key or other shared secret) to be used between the rpc.nisd daemon and the LDAP server. See Security and Authentication for more information.

nisplusLDAPTLS
nisplusLDAPTLSCertificateDBPath

Optionally use SSL, and specify the location of the certificate file. See Using SSL for more information.

Default Location in LDAP and NIS+

defaultSearchBase
The point in the LDAP DIT where the containers for RFC 2307- style naming services data live. This is the default used when individual container DNs do not specify a full search base. See nisplusLDAPobjectDN Attribute for more information.
nisplusLDAPbaseDomain
The default NIS+ domain name to use when NIS+ object specifications (see nisplusLDAPdatabaseIdMapping Attribute) are not fully qualified.

Timeout/Size Limits and Referral Action for LDAP Communication

nisplusLDAPbindTimeout
nisplusLDAPmodifyTimeout
nisplusLDAPaddTimeout
nisplusLDAPdeleteTimeout

The above parameters are timeouts for the ldap bind, modify, add, and delete operations, respectively. They should generally be left at their default values.

nisplusLDAPsearchTimeout
nisplusLDAPsearchTimeLimit

The above parameters set the timeout for the LDAP search operation, and request a server-side search time limit, respectively. Since the nisplusLDAPsearchTimeLimit will control how much time the LDAP server spends on the search request, make sure that nisplusLDAPsearchTimeLimit is not smaller than nisplusLDAPsearchTimeout. Depending on the performance of the NIS+ server, the LDAP server, and the connection between them, you might have to increase the search limits from the default values. Watch for timeout syslog messages from rpc.nisd as a clue to making these values larger.

nisplusLDAPsearchSizeLimit
The above parameter requests a limit on the amount of LDAP data returned for an LDAP search request. The default is to ask for no limitation. This is a server side limit. The LDAP server might impose restrictions on the maximum, and these restrictions might be tied to the proxy user (bind DN) used. Make sure that the LDAP server allows the rpc.nisd to transfer enough data to account for the largest container (depending on the site, often the container used for passwd.org_dir, mail_aliases.org_dir, or netgroup.org_dir). Consult your LDAP server documentation for more information.
nisplusLDAPfollowReferral
The above parameter defines the action to be taken when an LDAP operation results in a referral to another LDAP server. The default is to not follow referrals. Enable follow referrals if you want or need referrals to be honored. Keep in mind that while referrals are convenient, they can also slow down operations by making the rpc.nisd talk to multiple LDAP servers for each request. The rpc.nisd should generally be pointed directly to an LDAP server that can handle all LDAP requests that the rpc.nisd might make.

Error Actions

The following parameters define the actions to take when an error occurs during an LDAP operation. You should generally leave these at their defaults. See rpc.nisd(4) for more information.

nisplusLDAPinitialUpdateAction
nisplusLDAPinitialUpdateOnly
nisplusLDAPretrieveErrorAction
nisplusLDAPretrieveErrorAttempts
nisplusLDAPretrieveErrorTimeout
nisplusLDAPstoreErrorAction
nisplusLDAPstoreErrorAttempts
nisplusLDAPstoreErrorTimeout
nisplusLDAPrefreshErrorAction
nisplusLDAPrefreshErrorAttempts
nisplusLDAPrefreshErrorTimeout

General LDAP Operation Control

nisplusLDAPmatchFetchAction
The above parameter determines whether or not LDAP data should be pre-fetched for NIS+ match operations. In most cases, leave this value at the default. See rpc.nisd(4) for more information.

`/var/nis/NIS+LDAPmapping` File

The presence of the default NIS+LDAPmapping file serves as a master switch for NIS+/LDAP mapping.

If you use a non-default mapping file, you will have to edit the /lib/svc/method/nisplus script to specify the mapping file name on the rpc.nisd line by using the -m mappingfile option. See NIS+ to LDAP Tools and the Service Management Facility for more information.

For each NIS+ object that should be mapped to or from LDAP, the NIS+LDAPmapping file specifies two to five attributes, depending on the object and whether or not the default values are sufficient.

`nisplusLDAPdatabaseIdMapping` Attribute

You must establish an alias to be used in the other mapping attributes. If the NIS+ object name is not fully qualified (does not end in a dot), the value of the nisplusLDAPbaseDomain is appended.

For example,

nisplusLDAPdatabaseIdMapping    rpc:rpc.org_dir

defines the database id rpc as an alias for the NIS+ rpc.org_dir table.

Note that NIS+ table objects might appear twice with two different database ids, once for the table object itself (if the object should be mapped to LDAP), and once for the table entries. For example,

nisplusLDAPdatabaseIdMapping    rpc_table:rpc.org_dir
nisplusLDAPdatabaseIdMapping    rpc:rpc.org_dir

defines the database ids rpc_table and rpc as aliases for the rpc.org_dir table. Later definitions will make it clear that rpc_table is used for the rpc.org_dir table object, and rpc for the entries in that table.

`nisplusLDAPentryTtl` Attribute

Since the rpc.nisd daemon's local database (in memory and on disk) functions as a cache for LDAP data, the nisplusLDAPentryTtl attribute allows you to set the time-to-live (TTL) values of entries in that cache. There are three TTLs for each database ID. The first two control the initial TTL when the rpc.nisd first loads the corresponding NIS+ object data from disk, and the third TTL is assigned to an object when it is read or refreshed from LDAP.

For example the following results in the rpc.org_dir table object getting an initial TTL randomly selected in the range 21600 to 43200 seconds.

nisplusLDAPentryTtl    rpc_table:21600:43200:43200

When that initial TTL expires and the table object is refreshed from LDAP, the TTL will be set to 43200 seconds.

Similarly the following will assign an initial TTL between 1800 and 3600 seconds to the entries in the rpc.org_dir table when it is first loaded.

nisplusLDAPentryTtl    rpc:1800:3600:3600

Each entry gets its own randomly selected TTL in the range specified. When a table entry expires and is refreshed, the TTL is set to 3600 seconds.

When selecting TTL values, consider the trade-off between performance and consistency. If the TTLs used for LDAP data cached by the rpc.nisd are very long, performance is the same as if rpc.nisd was not mapping data from LDAP at all. However, if the LDAP data is changed (by some entity other than rpc.nisd), it can also take a very long time before that change is visible in NIS+.

Conversely, selecting a very short (or even zero) TTL means that changes to LDAP data are quickly visible in NIS+, but can also impose a significant performance penalty. Typically, an NIS+ operation that also reads data from or writes data to LDAP will take at least two to three times longer (plus the LDAP lookup overhead) than the same operation without LDAP communication. Although performance can vary greatly depending on the hardware resources, scanning a large (tens of thousands or hundreds of thousands of entries) LDAP container to identify NIS+ entries that should be refreshed can take a long time. The rpc.nisddaemon performs this scan in the background, continuing to serve possibly stale data while it is running, but the background scan still consumes CPU and memory on the NIS+ server.

Carefully consider how critical it is to have NIS+ data in close synchronization with LDAP, and select the longest TTL that is acceptable for each NIS+ object. The default (when no nisplusLDAPentryTtl is specified) is 1 hour. The template mapping file /var/nis/NIS+LDAPmapping.template changes this to 12 hours for objects other than table entries. However, there is no auto-recognition of non-entry objects, so if you add mapping for a non-entry object, the TTL will default to 1 hour.

Note - There are no TTLs for nonexistent objects. Hence, no matter which TTLs are in effect for LDAP-mapped entries in an NIS+ table, a request for an entry that does not exist in NIS+ will query LDAP for that entry.

`nisplusLDAPobjectDN` Attribute

For each mapped NIS+ object, nisplusLDAPobjectDN establishes the location in the LDAP DIT where the object data resides. It also allows specification of the action to take when an LDAP entry is deleted. Each nisplusLDAPobjectDN value has three parts. The first specifies where LDAP data is read from, the second to where it is written, and the third what should happen when LDAP data is deleted. Refer to the following example.

nisplusLDAPobjectDN    rpc_table:\
           cn=rpc,ou=nisPlus,?base?\
              objectClass=nisplusObjectContainer:\
           cn=rpc,ou=nisPlus,?base?\
              objectClass=nisplusObjectContainer,\
              objectClass=top

The above example shows that the rpc.org_dir table object should be read from the DN cn=rpc,ou=nisPlus, (since the value ends in a comma, the value of the defaultSearchBase attribute is appended), with scope base, and that entries with a value of nisplusObjectContainer for the ObjectClass attribute are selected.

The table object is written to the same place. The delete specification is missing, which implies the default action, which is as follows. If the NIS+ table object is deleted, the entire LDAP entry should also be deleted.

If data should be read from, but not written to LDAP, omit the write portion (and the colon separating it from the read part).

nisplusLDAPobjectDN    rpc_table:\
              cn=rpc,ou=nisPlus,?base?\
              objectClass=nisplusObjectContainer

Note that the nisplusObjectContainer object class is not part of RFC 2307. In order to use it, you must configure your LDAP server as detailed in Mapping NIS+ Objects Other Than Table Entries.

For the rpc.org_dir table entries, you could use the following example.

nisplusLDAPobjectDN rpc:ou=Rpc,?one?objectClass=oncRpc:\
              ou=Rpc,?one?objectClass=onRpc,objectClass=top

The above shows that the table entries are read from and written to the base ou=Rpc. Again, the trailing comma appends the defaultSearchBase value. Select entries that have an objectClass attribute value of oncRpc. When creating an entry in the ou=Rpc container in LDAP, you also must specify top as an objectClass value.

As an example showing a non-default delete specification, consider the following.

nisplusLDAPobjectDN    user_attr:\
              ou=People,?one?objectClass=SolarisUserAttr,\
                 solarisAttrKeyValue=*:\
              ou=People,?one?objectClass=SolarisUserAttr:\
                 dbid=user_attr_del

The user_attr.org_dir data resides in the ou=People LDAP container, which it shares with account information from other sources, such as the passwd.org_dir NIS+ table.

Select entries in that container that have the solarisAttrKeyValue attribute, since only those contain user_attr.org_dir data. The dbid=user_attr_del portion of the nisplusLDAPobjectDN shows that when an entry in the user_attr.org_dir NIS+ table entry is deleted, deletion of the corresponding LDAP entry (if any) should follow the rules in the rule set identified by the user_attr_del database ID. See nisplusLDAPcolumnFromAttribute Attribute for more information.

`nisplusLDAPattributeFromColumn` Attribute

nisplusLDAPattributeFromColumn specifies the rules used to map NIS+ data to LDAP. Mapping rules for the other direction is controlled by nisplusLDAPcolumnFromAttribute.

`nisplusLDAPcolumnFromAttribute` Attribute

nisplusLDAPcolumnFromAttribute specifies the rules used to map LDAP data to NIS+.

The full entry mapping syntax can be found on NIS+LDAPmapping(4). However, a few examples should make things clearer.

The NIS+ rpc.org_dir table contains four columns called cname, name, numbe, and comment. Therefore, the entries for the NIS+ RPC program number (100300) with the canonical name nisd and the aliases rpc.nisd and nisplusd could be represented by the following NIS+ entries in rpc.org_dir.

nisd nisd 100300    NIS+ server
nisd rpc.nisd 100300    NIS+ server
nisd nisplusd 100300    NIS+ server

Assuming the defaultSearchBase value is dc=some,dc=domain, the corresponding LDAP entry, as listed by ldapsearch(1), would be the following.

dn: cn=nisd,ou=Ppc,dc=some,dc=domain
cn: nisd
cn: rpc.nsid
cn: nisplusd
oncRpcNumber: 100300
description: NIS+ server
objectClass: oncRpc

This makes for a simple one-to-one mapping between NIS+ and LDAP data, and the corresponding mapping attribute value going from NIS+ to LDAP is the following.

nisplusLDAPattributeFromColumn \
rpc:        dn=("cn=%s,", name), \
                cn=cname, \
                cn=name, \
                oncRpcNumber=number, \
                description=comment

This constructs the DN for the entry to be cn=%s, with the value of the cname column substituted for %s.

cn=nisd,

Since the value ends in a comma, the read base value from the nisplusObjectDN is appended, and you have the following.

cn=nisd,ou=Rpc,dc=some,dc=domain

The oncRpcNumber and description attribute values are just simple assignments of the corresponding NIS+ column values. The rpc.nisd will collect the multiple NIS+ entries into one LDAP entry, with multiple cn values to represent the different name column values.

Similarly, the mapping from LDAP to NIS+ would be as follows.

nisplusLDAPcolumnFromAttribute \
       rpc:      cname=cn, \
                 (name)=(cn), \
                 number=oncRpcNumber, \
                 comment=description

The above assigns the oncRpcNumber and description values to the corresponding NIS+ columns. The multi-valued cn (denoted by (cn) is mapped to multiple name column values (denoted by (name)). Since the name column cannot be multi-valued, the rpc.nisd creates one NIS+ entry for each cn value.

Finally, the nisplusLDAPattributeFromColumn value is an example of rule sets used for deletion.

nisplusLDAPattributeFromColumn \
user_attr_del:    dn=("uid=%s,", name), \
           SolarisUserQualifier=, \
           SolarisAttrReserved1=, \
           SolarisAttrReserved2=, \
           SolarisAttrKeyValue=

Again, the user_attr.org_dir data shares the ou=People container with other account information (from the passwd.org_dir and other tables). If an entry in the user_attr.org_dir table is deleted, you probably do not want to delete the entire ou=People entry. Instead, the delete entry above says that when a user_attr.org_dir entry is deleted, the SolarisUserQualifier, SolarisAttrReserved1, SolarisAttrReserved2, and SolarisAttrKeyValue attributes (if any) are deleted from the ou=People entry specified by the following rule.

dn=("uid=%s,", name)

The rest of the LDAP entry is left unchanged.

NIS+ to LDAP Migration Scenarios

Likely scenarios for a migration from NIS+ to LDAP include the following.

Convert all NIS+ clients to LDAP in one operation. You can use the rpc.nisd daemon to upload any NIS+ data that does not yet exist in LDAP. See How to Convert All NIS+ Data to LDAP in One Operation.
Do a gradual migration from NIS+ to LDAP. Start by converting NIS+ data to LDAP (see How to Convert All NIS+ Data to LDAP in One Operation). You could have both NIS+ and LDAP clients sharing the same naming service data, and let the rpc.nisd automatically keep NIS+ and LDAP data synchronized. Initially, perhaps, NIS+ would be authoritative, and the LDAP server(s) would maintain a duplicate of the NIS+ data for the benefit of LDAP clients. At a convenient time, LDAP can become the authoritative naming service, and NIS+ service gradually phased out, until there are no more NIS+ clients.
LDAP is already used as a naming service, so you need to merge the NIS+ and LDAP data. There are three possible ways to perform this merge.
- Add the NIS+ data to LDAP. Entries that exist in NIS+, but not in LDAP, are added to LDAP. Entries that appear both in NIS+ and LDAP, but with different data, end up with the NIS+ data. See How to Convert All NIS+ Data to LDAP in One Operation.
- Overwrite the NIS+ data with the LDAP data. If there are entries that exist in NIS+ but not in LDAP, they will disappear from NIS+. Entries that exist both in NIS+ and LDAP end up with the LDAP data. See How to Convert All LDAP Data to NIS+ in One Operation.
- Merge NIS+ and LDAP data, resolving conflicts on an individual basis. See Merging NIS+ and LDAP Data.

How to Convert All NIS+ Data to LDAP in One Operation

Use the rpc.nisd to upload any NIS+ data that does not yet exist in LDAP.
Assuming all NIS+/LDAP data mappings have been established in the default location (/var/nis/NIS+LDAPmapping), use the following command.
```
# /usr/sbin/rpc.nisd -D \ 
 -x nisplusLDAPinitialUpdateAction=to_ldap \
 -x nisplusLDAPinitialUpdateOnly=yes
```
The above would make the rpc.nisd upload data to LDAP, and then exit. The NIS+ data would be unaffected by this operation.
See the nisplusLDAPinitialUpdateAction attribute on rpc.nisd(4).

How to Convert All LDAP Data to NIS+ in One Operation

Use the rpc.nisd to download all LDAP data to NIS+, overwriting existing NIS+ data.
Assuming all NIS+/LDAP data mappings have been established in the default location (/var/nis/NIS+LDAPmapping), use the following command.
```
# /usr/sbin/rpc.nisd -D \
-x nisplusLDAPinitialUpdateAction=from_ldap \
-x nisplusLDAPinitialUpdateOnly=yes
```
The above would make the rpc.nisd daemon download data from LDAP, and then exit. The LDAP data would be unaffected by this operation.
See the nisplusLDAPinitialUpdateAction attribute on rpc.nisd(4).

Merging NIS+ and LDAP Data

NIS+ to LDAP Migration Scenarios showed how to synchronize NIS+ and LDAP data when data conflicts between the two should be resolved by letting either the NIS+ or the LDAP data be authoritative. Merging data requires a more complicated procedure.

The example procedure in this section assumes the following.

You are putting a backup of the NIS+ data in the /nisbackup directory.
Valid mapping configuration already exists in /etc/default/rpc.nisd and /var/nis/tmpmap (for tables that should be merged).
Flat file representations of the NIS+ data before the merge are stored in /before, and after-merge representations in /after.
niscat is used to dump flat file representations of custom NIS+ tables not supported by nisaddent(1M). You might have your own commands or scripts for dumping and loading such custom tables from and to NIS+. If so, those commands/scripts should be used in preference to niscat since the latter has no convenient counterpart to load data back into NIS+.
If you are forced to dump data using niscat(1), you can use nistbladm(1) to load entries back into NIS+ one by one.
Your command path includes /usr/lib/nis (which is where nisaddent(1M) resides).

How to Merge NIS+ and LDAP Data

Caution - If the LDAP data should change between the download in Step 4 and the upload in Step 10, the upload might overwrite those changes. For this reason, you should try to prevent modifications to the LDAP data during this procedure. Consult your LDAP server documentation for more information.

Back up all NIS+ data using the nisbackup command.
```
# nisbackup -a /nisbackup
```
Identify the NIS+ tables that have data which must be merged with LDAP. Dump the contents of these tables to flat files. For example, dump the contents of group.org_dir by using nisaddent as follows.
```
# nisaddent -d group | sort > /before/group
```
Piping the nisaddent output to sort will make for convenient comparison later on.

Stop the NIS+ service.

# svcadm disable network/rpc/nisplus:default

Download LDAP data to NIS+.

# /usr/sbin/rpc.nisd -D -m tmpmap \
-x nisplusLDAPinitialUpdateAction=from_ldap \
-x nisplusLDAPinitialUpdateOnly=yes

Start the NIS+ service.
```
# svcadm enable network/rpc/nisplus:default
```
The rpc.nisd daemon will now be serving the data downloaded from LDAP. If the conflicts to be resolved are such that NIS+ clients should not be exposed to them, make sure to perform this and the following steps when there are few (preferably no) active NIS+ clients.
Dump the NIS+ data for the affected tables.
The following example uses the group.org_dir table.
```
# nisaddent -d group | sort > /after/group
```
Create merged versions of the tables.
Use the file merge procedure of your choice to produce the merged tables. If no other tools are available, you can use diff(1) to collect differences between the /before and /after files, and merge manually with a text editor.
The following example assumes that the merged results are available in /after.
Load the merged data into NIS+. The following example uses the group table.
```
# nisaddent -m -f /after/group group
```
Remove LDAP entries that should not exist after the merge.
A. If there are LDAP entries that do not exist in the (now merged) NIS+ data, and that should not exist in LDAP after the upload, you must remove those LDAP entries.
Your LDAP server might provide a convenient method for removing multiple entries, such as a way to delete all entries in a container. If this is not the case, you can use ldapsearch(1) to generate a list of entries for each container. For example, to generate a list of all entries in the ou=Rpc container, use ldapsearch(1) as follows.
```
# ldapsearch -h server-address -D bind-DN -w password \
 -b ou=Rpc,search-base 'objectClass=*' dn | \
grep -i ou=Rpc | grep -v -i \^ou=Rpc > /tmp/delete-dn
```
See Performance and Indexing for an explanation of the meta-arguments (server-address, bind-DN, for example).
B. You can now edit the result file (/tmp/delete-dn) to specify only those entries that should be removed. Alternatively, in order to remove all entries in the container, use the file as is, and rely on the NIS+ upload to restore the LDAP data. Either way, you should backup the LDAP data before performing the ldapdelete operation below.
C. Use ldapdelete to remove LDAP entries, redirecting stdout (which usually is one blank line for each entry removed) to /dev/null.
```
# ldapdelete -h server-address -D bind-DN -w password \
/tmp/delete-dn /dev/null
```
D. Repeat the above procedure for each container that has at least one entry which must be removed.

Upload the merged NIS+ data to LDAP.