Chapter 5 Architectural Changes in Directory Server

This chapter describes the architectural changes in Directory Server that affect migration from a previous version. For information on all changes and bug fixes in Directory Server, see What’s New at a Glance in Sun Java System Directory Server Enterprise Edition 6.3 Evaluation Guide.

This chapter covers the following topics:

• Changes in the Administration Framework

• Changes to ACIs

• Command Line Changes

• Changes to the Console

• New Password Policy

• Changes to Plug-Ins

• Changes to the Installed Product Layout

Changes in the Administration Framework

Directory Server 6.3 does not include an administration server, as in previous versions. Servers are now registered in the Directory Service Control Center (DSCC) and can be administered remotely by using the web-based GUI or the command-line tools.

To migrate to the new administration framework, you need to do the following:

• Upgrade each server individually

• Register each server in the DSCC

Removal of the ServerRoot Directory

In the new administration model, a Directory Server instance is no longer tied to a ServerRoot. Each Directory Server instance is a standalone directory that can be manipulated in the same manner as an ordinary standalone directory.

Removal of the o=netscapeRoot Suffix

In previous versions of Directory Server, centralized administration information was kept in o=netscapeRoot. In the new administration model, the concept of a configuration directory server no longer exists. The o=netscapeRoot suffix is no longer required, and the netscapeRoot database files are therefore not migrated. The configuration data for this suffix can be migrated, if it is specifically required.

Changes to ACIs

The following changes have been made to ACIs in Directory Server 6.3.

Changes in the ACI Scope

In Directory Server 5.2 ACIs on the root DSE had base scope. In Directory Server 6.3, ACIs on the root DSE have global scope by default, equivalent to targetscope="subtree".

To reproduce the same behavior as Directory Server 5.2, add targetscope="base" to ACIs on the root DSE. If you use dsmig to migrate the configuration, this is done automatically.

Changes in Suffix-Level ACIs

In Directory Server 5.2, the following ACI was provided, at the suffix level:

aci: (targetattr != "nsroledn || aci || nsLookThroughLimit || 
  nsSizeLimit || nsTimeLimit || nsIdleTimeout || passwordPolicySubentry || 
  passwordExpirationTime || passwordExpWarned || passwordRetryCount || 
  retryCountResetTime || acc ountUnlockTime || passwordHistory || 
  passwordAllowChangeTime")(version 3.0; acl "Allow self entry modification 
  except for nsroledn, aci, resource limit attributes, passwordPolicySubentry 
  and password policy state attributes"; allow (write)userdn ="ldap:///self";)

This ACI allowed self-modification of user passwords, among other things. This ACI is no longer provided in Directory Server 6.3. Instead, the following global ACIs are provided by default:

aci: (targetattr != "aci") (targetscope = "base") (version 3.0; 
aci "Enable read access to rootdse for anonymous users"; 
allow(read,search,compare) user dn="ldap:///anyone"; )

aci: (targetattr = "*") (version 3.0; acl "Enable full access 
for Administrators group";  allow (all)(groupdn = 
"ldap:///cn=Administrators,cn=config"); )

