Previous      Contents      Index      Next
Sun Java(TM) System Directory Server 5.2 2005Q1 Installation and Migration Guide

Chapter 2
Overview of Upgrading

This 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.

Note	This guide does not explain how to upgrade from Innosoft Distributed Directory Server 4.5.1.

This chapter includes the following sections:

Patch Update or Upgrade?
Before You Upgrade
The Upgrade and Data Migration Process
Migration for Specific Attribute Types

---

Patch Update or Upgrade?

Depending on the existing Directory Server version in use, you choose to:

Patch update Directory Server, replacing software binaries and migrating certificate formats but not migrating directory data
Upgrade Directory Server, installing new software and migrating directory data and server configuration to the new instance

Note	Directory Server remote administration depends on Administration Server. When you therefore patch update or upgrade Directory Server, you must also patch update or upgrade Administration Server for the same ServerRoot.

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 Upgrade

This 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.

Note	Ensure you have sufficient disk space on the host where you run the existing server. The upgrade process requires at least enough local disk space to house binaries and databases for both the old and new servers, and also enough extra space to hold LDIF files containing the entries in all existing suffixes. You may estimate the local disk space required as somewhat larger than: 2 * (space for existing server) + (space for LDIF files) The upgrade process must be performed with both servers on the same host, as data migration cannot be performed over networked drives.

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:

Upgrade the consumers.
Upgrade the hubs
Upgrade the masters.

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:

Upgrade the 4.x master
Upgrade each branch of consumers being replicated from the master, starting with the consumer closest to the master in terms of replication.

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 Process

Directory 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.

Note	The script does not migrate data under o=NetscapeRoot. When deploying a server such as Application Server, Identity Server, or Messaging Server that rely on data in this suffix, migrate the data in o=NetscapeRoot manually, or using tools provided with the server in question.

