5.2. Migrating 7.1 Servers

Red Hat Directory Server 7.1 servers are migrated to a new Directory Server 8.2 instance. This uses a special script which carries over the user and configuration data to the new instance.
The migration scenario differs depending on the type of Directory Server 7.1 configuration. It is possible to migrate a single Directory Server instance, all Directory Server instances on a machine or replicated servers and to migrate the Directory Server to a different machine, or to a different platform. The migration script has different options available to facilitate migration; the different usage scenarios are explained in the following sections.

IMPORTANT

Before beginning to migrate a Red Hat Directory Server instance, first perform all of the preparatory steps in Section 5.2.2, “Before Migration”.

WARNING

If Directory Server databases have been moved from their default location (/opt/redhat-ds/slapd-instancename/db), migration will not copy these databases, but will use the directly. This means that if you run migration, you may not be able to go back to the old version. Migration will not remove or destroy the data, but may change the format in such a way that you cannot use the older version of the Directory Server. Therefore, make a database backup using db2bak and an LDIF dump using db2ldif of the databases to make sure everything can be recovered.
The most common reason for using a non-default database location is the performance for large databases. For example, if a Directory Server instance has several gigabytes of data, the index files and transaction logs can be moved to a separate disk device to improve the Directory Server performance, especially if there are high update rates. In this case, migration will not attempt to move the databases to the new default location, /var/lib/dirsrv/slapd-instance_name/db, but will instead assume that the databases should be in their non-standard location and configure the new server to use the databases in the old location.
This issue does not occur in cross-platform migrations or migrating using LDIF files instead of the binary databases because these already work with an LDIF copy of the database.

5.2.1. About migrate-ds-admin.pl

The migration script, migrate-ds-admin.pl, has flexible options that allow a variety of different migration scenarios, including migrating between different different platforms. This options are listed in Table 5.1, “migrate-ds-admin Options”.
There is one required option with the migration script, oldsroot, which gives the directory path to the old Directory Server. There is also one required argument, General.ConfigDirectoryAdminPwd, which gives the password of the directory administrator for the old Directory Server. If either of these are not supplied, the migration script will exit. 
/usr/sbin/migrate-ds-admin.pl --oldsroot /opt/redhat-ds General.ConfigDirectoryAdminPwd=password

NOTE

On Red Hat Enterprise Linux 5 (64-bit) machines, the migrate-ds-admin tool is in the /usr/sbin directory.

Table 5.1. migrate-ds-admin Options

Option Alternate Options Description
General.ConfigDirectoryAdminPwd=password Required. This is the password for the configuration directory administrator of the old Directory Server (the default username is admin).
--oldsroot -o Required. This is the path to the server root directory in the old 7.1 Directory Server installation. The default path in 7.1 servers is /opt/redhat-ds/.
--actualsroot -a This is used for migrating between two machines to specify the real path to the current server root directory in the old 7.1 Directory Server installation if that directory is mounted on a networked drive or tarballed and moved to a relative directory. In that case, the oldsroot parameter sets the directory from which the migration is run (such as machine_new:/migrate/opt/redhat-ds/), while the actualsroot parameter sets the server root, (/opt/redhat-ds/).
--instance -i This parameter specifies a specific instance to migrate. This parameter can be used multiple time to migrate several instances simultaneously. By default, the migration script migrates all Directory Server instances on the machine.
--file=name -f name This sets the path and name of the .inf file provided with the migration script. The only parameter is the General.ConfigDirectoryAdminPwd parameter, which is the configuration directory administrator's password. Any other configuration setting is ignored by the migration script.
--cross -c or -x This parameter is used when the Directory Server is being migrated from one machine to another with a different architecture. For cross-platform migrations, only certain data are migrated. This migration action takes database information exported to LDIF and imports into the new 8.2 databases. Changelog information is not migrated. If a supplier or hub is migrated, then all its replicas must be reinitialized.
--debug -d[dddd] This parameter turns on debugging information. For the -d flag, increasing the number of d's increases the debug level.
--logfile name -l
This parameter specifies a log file to which to write the output. If this is not set, then the migration information is written to a temporary file, named /tmp/migrateXXXXX.log.
To disable logging, set /dev/null as the logfile.

