test

LDAP Setup and Configuration Guide

Chapter 2 Server Setup

This chapter describes how to set up an LDAP server to support Solaris LDAP clients for naming information lookup. In particular, the setup allows Solaris LDAP clients to use the well-known getXbyY interfaces or ldaplist(1) to look up naming information on the LDAP server.

This chapter has the following organization:

Requirements

To support Solaris naming clients for naming information lookup the server must support the LDAP v3 protocol. This is necessary because Solaris Naming clients use controls that are available only in v3.

The following controls are available only in v3:

The server must support one of the following authentication methods:

Verify that Directory Supports Simple Page Mode Control.

  1. Use ldapsearch to determine if the directory supports simple page mode control as identified by their OIDs: 1.2.840.113556.1.4.319 simple page mode control type and 2.16.840.1.113730.3.4.2 simple page mode control value.


    # ldapsearch -b "" -s base objectclass=\*

    For our example configuration, ldapsearch returns:


    objectclass=top
namingcontexts=dc=sun,dc=com,o=internet
subschemasubentry=cn=schema
supportedsaslmechanisms=CRAM-MD5
supportedextension=1.3.6.1.4.1.1466.20037
supportedcontrol=1.2.840.113556.1.4.319
supportedcontrol=2.16.840.1.113730.3.4.2
supportedldapversion=2
supportedldapversion=3
Verify that Directory Supports Virtual List Views.

  1. Use ldapsearch to determine if the directory supports Virtual List Views as identified by their OIDs: 1.2.840.113556.1.4.473 VLV control type and 2.16.840.1.113730.3.4.9 VLV control value.


    # ldapsearch -b "" -s base objectclass=\*

    For our example configuration, ldapsearch returns:


    objectclass=top
namingcontexts=dc=sun,dc=com
namingcontexts=o=NetscapeRoot
subschemasubentry=cn=schema
supportedcontrol=2.16.840.1.113730.3.4.2
supportedcontrol=2.16.840.1.113730.3.4.3
supportedcontrol=2.16.840.1.113730.3.4.4
supportedcontrol=2.16.840.1.113730.3.4.5
supportedcontrol=1.2.840.113556.1.4.473
supportedcontrol=2.16.840.1.113730.3.4.9
supportedcontrol=2.16.840.1.113730.3.4.12
supportedsaslmechanisms=EXTERNAL
supportedldapversion=2
supportedldapversion=3
dataversion=atitrain2.east.sun.com:389 020000605172910 
netscapemdsuffix=cn=ldap://:389,dc=atitrain2,dc=east,dc=sun,dc=com
    Note –

    For more information on ldapsearch see ldapsearch(1).

Schemas

To support Solaris LDAP Naming clients, schemas defined by IETF and some Solaris specific schemas are required.

There are two required LDAP schemas defined by IETF: the RFC 2307 Network Information Service schema and the LDAP mailgroups Internet draft. To support Naming Information Service, the definition of these schemas must be added to the directory server. Detailed information about IETF and Solaris specific schemas is included in Appendix A. The various RFCs can also be accessed on web at IETF site http://www.ietf.org.

Directory Information Tree

Solaris LDAP clients use the information in a default Directory Information Tree (DIT) . This default DIT, however, can be overridden by specifying the modified DIT in the profile. The DIT is divided into containers that are subtrees containing entries for a specific information type.

The search baseDN specifies the location in the DIT where all information for the client is found. In the node designated as the search base, the NisDomainObject objectclass must exist. The search base node subtrees designate all the containers for the various information types. See Figure 2–1.

Figure 2–1 Directory Information Tree Containers

Graphic

Table 2–1 lists the container and information type stored in the DIT:

Table 2–1 Directory Information Tree
 Container Information Type
 ou=Ethers bootparams(4), ethers(4)
 ou=Group group(4)
 ou=Hosts hosts(4), ipnodes(4),publickey(4)
 ou=Aliases aliases(4)
 ou=Netgroup netgroup(4)
 ou=Networks networks(4), netmasks(4)
 ou=People passwd(1), shadow(4), user_attr(4),audit_user(4), publickey for users
 ou=Protocols protocols(4)
 ou=Rpc rpc(4)
 ou=Services services(4)
 ou=SolarisAuthAttr auth_attr(4)
 ou=SolarisProfAttr prof_attr(4), exec_attr(4)
 ou=projects project
 nismapname=auto_* auto_*

Override the Default Containers in the DIT

If a particular LDAP deployment requires the default containers be overridden, it is possible to do so by specifying the modified container in the profile. You can define an alternate search baseDN for each of the databases

