Sun Java System Directory Server

Currently, this article applies to version 6 of Sun Java System Directory Server, Sun's implemention of an LDAP server. It is sometimes referred to as Sun Directory Server, Directory Server Enterprise Edition, or DSEE.

=Installation= /opt/SUNWdsee7/bin/dsccsetup war-file-create /opt/SUNWdsee7/bin/dsccsetup ads-create /opt/SUNWdsee7/bin/dsccsetup status
 * Currently we use the Java Enterprise System (JES) or native packages installers. Note that the native package installer for version 6.3 is really the JES installer for 6.0 + Solaris patch.
 * To use Identity Synchronization for Windows (ISW), you may need to download the ZIP distribution of DSEE. Note that you should still install the native packages distribution for DSEE, only using the ZIP distribution to get ISW.
 * To install DSEE, you must run `pkgadd -d ` in order to install all components needed.
 * After installing DSEE as the previous docs show, you must pre-configure the Directory Service Control Center:


 * Install Apache Tomcat on Solaris:
 * Downloade the latest from the 6.x train and put it in /opt/apache-tomcat
 * Configure Tomcat as shown here

Continue the installation from the Sun documentation
 * Starting at step 6:
 * ${CATALINA_HOME}/bin/shutdown.sh
 * export CATALINA_OPTS="-Djava.awt.headless=true"
 * ${CATALINA_HOME}/bin/startup.sh

Other information that might be useful, but not necessary for Tomcat 6.x):
 * http://stackoverflow.com/questions/567810/problem-running-java-war-on-tomcat
 * http://forums.sun.com/thread.jspa?threadID=5390073&messageID=10730344

Workarounds

 * cacaoadm fails after the instalation of patch 124463-02 - 'cacaoadm' returns "Cannot find property: [cacao.embedded]." -, upgraded from 123893-05. The easiest way to revert this is to use PCA and reinstall the original patch. This will require an init 6.

svc:> select system/webconsole svc:/system/webconsole> setprop options/tcp_listen=true svc:/system/webconsole> quit
 * By default, smcwebserver only listens on localhost:6789. To enable this to listen on ldap1:679:
 * 1) svccfg
 * 1) /usr/sbin/smcwebserver restart

cacaoadm stop cacaoadm set-param network-bind-address=0.0.0.0 cacaoadm start
 * By default, cacao only listens on IP 127.0.0.1, not allowing communication from the other LDAP servers.

=Configuration Notes= Any configuration steps listed below that are server-specific must be run on each LDAP instance! dn: cn=config changetype: modify replace: nsslapd-rootpw nsslapd-rootpw: newpassword /opt/SUNWdsee/ds6/bin/dsadm enable-service -T SMF /path/to/directory DSCC's LDAP server is located at /var/opt/SUNWdsee/dscc6/dcc/ads, while we locate the data-containing LDAP servers at /store/ds/{subdir}. Also run  in the event that a recovery needs to take a long time, otherwise SMF will kill and restart the LDAP server if a recovery operation takes longer than the default timeout (which means the directory server may not ever automatically restart after a system crash). Finally run  and   on the new SMF entries created for the Directory Servers. doesn't start anything so you don't need to enable that.
 * The databases are currently stored using ZFS, located at /store/ds/{subdir}.
 * We use the wildcard SSL certificate from ipsCA rather than a self-signed one for LDAP because we have it and it works. It needs to be imported in PKCS12 format (the password for which cannot be null).  A PKCS12 version of the currently valid certificate is located at TJcerts/main_ipsca/tjhsst.pkcs12 on the Sun administrative volume.  As last attempted, this process seems to be a little more involved than it should:
 * Import the certificate
 * Restart the Directory Server instance
 * Now switch to the new certificate
 * Restart again
 * To change the manager password, run ldapmodify with the appropriate arguments against this:
 * To enable starting the server at boot time using SMF, run

WARNING: svcadm refresh tells the SMF instances to reread the settings, including the new timeout that you set. If you don't run it, you may find that the new timeout is not being respected.


 * If using ISW: using DSCC, select the LDAP server instance, go to Server Configuration -> Plugins, select the "referential integrity postoperation" plugin. Set Argument 1 to "2".  This should make mass modifications and deletions faster.  This plugin is enabled by ISW, so if you change the setting before installing ISW, the plugin may still be disabled.
 * When importing data from OpenLDAP, you may have structuralObjectClass attributes on objects. Sun Directory Server doesn't seem to like this, so just change structuralObjectClass to plain objectClass.
 * The default DN of the manager account (basically a root account in LDAP) for Sun Directory Server is "cn=Directory Manager".

NSS
See also NSS LDAP.
 * NSS LDAP databases are stored in /store/ds/nss.
 * Currently ports 388 (non-SSL) and 635 (SSL) are used for NSS LDAP, but that is not a requirement. It is used because NSS LDAP used to coexist with another LDAP instance at the same IP address that used the normal 389/636 ports.  While that is no longer the case, the port numbers were kept to reduce impact on already configured client systems.