migrate-ds-admin.pl allows the password parameter to be provided on the command line, similar to the setup-ds-admin.pl script. The arguments set the section, parameter, and value of .inf parameters in the following form: 
section.parameter=value
The only required argument is the Configuration Directory Server administrator password (ConfigDirectoryAdminPwd): 
/usr/sbin/migrate-ds-admin.pl --oldsroot /opt/redhat-ds General.ConfigDirectoryAdminPwd=password
To avoid having this password in the clear on the command line, you can use a .inf file with the migration script that gives the administrator's password: 
/usr/sbin/migrate-ds-admin.pl --oldsroot /opt/redhat-ds --file=/export/example.inf
The .inf would have the following two lines: 
 [General]
 ConfigDirectoryAdminPwd=password
The migration script takes all of the other settings from the old configuration files in the old server root, specified in --oldsroot. Any other argument passed in the command line or listed in an inf file, such as those used with the setup-ds-admin/pl script, is ignored. The Directory Server configuration parameters are only taken from the old instance. It is not possible to change the configuration settings, such as the hostname or port, using the migration script.

5.2.2. Before Migration

For the safety of the Directory Server data, do these things before beginning to migrate the Directory Server instances:
  • Shut down all Directory Server instances and the Admin Server.
  • Back up all of your databases.
  • For servers which have a different configuration directory, make sure that the Directory Server Console write operations are moved from the configuration directory to the server itself.
  • Remove deprecated schema files, such as 10presence.ldif, from the schema/ directory for the old instance.

5.2.2.1. Backing up the Directory Server Configuration

All of the configuration files for Directory Server 7.1 instances are in the /opt/redhat-ds/slapd-serverID/config directory. Other important configuration files for the Admin Server and for shared configuration are in /opt/redhat-ds/admin-serv/config and /opt/redhat-ds/shared/config. Make a backup of all of these files in a secure location.

5.2.2.2. Configuring the Directory Server Console

If you have a multi-master replication setup which replicates o=NetscapeRoot replicated between the two master servers, server1 and server2. By default, writes made through server2's Directory Server Console are written to server1, then replicated over. Modify the Directory Server Console on the second server (server2) so that it writes its own Console instance instead of server1's.
  1. Shut down the Admin Server and Directory Server.
  2. Change the adm.conf file for the Admin Server to reflect server2 Directory Servers values: 
    ldapurl: ldap://server2.example.com:389/o=NetscapeRoot
  3. Change the dse.ldif for the Directory Server to reflect server2 Directory Server's values: 
    vim serverRoot/slapd-serverID/config/dse.ldif
 nsslapd-pluginarg0: ldap:///server2.example.com:389/o=NetscapeRoot
  4. Turn off the Pass-through Authentication Plug-in on server2 by editing its dse.ldif file and setting the nsslapd-pluginEnabled value to off. 
    vim serverRoot/slapd-serverID/config/dse.ldif

dn: cn=Pass Through Authentication,cn=plugins,cn=config
nsslapd-pluginEnabled: off  
  5. Restart the Directory Server and Admin Server.

5.2.2.3. Removing Deprecated Schema Files

The migration script may not properly remove all schema files that were deprecated between Red Hat Directory Server 7.1 and Red Hat Directory Server 8.2. To ensure that migration completes successfully, remove all of the deprecated schema files from the serverRoot/slapd-serverID/config/schema/ directory. This can be done by comparing the list of schema files in the old schema directory to the list in the new /etc/dirsrv/schema directory. Deprecated schema files include:
  • 10presence.ldif
  • 05rfc2247.ldif

5.2.3. Migrating a Server or Single Instance

To migrate a Directory Server installation to a new one on the same machine, run the migration script, specifying the old server root directory: 
/usr/sbin/migrate-ds-admin.pl --oldsroot /opt/redhat-ds General.ConfigDirectoryAdminPwd=password
That command automatically migrates every Directory Server instance configured. To migrate specific instances, use the instance with the migrate-ds-admin tool. For example, to migrate the Directory Server instance named example and example3, but not example2, the migration command would be as follows: 
/usr/sbin/migrate-ds-admin.pl --oldsroot /opt/redhat-ds --instance example --instance example3 General.ConfigDirectoryAdminPwd=password