For example, assume that an organization wants to replace the ou=People container with ou=employee and ou=contractor containers. For this profile entry (which can exist anywhere in the DIT), an alternate search DN needs to be specified. Generate the LDAP client profile using the -B option to specify an alternate search DN. See ldap_gen_profile(1M) for details. The attribute looks like:


SolarisDataSearchDN="passwd:(ou=employee,dc=mkt,dc=mystore,dc=com),
                     (ou=contractor,dc=mkt,dc=mystore,dc=com)"

NIS Domain

In order for the Solaris clients to find a server for a specific domain, the nisDomain attribute of the nisDomainObject objectclass must be defined in the root DN entry of the DIT representing the desired domain. This information is used by the client when initializing the system and refreshing the client profile. During the initialization, the client searches for an entry on the LDAP server that has the nisDomain matching the desired domain. The DN for the entry found will be used as the BaseDN for the naming information.

When refreshing the client profile, the ldap_cachemgr on the client machine verifies that nisDomain defined in the root DN entry matches the domain desired before refreshing its profile.

For illustrative purposes, this document uses the following nisDomain:


dn: dc=mkt,dc=mainstore,dc=com
dc: mkt
objectclass: top
objectclass: domain
objectclass: nisDomainObject
nisdomain: mkt.mainstore.com

Client Profile

To simplify Solaris client setup, a client profile needs to be defined. This profile must be created on the server. During the initialization stage, a client can easily set up the system with the profile name and the server's address. The client profile allows the system administrators to define the LDAP environment to be used by Solaris clients.

The most obvious benefit of using a profile, is the ease of installing a machine. However, the true benefit of using profiles only becomes apparent when you start making changes in your environment (such as adding or removing servers). See ldap_gen_profile(1M) for details.

The following list shows the possible attributes that can be defined in the profile;

The ldap_gen_profile(1M) command is provided as part of the Solaris client tools to create client profiles. This tool generates an LDIF file which can be stored in the LDAP server using the ldapadd(1) command. The following example shows how to create a client profile.

How to Create a Client Profile

  1. Use ldap_gen_profile(1M) to create a client profile.


    # /usr/sbin/ldap_gen_profile \
-P myprofile \
-b dc=mkt,dc=mainstore,dc=com \
-a simple -w mypasswd \
-D cn=proxyagent,ou=profile,dc=mkt,dc=mainstore,dc=com \
100.100.100.100

    The following example shows the profile generated:


    dn: cn=myprofile,ou=profile,dc=mkt,dc=mainstore,dc=com
SolarisBindDN: cn=proxyagent,ou=profile,dc=mkt,dc=mainstore,dc=com
SolarisBindPassword: {NS1}xxxxxxxxxxxxxx
SolarisLDAPServers: 100.100.100.100
SolarisSearchBaseDN: dc=mkt,dc=mainstore,dc=com
SolarisAuthMethod: NS_LDAP_AUTH_SIMPLE
SolarisTransportSecurity: NS_LDAP_SEC_NONE
SolarisSearchReferral: NS_LDAP_FOLLOWREF
SolarisSearchScope: NS_LDAP_SCOPE_ONELEVEL
SolarisSearchTimeLimit: 30
SolarisCacheTTL: 43200
cn: myprofile
ObjectClass: top
ObjectClass: SolarisNamingProfile

  2. Save the generated profile to a file (such as profile.ldif) and use ldapadd(1) to store the client profile file in the LDAP server. 


    # ldapadd -h ldap_server_hostname -D "cn=Directory Manager" \
-w nssecret -f profile.ldif

The ldap_cachemgr(1M) on every client machine automatically updates the content of the LDAP configuration files. This means changes need to be made only on the server and those changes automatically propagate to every client in the namespace. The periodic update is based on the TTL, time to live value specified in the profile SolarisCacheTTL.

Security Model

To access the information stored in the directory, clients must authenticate to the directory first. Once authenticated, and depending on the authorization information stored in the directory in the form of Access Control Information the client will have access to part or all of the information available in the directory. In this section, the concepts of client identity, authentication methods, and finally PAM modules will be discussed. For more information on ACI, please consult the iPlanet Directory Server Administrator's Guide.

Authentication Identity

LDAP name services could be configured to use one of two possible identities for authenticating clients to the directory: anonymous, and proxy agent.

Authentication Method

When a proxy agent is used the system administrator also needs to choose an authentication method for that identity to authenticate to the directory. Currently the supported mechanisms by Solaris 8 clients are SIMPLE, and CRAM-MD5.

Note –

Currently the iPlanet Directory Server version 4.11 does not support the CRAM-MD5 method.

Pluggable Authentication Module (PAM)

PAM provides a way for applications to remain independent of authentication scheme used in the Solaris Operating Environment. By using the PAM layer, applications can perform authentication without worrying about what authentication method is defined by the system administrator for the given client. To use LDAP naming service, one of two pam modules can be configured in pam.conf: pam_unix(5) and pam_ldap(5).

