Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Using the Gateway as a Transition Tool
The following tasks are recommended:
The Solaris 9 OE rpc.nisd(1M)can be configured to use an LDAP server as its data repository. In this way, the normal NIS+ database becomes a cache for the LDAP data, with configurable time to live (TTL) values. The cache improves performance, and enables the rpc.nisd to serve NIS+ data even if communication with the LDAP server is interrupted temporarily.
Two configuration files, rpc.nisd(4) and NIS+LDAPmapping(4), control communication between rpc.nisd and the LDAP server, and the way that NIS+ table entries are mapped to LDAP entries. A template configuration file, /var/nis/NIS+LDAPmapping.template, covers all standard NIS+ tables, and can be used as a basis when creating a customized NIS+ to LDAP mapping.
A test utility, nisldapmaptest(1M), can be used to try out mapping configurations without affecting NIS+ data.
The NIS+ passwd.org_dir table stores passwords in the UNIX crypt format, so the LDAP server must be set up to use crypt format for the userPassword attribute for those accounts that are shared with NIS+.
In general, migration from NIS+ to LDAP starts by installing and configuring one or more LDAP servers to support the Solaris OE name service clients.
Install the Solaris 9 OE on the NIS+ master, and configure rpc.nisd on the NIS+ master to map NIS+ data to and from LDAP. The rpc.nisd has options that enable uploading all NIS+ data to LDAP.
Only the NIS+ master needs to run the Solaris 9 OE. All other NIS+ servers and clients can remain on earlier Solaris OE releases (or whatever OS they are currently using).
Once a complete LDAP name service environment exists, conversion of NIS+ clients to LDAP clients can start. While this conversion is going on, NIS+ and LDAP name service clients share the same data, and the NIS+ master rpc.nisd keeps the data in sync.
NIS+ servers remain NIS+ clients until their NIS+ server role is decommissioned, at which time they can be converted to be LDAP name service clients. Once the NIS+ master is the only remaining NIS+ client, it can be converted to be an LDAP client and the conversion is complete.
The following sections examine the configuration files and the parameters they contain.
rpc.nisd - Configuration File for NIS+ Service Daemon
The /etc/default/rpc.nisd file specifies configuration information for the rpc.nisd server. Configuration information can come from a combination of three places (listed in order of precedence):
From the rpc.nisd command line
From the /etc/default/rpc.nisd file
From information stored in an LDAP directory
Although many configuration parameters can be set, in most cases the defaults will work fine.
Most of the parameters used in the /etc/default/rpc.nisd file have the same names as the corresponding LDAP attributes. Some of the initialization parameters do not have equivalents because they are used to locate and connect to the LDAP server to retrieve the configuration data.
The parameters can be placed in three categories:
Initialization parameters
Parameters used to retrieve data
Parameters to initiate some type of action
Each of these types is described in the following sections.
Initialization Parameters
The following attributes are not part of the nisplusLDAPconfig object class and can only be set locally, either in rpc.nisd(4), or from the command line. These are used only for loading configuration data from the LDAP server. If all the configuration data is set in NIS+LDAPmapping(4) and rpc.nisd(4), these parameters need not be set.
NOTE
If the LDAP service is unavailable, rpc.nisd(1M) will wait until it can successfully read the configuration data before offering the NIS+ service.
nisplusLDAPconfigDN – The DN for configuration information. If empty, all other nisplusLDAPConfig* values are ignored with the expectation that all attributes are specified in this file or on the command line. When nisplusLDAPConfigDN is not specified at all, the DN is derived from the NIS+ domain name by default. If the domain name is x.y.z., the default nisplusLDAPconfigDN is:
nisplusLDAPconfigDN=dc=x,dc=y,dc=z
nisplusLDAPconfigPreferredServerList – The list of servers to use for the configuration phase. There is no default. The following is an example of a value for nisplusLDAPconfigPreferredServerList:
nisplusLDAPconfigPreferredServerList=127.0.0.1:389
nisplusLDAPconfigAuthenticationMethod – The authentication method used to obtain the configuration information. The recognized values for nisplusLDAPconfigAuthenticationMethod are:
none – No authentication attempted.
simple – Password of proxy user sent in the clear to the LDAP server.
sasl/cram-md5 – Use SASL/CRAM-MD5 authentication. This authentication method may not be supported by all LDAP servers. A password must be supplied.
sasl/digest-md5 – Use SASL/DIGEST-MD5 authentication. This authentication method may not be supported by all LDAP servers. A password must be supplied.
There is no default value. The following is an example of a value for nisplusLDAPconfigAuthenticationMethod:
nisplusLDAPconfigAuthenticationMethod=simple
nisplusLDAPconfigTLS – The transport layer security used for the connection to the server. The recognized values are:
none – No encryption of transport layer data. This is the default value.
ssl – SSL encryption of transport layer data. The directory server must be configured for SSL and a certificate database is required.
Export and import control restrictions may limit the availability of transport layer security.
nisplusLDAPconfigTLSCertificateDBPath – The name of the file containing the certificate database. The default path is /var/nis, and the default file name is cert7.db. The certificate database is set up the same way as with the Secured LDAP Client.
nisplusLDAPconfigProxyUser – The proxy user used to obtain configuration information. There is no default value. If the value ends with a comma, the value of the nisplusLDAPconfigDN attribute is appended. For example:
nisplusLDAPconfigProxyUser=cn=nisplusAdmin,ou=People,
nisplusLDAPconfigProxyPassword – The password that should be supplied to LDAP for the proxy user when the authentication method requires one. In order to avoid having this password publicly visible on the machine, the password should only appear in the configuration file, and the file should have an appropriate owner, group, and file mode. There is no default value.
Data Retrieval Parameters
preferredServerList – The list of servers to use when reading or writing mapped NIS+ data from or to LDAP. There is no default value. Example:
preferredServerList=127.0.0.1:389
authenticationMethod – The authentication method to use when reading or writing mapped NIS+ data from or to LDAP. For recognized values, see the LDAPconfigAuthenticationMethod attribute. There is no default value. Example:
authenticationMethod=simple
nisplusLDAPTLS – The transport layer security to use when reading or writing NIS+ data from or to LDAP. For recognized values, see the nisplusLDAPconfigTLS attribute. The default value is none. Note that export and import control restrictions may limit the strength of encryption available to the transport layer security.
nisplusLDAPTLSCertificateDBPath – The name of the file containing the certificate DB. For recognized and default values see the nisplusLDAPconfigTLSCertificateDBPath attribute.
defaultSearchBase – The default portion of the DN to use when reading or writing mapped NIS+ data from or to LDAP. The default is derived from the value of the baseDomain attribute, which in turn usually defaults to the NIS+ domain name. If nisplusLDAPbaseDomain has the value x.y.z, the default defaultSearchBase is dc=x,dc=y,dc=z. Sample attribute value:
defaultSearchBase=dc=somewhere,dc=else
nisplusLDAPbaseDomain – The domain to append when NIS+ object names are not fully qualified. The default is the domain the rpc.nisd daemon is serving, or the first such domain, if there is more than one candidate.
nisplusLDAPproxyUser – Proxy user used by the rpc.nisd to read or write from or to LDAP. There is no default value. If the value ends in a comma, the value of the defaultSearchBase attribute is appended. Example:
nisplusLDAPproxyUser=cn=nisplusAdmin,ou=People,
nisplusLDAPproxyPassword – The password that should be supplied to LDAP for the proxy user when the authentication method so requires. In order to avoid having this password publicly visible on the machine, the password should only appear in the configuration file, and the file should have an appropriate owner, group, and file mode. There is no default value.
nisplusLDAPbindTimeout
nisplusLDAPsearchTimeout
nisplusLDAPmodifyTimeout
nisplusLDAPaddTimeout
nisplusLDAPdeleteTimeout
The five attributes listed above, establish timeouts for LDAP bind, search, modify, add, and delete operations, respectively. The default value is 15 seconds for each one. Floating point values are allowed.
nisplusLDAPsearchTimeLimit – Establish a value for the LDAP_OPT_TIMELIMIT option, which suggests a time limit for the search operation on the LDAP server. The server may impose its own constraints on possible values. Refer to LDAP server documentation. The default is the nisplusLDAPsearchTimeout value. Only integer values are allowed.
The nisplusLDAPsearchTimeout limits the amount of time the client rpc.nisd waits for completion of a search operation, so setting the nisplusLDAPsearchTimeLimit larger than the nisplusLDAPsearchTimeout is not recommended.
nisplusLDAPsearchSizeLimit – Establish a value for the LDAP_OPT_SIZELIMIT option, which suggests a size limit, in number of entries, for the search results on the LDAP server. The server may impose its own constraints on possible values. Refer to LDAP server documentation. The default is zero, which means unlimited. Only integer values are allowed.
nisplusLDAPfollowReferral – Determines if the rpc.nisd should follow referrals or not. Recognized values are yes and no. The default value is no.
nisplusNumberOfServiceThreads – Sets the maximum number of RPC service threads that the rpc.nisd may use. Note that the rpc.nisd can create additional threads for certain tasks, so that the actual number of threads running can be larger than the nisplusNumberOfServiceThreads value.
The value of this attribute is a decimal integer from 0 (zero) to (2**31)-1, inclusive. 0, which is the default, sets the number of service threads to three plus the number of CPUs available when the rpc.nisd daemon starts. Example:
nisplusNumberOfServiceThreads=16
Action-Related Parameters
The following attributes specify the action to be taken when some event occurs. The values are all of the form event=action. The default action is the first one listed for each event.
NOTE
A complete list of parameters is provided, although only the ones with LDAP in their names are directly related to the NIS+ to LDAP gateway.
nisplusLDAPinitialUpdateAction – Provides the optional capability to update all NIS+ data from LDAP, or vice versa, when the rpc.nisd starts. Depending on various factors such as both NIS+ and LDAP server and network performance, as well as the amount of data to be uploaded or downloaded, these operations can consume significant CPU and memory resources. During upload and download, the rpc.nisd has not yet registered with rpcbind, and provides no NIS+ service. When data is downloaded from LDAP, any new items added to the rpc.nisd's database get a TTL for an initial load. See the description for the nisplusLDAPentryTtl attribute on NIS+LDAPmapping(4).
none – No initial update in either direction. This is the default.
from_ldap – Causes the rpc.nisd to fetch data for all NIS+ objects it serves, and for which mapping entries are available, from the LDAP repository.
to_ldap – The rpc.nisd writes all NIS+ objects for which it is the master server, and for which mapping entries are available, to the LDAP repository.
nisplusLDAPinitialUpdateOnly – Use in conjunction with nisplusLDAPinitialUpdateAction.
nisplusLDAPretrieveErrorAction – If an error occurs while trying to retrieve an entry from LDAP, one of the following actions can be selected:
use_cached – Action according to nisplusLDAPrefreshError below. This is the default.
retry – Retry the retrieval the number of time specified by nisplusLDAPretrieveErrorAttempts, with the nisplusLDAPretrieveErrorTimeout value controlling the wait between each attempt.
try_again
unavail
no_such_name
Return – with NIS_TRYAGAIN, NIS_UNAVAIL, or NIS_NOSUCHNAME, respectively, to the client.
nisplusLDAPretrieveErrorAttempts – The number of times a failed retrieval should be retried. The default is unlimited. The nisplusLDAPretrieveErrorAttempts value is ignored unless nisplusLDAPretrieveErrorAction=retry.
nisplusLDAPretrieveErrorTimeout – The timeout (in seconds) between each new attempt to retrieve LDAP data. The default is 15 seconds. The value for nisplusLDAPretrieveErrorTimeout is ignored unless nisplusLDAPretrieveErrorAction=retry.
nisplusLDAPstoreErrorAction – An error occurred while trying to store data to the LDAP repository.
retry – Retry operation nisplusLDAPstoreErrorAttempts times with nisplusLDAPstoreErrorTimeout seconds between each attempt. Note that this might tie up a thread in the rpc.nisd daemon.
system_error – Return NIS_SYSTEMERROR to the client.
unavail – Return NIS_UNAVAIL to the client. Note that the client code may not be prepared for this and can react in unexpected ways.
nisplusLDAPstoreErrorAttempts – The number of times a failed attempt to store should be retried. The default is unlimited. The value for nisplusLDAPstoreErrorAttempts is ignored unless nisplusLDAPstoreErrorAction=retry.
nisplusLDAPstoreErrortimeout – The timeout, in seconds, between each new attempt to store LDAP data. The default is 15 seconds. The nisplusLDAPstoreErrortimeout value is ignored unless nisplusLDAPstoreErrorAction=retry.
nisplusLDAPrefreshErrorAction – An error occurred while trying to refresh a cache entry.
continue_using – Continue using expired cache entry, if one is available. Otherwise, the action is retry. This is the default.
retry – Retry operation nisplusLDAPrefreshErrorAttempts times with nisplusLDAPrefreshErrorTimeout seconds between each attempt. Note that this may tie up a thread in the rpc.nisd daemon.
cache_expired
tryagain
Return – NIS_CACHEEXPIRED or NIS_TRYAGAIN, respectively, to the client. Note that the client code may not be prepared for this and could can react in unexpected ways.
nisplusLDAPrefreshErrorAttempts – The number of times a failed refresh should be retried. The default is unlimited. This applies to the retry and continue_using actions, but for the latter, only when there is no cached entry.
nisplusLDAPrefreshErrorTimeout – The timeout (in seconds) between each new attempt to refresh data. The default is 15 seconds. The value for nisplusLDAPrefreshErrorTimeout applies to the retry and continue_using actions.
nisplusThreadCreationErrorAction – The action to take when an error occurred while trying to create a new thread. This only applies to threads controlled by the rpc.nisd daemon not to RPC service threads. An example of threads controlled by the rpc.nisd daemon are those created to serve nis_list(3NSL) with callback, as used by niscat(1) to enumerate tables.
pass_error – Pass on the thread creation error to the client, to the extent allowed by the available NIS+ error codes. The error might be NIS_NOMEMORY, or another resource shortage error. This action is the default.
retry – Retry operation nisplusThreadCreationErrorAttempts times, waiting nisplusThreadCreationErrorTimeout seconds between each attempt. Note that this might tie up a thread in the rpc.nisd daemon.
nisplusThreadCreationErrorAttempts – The number of times a failed thread creation should be retried. The default is unlimited. The value for nisplusThreadCreationErrorAttempts is ignored unless the nisplusThreadCreationErrorAction=retry.
nisplusThreadCreationErrorTimeout – The number of seconds to wait between each new attempt to create a thread. The default is 15 seconds. Ignored unless nisplusThreadCreationErrorAction=retry.
nisplusDumpError – An error occurred during a full dump of an NIS+ directory from the master to a replica. The replica can:
nisplusDumpErrorAttempts – The number of times a failed full dump should be retried. The default is unlimited. When the number of retry attempts has been used up, the full dump is abandoned, and will not be retried again until a resync fails because no update time is available.
nisplusDumpErrorTimeout – The number of seconds to wait between each attempt to execute a full dump. The default is 120 seconds.
nisplusResyncService – Type of NIS+ service to be provided by a replica during resync, that is, data transfer from NIS+ master to NIS+ replica. This includes both partial and full resyncs.
from_copy – Service is provided from a copy of the directory to be resynced while the resync is in progress. Rollback is possible if an error occurs. Note that making a copy of the directory might require a significant amount of time, depending on the size of the tables in the directory and available memory on the system.
directory_locked – While the resync for a directory is in progress, it is locked against access. Operations to the directory are blocked until the resync is done. Rollback is not possible.
from_live – The replica database is updated in place. Rollback is not possible. If there are dependencies between individual updates in the resync, clients might be exposed to data inconsistencies during the resync. In particular, directories or tables might disappear for a time during a full dump.
nisplusUpdateBatching – How updates should be batched together on the master.
accumulate – Accumulate updates for at least nisplusUp- dateBatchingTimeout seconds. Any update that comes in before the timeout has occurred will reset the timeout counter. Thus, a steady stream of updates less than nisplusUpdateBatchingTimeout seconds apart could delay pinging replicas indefinitely.
bounded_accumulate – Accumulate updates for at least nisplusUpdateBatchingTimeout seconds. The default value for timeout is 120 seconds. Incoming updates do not reset the timeout counter, so replicas will be informed once the initial timeout has expired.
none – Updates are not batched. Instead, replicas are informed immediately of any update. While this should maximize data consistency between master and replicas, it can also cause considerable overhead on both master and replicas.
nisplusUpdateBatchingTimeout – The minimum time (in seconds) during which to accumulate updates. Replicas will not be pinged during this time. The default is 120 seconds.
nisplusLDAPmatchFetchAction – An NIS+ match operation, that is, any search other than a table enumeration, will encounter one of the following situations:
Table believed to be entirely in cache, and all cached entries are known to be valid. The cached tabled data is authoritative for the match operation.
Table wholly or partially cached, but there may be individual entries that have timed out.
No cached entries for the table. Always attempt to retrieve matching data from LDAP. When the table is wholly or partially cached, the action for the nisplusLDAPmatchFetchAction attribute controls whether or not the LDAP repository is searched:
nisplusMaxRPCRecordSize – Sets the maximum RPC record size that NIS+ can use over connection-oriented transports. The minimum record size is 9000, which is the default. The default value will be used in place of any value less than 9000. The value of this attribute is a decimal integer from 9000 to 2**31, inclusive.
no – Following the initial update, the rpc.nisd starts serving NIS+ requests. This is the default.
yes – The rpc.nisd exits after the initial update. This value is ignored if specified together with nisplusLDAPinitialUpdateAction=none.
Note that the client code may not be prepared for this and can react in unexpected ways.
retry – Retry operation nisplusDumpErrorAttempts times waiting nisplusDumpErrorTimeout seconds between each attempt. Note that this may tie up a thread in the rpc.nisd.
rollback – Try to roll back the changes made so far before retrying per the retry action. If the rollback fails or cannot be performed due to the selected ResyncServiceAction level, the retry action is selected.
no_match_only – Only go to LDAP when there is no match at all on the search of the available NIS+ data, or the match includes at least one entry that has timed out.
always – Always make an LDAP lookup.
never – Never make an LDAP lookup.
Storing Configuration Attributes in LDAP
Most attributes previously described, as well as those from the NIS+LDAPmapping(4) man page, can be stored in LDAP. In order to do so, you must add definitions to your LDAP server. The definitions, provided here, are described in LDIF format, suitable for use with the ldapadd(1) command. The attribute and object class OIDs are examples only.
Using LDAP to Store Configuration Data
Except for the information required to locate and search an LDAP configuration server, the NIS+ Gateway configuration parameters can be stored in an LDAP directory. Most of the information is stored in the nisplusLDAPconfig object class, which is shown below.
The nisplusLDAPconfig Object Class:
NAME 'nisplusLDAPconfig' DESC 'NIS+/LDAP mapping configuration' MUST cn MAY preferredServerList defaultSearchBase authenticationMethod nisplusLDAPTLS nisplusLDAPTLSCertificateDBPath nisplusLDAPproxyUser nisplusLDAPproxyPassword nisplusLDAPinitialUpdateAction nisplusLDAPinitialUpdateOnly nisplusLDAPretrieveErrorAction nisplusLDAPretrieveErrorAttempts nisplusLDAPretrieveErrorTimeout nisplusLDAPstoreErrorAction nisplusLDAPstoreErrorAttempts nisplusLDAPstoreErrorTimeout nisplusLDAPrefreshErrorAction nisplusLDAPrefreshErrorAttempts nisplusLDAPrefreshErrorTimeout nisplusNumberOfServiceThreads nisplusThreadCreationErrorAction nisplusThreadCreationErrorAttempts nisplusThreadCreationErrorTimeout nisplusDumpErrorAction nisplusDumpErrorAttempts nisplusDumpErrorTimeout nisplusResyncService nisplusUpdateBatching nisplusUpdateBatchingTimeout nisplusLDAPmatchFetchAction nisplusLDAPbaseDomain nisplusLDAPdatabaseIdMapping nisplusLDAPentryTtl nisplusLDAPobjectDN nisplusLDAPcolumnFromAttribute nisplusLDAPattributeFromColumn
Most of the attributes that the nisplusLDAPconfig object class can contain are not included in any Sun ONE Directory Server schema files. The following attributes are also used by the DUAconfigProfile object class and are included when you run the idsconfig script to set up the directory server to support native LDAP clients.
preferredServerList
defaultSearchBase
authenticationMethod
The last six attributes shown in the previous example do not equate to configuration parameters in the /etc/default/rpc.nisd file. These are used to map data form NIS+ to LDAP.
The following are the schema definitions for the attributes used in the nisplusLDAPconfig object class. These are included for reference only. Instructions for using LDAP to store configuration parameters are provided in the upcoming Sun BluePrints book.
Attributes shared by DUAconfigProfile:
NAME 'defaultSearchBase' DESC 'Default LDAP base DN used by a DUA' EQUALITY distinguishedNameMatch SYNTAX SINGLE-VALUE ) NAME 'preferredServerList' DESC 'Preferred LDAP server host addresses used by DUA' EQUALITY caseIgnoreMatch SYNTAX SINGLE-VALUE NAME 'authenticationMethod' DESC 'Authenticationmethod used to contact the DSA' EQUALITY caseIgnoreMatch SYNTAX SINGLE-VALUE )
Attributes Requiring Configuration:
NAME nisplusLDAPTLS DESC Transport Layer Security SYNTAX SINGLE-VALUE NAME nisplusLDAPTLSCertificateDBPath DESC Certificate file SYNTAX SINGLE-VALUE NAME 'nisplusLDAPproxyUser' DESC 'Proxy user for data store/retrieval' SYNTAX SINGLE-VALUE NAME 'nisplusLDAPproxyPassword' DESC 'Password/key/shared secret for proxy user' SYNTAX SINGLE-VALUE NAME 'nisplusLDAPbaseDomain' DESC 'Default domain name used in NIS+/LDAP mapping' SYNTAX SINGLE-VALUE
NOTE
These attributes can be set locally in /etc/default/rpc.nisd.
Attributes Generally Not Requiring Configuration:
NAME 'nisplusNumberOfServiceThreads' DESC 'Max number of RPC service threads' SYNTAX SINGLE-VALUE NAME 'nisplusThreadCreationErrorAction' DESC 'Action
Error Action Attributes:
NAME 'nisplusLDAPinitialUpdateAction' DESC 'Type of initial update' SYNTAX SINGLE-VALUE NAME 'nisplusLDAPinitialUpdateOnly' DESC 'Exit after update ?' SYNTAX SINGLE-VALUE NAME 'nisplusLDAPretrieveErrorAction'
Attributes Used for Mapping Data:
NAME 'nisplusLDAPmatchFetchAction' DESC 'Should pre-fetch be done ?' SYNTAX SINGLE-VALUE NAME 'nisplusLDAPdatabaseIdMapping' DESC 'Defines a database id for a NIS+ object' SYNTAX NAME 'nisplusLDAPentryTtl' DESC 'TTL for cached objects derived from LDAP' SYNTAX NAME 'nisplusLDAPobjectDN' DESC 'Location in LDAP tree where NIS+ data is stored' SYNTAX NAME 'nisplusLDAPcolumnFromAttribute' DESC 'Rules for mapping LDAP attributes to NIS+ columns' SYNTAX NAME 'nisplusLDAPattributeFromColumn' DESC 'Rules for mapping NIS+ columns to LDAP attributes' SYNTAX