5.3. Upgrading 8.1 Servers

For Directory Server 8.1 servers, it is possible to perform an in-place upgrade. This is significantly simpler than a migration. An in-place upgrade updates the Red Hat Directory Server packages on the system, and then the setup script is used to update the server configuration.

IMPORTANT

If there are any duplicate entries (based on duplicate DNs), then the upgrade process makes a copy of the database. It is possible, in an extreme case, that the upgraded database could be twice the size of the original database, until the duplicate antries are resolved. As a precaution, make sure there is enough disk space available for the upgrade, meaning that there is twice the current database size available.

If there is not enough disk space available, the upgrade process files with the error message Failed to back up backend instance 'instance_name'.

5.3.1. Upgrading a Server

An in-place upgrade means that the packages for the Red Hat Directory Server are simply updated. No other migration process is necessary. In-place upgrade is supported for Directory Server 8.1.

IMPORTANT

If there is not enough disk space available, the upgrade process files with the error message Failed to back up backend instance 'instance_name'.

Back up all the Directory Server user and configuration data. For example:

 cd /usr/lib/dirsrv/slapd-instance_name  
 
 db2bak /var/lib/dirsrv/slapd-instance_name/bak/instance_name-2010_04_30_16_27_56

Get the repo name by running yum check-update. For example:

 yum check-update
 Loaded plugins: rhnplugin, security
 rhel-x86_64-server-5-rhdirserv-8

Install or upgrade the Directory Server 8.2 packages. For example:
```
yum update -y
```
This automatically updates the Red Hat Directory Server packages as well as any other required packages.
Red Hat Directory Server 8.2 requires that all of the packages in the Red Hat Directory Server channel be updated. Running simply yum update updates all Red Hat Directory Server and Red Hat Enterprise Linux packages. To exclude packages from updating on your system, you can use --exclude packages, restrict the update to only the Red Hat Directory Server channel, or explicitly list the packages to update. Run man yum for a list of options. For example:
```
yum update -y --disablerepo=* --enablerepo=rhel-x86_64-server-5-rhdirserv-8
```
Re-run the setup-ds-admin.pl script, using the -u to update the configuration. Make sure that the Directory Server and Admin Server are running when the script is run.
```
setup-ds-admin.pl -u
```
Go through the setup process again to re-register the updated Directory Server. The upgraded server has the same configuration as the 8.1 server. It is also possible to pass information with the setup-ds-admin.pl script, as in Section 4.5, “Silent Setup”
The setup-ds-admin.pl script updates the Directory Server core packages and configuration and the Directory Server and Admin Server consoles.
Verify that the packages have been properly updated by checking the version number on one of the Directory Server packages. For example:
```
rpm -qf /usr/sbin/setup-ds-admin.pl 
redhat-ds-admin-8.2.0-0.el5dsrv
```

Verify that the directory databases have been successfully migrated. Directory Server 8.2 normalizes DN syntax during the upgrade process from 8.1. Make sure that the upgraded database is functional and contains all the data before deleting the backups.

Check the errors log to see if any databases had upgraded DNs. Any databases which required upgrades would have already been updated as the setup script ran; checking the error logs simply highlights what data to verify.

# grep "Upgrade Dn.*complete" /var/log/dirsrv/slapd-instance_name/errors
[...] - upgradedn abcRoot: Upgrade Dn Dryrun complete.  abcRoot needs upgradednformat.
[...] - upgradedn abcRoot: Upgrade Dn complete.  Processed 2 entries in 1 seconds. (2.00 entries/sec)
[...] - upgradedn userRoot: Upgrade Dn Dryrun complete.  Processed 0 entries in 3 seconds. (0.00 entries/sec)
[...] - upgradedn userRoot: Upgrade Dn Dryrun complete.  userRoot is up-to-date.

During upgrade, the original database is written to db.orig, and an updated database is written in its place. Check the upgraded database directories and DBVERSION files against the original files. For example:

ls -R /var/lib/dirsrv/slapd-instance_name/db
db:
abcRoot  abcRoot.orig  DBVERSION  guardian  log.0000000001  userRoot

db/abcRoot:
aci.db4         DBVERSION     nsuniqueid.db4       parentid.db4
ancestorid.db4  entrydn.db4   numsubordinates.db4  seeAlso.db4
cn.db4          id2entry.db4  objectclass.db4      sn.db4

db/abcRoot.orig:
aci.db4         DBVERSION    id2entry.db4         objectclass.db4  sn.db4
ancestorid.db4  dnupgrade    nsuniqueid.db4       parentid.db4
cn.db4          entrydn.db4  numsubordinates.db4  seeAlso.db4