(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.

Note	Before replicating from a 5.2 Directory Server to a 5.1 server, set nsslapd-schema-repl-useronly on cn=config to on. Otherwise the 5.2 schema are pushed to the 5.1 server, preventing the 5.1 server from restarting due to duplicate objects.

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 Types

This 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.

Table 2-2 Mapping of Legacy Server Parameters to Configuration Attributes 

Legacy Configuration Parameter	Current Configuration Attribute
(No equivalent)	nsslapd-depends-on-named
(No equivalent)	nsslapd-depends-on-type
accesscontrol	nsslapd-accesscontrol
accesslog	nsslapd-accesslog
accesslog-level	nsslapd-accesslog-level
accesslog-logexpirationtime	nsslapd-accesslog-logexpirationtime
accesslog-logexpirationtimeunit	nsslapd-accesslog-logexpirationtimeunit
accesslog-logrotationtime	nsslapd-accesslog-logrotationtime
accesslog-logrotationtimeunit	nsslapd-accesslog-logrotationtimeunit
accesslog-maxlogdiskspace	nsslapd-accesslog-logmaxdiskspace
accesslog-maxlogsize	nsslapd-accesslog-maxlogsize
accesslog-MaxNumOfLogsPerDir	nsslapd-accesslog-maxlogsperdir
accesslog-minfreediskspace	nsslapd-accesslog-minfreediskspace
auditfile	nsslapd-auditlog
audit-logging-enabled	nsslapd-audit-logging-enabled
auditlog-logexpirationtime	nsslapd-auditlog-logexpirationtime
auditlog-logexpirationtimeunit	nsslapd-auditlog-logexpirationtimeunit
auditlog-logrotationtime	nsslapd-auditlog-logrotationtime
auditlog-logrotationtimeunit	nsslapd-auditlog-logrotationtimeunit
auditlog-maxlogdiskspace	nsslapd-auditlog-logmaxdiskspace
auditlog-maxlogsize	nsslapd-auditlog-maxlogsize
auditlog-MaxNumOfLogsPerDir	nsslapd-auditlog-maxlogsperdir
auditlog-minfreediskspace	nsslapd-auditlog-minfreediskspace
certmap-basedn	nsslapd-certmap-basedn
enquote_sup_oc	nsslapd-enquote_sup_oc
errorlog	nsslapd-errorlog
error-logging-enabled	nsslapd-error-logging-enabled
errorlog-logexpirationtime	nsslapd-errorlog-logexpirationtime
errorlog-logexpirationtimeunit	nsslapd-errorlog-logexpirationtimeunit
errorlog-logrotationtime	nsslapd-errorlog-logrotationtime
errorlog-logrotationtimeunit	nsslapd-errorlog-logrotationtimeunit
errorlog-maxlogdiskspace	nsslapd-errorlog-logmaxdiskspace
errorlog-maxlogsize	nsslapd-errorlog-maxlogsize
errorlog-maxlogsperdir	nsslapd-errorlog-maxlogsperdir
errorlog-minfreediskspace	nsslapd-errorlog-logminfreediskspace
idletimeout	nsslapd-idletimeout
instancedir	nsslapd-instancedir
ioblocktimeout	nsslapd-ioblocktimeout
lastmod	nsslapd-lastmod
listenhost	nsslapd-listenhost
localhost	nsslapd-localhost
localuser	nsslapd-localuser
logbuffering	nsslapd-accesslog-buffering
loglevel	nsslapd-infolog-area
maxbersize	nsslapd-maxbersize
maxdescriptors	nsslapd-maxdescriptors
maxthreadsperconn	nsslapd-maxthreadsperconn
nagle	nsslapd-nagle
port	nsslapd-port
pw_change	passwordChange
pw_exp	passwordExp
pw_inhistory	passwordinHistory
pw_lockduration	passwordLockoutDuration
pw_lockout	passwordLockout
pw_maxage	passwordMaxAge
pw_maxfailure	passwordMaxFailure
pw_minage	passwordMinAge
pw_minlength	passwordMinLength
pw_must_change	passwordMustChange
pw_reset_failurecount	passwordResetFailureCount
pw_storagescheme	passwordStorageScheme
pw_syntax	passwordCheckSyntax
pw_unlock	passwordUnlock
pw_warning	passwordWarning
referral	nsslapd-referral
reservedescriptors	nsslapd-reservedescriptors
result_tweak	nsslapd-result_tweak
return_exact_case	nsslapd-return_exact_case
rootdn	nsslapd-rootdn
rootpw	nsslapd-rootpw
rootpwstoragescheme	nsslapd-rootpwstoragescheme
schemacheck	nsslapd-schemacheck
secure-port	nsslapd-securePort
security	nsslapd-security
sizelimit	nsslapd-sizelimit
SSL3ciphers	nsslapd-SSL3ciphers
threadnumber	nsslapd-threadnumber
timelimit	nsslapd-timelimit

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-3 Mapping of General Legacy Database Parameters to Configuration Attributes 

Legacy Configuration Parameter	Current Configuration Attribute
allidsthreshold	nsslapd-allidsthreshold
database	OBSOLETE (used to specify database type)
lookthroughlimit	nsslapd-lookthroughlimit
mode	nsslapd-mode

Table 2-4 shows the mapping of database-specific parameters between Directory Server 4.x and Directory Server 5.2.

Table 2-4 Mapping of Database-Specific Legacy Parameters to Configuration Attributes 

Legacy Configuration Parameter	Current Configuration Attribute
cachesize	nsslapd-cachesize
directory	nsslapd-directory
readonly	nsslapd-readonly

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-5 Legacy Parameters Not Migrated by the Migration Script 

Legacy Configuration Parameter	Current Configuration Attribute	Reason
accesslog	nsslapd-accesslog	Set up automatically. Path name of the database access log.
auditfile	nsslapd-auditlog	Set up automatically. Path name of the log used to record changes made to the database.
database	(No equivalent)	OBSOLETE (used to specify database type)
directory	nsslapd-directory	Set up during installation.
errorlog	nsslapd-errorlog	Set up automatically. Path name of the log used to record error messages generated by Directory Server.
instancedir	nsslapd-instancedir	Set up during installation.
localhost	nsslapd-localhost	Already configured.
port	nsslapd-port	Configured manually during installation.
pw_history	(No equivalent)	OBSOLETE
result_tweak	nsslapd-result_tweak	Reserved for future use. Do not use, change or remove. Doing so may have unpredictable results.
rootdn	nsslapd-rootdn	Configured manually during installation.
rootpw	nsslapd-rootpw	Configured manually during installation.

Table 2-6 indicates the parameters that are migrated but are potentially problematic. You are advised to check their values in the new installation:

Table 2-6 Legacy Parameters Migrated by the Migration Script 

Legacy Configuration Parameter	Directory Server 5.2 Configuration Attribute
maxbersize	nsslapd-maxbersize
maxthreadsperconn	nsslapd-maxthreadsperconn
nagle	nsslapd-nagle
return_exact_case	nsslapd-return_exact_case
threadnumber	nsslapd-threadnumber

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

Note	The attribute nsslapd-errorlog-level has been deprecated. It is still supported for backward compatibility but has been replaced by the nsslapd-infolog-area and nsslapd-infolog-level attributes.

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.

Table 2-7 Attributes in cn=config Not Migrated 

Attribute Name	Reason for not Migrating Automatically
nsslapd-accesslog	Path name to the log that records database access. It is set up during installation.
nsslapd-accesslog-list	Read-only attribute.
nsslapd-auditlog	Path name to the log that records changes made to the directory database. It is set up during installation.
nsslapd-errorlog	Path name to the log that records error messages generated by Directory Server. It is set up during installation.
nsslapd-errorlog-list	Read-only attribute.
nsslapd-instancedir	Configured during the installation process.
nsslapd-localhost	Already set up.
nsslapd-localuser	Configured during the installation process.
nsslapd-maxbersize	Do not change the value of this attribute unless told to do so by Sun technical staff.
nsslapd-maxthreadsperconn	This attribute corresponds to a system parameter.
nsslapd-plugin	Internal computed attribute.
nsslapd-port	Configured during the installation process.
nsslapd-result-tweak	Reserved for future use. Do not change or remove.
nsslapd-return-exact-case	Do not modify unless you have legacy client applications that can check the case of attribute names in results returned from the server.
nsslapd-rootdn	Configured during the installation process.
nsslapd-rootpw	Configured during the installation process.
nsslapd-threadnumber	This attribute is not available from Directory Server Console.

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:

passwordChange
passwordCheckSyntax
passwordExp
passwordExpireWithoutWarning
passwordInHistory
passwordLockout
passwordLockoutDuration
passwordMaxAge
passwordMaxFailure
passwordMinAge
passwordMinLength
passwordMustChange
passwordResetFailureCount
passwordStorageScheme
passwordUnlock
passwordWarning

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:

nsslapd-allidthreshold
nsslapd-cache-autosize
nsslapd-cache-autosize-split
nsslapd-dbcachesize
nsslapd-db-transaction-logging
nsslapd-lookthroughlimit
nsslapd-mode

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:

nsslapd-cachememsize
nsslapd-cachesize
nsslapd-readonly
nsslapd-require-index

Table 2-8 lists the attributes that are not migrated automatically and indicates why this is the case.

Table 2-8 Database-Specific Attributes Not Migrated 

Attribute Name	Reason For Not Migrating Automatically
nsslapd-db-checkpoint-interval	This attribute is provided only for system modification/diagnostics and should be changed only under guidance from Sun technical staff. Inconsistent settings of this attribute might cause Directory Server crashes.
nsslapd-db-durable-transactions	This attribute is provided only for system modification/diagnostics and should be changed only under guidance from Sun technical staff. Inconsistent settings of this attribute might cause Directory Server crashes.
nsslapd-db-home-directory	If you have several Directory Servers running on the same machine, the value of this attribute must be different for each instance of Directory Server. Therefore, it needs to be configured manually.
nsslapd-db-logdirectory	Set up automatically during installation.
nsslapd-directory	Set up automatically during installation.

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.

nsActivechainingComponents
nsTransmittedControls

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:

nssnmpcontact
nssnmpdescription
nssnmpenabled
nssnmplocation
nssnmpmasterhost
nssnmpmasterport
nssnmporganization

Previous      Contents      Index      Next

---

Copyright 2005 Sun Microsystems, Inc. All rights reserved.