NOTE

On Red Hat Enterprise Linux 5 (64-bit) machines, the migrate-ds-admin tool is in the /usr/sbin directory.

IMPORTANT

Before beginning to migrate a Red Hat Directory Server instance, first perform all of the preparatory steps in Section 5.2.2, “Before Migration”.
  1. Stop all old Directory Server instances and the Admin Server.
  2. Back up all the Directory Server user and configuration data.
  3. On the machine where your legacy Directory Server is installed, install the Directory Server 8.2 packages.

    IMPORTANT

    Do not set up the new Directory Server instances with setup-ds-admin.pl before running the migration script.
  4. Run the migration script, as root. 
    # /usr/sbin/migrate-ds-admin.pl --oldsroot /opt/redhat-ds/ General.ConfigDirectoryAdminPwd=password
    /opt/redhat-ds/ is the directory where the old Directory Server is installed.
  5. The migration process starts. The legacy Directory Server is migrated, and a new Directory Server 8.2 instance is installed using the configuration information from the legacy Directory Server.
  6. After the migration process ends, then the Windows Synchronization service has to be manually resynchronized.
    1. Reboot the Windows machine.
    2. In the Directory Server Console, open the Configuration tab.
    3. Expand the Replication folder, and select the database.
    4. Right-click the synchronization agreement, and select Initialize Full Re-synchronization from the drop down menu.
  7. Verify the Directory Server settings.

    IMPORTANT

    Always verify the Directory Server configuration after migrating from 7.1 to 8.2. Some configuration settings, like passwordMinLength for a global password policy, are not migrated.
    Review all policy settings in the new 8.2 instance and make any changes before putting the system into production.
  8. Check for any migrated entries with duplicate DNs.
    Migrated instances may encounter entries which had duplicate entry DNs with slightly different DN formats. If any entries have duplicate DNs, then it will be recorded in the error logs: 
    [...] - import userRoot: WARNING: Skipping duplicate entry "cn=uid\3Dtuser1\2Cou\3DOU0\2Co\3DO0,ou=People,dc=example,dc=com" found at line 35 of file "/opt/redhat-ds/slapd-ID/db/example.ldif"
    Examine any duplicate entry messages to see if the resulting entry is acceptable. The import utility used during migration picks up the first entry and skips any subsequent duplicated entries. If necessary, edit the original LDIF file, and delete the unwanted entries. Run remove-ds-admin.pl to remove the newly-migrated server, and run the migration script again.

5.2.4. Migrating Replicated Servers

The process for migrating a replicated system is the same as for a single server, but the order in which the Directory Server instances is important to keep from interrupting replication. First migrate all master servers, then all hubs, and then all consumers. If any Directory Server the in replicated system will be moved to a different machine or a different platform, use the --actualsroot and --cross parameters with migrate-ds-admin.pl, as described in Section 5.2.5, “Migrating a Directory Server from One Machine to Another” and Section 5.2.6, “Migrating a Directory Server from One Platform to Another”.

NOTE

On Red Hat Enterprise Linux 5 (64-bit) machines, the migrate-ds-admin tool is in the /usr/sbin directory.
To migrate a replicated site:
  1. Stop all old Directory Server instances and the Admin Server.
  2. Back up all the Directory Server user and configuration data.
  3. Stop directory writes to the master or hub server being migrated.
  4. On the machine where your legacy Directory Server is installed, install the Directory Server 8.2 packages.
    • Make the first migrated master the configuration instance since it is not replicated. Then, register other master and hub servers with the first master Directory Servers configuration instance.
    • This instance needs to listen on your standard port, usually 389.
  5. Run the migration script, as root.

    IMPORTANT

    Do not set up the new Directory Server instances with setup-ds-admin.pl before running the migration script. 
    # /usr/sbin/migrate-ds-admin.pl --oldsroot /opt/redhat-ds/ General.ConfigDirectoryAdminPwd=password
    /opt/redhat-ds/ is the directory where the old Directory Server is installed.
  6. The migration process starts. The legacy Directory Server is migrated, and a new Directory Server 8.2 instance is installed using the configuration information from the legacy Directory Server.
  7. Once the old Directory Server instance is migrated, test replication to make sure it is working correctly.
  8. After you finish this process for all of the master server, repeat the steps for the hub servers and then for the replicas.
  9. After the migration process ends, then the Windows Synchronization service has to be manually resynchronized.
    1. Reboot the Windows machine.
    2. In the Directory Server Console, open the Configuration tab.
    3. Expand the Replication folder, and select the database.
    4. Right-click the synchronization agreement, and select Initialize Full Re-synchronization from the drop down menu.