aci: (targetattr="dspswpassword")(version 3.0; acl "No read access to dspswpas sword"; deny(read, search, compare) userdn="ldap:///anyone";) aci: (targetattr="dspswuserlink || dspswloop || dspswvalidate")(version 3.0; a cl "deny write access to dspswuserlink, dspswloop, dspswvalidate"; deny(writ e) userdn="ldap:///self";) aci: (targetattr="*")(version 3.0; acl "Full rights for PSW Connector"; allow( all) userdn="ldap:///uid=PSWConnector,dc=csl,dc=tjhsst,dc=edu";) aci: (target="ldap:///dc=csl,dc=tjhsst,dc=edu")(targetattr !="aci")(version 3. 0;acl "anonymous, no acis"; allow (read, search, compare) userdn = "ldap:/// anyone";)
 * Verify that the following 4 acis exist on the root dn entry dc=csl,dc=tjhsst,dc=edu (easily done by reading a backup LDIF dump):

VLV indexes
In order for NSS LDAP to fully work for Solaris clients, we need to set up VLV indexes (nowadays sometimes referred to as "browsing indexes". This must be done on EACH replica server, not just the master(s).  Without these indexes, while the system will probably work fine, you won't be able to "dump" the NSS databases using getent passwd or getent group.
 * From the DSCC web interface, select the LDAP instance, then go to Entry Management -> Access Control
 * Edit the "VLV Request Control" entry to apply to ldap:///anyone instead of ldap:///all (anyone means anonymous access while all means any bound user)
 * On the command line, ldapadd the vlvindexes.ldif file (currently located in the ds folder on the Sun admin volume)
 * If you want to try and understand what we are adding, examine the /usr/lib/ldap/idsconfig script
 * Stop the directory instance
 * Generate the VLV indexes:

Indexing
We also want to supplement the default attribute indexes.
 * After logging into the DSCC, go to Directory Servers -> Suffixes -> [choose the suffix] -> Indexes.
 * For "uid", enable Presence and Substring (Equality should already be enabled).
 * ldapadd the nssindexes.ldif file (same location as vlvindexes.ldif above) to add all the other indexes that we want.
 * Indexes shouldn't need to be regenerated since there shouldn't be any data in the directory server yet.

Performance tuning
Adjust the default limits and cache values.
 * In DSCC, select the LDAP instance, then go to Server Configuration.
 * On the LDAP subtab, set the Size Limit and Lookthrough Limit to Unlimited. The default 3600 second Time Limit and Unlimited Idle Timeout should be fine.
 * On the Performance subtab, change the following values:
 * Database Cache (Global): 256 MB (default 32 MB)
 * Initialization Cache (Global): 512 MB (default 64 MB)
 * Cache Size Limits: dc=csl,dc=tjhsst,dc=edu: 64 MB (default 10 MB)

Intranet
See also Intranet2. While Intranet currently uses OpenLDAP, Sun Directory Server has also been evaluated for Intranet use. The notes below reflect what has been found so far in that considering process.

Since there isn't really an Intranet2 functional article, here's a short blurb on the role of LDAP: LDAP is used to store student information. In Intranet 1, MySQL was used exclusively for this purpose, but now LDAP is used for most static student information, including biographical information, class schedule, and contact information. Eighth period, Intranet groups, polls, and several other services are still managed through MySQL since it is better for things that are more likely to change. Access controls are also applied using LDAP and not using Intranet. In this way, by having the Intranet LDAP server run by a staff member, students are not necessarily able to easily access private student information even while retaining administrative privileges over other components of Intranet.


 * The manager DN for I2 LDAP is "cn=Manager,dc=tjhsst,dc=edu"; if importing from an LDIF, take out the entry from the file since this DN is managed privately.
 * Most files referenced below are located in the ds/i2 subdirectory on the Sun admin volume.
 * Anywhere below that it says "ldapadd this", the basic command to use is: .  The "-c" argument is recommended so ldapadd will continue trying to add the rest of the LDIF even if it encounters an error with one of the entries in the middle.
 * The following items are not listed in any particular order, and may be incomplete.

Schema
Among other things:
 * There's a 99iodine_schema.ldif file that works with Sun Directory Server. It was converted from the OpenLDAP by some combination of scripts and temporary files, currently located at sun/ds/schema_convert.
 * Sun DSEE 6.3.1 doesn't have alias support for objectClasses, but does for attribute names.
 * Sun DSEE 6.3.1 doesn't have support for numericStringSyntax 1.3.6.1.4.1.1466.115.121.1.36 (RFC 2252).

GSSAPI

 * ldapadd the gssapi.ldif file to configure GSSAPI.
 * At this time you can't enable GSSAPI by just adding the ldif, so see http://forum.java.sun.com/thread.jspa?threadID=5202246&tstart=210 and Deason's page on editing dse.ldif to enable GSSAPI.

ACIs

 * Delete all of the default ACIs.
 * ldapadd the acis_full.ldif or the acis_condensed.ldif file.

Indexing

 * ldapadd the indexes.ldif file
 * Indexes that are currently seen in the OpenLDAP slapd.conf that aren't in this LDIF are missing because they are defaults for Sun Directory Server.
 * If the indexes used have changed, the gen_indexldif.sh and indexes.in files can be used to easily generate a new indexes.ldif.
 * Sun docs for v6.0: http://docs.sun.com/app/docs/doc/819-0995/6n3cq3avo?a=view

Performance tweaking

 * Use DSCC, select the LDAP instance, go to the Server Configuration -> Performance.
 * Under Cache Settings, set the following values:
 * Database Cache (Global): 512 MB (default 32 MB)
 * Initialization Cache (Global): 768 MB (default 64 MB)
 * Cache Size Limits: dc=tjhsst,dc=edu: 384 MB (default 10 MB)
 * Under Resource Usage, set Entry Modification Time Tracking: Disabled.

Client control configuration

 * Use DSCC, select the LDAP instance, go to the Server Configuration -> LDAP.
 * Set the following values:
 * Size limit: Unlimited (default 2000)
 * Time limit: 60 (default 3600 secs)
 * Lookthrough limit: Unlimited (default 5000)

Simple bind users

 * At time of writing this applies only to cn=authuser, but for all users that have a hashed password stored in LDAP (so those that would use a simple bind as opposed to a SASL/GSSAPI bind to access LDAP), reset the password manually after the user(s) have been loaded into LDAP from LDIF, unless you are able to successfully bind as that user without doing so.

Other pending tasks
If I2 switches to Sun DS, the following tasks remain:
 * Determine whether we will use multi-master (r/w) replication or read-only replication.
 * Modify Intranet code slightly to handle multiple LDAP hosts (it might be able to do it already). Capability of PHP described in the second-to-last comment (as of 8/10/2007) on: http://www.php.net/manual/en/function.ldap-connect.php (Thanks Deason!)
 * Decide whether or not to use ISW (Identity Synchronization for Windows). It offers attribute synchronization with AD, among other things, but the software is currently (as of 7/21/2009) pretty old and sometimes a bit buggy.  Also, name changes occur infrequently enough that it would only provide limited benefits.
 * If we want encryption, consider getting a non-wildcard SSL certificate. My understanding is anyone with the SSL certificate can decrypt the database.  If the goal is to use encryption to protect student private data from student sysadmins, then we probably want to restrict access to the SSL certificate used to protect the database.

=Administration/Management= Listed below are general ways to administer DSEE. See NSS LDAP for some special ways to administer its LDAP server.

Web interface
Access to the web interface is on the primary LDAP server only at this time. The Directory Service Control Center (DSCC) is accessed through the Sun Java Web Console, available at https://ldap1.sun.tjhsst.edu:6789/. This address is NOT open to the world; you will need to be on the TJ network to access it. To login to Web Console, use the root account and password. Once logged into the Web Console, you will need to launch the DSCC app. Login as "admin" with the DSCC admin password. DSCC makes it easy to manage multiple Sun Directory Server instances on any number of servers.

Details of how to use the console aren't provided here, but here is a short list of things you can do:
 * Manage replication
 * Restart LDAP servers
 * Modify performance parameters (indexing, caches, etc.)
 * Access logs
 * Manage entries (mostly users and groups)

Note that server-specific changes should be made to both servers; i.e. server configuration is not replicated. However, if setting up new LDAP servers, it may be easier to finish setting up one server before setting up its partner as many settings can be copied from an existing LDAP server by DSCC.

If the primary LDAP server (not just the service) is down, the console will also be unavailable as it runs there. There should be a way to replicate DSCC settings as well since it is just dependent on another smaller LDAP instance; however, we do not currently use it as the need doesn't seem to be there. Note that an LDAP server can only be registered in one DSCC at a time.

CLI tools
This just means you can use ldapadd, ldapmodify, ldapdelete, etc. to work on LDAP. Either Sun LDAP client tools or OpenLDAP tools may be used, just be aware that syntaxes may vary for command line options and binary or hashed contents in LDIFs. Note that when using Sun LDAP client tools, you should NOT pass the "-w -" option to prompt interactively for password. For whatever reason, if you do that, and the password contains special characters, it won't read successfully. If you don't pass "-w -", you will still be interactively prompted for a bind password, but this way it will be read successfully even if it contains special characters.

dsadm command on the LDAP servers is also used to manage the server instance itself. It is located in /opt/SUNWdsee/ds6/bin, which should already be in the PATH.

Everything that can be done through the web interface should also be doable using CLI tools, albeit not always as easily.

=See Also=
 * LDAP
 * Sun Identity Synchronization for Windows
 * ACM Admin wiki: Setting up Directory Server 6.0 - Courtesy of former admin Andrew Deason