Sun Java(TM) System Directory Server 5.2 2005Q1 Installation and Migration Guide |
Chapter 2
Overview of UpgradingThis chapter helps you determine whether to patch your Directory Server installation or perform full upgrade and migration from an earlier version of Directory Server. Earlier versions include Netscape Directory Server 4.x, iPlanet Directory Server 5.x, Sun ONE Directory Server 5.2, and Sun Java System Directory Server 200xQx. This chapter also helps you understand the full upgrade process, and identify attribute values you may need to set manually after performing full upgrade.
This chapter includes the following sections:
Patch Update or Upgrade?Depending on the existing Directory Server version in use, you choose to:
Decision to Update or to Upgrade
Table 2-1 helps you determine whether you may patch update, or must upgrade and migrate data.
Table 2-1 Patch Updating or Upgrading and Migrating Data to the Current Version
Existing Version
On Solaris Systems
On Other Platforms
4.x, 5.0, 5.1
Upgrade and migrate
Upgrade and migrate
5.2 packages (SUNWds*) including 5.2 2003Q4
Patch update
N/A
5.2 packages (SUNWds*) including 5.2 2004Q2
Patch update
N/A
5.2 compressed archive (all platforms)1
Patch update
Patch update
1Refer to the Directory Server 5.2 Release Notes for details. The updates for 5.2 compressed archive versions contain essentially the same fixes and enhancements as those provided in the packaged version.
For instructions on performing a patch update, see the Java Enterprise System Upgrade and Migration Guide.
For instructions on performing upgrade and migration, read the rest of this chapter then refer to Chapter 3, "Upgrading and Migrating Data for a Single Directory Server Installation".
Data Service Interruption When Patch Updating on Sun Cluster
When patch updating Directory Server running as a data service on Sun Cluster, you must stop both the Directory Server and associated Administration Server data services during the patch update process. If you leave the data services running during and the service fails over to a node not running the same version of the software, you run the risk of corrupting directory data.
Before You UpgradeThis section provides an overview of upgrade and data migration. Before upgrading, familiarize yourself with the new features and fixes available in the current version. Take the opportunity to review design decisions made during implementation of existing directory services.
When Upgrading a Single Server Instance
Upgrading a server instance involves installing the new server alongside the existing server in a different installation location, using a different serverID and a different port number, stopping the old server, migrating configuration and directory data, and then having clients make requests to the new server.
Handling a Central Configuration Directory Server
If you have a separate, central Directory Server maintaining configuration data for your server topology (o=NetscapeRoot suffix), then that server needs to remain available during upgrade of all other servers. You might for example upgrade the configuration directory server before all other servers in your topology.
When Upgrading Multiple Replicated Servers
Not surprisingly, upgrading multiple servers involves upgrading each server individually. The order in which you upgrade servers depends, however, on the software version of existing servers and on the replication topology.
For upgrades from 5.x, perform the upgrade in the following order:
Refer to Example 5.x Upgrade Scenario for how you might do this in a particular instance.
For upgrades from 4.x, perform the upgrade in the following order:
Refer to Example 4.x Upgrade Scenario for how you might do this in a particular instance.
If the existing environment involves multiple, replicated servers, read all relevant sections of this chapter carefully before proceeding with the upgrade. You must plan your approach fully to avoid unnecessary downtime.
The Upgrade and Data Migration ProcessDirectory Server provides a script (migrateInstance5) to help you migrate data from previous versions to the current version. The migration script performs the following tasks in sequence:
- Stops your old server, and backs up its current configuration.
- Checks schema configuration files, notifying you of differences between the standard schema configuration files and those used by your old server.
(From 4.x only) If a 4.x server uses custom schema not installed in the default location, under ServerRoot/slapd-serverID/config, you must adjust the configuration manually before migrating directory data.
- Creates a database for each suffix stored in the old server.
(From 4.x only) 4.x servers supported multiple suffixes per database. The migration script creates a database for each suffix on the new server.
- Migrates server and database configuration parameters.
4.x servers store such parameters in slapd.conf. 5.x servers store such parameters as entries in dse.ldif.
(From 4.x only) The migration script does not migrate all 4.x server parameters. In some cases, you must migrate 4.x attribute values manually. Refer to Migration for Specific Attribute Types for details.
- Migrates user-defined schema objects.
- Migrates indexes.
- Migrates the configuration of standard server plug-ins, including:
- 7-bit Check
- Binary Syntax
- Case Exact String Syntax
- Case Ignore String Syntax
- Distinguished Name Syntax
- Integer Syntax
- Internationalization
- Retro Changelog
- Referential Integrity (see note that follows)
- Telephone Syntax
- UID Uniqueness
If you have changed the configuration of a plug-in not in the list, you must fix that configuration manually after running the script.
You must also migrate all custom plug-ins manually. At minimum, you must recompile all custom plug-ins and add their configuration to the directory. Refer to the Directory Server Plug-in Developer's Guide for a detailed list of plug-in API changes.
Note
When replicating from a 4.x master to a 5.x consumer with referential integrity enabled, you must reconfigure the referential integrity plug-in on the 4.x master to write referential integrity changes to the 4.x changelog. Refer to the Directory Server Administration Guide for further details.
- (From 5.x only) Migrates replication agreements.
You must, however, reinitialize replicas after migrating the data.
- Migrates the certificate database, and SSL parameters.
- (From 5.x only) Migrates database links.
- (From 5.x only) Migrates replication entries.
- Migrates the SNMP configuration.
After the migration script completes, clients may send requests to the new server.
Migration for Specific Attribute TypesThis section covers attribute types whose values are migrated by the migrateInstance5 script. It identifies which attributes are migrated automatically by the migration script, and which ones must be set manually.
For migration from 4.x, it also describes the mapping of configuration parameters to configuration attributes and configuration entries in the current format.
Migrating From Directory Server 4.x
In Directory Server 4.x architecture, all configuration parameters were stored in text files. In Directory Server 5.x, all configuration attributes are stored in LDAP configuration entries in the dse.ldif file.
This section describes the mapping of configuration parameters in Directory Server 4.x to the corresponding LDAP configuration entries and attributes in Directory Server 5.2.
Server Attributes
In Directory Server 4.x, configuration parameters are stored in the slapd.conf file under the /usr/netscape/server4/slapd-serverID directory.
The corresponding configuration attributes in the current version are stored in the cn=config entry. Table 2-2 shows the mapping of Directory Server 4.x configuration parameters to current configuration attributes.
Database Attributes
In Directory Server 4.x, database parameters are stored in the slapd.ldbm.conf file under the /usr/netscape/server4/slapd-serverID directory.
Because one instance of Directory Server 5.x can manage several databases, the corresponding attributes in Directory Server 5.x are stored in a general entry for all databases (cn=config,cn=ldbm database,cn=plugins,cn=config), or in an entry specific to a particular database, of the form
cn=database instance name,cn=ldbm database,cn=config
Table 2-3 shows the mapping of general database configuration parameters between Directory Server 4.x and Directory Server 5.2.
Table 2-4 shows the mapping of database-specific parameters between Directory Server 4.x and Directory Server 5.2.
Not all parameters are migrated by the migrateInstance5 script. Table 2-5 indicates Directory Server 4.x parameters that are not migrated automatically, and why automatic migration is not done in each case.
Table 2-6 indicates the parameters that are migrated but are potentially problematic. You are advised to check their values in the new installation:
Migrating From Directory Server 5.x
All versions of Directory Server 5.x store configuration information in the same way. This section explains which configuration attributes are automatically migrated by the migrateInstance5 script, and which ones are not. Attributes which are not automatically migrated are either configured during the installation process for the new Directory Server, or need to be configured manually for security reasons after the initial setup.
Global Server Configuration Attributes
The following list provides the configuration attributes stored in the cn=config entry that are automatically migrated when you run the migrateInstance5 script:
- nsslapd-accesscontrol
- nsslapd-accesslog-level
- nsslapd-accesslog-logbuffering
- nsslapd-accesslog-logexpirationtime
- nsslapd-accesslog-logexpirationtimeunit
- nsslapd-accesslog-logging-enabled
- nsslapd-accesslog-logmaxdiskspace
- nsslapd-accesslog-logminfreediskspace
- nsslapd-accesslog-logrotationtime
- nsslapd-accesslog-logrotationtimeunit
- nsslapd-accesslog-maxlogsize
- nsslapd-accesslog-maxlogsperdir
- nsslapd-attribute_name_exceptions
- nsslapd-auditlog-logexpirationtime
- nsslapd-auditlog-logexpirationtimeunit
- nsslapd-auditlog-logging-enabled
- nsslapd-auditlog-logmaxdiskspace
- nsslapd-auditlog-logminfreediskspace
- nsslapd-auditlog-logrotationtime
- nsslapd-auditlog-logrotationtimeunit
- nsslapd-auditlog-maxlogsize
- nsslapd-auditlog-maxlogsperdir
- nsslapd-certmap-basedn
- nsslapd-ds4-compatible-schema
- nsslapd-enquote_sup_oc
- nsslapd-errorlog-level
- nsslapd-errorlog-logexpirationtime
- nsslapd-errorlog-logexpirationtimeunit
- nsslapd-errorlog-logging-enabled
- nsslapd-errorlog-logmaxdiskspace
- nsslapd-errorlog-logminfreediskspace
- nsslapd-errorlog-logrotationtime
- nsslapd-errorlog-logrotationtimeunit
- nsslapd-errorlog-maxlogsize
- nsslapd-errorlog-maxlogsperdir
- nsslapd-groupevalnestlevel
- nsslapd-idletimeout
- nsslapd-ioblocktimeout
- nsslapd-lastmod
- nsslapd-listenhost
- nsslapd-maxdescriptors
- nsslapd-nagle
- nsslapd-plugin-depends-on-name
- nsslapd-plugin-depends-on-type
- nsslapd-readonly
- nsslapd-referral
- nsslapd-referralmode
- nsslapd-reservedescriptors
- nsslapd-rootpwstoragescheme
- nsslapd-schemacheck
- nsslapd-securePort
- nsslapd-security
- nsslapd-sizelimit
- nsslapd-SSL3ciphers
- nsslapd-timelimit
Table 2-7 lists the configuration attributes stored in the cn=config entry that are not automatically migrated when you run the migrateInstance5 script. Attributes that are not automatically migrated are either configured during the installation process for the new Directory Server, or need to be configured manually. The reason for not migrating an attribute is stated in the table.
Password Policy Attributes
The attributes that determine the password policy are stored in the entry cn=Password Policy,cn=config. Note that the location of these attributes has changed. In previous versions of Directory Server, they were located directly under cn=config. The following list provides the password policy attributes that are automatically migrated when you run the migrateInstance5 script:
Database Attributes
All general database configuration attributes are automatically migrated. These attributes are stored in the entry cn=config,cn=ldbm database, cn=plugins,cn=config, and are as follows:
Database-specific attributes are stored in entries of the form cn=database instance name,cn=ldbm database,cn=config. The following list provides the attributes that are migrated:
Table 2-8 lists the attributes that are not migrated automatically and indicates why this is the case.
Chained Suffix Attributes
All chained suffix configuration attributes are migrated automatically. The following configuration attributes are common to all chained suffixes. These attributes are stored in the entry cn=config,cn=chaining database, cn=plugins,cn=config.
The following configuration attributes apply to a default instance of a chained suffix. These attributes are stored in the entry cn=default instance config, cn=chaining database,cn=plugins,cn=config.
- nsAbandonedSearchCheckInterval
- nsBindConnectionsLimit
- nsBindRetryLimit
- nsBindTimeout
- nsCheckLocalACI
- nsConcurrentBindLimit
- nsConcurrentOperationsLimit
- nsConnectionLife
- nsHopLimit
- nsmaxresponsedelay
- nsmaxtestresponsedelay
- nsOperationConnectionslimit
- nsProxiedAuthorization
- nsReferralOnScopedSearch
- nsslapd-sizelimit
- nsslapd-timelimit
SNMP Attributes
All SNMP configuration attributes are automatically migrated. These attributes are stored in the entry cn=SNMP,cn=config, and are as follows: