Installation Guide Netscape Directory Server

Previous      Contents      Index      DocHome      Next

Chapter 6   Migrating and Upgrading From Previous Versions

If you have a previous installation of Directory Server, depending on it's version, you can migrate or upgrade to Netscape Directory Server 6.x. Migration refers to the process of migrating Directory Server 4.x or 5.x files to Directory Server 6.x. Upgrade refers to the process of updating Directory Server 6.0x files to Directory Server 6.x.

This chapter covers the migration and upgrade processes in these sections:

• Migration Overview
• Migration Prerequisites
• Migration Procedure
• Upgrading From Directory Server 6.x Versions

This chapter does not explain how to upgrade from Innosoft Distributed Directory Server 4.5.1. That process is described in the Innosoft Distributed Directory Server Transition Guide.

Migration Overview

---

Before you migrate your directory service, you should become familiar with the new features offered in this release of the Directory Server.

The migration process is performed by running the migrateInstance6 script on the system where your legacy Directory Server is installed. You must shut down your directory service before running the migration script.

The migration script performs the following tasks in sequence:

• Checks the schema configuration files and notifies you of any changes between the standard configuration files and the ones present on your system; see
• Creates a database for each suffix stored in the legacy Directory Server. (In Directory Server 5.x and 6.x you can have multiple databases, but just one suffix per database).
• Checks if any database exists and if it does, gives you the option to save the database (by exporting it to a file), skip the database, or overwrite the database.
• Migrates the server parameters and database parameters. (In Directory Server 5.x and 6.x, these are stored as LDAP entries in the dse.ldif file.)
• Migrates user-defined schema objects.
• Migrates indexes.
• Migrates standard server plug-ins.
• Migrates the certificate database and SSL parameters.
• Migrates database links.
• Migrates replication entries (change log).
• Migrates the SNMP configuration.

The migration script shuts down your legacy Directory Server before performing the migration process. The migration script also backs up your current configuration.

Migration Prerequisites

---

This section lists the prerequisites that your system must meet before you can consider beginning the migration process.

