ITS#7786 Document cn=config recovery options

doc/guide/admin/slapdconf2.sdf

@@ -34,6 +34,8 @@ Note: Although the {{slapd-config}}(5) system stores its configuration
 as (text-based) LDIF files, you should {{1:never}} edit any of
 the LDIF files directly.  Configuration changes should be performed via LDAP
 operations, e.g. {{ldapadd}}(1), {{ldapdelete}}(1), or {{ldapmodify}}(1).
+For offline modifications (when the server is not running), use {{slapadd}}(8)
+and {{slapmodify}}(8).
 
 
 Note: You will need to continue to use the older {{slapd.conf}}(5)
@@ -1117,3 +1119,83 @@ if you are not using the default directory path.
 Note: When converting from the slapd.conf format to slapd.d format, any
 included files will also be integrated into the resulting configuration
 database.
+
+
+H2: Recovering from a broken configuration
+
+If the server using {{cn=config}} does not start, either because the
+configuration does not represent the current version or because it has been
+corrupted, these actions are available, in the order of decreasing preference.
+
+Make sure you have made a backup of the "broken" version before you attempt any
+of these:
+
+
+H3: Generate an ldif version of the configuration database and reload from that
+
+Most of the time, the configuration can be parsed and a text version generated
+with {{slapcat}}(8):
+
+> slapcat -F /usr/local/etc/openldap/slapd.d -n0 -l extracted_config.ldif
+
+After you have backed up and removed the old configuration database contents,
+this output ldif can be hand-edited to adjust or remove the offending entries
+and imported again:
+
+> slapadd -F /usr/local/etc/openldap/slapd.d -l updated_config.ldif
+> slaptest -F /usr/local/etc/openldap/slapd.d
+
+
+H3: Modify config in-place
+
+If the configuration can be parsed and you know exactly what you need to do,
+you can use {{slapmodify}}(8) to effect the required changes directly:
+
+> slapmodify -F /usr/local/etc/openldap/slapd.d
+> dn: ..., cn=config
+> changetype: ...
+> ...
+
+
+H3: Recover with plain back-ldif
+
+If the configuration contains items that {{slapd}}(8) cannot process as a
+{{cn=config}} database at all, the last resort is to disable schema checking
+and operate on it as a regular back-ldif database. This might cease to work
+with future versions of OpenLDAP without notice, attempt this only when all of
+the above fail.
+
+First, create a directory to serve as the hosting DB and create the structure:
+
+> mkdir ./recovery ./recovery/cn=recovery
+> cp /usr/local/etc/openldap/slapd.d/cn=config.ldif ./recovery/cn=recovery
+> cp -r /usr/local/etc/openldap/slapd.d/cn=config ./recovery/cn=recovery
+
+Or, if you have already backed up your old configration, you can symlink it
+into place:
+
+> mkdir ./recovery
+> ln -s /usr/local/etc/openldap/slapd.d ./recovery/cn=recovery
+
+Next, create a trivial {{slapd.conf}}(5) to access the new database:
+
+> database ldif
+> suffix cn=recovery
+> directory ./recovery/
+
+Note the change of suffix, {{EX:cn=config}} is hardcoded to correspond to an
+active config database, so we have to home it one level deeper - at
+{{EX:cn=config,cn=recovery}}.
+
+Now you can use {{slapmodify}}(8) to modify the database, it is most likely you
+will need to run with schema checking disabled:
+
+> slapmodify -f ./recovery.conf -s
+
+You can test the validity of your config with {{slaptest}}(8):
+
+> slaptest -F ./recovery/cn=recovery
+
+And generate a full ldif with {{slapcat}}(8):
+
+> slapcat -F ./recovery/cn=recovery -n0