db/abcRoot.orig/dnupgrade:
DBVERSION  guardian

db/userRoot:
aci.db4         entrydn.db4    nsuniqueid.db4       sn.db4
ancestorid.db4  givenName.db4  numsubordinates.db4  telephoneNumber.db4
cn.db4          id2entry.db4   objectclass.db4      uid.db4
DBVERSION       mail.db4       parentid.db4

# find . -name DBVERSION | xargs head
==> ./db/abcRoot/DBVERSION <==
bdb/4.7/libback-ldbm/dn-4514  

==> ./db/DBVERSION <==
bdb/4.7/libback-ldbm

==> ./db/abcRoot.orig/DBVERSION <==
bdb/4.7/libback-ldbm  

==> ./db/abcRoot.orig/dnupgrade/DBVERSION <==
bdb/4.7/libback-ldbm  
bdb/4.7/libback-ldbm

=> ./db/userRoot/DBVERSION <==
bdb/4.7/libback-ldbm/dn-4514

Search an entry which could contain escaped characters; the DNs should be updated. For example, for a DN which was previously cn="a=abc,x=xyz":
```
/usr/lib64/mozldap/ldapsearch -b "dc=example,dc=com" '(cn=\"*\")' entrydn
dn: cn=a\3Dabc\2Cx\3Dxyz,dc=example,dc=com
entrydn: cn=a\3dabc\2cx\3dxyz,dc=example,dc=com
```
If the search results are correctly escaped, the original database backend instance directory can be removed.

Restart the Directory Server.
```
service dirsrv restart
```
NOTE
Manually restarting the server should only be required for Red Hat Enterprise Linux 4 systems. Other systems should restart automatically.
NOTE
The setup-ds-admin.pl script updates both the Directory Server instances and the local Admin Server instance. However, the Admin Server console shows the old version number, like 8.1.4, even though it has been successfully upgraded. Restart the Admin Server to refresh the version number.
Restart the Directory Server Console to make sure that the version and build numbers are appropriately updated.

Check the error logs to see if there are any duplicate entries in the database.

Directory Server 8.1 allowed entries with identical DNs, but slightly different DN formats, to be added to the directory. For example:

dn: cn="uid=jsmith,ou=Dev0,o=Engineering0",ou=People,dc=example,dc=com
uid: jsmith
givenName: test
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetorgperson
sn: smith
cn: uid=jsmith,ou=Dev0,o=Engineering0
userPassword: secret

dn: cn=uid\=jsmith\,ou\=Dev0\,o\=Engineering0,ou=People,dc=example,dc=com
uid: jsmith
givenName: test
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetorgperson
sn: smith
cn: uid=jsmith,ou=Dev0,o=Engineering0
userPassword: secret

When these duplicate entries are migrated and their DNs are upgraded to the new, stricter DN format, the duplicate is given a slightly differnet DN that incorporates its unique ID. After the server upgrade, these duplicate entires can be preserved (which takes up additional space) or they can be purged.

Open the error log for the instance.

vim /var/log/dirsrv/slapd-instance_name/error

Look for error messages related to duplicate entries. These messages will have the term Duplicated entrydn or Duplicated entry in them. For example:

[..] - upgradedn userRoot: Duplicated entrydn detected: "cn=uid\3djsmith1\2cou\3ddev0\2co\3dengineering0,ou=people,dc=example,dc=com": Entry ID: (10, 11)
[..] - upgradedn userRoot: WARNING: Duplicated entry cn=uid\=jsmith1\,ou\=Dev0\,o\=Engineering0,ou=People,dc=example,dc=com is renamed to cn=uid\3Djsmith1\2Cou\3DDev0\2Co\3DEngineering0+nsuniqueid=ae8c95af-8fac11df-80000000-00000000,ou=People,dc=example,dc=com; Entry ID: 11

Decide which duplicated entry to keep. One entry will have the standard DN. The other has an RDN in the format cn=cn+nsuniqueid.

Delete the duplicate entries. Each specific duplicate entry must be deleted manually. For example:

/usr/lib64/mozldap/ldapdelete -D 'cn=directory manager' -w secret

dn: cn=uid\3djsmith1\2cou\3ddev0\2co\3dengineering0,ou=people,dc=example,dc=com

If the entry which was kept has the renamed RDN format (cn=cn+nsuniqueid), then rename the entry to the original DN. For example:

/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389

dn: cn=uid\3Djsmith1\2Cou\3DDev0\2Co\3DEngineering0+nsuniqueid=ae8c95af-8fac11df-80000000-00000000,ou=People,dc=example,dc=com
changetype: modrdn
newrdn: cn=uid\3djsmith1\2cou\3ddev0\2co\3dengineering0
deleteoldrdn: 0

