Uninstall/Upgrade Symas OpenLDAP

Uninstalling

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 Symas processes left running

    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 DB

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

For multiple DBs

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

-b allows DB to be selected by name -n# can be used to specify DB 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 DB 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 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 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

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, https://downloads.symas.com.

Example: (note there is more than one warning) 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 ’pwdMaxRe
cordedFailure’ 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 Symas processes left running

    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 DB

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

For multiple DBs

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

-b allows DB to be selected by name -n# can be used to specify DB by number Use one or the other; not both. If -b or -n # is used to specify DB 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 DB will reinitialize them.

Step 3: Custom Schemas

NOTE: Custom schemas should always be kept in a separate directory from

    /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 Certs

Step 6: Remove the database files (If DB reload is stipulated by an Upgrade Warning)

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

Step 7: Download and Install the latest Production release

Download the latest release installers from https://downloads.symas.com Installed 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 the slapd.conf or slapd.d configuration (the config should not be removed during the uninstall process, but if, for some reason, it was follow this step.

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.

Slapadd main DB and changedb files (if delta-syncrepl is used)

For single DB

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

For multiple DBs

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

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

The changedb ldif only gets imported to producer servers; not consumers

    slapdadd -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

Recommended Order

Normally upgrades can be performed to any server in any order. However, Symas recommends performing upgrades to consumer servers before producers. If any part of the process should encounter 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).