Indexes

Most LDAP servers use indexes to improve the search performance. To use indexes, consult your directory server documentation.

In addition to the basic indexed attributes, the following list of attributes must be indexed to ensure that Solaris clients will be able to retrieve naming information in a reasonable time. 


membernisnetgroup    pres,eq,sub
nisnetgrouptriple    pres,eq,sub
memberuid            pres,eq
macAddress           pres,eq
uid                  pres,eq
uidNumber            pres,eq
gidNumber            pres,eq
ipHostNumber         pres,eq
ipNetworkNumber      pres,eq
ipProtocolNumber     pres,eq
oncRpcNumber         pres,eq
ipServiceProtocol    pres,eq
ipServicePort        pres,eq
nisDomain            pres,eq
nisMapName           pres,eq
mail                 pres,eq
Note –

The abbreviations used in attribute list expand to: pres is presence, eq is equality, and sub is substring

Additionally, if Virtual List View control (vlv) is supported by the server, vlv indexes also need to be created. Create these indexes for any container in the tree that contains a large number of objects. (Large is relative to other objects in the tree.) For information on how to create these indexes, consult your directory server documentation. Ensure that the vlv sort value is set to cn uid and the vlv filter and scope are defined per the following list: 


getpwent:      vlvFilter: (objectclass=posixAccount),     vlvScope: 1
getspent:      vlvFilter: (objectclass=posixAccount),     vlvScope: 1
getgrent:      vlvFilter: (objectclass=posixGroup),       vlvScope: 1
gethostent:    vlvFilter: (objectclass=ipHost),           vlvScope: 1
getnetent:     vlvFilter: (objectclass=ipNetwork),        vlvScope: 1
getprotoent:   vlvFilter: (objectclass=ipProtocol),       vlvScope: 1
getrpcent:     vlvFilter: (objectclass=oncRpc),           vlvScope: 1
getaliasent:   vlvFilter: (objectclass=rfc822MailGroup),  vlvScope: 1
getserviceent: vlvFilter: (objectclass=ipService),        vlvScope: 1

The Cost of Indexing

Although indexes improve search performance, they incur the following costs:

Loading Data

Solaris Directory extension package has tools and documents needed to migrate from NIS to LDAP. It is available on iPlanet Advantage Software (Volume 1) cd, and also on iPlanet website. dsimport is a tool used to convert NIS data to ldap format. It makes use of a mapping file, nis.mapping, which needs to be customized as per the input data format, environment variables and so on. For detailed information on these, refer to above mentioned cd or website.

Command Line Tools

LDAP provides command line tools that correspond to the operations performed by the LDAP API. Each tool supports a common set of options, including authentication and bind parameters.

The ldapsearch, ldapadd, and ldapmodify tools support a common text-based format for representing directory information called the LDAP Data Interchange Format (LDIF).

LDAP Data Interchange Format

LDIF is the format produced by the ldapsearch tool, the format accepted by the ldapadd tool, and is the basis for the change information format that the ldapmodify tool uses.

An LDIF file contains one or more entries. Each entry is separated by an empty line. The basic form on an LDIF file entry is: 


 [id]
dn: entryDN
attrtype: attrvalue
...

where:

The attrtype: attrvalue line can be repeated as many times as necessary to list all of the attribute values present in an entry. The line can be continued by inserting a single space or horizontal tab character at the start of the next line.

For example, an LDIF file that contains Joe Qwerty's entry includes five attributes (cn and objectclass have two values):


dn: cn=Joseph Qwerty, o=Ultra Keyboards Inc., c=US
cn: Joseph Qwerty
cn: Joe Qwerty
sn: Qwerty
mail: jqwerty@ultra.com
seeAlso: cn=Joe Qwerty, ou=Engineering Division, o=Peo
 ple, o=IEEE, c=US
objectClass: top
objectClass: person
Note –

The value of seeAlso is split across two lines by inserting a single space character at the start of the line that begins with “ ple, ...”.

How to Search the Directory

Use ldapsearch(1) to find a directory entry. ldapsearch opens a connection to the LDAP directory server, binds to the directory server, and performs a search of the directory.

  1. Find members of IEEE that work at Ultra Keyboards in the United States.


    % ldapsearch -L -b "o=IEEE, o=Ultra Keyboards Inc., c=US" uid=\*

The results of the search are:


dn: uid=jqwerty, o=IEEE, o=Ultra keyboards Inc., c=US
uid: jqwerty
cn: jqwerty
userpassword: {crypt}somecryptedtext
uidnumber: 12345
gidnumber: 123
gecos: Joseph Qwerty
homedirectory: /home/jqwerty
loginshell: /bin/csh
objectclass: top
objectclass: shadowAccount
objectclass: account
objectclass: posixAccount
shadowlastchange: 3455