IMPORTANT

Always verify the Directory Server configuration after migrating from 7.1 to 8.2. Some configuration settings, like passwordMinLength for a global password policy, are not migrated.
Review all policy settings in the new 8.2 instance and make any changes before putting the system into production.

5.2.5. Migrating a Directory Server from One Machine to Another

To migrate a Directory Server installation from one machine to a new Directory Server instance on a new machine of the same platform, run the migration script (migrate-ds-admin) with options specifying the physical, network-accessible old server root directory (oldsroot), such as tarball or network drive, and specifying the actual directory name of the server root on the old machine (actualsroot), such as /opt/redhat-ds. In this case, actualsroot names the original absolute installation directory, which oldsroot gives the path to access that directory.

NOTE

If the new machine has a different architecture than the old machine, such as moving from x86 to x86_64, you must perform a cross platform migration, described in Section 5.2.6, “Migrating a Directory Server from One Platform to Another”. The procedure in this section assumes that the Directory Server is being migrated from one machine to another of the same architecture, such as x86 to x86.

WARNING

Migration cannot change the hostname used by the Directory Server and Admin Server. The old machine must have the same hostname as your new machine. If you are going to commission a new machine on which to run Directory Server 8.2, first rename the old machine (for example, change ldap.example.com to ldap_old.example.com), then give the new machine the original name of the old machine (ldap.example.com). Because of the large number of configuration issues based on the Directory Server's hostname — including the Console, replication, TLS/SSL, and Kerberos — it is extremely difficult to rename the server with the migration script. Red Hat strongly recommends that you do not attempt to change the Directory Server hostname.

NOTE

On Red Hat Enterprise Linux 5 (64-bit) machines, the migrate-ds-admin tool is in the /usr/sbin directory.
For example, this script migrates a Directory Server on server1 to server2, using an NFS-mounted directory: 
# /usr/sbin/migrate-ds-admin.pl --oldsroot server2:/migration/opt/redhat-ds --actualsroot /opt/redhat-ds General.ConfigDirectoryAdminPwd=password
The oldsroot can also specify a local directory on the target machine that was created from a tarball. In that case, create a tarball of your old server root directory, and untar it on the target machine. In this example, a tarball was created of /opt/redhat-ds on the source machine, and it was untarred under /migration on the target machine: 
# /usr/sbin/migrate-ds-admin.pl --oldsroot /migration/opt/redhat-ds --actualsroot /opt/redhat-ds General.ConfigDirectoryAdminPwd=password
The migrate-ds-admin command automatically migrates every Directory Server instance configured. As with migrating Directory Server on the same machine, using the instance parameter allows you to set the specific instance to migrate. For example, this command migrated a Directory Server instance named example: 
# /usr/sbin/migrate-ds-admin.pl --oldsroot server2:/migration/opt/redhat-ds --actualsroot /opt/redhat-ds --instance example General.ConfigDirectoryAdminPwd=password
  1. Stop all Directory Server instances and the Admin Server.
  2. Back up all the Directory Server user and configuration data.
  3. Install the Directory Server 8.2 packages on the new machine which will host Directory Server.
  4. Make the old Directory Server accessible to the new machine, either through an NFS-mounted drive or tarball.
  5. Run the migration script as root. Specify the current physical location of the Directory Server with the oldsroot parameter and the location on the old machine with the actualsroot parameter.

    IMPORTANT

    Do not set up the new Directory Server instances with setup-ds-admin.pl before running the migration script.
    For example: 
    # /usr/sbin/migrate-ds-admin.pl --oldsroot server2:/migration/opt/redhat-ds --actualsroot /opt/redhat-ds General.ConfigDirectoryAdminPwd=password
  6. The migration process starts. The legacy Directory Server is migrated, and a new Directory Server 8.2 instance is installed using the configuration information from the legacy Directory Server.
  7. After the migration process ends, then the Windows Synchronization service has to be manually resynchronized.
    1. Reboot the Windows machine.
    2. In the Directory Server Console, open the Configuration tab.
    3. Expand the Replication folder, and select the database.
    4. Right-click the synchronization agreement, and select Initialize Full Re-synchronization from the drop down menu.
  8. Verify the Directory Server settings.

    IMPORTANT

    Always verify the Directory Server configuration after migrating from 7.1 to 8.2. Some configuration settings, like passwordMinLength for a global password policy, are not migrated.
    Review all policy settings in the new 8.2 instance and make any changes before putting the system into production.