• You must be using Directory Server 4.x or 5.x. When you run the migration script, the legacy server process ns-slapd should be stopped. (If you don't stop the server, the migration script stops it.)
• Your legacy Directory Server and your new Directory Server must be installed on the same host; migration cannot occur over networked drives.
• Do not install the new Directory Server on top of an existing Directory Server installation. Install your new Directory Server in a separate directory. Migrate your legacy directory data into your new directory and when you are satisfied with the result of the migration, remove your legacy Directory Server.
• If you want to continue to run your legacy Directory Server, when you install the new Directory Server choose different ports for LDAP traffic and for secured connections from the ones used by your legacy Directory Server.

If you will not be running your legacy Directory Server, use the same port numbers to ensure that any directory clients that have static configuration information (including Directory Server port numbers) will continue to work.
 

• Your new Directory Server must be running when you execute the migration script.
• Any custom schema that you created in a legacy 4.x Directory Server must be stored in the default files or included using an include statement in the slapd.conf file. The default files for custom schema are slapd.user_oc.conf and slapd.user_at.conf files in Directory Server 4.x. If you have custom schema that is not stored in those files, refer to the procedure described in "Identifying Custom Schema"" to move it to those files.
• Any custom schema that you created in a 5.x Directory Server must be stored in an LDIF file in the serverRoot/slapd-serverID/config/schema directory.
• Before performing the migration, check that the user-defined variables contain the following associated values, where server6Root is the path to where your new, Directory Server 6.x is installed:

On UNIX, set the following environment variables:
 

PERL5LIB=server6Root/bin/slapd/admin/bin
PATH=server6Root/bin/slapd/admin/bin:$PATH

On Windows, set the following environment variables:
 

PERL5LIB=server6Root\bin\slapd\admin\bin
PATH=server6Root\bin\slapd\admin\bin

• Windows only. If you are migrating a Directory Server 5.x multi master replicated (MMR) environment to Directory Server 6.2, before you run the migration script, export all exports from the old server's backend databases using the db2ldif -r option.
• When you run the migration script, it migrates the configuration files or configuration entries, database instances, and schema with minimum manual intervention. For complete information on the configuration parameters and attributes that are migrated, check chapter "Migration from Earlier Versions" of the Netscape Directory Server Configuration, Command, and File Reference.
• Check the command syntax for the migration script in chapter "Command-Line Scripts" of the Netscape Directory Server Configuration, Command, and File Reference.

Identifying Custom Schema

If you customized the schema in your legacy Directory Server by modifying slapd.at.conf or slapd.oc.conf directly, then the server migration process cannot migrate your custom schema for you. Instead, you are notified during migration that you have modified the standard schema and that you need to manually fix the problem. The migration process then saves a copy of your schema files and uses standard legacy schema files in their place.

While the migration will complete in this situation, you will probably find that you cannot modify your data in Directory Server 6.x. Therefore, you are strongly recommended to copy your custom schema into separate files before you perform the migration. You can use the standard slapd.user_oc.conf and slapd.user_at.conf files or any files declared in slapd.conf with the useroc and userat keywords respectively. Make these changes with the server shut down.

To separate your custom schema from your standard schema:

1. Examine your old slapd.at.conf and slapd.oc.conf files to discover all the schema additions that you made there.

To ensure that you have properly identified all your changes to standard files, you can compare them with the standard files provided in the /bin/slapd/install/version4 directory. Alternatively, if you have already tried to run the migrateInstance6 script, use the notifications that it issues.
 

2. Move your custom schema elements to the following files:

serverRoot/slapd-serverID/config/slapd.user_at.conf and serverRoot/slapd-serverID/config/slapd.user_oc.conf

These file names are recommended because the 4.x schema configuration editor writes to them. However, you can use any file name you like.
 

Note that if there are inheritance relationships between custom defined object classes, you must ensure that in the order in which they appear in the schema configuration file, the superior object class is defined before the others.
 

3. Include these files into your slapd.conf file using the userat and useroc directives. Place your new directives at the same place in the file as the include statements for other configuration files.

The order in which the various configuration files are included is not important. Then, if you added custom attributes to standard object classes in slapd.oc.conf, you must do the following:
 

1. In the slapd.user_oc.conf file (or your equivalent), create a new object class that includes your custom attributes.
2. Add this new object class to every entry in your directory that uses the custom attributes.

Migration Procedure

---

Before you start with migration process, ensure the following:

• Read sections "Migration Overview" and "Migration Prerequisites".
• The migration script will automatically back up your Directory Server configuration, if it's in the default location.
• If you are migrating from Directory Server 4.x, all of the files with a .conf extension in the /usr/netscape/server4/slapd-serverID directory are backed up.
• If you are migrating from Directory Server 5.x, all of the configuration files in the /usr/netscape/servers/slapd-serverID/config directory will be backed up to a directory named serverRoot/slapd-serverID/config_backup.

If your configuration files are stored in non-default locations, before you migrate your server, copy them to a secure place.
 

This section contains the following information:

• Migrating a Standalone Server
• Migrating a 4.x Replicated Site
• Migrating a 5.x Replicated Site
• Migrating a 5.x Multi-Master Deployment
• Managing Console Fail Over

Migrating a Standalone Server

Once you have backed up your critical configuration information, do the following to migrate a server:

1. Stop your legacy Directory Server.

If you do not stop the legacy Directory Server, the migration script does it for you.
 

2. On the machine where your legacy Directory Server is installed, install a new, 6.x Directory Server.

The installation process is described in Chapter 2 "Using Express and Typical Installation" or Chapter 4 "Silent Installation and Instance Creation."
 

Use the same port numbers as your legacy production server if you want to ensure that any directory clients that have static configuration information (including Directory Server port numbers) will continue to work.
 

3. Run the migration script.

As root user (on UNIX) or administrator (on Windows), change directory to serverRoot/bin/slapd/admin/bin. Then enter the following command:
 

On UNIX:
 

migrateInstance6 -D rootDN -w password -p port -o oldInstancePath -n newInstancePath

On Windows:
 

perl migrateInstance6 -D rootDN -w password -p port -o oldInstancePath -n newInstancePath

where:
 

• rootDN is the Directory Server 6.x user DN with root permissions, such as Directory Manager.
• password is the password for Directory Manager in Directory Server 6.x.
• port is the LDAP port number assigned to Directory Server 6.x.
• oldInstancePath is the path to the installation directory of the legacy Directory Server (for example, /usr/netscape/server4/slapd-serverID).
• newInstancePath is the path to the installation directory of Directory Server 6.x (for example, /usr/netscape/servers/slapd-serverID).

The following is an example of a command you would use on a UNIX machine to migrate an instance of Directory Server 4.11 to Directory Server 6.x:
 

migrateInstance6 -D "cn=Directory Manager" -w secret -p 1389
-o /usr/netscape/server4/slapd-phonebook
-n /usr/netscape/servers/slapd-phonebook

The following is an example of the same command on a Windows machine:
 

perl migrateInstance6 -D "cn=Directory Manager" -w secret -p 1389
-o c:\netscape\server4\slapd-phonebook
-n c:\netscape\servers\slapd-phonebook

4. Follow the prompts. For example, if you're prompted to provide a path and filename for your backup directory, enter one or accept the default.

The migration process starts. At the end of migration, your legacy Directory Server is migrated. Additionally, as a result of this migration: a new Directory Server 6.x instance is installed using the configuration information obtained from your legacy Directory Server; the data from your old server is migrated to the new server; and the new server is started.
 

A sample output showing migration of Directory Server 5.0 to Directory Server 6.1 is provided below. Notice that the script detects three backends, backend1, backend2, and userRoot, which exist in the legacy server as well as in the new server instances. To demonstrate the various options, for each backend a different option was chosen: for backend1, the choice was to continue with the migration and export processes; for backend2, the choice was to continue with the migration process only (without exporting); and for userRoot, the choice was to skip the migration process.
 

migrate5to6 -D "cn=directory manager" -w secret12 -p 11440 -o
/export/home/jdoe/50-latest/slapd-bart -n
/export/home/jdoe/61-latest/slapd-bart -t 3 -L log.out

oldDir: /export/home/jdoe/50-latest,
oldHome:/export/home/jdoe/50-latest/slapd-bart,
oldConfDir: /export/home/jdoe/50-latest/slapd-bart/config/,
ldif_rep: /export/home/jdoe/50-latest/slapd-bart/config//ldif/,

rootDN: cn=directory manager,
Port: 11440,
Newname: bart


Shutdown the legacy Directory Server instance:
/usr/netscape/servers/ds50/slapd-bart

Shutting down server slapd-bart . . .

. . .

Name of the old LDAP server: bart.netscape.com
Name of the new LDAP server: bart.netscape.com
6.0 localuser: jdoe, uid: 9871, gid: 10
5.x localuser: jdoe, uid: 9871, gid: 10

Backup /export/home/jdoe/61-latest/slapd-bart/config on /export/home/jdoe/61-latest/slapd-bart/config_backup ...

Where do you want to back up your configuration directory
[/export/home/jdoe/61-latest/slapd-bart/config_backup] ?

Migrate the schema...

Connected to 6.1 LDAP server

-------------------------------------------------------------------------

Parse the old DSE ldif file:
/export/home/jdoe/50-latest/slapd-bart/config/dse.ldif *****

This may take a while ...

Migrate DSE entries...

SECURITY - Update successfull: cn=encryption,cn=config
SNMP - Update successfull: cn=snmp,cn=config

Compared to the old instance, the current new plugin cn=referential
integrity postoperation,cn=plugins,cn=config belongs this attribute:
nsslapd-pluginarg7

Param: nstransmittedcontrols values To migrate: 2.16.840.1.113730.3.4.2
2.16.840.1.113730.3.4.9 1.2.840.113556.1.4.473 1.3.6.1.4.1.1466.29539.12
Param: nstransmittedcontrols new current values: 2.16.840.1.113730.3.4.2
2.16.840.1.113730.3.4.9 1.2.840.113556.1.4.473 1.3.6.1.4.1.1466.29539.12
Param: nsslapd-timelimit values To migrate: 3600
Param: nsslapd-timelimit new current values: 3600
Param: nsconcurrentbindlimit values To migrate: 10
Param: nsconcurrentbindlimit new current values: 10
Param: nsbindconnectionslimit values To migrate: 3
Param: nsbindconnectionslimit new current values: 3
Param: nsconnectionlife values To migrate: 0
Param: nsconnectionlife new current values: 0
Param: nsbindretrylimit values To migrate: 3
Param: nsbindretrylimit new current values: 3
Param: nsoperationconnectionslimit values To migrate: 10
Param: nsoperationconnectionslimit new current values: 10
Param: nsreferralonscopedsearch values To migrate: off
Param: nsreferralonscopedsearch new current values: off
Param: nsmaxtestresponsedelay values To migrate: 15
Param: nsmaxtestresponsedelay new current values: 15
Param: nsmaxresponsedelay values To migrate: 60
Param: nsmaxresponsedelay new current values: 60
Param: nsbindtimeout values To migrate: 15
Param: nsbindtimeout new current values: 15
Param: nsabandonedsearchcheckinterval values To migrate: 2
Param: nsabandonedsearchcheckinterval new current values: 2
Param: nsconcurrentoperationslimit values To migrate: 10
Param: nsconcurrentoperationslimit new current values: 10
Param: nschecklocalaci values To migrate: off
Param: nschecklocalaci new current values: off
Param: nshoplimit values To migrate: 10
Param: nshoplimit new current values: 10
Param: nsslapd-sizelimit values To migrate: 2000
Param: nsslapd-sizelimit new current values: 2000
Param: nsproxiedauthorization values To migrate: on
Param: nsproxiedauthorization new current values: on

-------------------------------------------------------------------------

Migrate LDBM backend instances...

*** LDBM_BACKEND_INSTANCE - cn=backend1,cn=ldbm database,cn=plugins,cn=config already exists

*** Migration will overwrite existing database
Do you want to continue Yes/No [No] ? y
Do you want to export the existing data Yes/No [Yes] ?

Enter the full pathname of the file
[/export/home/jdoe/61-latest/slapd-bart/db_backup/backend1.ldif]:

Existing data will be exported under
/export/home/jdoe/61-latest/slapd-bart/db_backup/backend1.ldif

Continue Yes/No [No] ? y

Now baking up database backend1 in
/export/home/jdoe/61-latest/slapd-bart/db_backup/backend1.ldif

Shutting down server slapd-bart . . .

ldiffile: /export/home/jdoe/61-latest/slapd-bart/db_backup/backend1.ldif
[12/Jun/2002:10:32:05 -0700] - export backend1: Processed 3 entries (100%).
[12/Jun/2002:10:32:05 -0700] - Waiting for 4 database threads to stop
[12/Jun/2002:10:32:07 -0700] - All database threads now stopped

try to reconnect to search cn=backend2,cn=ldbm database,cn=plugins,cn=config


*** LDBM_BACKEND_INSTANCE - cn=backend2,cn=ldbm database,cn=plugins,cn=config already exists

*** Migration will overwrite existing database

Do you want to continue Yes/No [No] ? y
Do you want to export the existing data Yes/No [Yes] ? n

We should add the backend instance cn=backend3,cn=ldbm database,cn=plugins,cn=config

LDBM_BACKEND_INSTANCE - Add successfull: cn=backend3,cn=ldbm database,cn=plugins,cn=config

*** INFORMATION - NetscapeRoot is NOT migrated

*** LDBM_BACKEND_INSTANCE - cn=userroot,cn=ldbm database,cn=plugins,cn=config already exists

*** Migration will overwrite existing database

Do you want to continue Yes/No [No] ?

*** Migration will not update it

-------------------------------------------------------------------------

Migrate mapping tree...

*** MAPPING_TREE - cn="dc=backend1,dc=com",cn=mapping tree,cn=config already exists
*** Migration will not add the suffix
*** MAPPING_TREE - cn="dc=backend2,dc=com",cn=mapping tree,cn=config already exists
*** Migration will not add the suffix

MAPPING_TREE - Add successfull: cn="dc=backend3,dc=com",cn=mapping tree,cn=config
*** MAPPING_TREE - cn="dc=netscape,dc=com",cn=mapping tree,cn=config already exists
*** Migration will not add the suffix

-------------------------------------------------------------------------

Migrate default indexes...

-------------------------------------------------------------------------

Migrate indexes...

-------------------------------------------------------------------------

Migrate replicas...

-------------------------------------------------------------------------

Migrate replication agreements...

-------------------------------------------------------------------------

Migrate key/cert databases...

-------------------------------------------------------------------------

Migrate Certmap.conf...

Where do you want to back up the file /export/home/jdoe/61-latest/shared/config/certmap.conf [/export/home/jdoe/61-latest/shared/config/certmap.conf_backup] ?

***** Close the LDAP connection to the new Directory Server instance *****
Shutting down server slapd-bart . . .

. . .

-------------------------------------------------------------------------

Data processing...

ldiffile: /export/home/jdoe/50-latest/slapd-bart/config//ldif/backend1.ldif
[12/Jun/2002:10:33:25 -0700] - export backend1: Processed 3 entries (100%).
[12/Jun/2002:10:33:25 -0700] - Waiting for 2 database threads to stop
[12/Jun/2002:10:33:26 -0700] - All database threads now stopped

ldiffile: /export/home/jdoe/50-latest/slapd-bart/config//ldif/backend2.ldif
[12/Jun/2002:10:33:29 -0700] - export backend2: Processed 3 entries (100%).
[12/Jun/2002:10:33:29 -0700] - Waiting for 1 database threads to stop
[12/Jun/2002:10:33:30 -0700] - All database threads now stopped

ldiffile: /export/home/jdoe/50-latest/slapd-bart/config//ldif/backend3.ldif
[12/Jun/2002:10:33:32 -0700] - export backend3: Processed 2 entries (100%)
[12/Jun/2002:10:33:32 -0700] - Waiting for 1 database threads to stop
[12/Jun/2002:10:33:33 -0700] - All database threads now stopped

Done.
[12/Jun/2002:10:33:37 -0700] - import backend1: Index buffering enabled with
bucket size 15
[12/Jun/2002:10:33:37 -0700] - import backend1: Beginning import job...
[12/Jun/2002:10:33:37 -0700] - import backend1: Processing file

"/export/home/jdoe/50-latest/slapd-bart/config//ldif/backend1.ldif"
[12/Jun/2002:10:33:37 -0700] - import backend1: Finished scanning file
"/export/home/jdoe/50-latest/slapd-bart/config//ldif/backend1.ldif" (3 entries)
[12/Jun/2002:10:33:40 -0700] - import backend1: Cleaning up producer thread...
[12/Jun/2002:10:33:40 -0700] - import backend1: Indexing complete.
Post-processing...
[12/Jun/2002:10:33:40 -0700] - import backend1: Flushing caches...
[12/Jun/2002:10:33:40 -0700] - import backend1: Closing files...
[12/Jun/2002:10:33:40 -0700] - import backend1: Import complete. Processed 3
entries in 3 seconds. (1.00 entries/sec)
[12/Jun/2002:10:33:44 -0700] - import backend2: Index buffering enabled with
bucket size 15
[12/Jun/2002:10:33:44 -0700] - import backend2: Beginning import job...
[12/Jun/2002:10:33:44 -0700] - import backend2: Processing file
"/export/home/jdoe/50-latest/slapd-bart/config//ldif/backend2.ldif"
[12/Jun/2002:10:33:44 -0700] - import backend2: Finished scanning file
"/export/home/jdoe/50-latest/slapd-bart/config//ldif/backend2.ldif" (3 entries)
[12/Jun/2002:10:33:44 -0700] - import backend2: Workers finished; cleaning up...
[12/Jun/2002:10:33:47 -0700] - import backend2: Workers cleaned up.
[12/Jun/2002:10:33:47 -0700] - import backend2: Cleaning up producer thread...
[12/Jun/2002:10:33:47 -0700] - import backend2: Indexing complete.
Post-processing...
[12/Jun/2002:10:33:47 -0700] - import backend2: Flushing caches...
[12/Jun/2002:10:33:47 -0700] - import backend2: Closing files...
[12/Jun/2002:10:33:47 -0700] - import backend2: Import complete. Processed 3
entries in 3 seconds. (1.00 entries/sec)
[12/Jun/2002:10:33:50 -0700] - import backend3: Index buffering enabled with
bucket size 15
[12/Jun/2002:10:33:50 -0700] - import backend3: Beginning import job...
[12/Jun/2002:10:33:51 -0700] - import backend3: Processing file
"/export/home/jdoe/50-latest/slapd-bart/config//ldif/backend3.ldif"
[12/Jun/2002:10:33:51 -0700] - import backend3: Finished scanning file
"/export/home/jdoe/50-latest/slapd-bart/config//ldif/backend3.ldif" (2 entries)
[12/Jun/2002:10:33:51 -0700] - import backend3: Workers finished; cleaning up...
[12/Jun/2002:10:33:54 -0700] - import backend3: Workers cleaned up.
[12/Jun/2002:10:33:54 -0700] - import backend3: Cleaning up producer thread...
[12/Jun/2002:10:33:54 -0700] - import backend3: Indexing complete.
Post-processing...
[12/Jun/2002:10:33:54 -0700] - import backend3: Flushing caches...
[12/Jun/2002:10:33:54 -0700] - import backend3: Closing files...
[12/Jun/2002:10:33:54 -0700] - import backend3: Import complete. Processed 2
entries in 4 seconds. (0.50 entries/sec)

-------------------------------------------------------------------------

Migrate Changelog...

-------------------------------------------------------------------------

***** Migrate ReplicaBindDN entries...

-------------------------------------------------------------------------

***** Migrate MultiplexorBindDN entries...

****** End of migration ******

Migrating a 4.x Replicated Site

The procedure described in this section explains the migration path that you can follow to migrate a replication topology of 4.x servers to a replication topology of 6.x Directory Servers.

You can migrate instances of Directory Server 4.x because these releases of the Directory Server can replicate to a Directory Server 6.x configured as a consumer. However, the following constraints must be observed in order to successfully complete the migration of a replicated environment:

• The replication topology of legacy servers must be a valid topology.
• The new 6.x Directory Server must be configured as a legacy consumer of the 4.x Directory Server, as explained in Chapter 8, "Managing Replication" of the Netscape Directory Server Administrator's Guide.
• The replication agreement between the 4.x supplier server and the 6.x consumer server must be a 4.x supplier-initiated replication agreement.

The following sections summarize how you can migrate a replicated environment:

• Migrating a Replicated 4.x Site - Approach 1
• Migrating a Replicated 4.x Site - Approach 2

Migrating a Replicated 4.x Site - Approach 1

Given the constraints, an approach to migrating a replication topology of 4.x servers is to:

1. Install the 6.x Directory Server and configure it both:
• As a read-write replica, the role the server will fulfill once the migration process is completed, that logs changes.
• As a legacy consumer, the role the server must play during the migration process.
2. Configure the 4.x supplier to send updates to the 6.x Directory Server.
3. Upgrade 4.x consumer servers to Directory Server 6.x, and change their supplier server to be the Directory Server 6.x that you configured in Step 1.

This Directory Server now acts as a hub supplier.
 

4. Retire the 4.x supplier.

The Directory Server 6.x that you configured in Step 1 is now the only supplier in the topology.
 

To better understand Approach 1, consider a fairly simple replication topology:

• One supplier server, ServerA.
• Two consumer servers, ServerB and ServerC.
• ServerA has a supplier-initiated replication agreement to ServerB and to ServerC.
• ServerA, ServerB, and ServerC are 4.x Directory Servers.

Note	You can migrate a topology where ServerB and ServerC have consumer initiated replication (CIR) agreements with ServerA. However, you cannot have CIR agreements in the new replication environment because Directory Server 6.x does not support consumer-initiated replication.

To migrate this topology using Approach 1, follow these steps:

1. Install Directory Server 6.x on a new server, ServerD.
2. Configure ServerD for the role it will fulfill in the migrated replication topology, that is as a read-write replica that logs changes.

This procedure is explained in Chapter 8, "Managing Replication" of the Netscape Directory Server Administrator's Guide.
 

3. Then configure ServerD to be a legacy consumer.

This procedure is explained in Chapter 8, "Managing Replication" of the Netscape Directory Server Administrator's Guide.
 

4. Migrate ServerB to Directory Server 6.x following the instructions given in "Migrating a Standalone Server".
5. Make ServerB a read-only replica of ServerD.

This means that ServerD is now a hub supplier—it receives updates from ServerA, and in turn updates ServerB.
 

6. Upgrade ServerC to Directory Server 6.x, and make it a read-only replica of ServerD.
7. Retire ServerA.
8. Disable legacy consumer settings on ServerD.

This leaves ServerD as the single supplier for consumer ServerB and ServerC.
 

When you have completed the migration of your replication topology, you can evolve it to use multi-master replication. To do this, you must add a new Directory Server 6.x that acts as a master to your replication topology. You cannot change one of the read-only replicas to become a read-write replica.

For more information on multi-master replication topologies, see Chapter 8, "Managing Replication" of the Netscape Directory Server Administrator's Guide.

Migrating a Replicated 4.x Site - Approach 2

Given the constraints, another approach to migrating a replication topology of 4.x servers is to:

1. Shut down all writes to the directory.
2. Migrate the master using the approach given in section "Migrating a Standalone Server".
3. At this point, writes may resume to the master.
4. Migrate consumers one at a time. After each migration, recreate migration agreements and re-initialize the migrated consumers.

To better understand Approach 2, consider a fairly simple replication topology:

• One supplier server, ServerA.
• Two consumer servers, ServerB and ServerC.
• ServerA has a supplier-initiated replication agreement to ServerB and to ServerC.
• ServerA, ServerB, and ServerC are 4.x Directory Servers.

Note	You can migrate a topology where ServerB and ServerC have consumer-initiated replication (CIR) agreements with ServerA. However, you cannot have CIR agreements in the new replication environment because Directory Server 6.x does not support consumer-initiated replication.

To migrate this topology using Approach 2, follow these steps:

1. Migrate Directory Server 6.x on ServerA following the instruction given in section "Migrating a Standalone Server".
2. Migrate ServerB to Directory Server 6.x following the instructions given in section "Migrating a Standalone Server".
3. Recreate migration agreement between ServerA and ServerB.
4. Re-initialize ServerB.
5. Upgrade ServerC to Directory Server 6.x, and make it a read-only replica of ServerD.
6. Recreate migration agreement between ServerA and ServerC.
7. Re-initialize ServerC.

When you have completed the migration of your replication topology, you can evolve it to use multi-master replication. To do this, you must add a new Directory Server 6.x that acts as a master to your replication topology. You cannot change one of the read-only replicas to become a read-write replica.

For more information on multi-master replication topologies, see Chapter 8, "Managing Replication" of the Netscape Directory Server Administrator's Guide.

Migrating a 5.x Replicated Site

If you are upgrading from Directory Server 5.x to Directory Server 6.x, your replication configuration is automatically migrated when you run the migrateInstance6 script.

To migrate a 5.x replicated site:

1. Stop your Directory Server 5.x.
2. Install Directory Server 6.x.
3. Run the migration script as shown in section "Migrating a Standalone Server".
4. Once your 5.x server is migrated, test replication and make sure it is working correctly.
5. After you finish this process for the master, repeat the steps for the consumers.

Migrating a 5.x Multi-Master Deployment

This section explains how to migrate a live multi master replication (MMR) architecture built using Directory Server 5.x to Directory Server 6.x in a production environment. The procedure outlined here ensures that your environment will stay live and no re-initialization will be needed.

The instructions are written with these assumptions:

• Your deployment consists of separate configuration and standard access instances of Directory Server.
• You are upgrading to Directory Server 6.2.

The migration process can be summarized into these steps:

1. Stop directory writes on both masters.

It is imperative that there are no entries being written or changed on the masters during the migration. After both the masters are migrated, writes can resume.
 

2. After stopping provisioning, make sure all changes have been replicated from the server to migrate to all of its consumers.

Any changes left over in the changelog will be lost after migration, so make sure all changes in the changelog have been replicated to all consumers.
 

3. Migrate the first master; see section "Master Migration".
4. Verify that writes and changes are being replicated through the servers.
5. Migrate the second master; see section "Master Migration".
6. Verify that writes and changes are being replicated through the servers.
7. Migrate the hubs (if any); see section "Hub Migration".
8. Verify that writes and changes are being replicated through the servers.
9. Migrate the consumers; see section "Consumer Migration".
10. Verify that writes and changes are being replicated through the servers.

Master Migration

Follow these steps for the first master and then, repeat the steps for the second:

1. Stop the 5.x Directory Server.
2. Install Directory Server 6.x.

Make this your configuration instance, as it is not replicated. For the second master, register against the first master's configuration instance.
 

3. Log into console and create a new instance that you are going to migrate to.

This instance will need to be created to listen on the port that your standard access will be to (usually 389).
 

4. Run the migration script following the instruction in "Migrating a Standalone Server".
5. Once your master is migrated, test replication and make sure that it is working correctly.
6. After you finish this process for the first master, repeat the steps for the second master.

You may wish to set up multi-master replication for o=NetscapeRoot between the instances on the masters.
 

Hub Migration

To migrate a 5.x hub:

1. Stop your Directory Server 5.x.
2. Install Directory Server 6.x, registering against the first master's configuration instance.
3. Run the migration script following the instructions in "Migrating a Standalone Server".
4. Once your hub is migrated, test replication and make sure that it is working correctly.
5. After you finish this process for the first hub, repeat the steps for any additional hubs.

Consumer Migration

To migrate a 5.x consumer server:

1. Stop the 5.x Directory Server.
2. Install Directory Server 6.x, registering against the first master's configuration instance.
3. Run the migration script; see section "Migrating a Standalone Server".
4. Once your consumer is migrated, test replication and make sure that it is working correctly.
5. After you finish this process for the first consumer, repeat the steps for any additional consumers.

Managing Console Fail Over

If you have a multi-master installation with o=NetscapeRoot replicated between your two masters, Server1 and Server2, you can modify the console on the second server (Server2) so that it uses Server2's instance instead of Server1's. (By default, writes with Server2's console would be made to Server1 then replicated over.)

To accomplish this, you must:

1. Shut down the Administration Server and Directory Server.
2. Change these files to reflect Server2's values:

serverRoot/userdb/dbswitch.conf:directory default
ldap://configHostname:configPort/o%3DNetscapeRoot

serverRoot/admin-serv/config/adm.conf:ldapHost: configHostname
serverRoot/admin-serv/config/adm.conf:ldapPort: configPort

serverRoot/shared/config/dbswitch.conf:directory default
ldap://configHostname:configPort/o%3DNetscapeRoot

serverRoot/slapd-serverID/config/dse.ldif:nsslapd-pluginarg0:
ldap://configHostname:configPort/o%3DnetscapeRoot

3. Turn off the pass through authentication (PTA) plug-in on Server2 by editing its dse.ldif file.
1. In a text editor, open this file:

serverRoot/slapd-serverID/config/dse.ldif

2. Locate the entry for the PTA plug-in:

dn: cn=Pass Through Authentication,cn=plugins,cn=config

3. Change nsslapd-pluginEnabled: on to nsslapd-pluginEnabled: off.
4. Restart the Directory Server and Administration Server.

Upgrading From Directory Server 6.x Versions

---

You can upgrade an instance of Directory Server 6.0x or 6.1x (for example, 6.0, 6.01, 6.02, 6.1, or 6.11) to Directory Server 6.2 by installing Directory Server 6.2 into the same installation directory in which your 6.0x or 6.1x Directory Server instance is installed. These sections explain the upgrade process:

• Before You Begin
• Upgrading
• After You Upgrade

Before You Begin

Before you begin the upgrade process, back up your entire 6.0x or 6.1x Directory Server. For instructions, check backing up and exporting related topics in Chapter 4, "Populating Directory Databases" of the Netscape Directory Server Administrator's Guide.

Upgrading

The steps below show how to perform an upgrade using the Typical mode of installation on UNIX:

1. On your Directory Server 6.0x or 6.1x host machine, log in as root or superuser (su).
2. Stop the server.

# serverRoot/slapd-serverID/stop-server

3. Create a new directory, for example:

# mkdir ds62
# cd ds62
 

4. Download the Directory Server product binaries file to the directory you created.
5. Unpack the product binaries file using the following command:

# gunzip -dc filename.tar.gz | tar -xvof -

where filename corresponds to the product binaries that you want to unpack.
 

6. In the list of files, locate the setup program.
7. Run the setup program by issuing the following command (from the installation directory):

./setup
 

The setup program asks if you would like to proceed with the setup.
 

8. Press Enter to respond with the default (the default for this prompt is Yes) or press n if you would like to exit the setup program.

(If you want to log in as root or superuser (use the su command), you will need to exit the setup program.)
 

9. Next, the setup program asks you if you agree to the license terms. Press y to agree with the license terms.
10. When you are asked what you would like to install, press Enter to select the default, Netscape Servers.
11. When you are asked what type of installation you would like to perform, press Enter to select the default, Typical Installation.
12. When prompted to enter the server root (or the installation directory), enter the full path to the location where your Directory Server 6.0x or 6.1x is installed.

By default, the setup program provides the following path:
 

/usr/netscape/servers
 

If your 6.0x or 6.1x Directory Server is installed in a different path, be sure to select that path. Once you supply the correct path, press Enter.
 

13. The setup program starts upgrading your server. Follow the prompts and complete the upgrade process.
14. Restart the server.

# serverRoot/slapd-serverID/stop-server

After You Upgrade

To verify that the upgrade process was successful, it is recommended that you check the upgraded server for data consistency and any custom schema.

© 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002-2003 Netscape Communications Corporation. All rights reserved.
Read the Full Copyright and Thrid-Party Acknowledgments.

Last Updated October 30, 2003