8.4. Migration Scenarios
The migration scenario differs depending on the type of existing Directory Server configuration you have. 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.
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
On Red Hat Enterprise Linux and Solaris machines, the migrate-ds-admin tool is in the /usr/sbin/ directory. On HP-UX machines, the migrate-ds-admin is in the /opt/dirsrv/sbin/ directory.
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-instancename/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.
Stop all old Directory Server instances and the Administration Server.
Back up all the Directory Server user and configuration data.
On the machine where your legacy Directory Server is installed, install the Directory Server 8.0 packages.
Do not set up the new Directory Server instances with setup-ds-admin.pl before running the migration script.
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.
The migration process starts. The legacy Directory Server is migrated, and a new Directory Server 8.0 instance is installed using the configuration information from the legacy Directory Server.
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 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 8.4.3, “Migrating a Directory Server from One Machine to Another” and Section 8.4.4, “Migrating a Directory Server from One Platform to Another”.
On Red Hat Enterprise Linux and Solaris machines, the migrate-ds-admin tool is in the /usr/sbin/ directory. On HP-UX machines, the migrate-ds-admin is in the /opt/dirsrv/sbin/ directory.
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-instancename/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.
To migrate a replicated site, do the following:
Stop all old Directory Server instances and the Administration Server.
Back up all the Directory Server user and configuration data.
Stop directory writes to the master or hub server being migrated.
On the machine where your legacy Directory Server is installed, install the Directory Server 8.0 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.
Run the migration script, as root.
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.
The migration process starts. The legacy Directory Server is migrated, and a new Directory Server 8.0 instance is installed using the configuration information from the legacy Directory Server.
Once the old Directory Server instance is migrated, test replication to make sure it is working correctly.
After you finish this process for all of the master server, repeat the steps for the hub servers and then for the replicas.
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.
If the new machine has a different architecture than the old machine, such as moving from i386 to x86_64, you must perform a cross platform migration, described in Section 8.4.4, “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 i386 to i386.
Migration cannot change the hostname used by the Directory Server and Administration 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.0, 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 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.
On Red Hat Enterprise Linux and Solaris machines, the migrate-ds-admin tool is in the /usr/sbin/ directory. On HP-UX machines, the migrate-ds-admin is in the /opt/dirsrv/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 --actualroot /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 --actualroot /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 --actualroot /opt/redhat-ds --instance example General.ConfigDirectoryAdminPwd=password
Stop all Directory Server instances and the Administration Server.
Back up all the Directory Server user and configuration data.
Install the Directory Server 8.0 packages on the new machine which will host Directory Server.
Make the old Directory Server accessible to the new machine, either through an NFS-mounted drive or tarball.
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.
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
The migration process starts. The legacy Directory Server is migrated, and a new Directory Server 8.0 instance is installed using the configuration information from the legacy Directory Server.
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 8.4.3, “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.
On Red Hat Enterprise Linux and Solaris machines, the migrate-ds-admin tool is in the /usr/sbin/ directory. On HP-UX machines, the migrate-ds-admin is in the /opt/dirsrv/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
--actualroot /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
--actualroot /opt/redhat-ds --instance example General.ConfigDirectoryAdminPwd=password
Stop all Directory Server instances and the Administration Server.
Back up all the Directory Server user and configuration data.
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
Install the Directory Server 8.0 packages on the new machine which will host Directory Server.
Make the old Directory Server accessible to the new machine, either through an NFS-mounted drive or tarball.
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.
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
The migration process starts. The legacy Directory Server is migrated, and a new Directory Server 8.0 instance is installed using the configuration information from the legacy Directory Server.