5.2.6. Migrating a Directory Server from One Platform to Another

To migrate a Directory Server installation from one platform to another is similar to migrating from one machine to another. The difference between a migration between platforms and other migration scenarios is the information migrated from the old Directory Server. The databases are in an architecture-dependent binary format and can be migrated only after they are exported to LDIF. Other data, such as the changelog, is not migrated. As explained in Section 5.2.5, “Migrating a Directory Server from One Machine to Another”, the migration script uses the actualsroot and oldsroot parameters to migrate across machines and the cross parameter to signal that the migration is cross-platform.

NOTE

On Red Hat Enterprise Linux 5 (64-bit) machines, the migrate-ds-admin tool is in the /usr/sbin directory.
The command format to move from one platform to another is similar to the following: 
# /usr/sbin/migrate-ds-admin.pl --cross --oldsroot server2:/migration/opt/redhat-ds --actualsroot /opt/redhat-ds General.ConfigDirectoryAdminPwd=password
The migrate-ds-admin command automatically migrates every Directory Server instance configured. As with migrating Directory Server on the same machine, using the instance parameter allows you to set the specific instance to migrate. For example, this command migrated a Directory Server instance named example: 
/usr/sbin/migrate-ds-admin.pl --oldsroot server2:/migration/opt/redhat-ds --actualsroot /opt/redhat-ds --instance example General.ConfigDirectoryAdminPwd=password
  1. Stop all Directory Server instances and the Admin Server.
  2. Back up all the Directory Server user and configuration data.
  3. Export all of the database information to LDIF. The LDIF file must be named the name of the database with .ldif appended. For example: 
     cd /opt/redhat-ds/slapd-instance    

 ./db2ldif -n userRoot -a /opt/redhat-ds/slapd-instance/db/userRoot.ldif
 ./db2ldif -n NetscapeRoot -a /opt/redhat-ds/slapd-instance/db/NetscapeRoot.ldif
  4. Make sure all of the LDIF files are readable by the setup script. 
    chmod 444 /opt/redhat-ds/slapd-instance/db/userRoot.ldif
chmod 444 /opt/redhat-ds/slapd-instance/db/NetscapeRoot.ldif
  5. Install the Directory Server 8.2 packages on the new machine which will host Directory Server.
  6. Make the old Directory Server accessible to the new machine, either through an NFS-mounted drive or tarball.
  7. Run the migration script as root. Specify the current physical location of the Directory Server with the oldsroot parameter and the location on the old machine with the actualsroot parameter.

    IMPORTANT

    Do not set up the new Directory Server instances with setup-ds-admin.pl before running the migration script.
    For example: 
    /usr/sbin/migrate-ds-admin.pl --cross --oldsroot server2:/migration/opt/redhat-ds --actualsroot /opt/redhat-ds General.ConfigDirectoryAdminPwd=password
  8. The migration process starts. The legacy Directory Server is migrated, and a new Directory Server 8.2 instance is installed using the configuration information from the legacy Directory Server.
  9. After the migration process ends, then the Windows Synchronization service has to be manually resynchronized.
    1. Reboot the Windows machine.
    2. In the Directory Server Console, open the Configuration tab.
    3. Expand the Replication folder, and select the database.
    4. Right-click the synchronization agreement, and select Initialize Full Re-synchronization from the drop down menu.
  10. Verify the Directory Server settings.

    IMPORTANT

    Always verify the Directory Server configuration after migrating from 7.1 to 8.2. Some configuration settings, like passwordMinLength for a global password policy, are not migrated.
    Review all policy settings in the new 8.2 instance and make any changes before putting the system into production.