1 files changed, 74 insertions, 0 deletions
diff --git a/doc/guide/admin/appendix-upgrading.sdf b/doc/guide/admin/appendix-upgrading.sdf
new file mode 100644
index 0000000..d39d69a
--- /dev/null
+++ b/doc/guide/admin/appendix-upgrading.sdf
@@ -0,0 +1,74 @@
+# $OpenLDAP$
+# Copyright 2007-2022 The OpenLDAP Foundation, All Rights Reserved.
+# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
+
+H1: Upgrading from 2.4.x
+
+The following sections attempt to document the steps you will need to take in order 
+to upgrade from the latest 2.4.x OpenLDAP version.
+
+The normal upgrade procedure, as discussed in the {{SECT:Maintenance}} section, should 
+of course still be followed prior to doing any of this.
+
+H2: {{B:cn=config}} olc* attributes
+
+The {{olcMirrorMode}} attribute has been renamed to {{olcMultiProvider}}.  Existing configurations
+will continue to work with the old parameter name, but it is advised to update to the new name as a
+part of the upgrade process.
+
+H2: ppolicy overlay
+
+The overlay now implements version 10 of the ppolicy draft in full. This includes the notion of a password
+administrator where applicable (as determined by having a {{manage}} permission to the {{userPassword}} attribute)
+and skips certain processing when there is no valid policy in effect or where the operation is initiated by
+a password administrator. Many attributes are now tagged with {{NO-USER-MODIFICATION}} in the schema, requiring
+the use of {{relax}} control to modify them.
+
+In OpenLDAP 2.4 the {{slapo-ppolicy}}(5) overlay relied on a separate schema file to be included for it to function.
+This schema is now implemented internally in the slapo-ppolicy module. When upgrading {{slapd.conf}}(5) deployments
+the include statement for the schema must be removed.  For {{slapd-config}}(5) deployments, the config database
+must be exported via slapcat and the old ppolicy schema removed from the export.  The resulting config database
+can then be imported.
+
+H2: unique overlay
+
+In OpenLDAP 2.4 it was possible to bypass {{slapo-unique}}(5) checks by using the manageDSAIT control as a part of the
+request. This is no longer possible. To achieve the same functionality the relax control must be used instead, and the
+binding identity must have manage permissions on the entry being modified.
+
+With OpenLDAP 2.5 a new keyword "serialize" has been added as a part of the unique_uri configuration parameter. This
+will cause all write operations requiring uniqueness to be serialized so as to avoid the scenario where multiple
+concurrent updates can prevent uniqueness from being enforced. See the {{slapo-unique}}(5) man page for further details.
+
+H2: ldap and meta backends
+
+Several deprecated configuration directives for {{slapd-ldap}}(5) and {{slapd-meta}}(5) have been removed. Configurations
+using those directive must be updated to use supported directives prior to upgrade.  See the {{slapd-ldap}}(5) and
+{{slapd-meta}}(5) man pages from OpenLDAP 2.4 for a list of deprecated directives.
+
+H2: shell backend
+
+This deprecated backend has been removed from OpenLDAP 2.5. Configurations making use of this backend must remove it
+prior to upgrade. The {{slapd-sock}}(5) backend is recommended as an alternative.
+
+H2: perl and sql backends
+
+The {{slapd-perl}}(5) and {{slapd-sql}}(5) backends are now deprecated and no longer automatically enabled with
+the --enable-backends configure flag.
+
+H2: hdb and bdb backends
+
+The Berkeley DB based slapd-bdb and slapd-hdb backends have been removed from OpenLDAP 2.5. Deployments making use
+of these backends must migrate their configurations to use {{slapd-mdb}}(5) prior to upgrade.
+
+H2: mdb backend
+
+It is advised to determine if the new {{slapd-mdb}}(5) idlexp backend directive and/or
+the multival database directive should be added to the OpenLDAP 2.5 configuration as well as the existing global
+sortvals directive. Configuring any of these items requires that existing databases be reloaded for them to take full
+effect. This can be done separately from the overall upgrade from OpenLDAP 2.4 to OpenLDAP 2.5 if desired.
+
+H2: Client utility changes
+
+The deprecated "-h" (host) and "-p" (port) options for the ldap client utilities have been removed. It is required to
+use a properly formatted LDAP URI with the "-H" option in OpenLDAP 2.5 and later.