dn: uid=bhand, o=IEEE, o=Ultra keyboards Inc., c=US
uid: bhand
cn: bhand
userpassword: {crypt}somecryptedtext
uidnumber: 12347
gidnumber: 123
gecos: William Handset
homedirectory: /home/bhand
loginshell: /bin/csh
objectclass: top
objectclass: shadowAccount
objectclass: account
objectclass: posixAccount
shadowlastchange: 3440

How to Modify a Directory Entry

Use ldapmodify(1) to change a directory entry. ldapmodify opens a connection to the LDAP directory server, binds to the directory server, and performs a sequence of LDAP modify operations on the directory.

  1. Bind as the directory manager (password “enigma”) and add email address eng@ultra.com Joe Qwerty entry


    % ldapmodify -D "cn=Manager, o=Ultra Keyboards Inc., \
c=US" -w enigma < modfile

The contents of modfile are:


dn: cn=carol,ou=People,o=Ultra Keyboards Inc.,c=US
changetype: modify
replace: userpassword
userpassword: {crypt}mgq25KV6CE0p6
-
replace: objectclass
objectclass: top
objectclass: shadowAccount
objectclass: account
objectclass: posixAccount
-
add: shadowlastchange
shadowlastchange: 6447
-

dn: cn=stephen,ou=People,o=Ultra Keyboards Inc.,c=US
changetype: modify
replace: userpassword
userpassword: {crypt}w.4P1JPV3w.Zs
-
replace: objectclass
objectclass: top
objectclass: shadowAccount
objectclass: account
objectclass: posixAccount
-
add: shadowlastchange
shadowlastchange: 6447
-

dn: cn=frank,ou=People,o=Ultra Keyboards Inc.,c=US
changetype: modify
replace: userpassword
userpassword: {crypt}mMBEaHRlf5rJQ
-
replace: objectclass
objectclass: top
objectclass: shadowAccount
objectclass: account
objectclass: posixAccount
-
add: shadowlastchange
shadowlastchange: 9712
-
Note –

A line with just a hyphen separates a series of modification commands for the same directory entry. A blank lines separates different directory entries.

If the operation is successful, ldapmodify returns a message similar to the following:


# ldapmodify -D "cn=Directory Manager" -w nssecret -f domain.ldif
modifying entry dc=sun,dc=com

If unsuccessful an error message is displayed.

How to Add an entry to the Directory

Use ldapadd(1) to add an entry to the directory. ldapadd opens a connection to the LDAP directory server, binds to the directory server, and performs a sequence of LDAP add operations on the directory.

  1. Bind as the directory manager (password “enigma”) and add an entries for Penny Gold and Amy Lamb.


    % ldapadd -D "cn=Manager, o=Ultra Keyboards Inc., \
c=US" -w enigma < addfile

The contents of addfile are:


dn: cn=Penny Gold, o=Ultra Keyboards Inc., c=US
changetype: add
objectclass: top
objectclass: person
objectclass: inetOrgPerson
cn: Penny Gold
sn: Gold
mail: pgold@ultra.com
 
dn: cn=Amy Lamb, o=Ultra Keyboards Inc., c=US
changetype: add
objectclass: top
objectclass: person
objectclass: inetOrgPerson
cn: Amy Lamb
sn: Lamb
mail: alamb@ultra.com

How to Delete an entry From the Directory

Use ldapdelete(1) to delete an entry from the directory. ldapdelete opens a connection to the LDAP directory server, binds to the directory server, and performs one or more LDAP delete entry operations on the directory.

  1. Bind as the directory manager (password “enigma”) and delete the entry for Penny Gold.


    % ldapdelete -D "cn=Manager, o=Ultra Keyboards Inc., \
c=US" -w enigma "cn=Penny Gold, o=Ultra Keyboards Inc., c=US"

ldapdelete returns nothing if the operation is successful; otherwise, an error message is displayed.

How to Rename a Directory Entry

Use ldapmodrdn(1) to rename an existing directory entry. ldapmodrdn opens a connection to the LDAP directory server, binds to the directory server, and performs one or more LDAP modify RDN (rename) operations on the directory.

  1. Bind as the directory manager (password “enigma”) and change the RDN cn value from “User Interface” to “Ergonomic”.


    % ldapmodrdn -r -D "cn=Manager, o=Ultra Keyboards Inc., \
c=US" -w enigma "cn=User Interface, o=Ultra Keyboards Inc., \
c=US" "cn=Ergonomic"

ldapmodrdn returns nothing if the operation is successful; otherwise, an error message is displayed.