NOTE

The deleteoldrdn value must be 0 since the nsuniqueid operational attribute cannot be deleted.

5.3.2. Upgrading Servers in Replication

The process for upgrading servers in replication 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 upgrade all supplier servers, then all hubs, and then all consumers.

Always stop directory writes to the master or hub server before beginning the upgrade process.
After upgrading all of the supplier servers, then upgrade all of the hubs and, last, all of the consumer replicas.
Then, after the Directory Server instances is upgraded, test replication to make sure it is working correctly.
A supplier, hub, or consumer can be migrated to a different or platform as described in Section 5.3.3, “Migrating an 8.1 Directory Server to 8.2 on Another Machine”.

5.3.3. Migrating an 8.1 Directory Server to 8.2 on Another Machine

To upgrade Directory Server and move the instance from one machine to another, the 8.1 information must be imported into the new instance manually. This is true for both moving to another machine and moving to a new platform.

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. 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. Red Hat strongly recommends that you do not attempt to change the Directory Server hostname.

Back up all the Directory Server user and configuration data. For example:

 cd /usr/lib/dirsrv/slapd-instance_name  
 
 db2bak /var/lib/dirsrv/slapd-instance_name/bak/instance_name-2010_04_30_16_27_56

Export all of the database information to LDIF. The LDIF file must be named the name of the database with .ldif appended. For example:
```
db2ldif -r -n userRoot -a /var/lib/dirsrv/slapd-instance_name/db/userRoot.ldif

db2ldif -r -n NetscapeRoot -a /var/lib/dirsrv/slapd-instance_name/db/NetscapeRoot.ldif
```
NOTE
Use the -r option if the server is used in replication.
On the new machine which will host Directory Server, install or upgrade the Directory Server 8.2 packages. For example:
```
yum install -y
```
This automatically updates the Red Hat Directory Server packages as well as any other required packages.
Red Hat Directory Server 8.2 requires that all of the packages in the Red Hat Directory Server channel be updated. Running simply yum update updates all Red Hat Directory Server and Red Hat Enterprise Linux packages. To exclude packages from updating on your system, you can use --exclude packages, restrict the update to only the Red Hat Directory Server channel, or explicitly list the packages to update. Run man yum for a list of options. For example:
```
yum install -y --disablerepo=* --enablerepo=rhel-x86_64-server-5-rhdirserv-8
```
Copy the LDIF files from the old machine to the new machine.

Import the LDIF files into the new Directory Server 8.2 databases.

ldif2db -n userRoot -i /path/to/userRoot.ldif

ldif2db -n NetscapeRoot -i /path/to/NetscapeRoot.ldif

Verify that the directory databases have been successfully migrated. Directory Server 8.2 normalizes DN syntax during the upgrade import process from 8.1. Make sure that the upgraded database is functional and contains all the data before deleting the backups.
Search an entry which could contain escaped characters; the DNs should be updated. For example, for a DN which was previously cn="a=abc,x=xyz":
```
/usr/lib64/mozldap/ldapsearch -b "dc=example,dc=com" '(cn=\"*\")' entrydn
dn: cn=a\3Dabc\2Cx\3Dxyz,dc=example,dc=com
entrydn: cn=a\3dabc\2cx\3dxyz,dc=example,dc=com
```
If the search results are correctly escaped, the original database backend instance directory can be removed.

5.3.4. Upgrading Directory Server on Solaris

The upgrade process on Solaris is slightly different than on Red Hat Enterprise Linux because of the differences in Solaris and Red Hat Enterprise Linux package management tools. To upgrade the server on Solaris:

Download the product binaries (from Red Hat Network or media) to the Directory Server installation directory.

Unzip the package.

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

Stop the Directory Server and Admin Server.

/etc/init.d/dirsrv stop
/etc/init.d/dirsrv-admin stop/

Back up the old console.conf file.

 cd /etc/dirsrv/admin-serv ; cp -fp@ console.conf console.conf.save

Remove the old packages.
```
pkgrm -n DS_packages
```

Install the new packages.

pkgadd -d /path/to/DS_packages.sparcv9.pkg

Restore the console.conf file.

cd /etc/dirsrv/admin-serv ; cp -fp@ console.conf console.conf.new cp -fp@console.conf.save  console.conf.new

Run setup-ds.pl with the -u option. This updates the DN formats in any migrated databases to be compliant with RFC 4514.
```
setup-ds.pl -u
```

Restart the Directory Server and Admin Server.

/etc/init.d/dirsrv start
/etc/init.d/dirsrv-admin stop

Run setup-ds-admin.pl with the -u option to complete the upgrade process.
```
setup-ds-admin.pl -u
```