Date: 01-17-2022

Updated: 07-08-2024

Recommended Order for Upgrades

Normally, upgrades can be performed on any server in any order. However, Symas recommends performing upgrades to consumer servers before producer servers. If any part of the process encounters a problem, it is easier to restore a consumer server than a producer. Additionally, this will minimize downtime as the only time modifications to the database will be unavailable is while the producer is being upgraded. All other read operations will continue to function normally. To eliminate all downtime, modifications can be referred to a load balancer configured to direct them toward a second master (Multi-Master Replication).

Uninstalling Symas OpenLDAP

Step 1: Stop Solserver

Stop the ‘slapd’ service and kill any running processes:

sudo /opt/symas/etc/solserver stop
sudo /opt/symas/etc/krbserver stop

Find the Process ID (PID) for any remaining Symas processes:

pgrep slapd

Stop any PIDs found:

sudo kill <PID>

Step 2: Backup the database

NOTE: If using slapd.d, replace -f /opt/symas/etc/openldap/slapd.conf with -F /opt/symas/etc/openldap/slapd.d/ in the following commands.

For a single database:

/opt/symas/bin/slapcat -f /opt/symas/etc/openldap/slapd.conf -l /tmp/mydb_export.ldif

For multiple databases:

/opt/symas/bin/slapcat -f /opt/symas/etc/openldap/slapd.conf -b <suffix> -l /tmp/mydb_<suffix>_export.ldif

-b allows the database to be selected by name. -n# can be used to specify the database by number. Use one or the other, not both.

If using delta-syncrepl, backup the accesslog database:

/opt/symas/bin/slapcat -f /opt/symas/etc/openldap/slapd.conf -b cn=accesslog -l changedb.ldif

NOTE: If accesslog database files are deleted (instead of backed up), running a write operation (ldapadd or ldapmodify) against the database will reinitialize them.

Step 3: Custom Schemas

Make a secure copy of any custom schema directory.

Step 4: Slapd.conf

Make a secure copy of the ‘slapd.conf’ file in a location outside of the ‘/opt/symas/’ directory:

cp /opt/symas/etc/openldap/slapd.conf /tmp/slapd.conf 

NOTE: If using slapd.d or cn=config, copying slapd.conf will not capture the current configuration. Instead, export the slapd.d config to an LDIF in a location outside of the /opt/symas/ directory:

slapcat -F /opt/symas/etc/openldap/slapd.d -n0 -l /tmp/config_backup_01.ldif

NOTE: Use the -n0 option to tell slapcat to read the cn=config database.

Step 5: SSL Keys and Certs

Make a secure copy of the cacert.pem (in the /opt/symas/ssl/ directory), slapdcert.pem, and slapdkey.pem (in the /opt/symas/etc/openldap/ directory) files in a location outside of the /opt/symas/ directory.

Step 6: Uninstall Symas OpenLDAP

Use the commands for your operating system from the section below.

NOTE: Uninstalling will leave the /var/symas/ and /opt/symas/ folders with some content in them. If permanently uninstalling Symas OpenLDAP, delete these directories as well.

Uninstall Commands

• RedHat and CentOS

sudo yum erase symas-openldap-gold-client
sudo yum erase symas-openldap-gold
sudo yum erase symas-openldap-gold-devel

• Debian and Ubuntu

sudo dpkg --purge symas-openldap-gold-client 
sudo dpkg --purge symas-openldap-gold
sudo dpkg --purge symas-openldap-gold-devel

• SUSE

sudo zypper rm -y symas-openldap-gold-client
sudo zypper rm -y symas-openldap-gold
sudo zypper rm -y symas-openldap-gold-devel 

• Solaris

sudo pkgrm symas-openldap-gold-client
sudo pkgrm symas-openldap-gold
sudo pkgrm symas-openldap-gold-auxlibs
sudo pkgrm symas-openldap-gold-devel

• FreeBSD

pkg delete -y symas-openldap-gold-client.amd64
pkg delete -y symas-openldap-gold.amd64
pkg delete -y symas-openldap-gold.amd64_nonopt 
pkg delete -y symas-openldap-gold-devel.amd64

Upgrading Symas OpenLDAP

Philosophy

The philosophy behind the packaging for Symas OpenLDAP is never to overwrite active configuration files or data during installation and removal. If you are removing Symas OpenLDAP for purposes of upgrading to a newer release, simply use your system's native commands to remove the current version and install the new one. Conversely, if you are permanently removing Symas OpenLDAP, you may also want to delete the configuration files and databases that were created in the course of using the software.

It is tempting to customize standard schema files "in place". Note that Symas OpenLDAP will remove schema files it installed, so make provisions to preserve any modified schema files prior to removing the software.

Important: Check for Database Format Changes

Upgrade Warning(s)

When upgrading or downgrading Symas OpenLDAP, it is extremely important to check the release notes of the version to be installed. If the binary format of the backend database has changed, a reload of your database is required. These changes in database format are always announced in the release notes. The release notes are located in the /opt/symas/etc directory, and online in the Symas Download Portal.

Example: Upgrade warning:

This release has the potential to change the on-disk format for LMDB/MDB databases for versions prior to 2.4.44.5.

If you are setting or changing the back-mdb values multival_hi and multival_lo, it will be necessary to back up any affected databases using slapcat before making the change and restoring them with slapadd after making the change.

If you are not setting these values, then a database reload is not needed.

Please contact support for additional assistance. Back-BDB/HDB databases are unaffected.