aci: (targetattr = "userPassword") ( version 3.0; acl "allow 
userpassword self modification"; allow (write) userdn = "ldap:///self";)

In Directory Server 6.3, the default userPassword ACI at root DSE level provides equivalent access control to the default 5.2 ACI at suffix level. However, if you want to reproduce exactly the same access control as in 5.2, add the following ACI to your suffix. This ACI is the 5.2 ACI, with the new password policy operational attributes for Directory Server 6.3.

aci: (targetattr != "nsroledn || aci || nsLookThroughLimit || 
  nsSizeLimit || nsTimeLimit || nsIdleTimeout || passwordPolicySubentry || 
  passwordExpirationTime || passwordExpWarned || passwordRetryCount || 
  retryCountResetTime || accountUnlockTime || passwordHistory || 
  passwordAllowChangeTime || pwdAccountLockedTime || pwdChangedTime || 
  pwdFailureTime || pwdGraceUseTime || pwdHistory || 
  pwdLastAuthTime || pwdPolicySubentry || pwdReset")(version 3.0; 
  acl "Allow self entry modification except for nsroledn, 
  aci, resource limit attributes, passwordPolicySubentry 
  and password policy state attributes"; allow (write)userdn ="ldap:///self";)

Do not allow users write access to everything and then deny write access to specific attributes. Instead, explicitly list the attributes to which you allow write access.

Command Line Changes

In Directory Server 6.3 the functionality of most command-line tools is replaced by only two commands: dsadm and dsconf.

The following table shows commands used in Directory Server 5, and the corresponding commands for Directory Server 6.3. The default path of these commands when installed from native packages is /opt/SUNWdsee/ds6/bin. When installed from the zip installation, the default path is install-path/ds6/bin.

Deprecated Commands

Some version 5 commands have been deprecated in Directory Server 6.3. The following table provides a list of these commands.

Changes to the Console

The downloaded, Java Swing-based console has been replaced by Directory Service Control Center (DSCC). DSCC is a graphical interface that enables you to manage an entire directory service by using a web browser. The DSCC requires no migration. Migrated Directory Server instances can be registered in the DSCC. For more information about the DSCC see Chapter 1, Directory Server Overview, in Sun Java System Directory Server Enterprise Edition 6.3 Reference.

New Password Policy

Directory Server6.3 implements a new password policy that uses the standard object class and attributes described in the “Password Policy for LDAP Directories” Internet-Draft.

The new password policy provides the following new features:

• A grace login limit, specified by the pwdGraceAuthNLimit attribute. This attribute specifies the number of times an expired password can be used to authenticate. If it is not present or if it is set to 0, authentication will fail.

• Safe password modification, specified by the pwdSafeModify attribute. This attribute specifies whether the existing password must be sent when changing a password. If the attribute is not present, the existing password does not need to be sent.

In addition, the new password policy provides the following new controls:

• LDAP_CONTROL_PWP_[REQUEST|RESPONSE]

• LDAP_CONTROL_ACCOUNT_USABLE_[REQUEST|RESPONSE]

These controls enable LDAP clients to obtain account status information.

The LDAP_CONTROL_PWP control provides account status information on LDAP bind, search, modify, add, delete, modDN, and compare operations.

The following information is available, using the OID 1.3.6.1.4.1.42.2.27.8.5.1 in the search:

• Period of time before the password expires

• Number of grace login attempts remaining

• The password has expired

• The account is locked

• The password must be changed after being reset

• Password modifications are allowed

• The user must supply his/her old password

• The password quality (syntax) is insufficient

• The password is too short

• The password is too young

• The password already exists in history

The LDAP_CONTROL_PWP control indicates warning and error conditions. The control value is a BER octet string, with the format {tii}, which has the following meaning:

• t is a tag defining which warning is set, if any. The value of t can be one of the following:

  LDAP_PWP_WARNING_RESP_NONE (0x00L)
  LDAP_PWP_WARNING_RESP_EXP (0x01L)
  LDAP_PWP_WARNING_RESP_GRACE (0x02L)

• The first i indicates warning information.

  The warning depends on the value set for t as follows:

  • If t is set to LDAP_PWP_WARNING_RESP_NONE, the warning is -1.

  • If t is set to LDAP_PWP_WARNING_RESP_EX, the warning is the number of seconds before expiration.

  • If t is set to LDAP_PWP_WARNING_RESP_GRACE, the warning is the number of remaining grace logins.

• The second i indicates error information. If t is set to LDAP_PWP_WARNING_RESP_NONE, the error contains one of the following values:

pwp_resp_no_error (-1)
pwp_resp_expired_error (0)
pwp_resp_locked_error (1)
pwp_resp_need_change_error (2)
pwp_resp_mod_not_allowed_error (3)
pwp_resp_give_old_error (4)
pwp_resp_bad_qa_error (5)
pwp_resp_too_short_error (6)
pwp_resp_too_young_error (7)
pwp_resp_in_hist_error (8)

The LDAP_CONTROL_ACCOUNT_USABLE control provides account status information on LDAP search operations only.

Password Policy Compatibility

For migration purposes, the new password policy maintains compatibility with previous Directory Server versions by implementing a compatibility mode. The compatibility mode determines whether password policy attributes are handled as old attributes or new attributes, where old refers to Directory Server 5 password policy attributes.

This section contains information to help you set the compatibility mode and to decide which mode is appropriate for your deployment.

Setting the Compatibility Mode

The compatibility mode can be read using dsconf command as follows:

$ dsconf get-server-prop pwd-compat-mode

The pwd-compat-mode property can have one of the following values:

DS5-compatible-mode

The purpose of DS5-compatible-mode is to allow an existing replicated topology to be migrated from Directory Server 5 instances to Directory Server 6.3 instances. A Directory Server 6.3 instance in DS5-compatible-mode accepts updates containing either old or new password policy attributes, and produces updates containing both sets of attributes. Updates can arrive from an LDAP client or from replication, and changes are produced locally as a result of password policy evaluation (for example, as a result of a failed authentication or a password change). Note that any version 5 instance consuming replicated updates produced by a version 6.3 instance (either directly or through another instance) must have its schema updated with 00ds6pwp.ldif as described in Issues With the New Password Policy. While the Directory Server 5 instance will ignore any new attributes during password policy processing, when an entry containing the new attributes is modified at that instance, without the schema update, the schema check will fail when the modified entry is written.

DS6-migration-mode

DS6-migration-mode is an intermediate step between DS5-compatible-mode and DS6-mode, All policy decisions are based on the new password policy attributes and the old (Directory Server 5) password policy attributes are removed from the server's data. Since the number of policy configuration entries is small, the old password policy configuration attributes are cleaned from all policy entries as soon as the instance is advanced to DS6-migration-mode. However, the cleanup of a user entry is deferred until the entry is modified as part of normal password policy processing during a password modify operation. This approach allows the cleanup to proceed gradually, so as to not degrade the server's performance. The modifications necessary to remove any old policy attributes are not replicated so that they do not interfere with the operation of instances still in DS5-compatible-mode.

DS6-mode

A Directory Server 6.3 instance in DS6-mode uses only new policy attributes in computing password policy decisions. Any old password policy attributes remaining in an entry are ignored.

The compatibility mode is set using the dsconf command as follows:

$ dsconf pwd-compat new-mode

The new-mode action takes one of the following values:

to-DS6-migration-mode

Change to DS6-migration-mode from DS5-compatible-mode.

Once the change is made, only DS6-migration-mode and DS6-mode are available.

to-DS6-mode

Change to DS6-mode from DS6-migration-mode.

Once the change is made, only DS6-mode is available.

The server state can move only towards stricter compliance with the new password policy specifications. Compatibility with the old password policy will not be supported indefinitely. You should therefore migrate to the new password policy as soon as is feasible for your deployment.

Guidelines for Choosing a Compatibility Mode

The pwd-compat-mode setting affects the internal server operation and is largely isolated from the password policy behavior seen by an LDAP client. In particular, the pwd-compat-mode setting does not affect the range of server responses to an LDAP client authentication (bind).

The configuration and operational attributes used to implement the password policy depend on the pwd-compat-mode setting. Therefore, an LDAP application that accesses the old (Directory Server 5) attributes will need to be modified prior to advancing the pwd-compat-mode beyond the initial DS5-compatible-mode.

DS5-compatible-mode is the default setting. If you upgrade an existing server to Directory Server 6.3 or if you create a new Directory Server 6.3 instance, the compatibility state is set to DS5-compatible-mode.

This section provides details about the compatibility mode appropriate to your Directory Server deployment.

New Directory Server 6.3 Deployment

If you install a standalone Directory Server instance or are deploying a new replicated topology, set the compatibility mode to DS6-mode to immediately take advantage of the features available in the new password policy implementation. Since a new Directory Server 6.3 instance is created with the compatibility mode set to DS5-compatible-mode, you will need to remember to advance the instance to DS6-mode before installing it into a replicated topology whose instances are already set to DS6-mode.

Migrating a Deployment from Directory Server 5 to Directory Server 6.3

If you are migrating an existing replicated topology, as long as at least one Directory Server 5 instance remains in the replication topology, all of the Directory Server 6.3 instances must be set to DS5-compatible-mode.

Once a replicated topology has been completely migrated from Directory Server 5 to Directory Server 6.3 (in DS5-compatible-mode), you can consider advancing from maintaining compatibility with the old password policy to using the new password policy exclusively. Moving from DS5-compatible-mode to DS6-mode occurs in two phases, which includes an intermediate stage in DS6-migration-mode. First, the Directory Server 6.3 instances must be left in DS5-compatible-mode for an entire password expiration cycle so that the user entries are populated with the new pwdChangedTime attribute. Any applications that depend on the old password policy attributes must also be migrated to the new attributes while the Directory Server 6.3 instances are in DS5-compatible-mode, since the old attributes are no longer available in DS6-migration-mode. At this point, the instances comprising the replicated topology can be advanced to DS6-migration-mode.

The second phase consists of running all instances of the replicated topology in the intermediate DS6-migration-mode to clean out the old operational attributes in the entries. This cleanup must occur before advancing from DS6-migration-mode to DS6-mode. Otherwise, the stale attributes will remain in the entries. To mitigate the overhead of cleaning the old password policy operational attributes, the Directory Server 6.3 instance only removes the attributes in conjunction with a password modify. Thus a simple approach to the cleanup, assuming the password expiration feature is enabled, is to leave the Directory Server 6.3 instances in DS6-migration-mode for an entire password expiration cycle. Finally, once the old password policy attributes have been cleaned from the entries, the instances can be moved to DS6-mode. Remember that the new Directory Server 6.3 instance is created set to DS5-compatible-mode. You will need to remember to advance the instance to DS6-mode before installing it into a replicated topology whose instances are already at DS6-mode.

The following table shows the allowed combinations of Directory Server versions and password policy compatibility modes. Note that at most two variations are allowed in a replicated topology at any time. For example, if a topology contains a Directory Server 6.3 instance in DS5-compatible-mode and one in DS6-migration-mode, then those are the only two variants allowed: no Directory Server 5 instances or Directory Server 6.3 instances in DS6-mode are allowed.

Changes to Administrative Password Reset Classification

Password policy features such as must-change-on-reset (pwd-must- change-enabled) and administrative bypass of password quality checks (pwd-root-dn-bypass-enabled) depend on classifying the modification of the userPassword attribute as either a self-change or an administrative reset.

In Directory Server 5, by default, only the Directory Manager can perform an administrative reset of a user's password. Any other password change is considered as a self-change. Directory Server 5.2p4 introduced the password policy configuration attribute passwordNonRootMayResetUserpwd that, when enabled, limits the userPassword modify operations that are considered as a self-change to the following two cases:

1. A user is authenticated and changing the password of his or her own account.

2. An administrator changes the password, but the LDAP Proxied Authorization Control (http://www.ietf.org/rfc/rfc4370.txt) is set for the userPassword modify operation, and the proxied user DN is the target of the modify operation.

Any other password change is considered as an administrative reset. This feature eliminates the requirement of using Directory Manager for routine password administration, while the simple other-than- self (password change made by any other user but not by self) test avoids the complexity of a separate scheme to identify administrative users.

Directory Server 6.x evaluates password changes similar to Directory Server 5.x with passwordNonRootMayResetUserPassword enabled. That is, Directory Server 6.x considers a password change as an administrative reset except for a user changing his or her own password, or when the proxied authorization control is used. Even though the passwordNonRootMayResetUserpwd attribute can be present in a Directory Server 6.x password policy configuration entry when the instance is in Directory Server 5.x compatible mode, the attribute can not be modified and the feature is always enabled.

If your Directory Server 5 based LDAP application uses an administrative account other than Directory Manager to change a password on behalf of a user (that is, the change should be a self-change), when the application is used with Directory Server 6.x, the change will be considered as an administrative reset. You can restore the original behavior by using the LDAP Proxied Authorization Control (http://www.ietf.org/rfc/rfc4370.txt) with the userPassword modify operation. The proxied authorization control handles the operation as if it is invoked by the proxied user. The control is available in the LDAP C SDK (http://wiki.mozilla.org/LDAP_C_SDK) and LDAP SDK for Java (http://www.mozilla.org/directory/javasdk.html), and the ldapmodify command included with DSRK 6. Invoke the proxied authorization control using the ldapmodify command as follows:

$ ldapmodify -D <administrative-user-DN > -Y <proxied-user-DN>

The ldapmodify commands from other products might use a different flag, or might not support the proxied authorization control at all.

Changes to Plug-Ins

This section lists the new and deprecated plug-ins in Directory Server 6.3. The section also describes what you need to do if you have custom plug-ins created with the old plug-in API.

New Plug-Ins in Directory Server 6.3

The following plug-ins have been added in Directory Server 6.3:

cn=example,cn=ldbm database,cn=plugins,cn=config
cn=gle,cn=plugins,cn=config
cn=MemberOf Plugin,cn=plugins,cn=config
cn=Monitoring Plugin,cn=plugins,cn=config
cn=ObjectDeletionMatch,cn=plugins,cn=config
cn=pswsync,cn=plugins,cn=config
cn=Replication Repair,cn=plugins,cn=config
cn=RMCE,cn=Password Storage Schemes,cn=plugins,cn=config
cn=Strong Password Check,cn=plugins,cn=config

For information about these plug-ins see the plugin(5dsconf) man page.

Plug-Ins Deprecated in Directory Server 6.3

The legacy 4.x replication plug-ins are deprecated.

Changes to the Plug-In API

If you have developed your own custom plug-ins, you need to recompile these to work with Directory Server 6.3. For a complete list of the changes made to the plug-in API, see Chapter 2, Changes to the Plug-In API Since Directory Server 5.2, in Sun Java System Directory Server Enterprise Edition 6.3 Developer’s Guide.

Changes to the Installed Product Layout

This section summarizes the changes to the installed product layout from Directory Server 5.2. Several files and utilities have been deprecated since Directory Server 5.2, as described in the following sections.

Administration Utilities Previously Under ServerRoot

In Directory Server 6.3 the Administration Server is no longer used to manage server instances.

The following system administration utilities previously located under ServerRoot have therefore been deprecated:

• restart-admin

• start-admin

• startconsole

• stop-admin

• uninstall

Binaries Previously Under ServerRoot/bin

The following utilities under ServerRoot/bin have been deprecated:

• ServerRoot/bin/admin/admconfig

• ServerRoot/bin/https/bin/ns-httpd

• ServerRoot/bin/https/bin/uxwdog

• ServerRoot/bin/slapd/server/ns-ldapagt

On Solaris SPARC, the ns-slapd daemon is located in install-path/ds6/bin/lib/sparcvSolaris-Version. On platforms other than Solaris SPARC, the ns-slapd daemon is located in install-path/ds6/bin/lib.

Libraries and Plug-Ins Previously Under ServerRoot/lib

Product libraries and plug-ins in Directory Server 5.2 were located under ServerRoot/lib. In Directory Server 6.3, on Solaris SPARC, these libraries and plug-ins are located in install-path/ds6/lib/sparcvSolaris-Version. On platforms other than Solaris SPARC, they are located directly under install-path/ds6/lib.

Online Help Previously Under ServerRoot/manual

Console online help files were previously located under ServerRoot/manual. The console online help files for Directory Server 6.3 are located under opt/SUNWdsee/ds6/dccapp/html.

Plug-Ins Previously Under ServerRoot/plugins

The following tables describes the new location of sample server plug-ins, and header files for plug-in development.

SNMP support is no longer handled within Directory Server. SNMP monitoring is now handled by the Java Enterprise System Monitoring Framework (Java ES MF). All plug-ins and binaries related to SNMP have therefore been deprecated within Directory Server.

These plug-ins include the following:

• ServerRoot/plugins/snmp/magt/magt

• ServerRoot/plugins/snmp/mibs/

• ServerRoot/plugins/snmp/sagt/sagt

For information about enabling monitoring Java ES MF monitoring, see Enabling Java ES MF Monitoring in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

Utilities Previously Under ServerRoot/shared/bin

The following tables describes the new location of the administrative tools previously under ServerRoot/shared/bin. Note that as a result of the change to the administrative framework, some of these tools have been deprecated.

Certificate and Key Files

The following table shows the new locations of the certificate and key files in Directory Server 6.3.

Silent Installation and Uninstallation Templates

In Directory Server 5.2, the ServerRoot/setup5 directory contained sample templates for silent installation and uninstallation. Silent installation and uninstallation are no longer needed for Directory Server 6.3 and these files have therefore been deprecated.

Server Instance Scripts Previously Under ServerRoot/slapd-ServerID

The command-line administration scripts previously under ServerRoot/slapd-ServerID have been replaced in the new administration framework and deprecated. These commands and their Directory Server 6.3 equivalents are described in Command Line Changes.

Server Instance Subdirectories

The following table describes the new locations for the configuration, log and backup data previously located under ServerRoot/slapd-instance-name