This release has the potential to change the schema requirements for slapo-ppolicy for customers using the cn=config backend if it was configured prior to the SOLD 2.4.43.1 release.

If upgrading from a release prior to 2.4.43.1 and slapo-ppolicy is in use via cn=config, then it will be necessary to modify the schema for ppolicy prior to upgrading.

Specifically, the following attribute definition must be added:

olcAttributeTypes: {16}( 1.3.6.1.4.1.42.2.27.8.1.30 NAME 'pwdMaxRecordedFailure' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE )

Please contact support for additional assistance.

Process

Step 1: Stop Solserver

Stop the slapd service and kill any running processes:

sudo /opt/symas/etc/solserver stop
sudo /opt/symas/etc/krbserver stop

Find the Process ID (PID) for any remaining Symas processes:

pgrep slapd

Stop any PIDs found

sudo kill <PID>

Step 2: Backup the Database (If DB reload is stipulated by an Upgrade Warning)

NOTE: If using slapd.d, replace -f /opt/symas/etc/openldap/slapd.conf with -F /opt/symas/etc/openldap/slapd.d/ in the following commands.

For a single database:

/opt/symas/bin/slapcat -f /opt/symas/etc/openldap/slapd.conf -l /tmp/mydb_export.ldif

For multiple databases:

/opt/symas/bin/slapcat -f /opt/symas/etc/openldap/slapd.conf -b <suffix> -l /tmp/mydb_<suffix>_export.ldif

-b allows the database to be selected by name. -n# can be used to specify the database by number. Use one or the other, not both. If -b or -n# is used to specify the database in slapcat, it must also be used in slapadd.

If using delta-syncrepl, backup the accesslog database.

/opt/symas/bin/slapcat -f /opt/symas/etc/openldap/slapd.conf -b cn=accesslog -l changedb.ldif

NOTE: If accesslog database files are deleted (instead of backed up), running a write operation (ldapadd or ldapmodify) against the database will reinitialize them.

Step 3: Custom Schemas

NOTE: Custom schemas should always be kept in a separate directory from /opt/symas/etc/openldap/schema/.

/opt/symas/etc/openldap/schema/.

Copy the custom schemas directory to a location outside of the /opt/symas/ directory.

Step 4: Slapd.conf/Slapd.d

Make a secure copy of the slapd.conf file in a location outside of the /opt/symas/ directory.

cp /opt/symas/etc/openldap/slapd.conf /tmp/slapd.conf 

NOTE: If using slapd.d or cn=config, copying slapd.conf will not capture the current configuration. Instead, export the slapd.d config as an LDIF to a location outside of the /opt/symas/ directory.

slapcat -F /opt/symas/etc/openldap/slapd.d -n0 -l /tmp/config_backup_01.ldif

NOTE: Use the -n0 option to tell slapcat to read the cn=config database.

Step 5: SSL Keys and Certificates

Make a secure copy of the cacert.pem (in the /opt/symas/ssl/ directory), slapdcert.pem, and slapdkey.pem (in the /opt/symas/etc/openldap/ directory) files to a location outside of the /opt/symas/ directory.

Step 6: Remove Database Files (If DB reload is stipulated by an Upgrade Warning)

If a database reload is stipulated by an upgrade warning, remove the database files:

sudo rm -rf /var/symas/openldap-data/<database>/*.mdb 

Step 7: Download and Install the Latest Production Release

Download the latest release installers from Symas Download Portal and install the latest release.

See Prerequisites → Basic Install → Install/Uninstall Commands for your Operating System's specific command.

Download and install the Development Kit add-ons if necessary

See Prerequisites → Basic Install → Install/Uninstall Commands for your Operating System's specific command.

Step 8 (Optional): Restore Slapd.conf or Slapd.d Configuration

If the configuration was removed during the uninstall process (which it typically shouldn't be), follow this step to restore it.

NOTE: If using slapd.d, you may need to (re)create the /opt/symas/etc/openldap/slapd.d directory. Import the slapd.d config from the config_backup_01.ldif to the /opt/symas/etc/openldap/slapd.d directory.

slapadd -F /opt/symas/etc/openldap/slapd.d -n0 -l /tmp/config_backup_01.ldif

NOTE: Use the -n0 option to tell slapcat to create the cn=config database

Step 9: Restore the Database(s) (If DB Reload is Stipulated by an Upgrade Warning)

NOTE: If using slapd.d, replace -f /opt/symas/etc/openldap/slapd.conf with -F /opt/symas/etc/openldap/slapd.d/ in the following commands.

Restore the main database and changedb files (if delta-syncrepl is used).

For a single database:

slapadd -q -f /opt/symas/etc/openldap/slapd.conf -l /tmp/mydb_export.ldif

For multiple databases:

slapadd -q -f /opt/symas/etc/openldap/slapd.conf -b <suffix> -l /tmp/mydb_<suffix>_export.ldif

-b allows the database to be selected by name. -n# can be used to specify the database by number. If -n# was used in slapcat to specify a database, it must also be included in the slapadd command.

The changedb LDIF only gets imported to producer servers, not consumers:

slapadd -f /opt/symas/etc/openldap/slapd.conf -b cn=accesslog -l /tmp/changedb.ldif

Step 10: Run a slaptest

slaptest -f /opt/symas/etc/openldap/slapd.conf 

Resolve any reported errors.

Step 11: Start the solserver service

sudo /opt/symas/etc/solserver start