1# OpenLDAP: pkg/openldap-guide/admin/maintenance.sdf,v 1.7.2.10 2010/04/13 20:22:34 kurt Exp 2# Copyright 2007-2010 The OpenLDAP Foundation, All Rights Reserved. 3# COPYING RESTRICTIONS APPLY, see COPYRIGHT. 4 5H1: Maintenance 6 7System Administration is all about maintenance, so it is only fair that we 8discuss how to correctly maintain an OpenLDAP deployment. 9 10 11H2: Directory Backups 12 13Backup strategies largely depend on the amount of change in the database 14and how much of that change an administrator might be willing to lose in a 15catastrophic failure. There are two basic methods that can be used: 16 171. Backup the Berkeley database itself and periodically back up the transaction 18log files: 19 20Berkeley DB produces transaction logs that can be used to reconstruct 21changes from a given point in time. For example, if an administrator were willing to only 22lose one hour's worth of changes, they could take down the server in 23the middle of the night, copy the Berkeley database files offsite, and bring 24the server back online. Then, on an hourly basis, they could force a 25database checkpoint, capture the log files that have been generated in the 26past hour, and copy them offsite. The accumulated log files, in combination 27with the previous database backup, could be used with db_recover to 28reconstruct the database up to the time the last collection of log files was 29copied offsite. This method affords good protection, with minimal space 30overhead. 31 32 332. Periodically run slapcat and back up the LDIF file: 34 35Slapcat can be run while slapd is active. However, one runs the risk of an 36inconsistent database- not from the point of slapd, but from the point of 37the applications using LDAP. For example, if a provisioning application 38performed tasks that consisted of several LDAP operations, and the slapcat 39took place concurrently with those operations, then there might be 40inconsistencies in the LDAP database from the point of view of that 41provisioning application and applications that depended on it. One must, 42therefore, be convinced something like that won't happen. One way to do that 43would be to put the database in read-only mode while performing the 44slapcat. The other disadvantage of this approach is that the generated LDIF 45files can be rather large and the accumulation of the day's backups could 46add up to a substantial amount of space. 47 48You can use {{slapcat}}(8) to generate an LDIF file for each of your {{slapd}}(8) 49back-bdb or back-hdb databases. 50 51> slapcat -f slapd.conf -b "dc=example,dc=com" 52 53For back-bdb and back-hdb, this command may be ran while slapd(8) is running. 54 55MORE on actual Berkeley DB backups later covering db_recover etc. 56 57H2: Berkeley DB Logs 58 59Berkeley DB log files grow, and the administrator has to deal with it. The 60procedure is known as log file archival or log file rotation. 61 62Note: The actual log file rotation is handled by the Berkeley DB engine. 63 64Logs of current transactions need to be stored into files so that the database 65can be recovered in the event of an application crash. Administrators can change 66the size limit of a single log file (by default 10MB), and have old log files 67removed automatically, by setting up DB environment (see below). The reason 68Berkeley DB never deletes any log files by default is that the administrator 69may wish to backup the log files before removal to make database recovery 70possible even after a catastrophic failure, such as file system corruption. 71 72Log file names are {{F:log.XXXXXXXXXX}} (X is a digit). By default the log files 73are located in the BDB backend directory. The {{F:db_archive}} tool knows what 74log files are used in current transactions, and what are not. Administrators can 75move unused log files to a backup media, and delete them. To have them removed 76automatically, place set_flags {{DB_LOG_AUTOREMOVE}} directive in {{F:DB_CONFIG}}. 77 78Note: If the log files are removed automatically, recovery after a catastrophic 79failure is likely to be impossible. 80 81The files with names {{F:__db.001}}, {{F:__db.002}}, etc are just shared memory 82regions (or whatever). These ARE NOT 'logs', they must be left alone. Don't be 83afraid of them, they do not grow like logs do. 84 85To understand the {{F:db_archive}} interface, the reader should refer to 86chapter 9 of the Berkeley DB guide. In particular, the following chapters are 87recommended: 88 89* Database and log file archival - {{URL:http://www.oracle.com/technology/documentation/berkeley-db/db/ref/transapp/archival.html}} 90* Log file removal - {{URL:http://www.oracle.com/technology/documentation/berkeley-db/db/ref/transapp/logfile.html}} 91* Recovery procedures - {{URL:http://www.oracle.com/technology/documentation/berkeley-db/db/ref/transapp/recovery.html}} 92* Hot failover - {{URL:http://www.oracle.com/technology/documentation/berkeley-db/db/ref/transapp/hotfail.html}} 93* Complete list of Berkeley DB flags - {{URL:http://www.oracle.com/technology/documentation/berkeley-db/db/api_c/env_set_flags.html}} 94 95Advanced installations can use special environment settings to fine-tune some 96Berkeley DB options (change the log file limit, etc). This can be done by using 97the {{F:DB_CONFIG}} file. This magic file can be created in BDB backend directory 98set up by {{slapd.conf}}(5). More information on this file can be found in File 99naming chapter. Specific directives can be found in C Interface, look for 100{{DB_ENV->set_XXXX}} calls. 101 102Note: options set in {{F:DB_CONFIG}} file override options set by OpenLDAP. 103Use them with extreme caution. Do not use them unless You know what You are doing. 104 105The advantages of {{F:DB_CONFIG}} usage can be the following: 106 107* to keep data files and log files on different mediums (i.e. disks) to improve 108 performance and/or reliability; 109* to fine-tune some specific options (such as shared memory region sizes); 110* to set the log file limit (please read Log file limits before doing this). 111 112To figure out the best-practice BDB backup scenario, the reader is highly 113recommended to read the whole Chapter 9: Berkeley DB Transactional Data Store Applications. 114This chapter is a set of small pages with examples in C language. Non-programming 115people can skip these examples without loss of knowledge. 116 117 118H2: Checkpointing 119 120MORE/TIDY 121 122If you put "checkpoint 1024 5" in slapd.conf (to checkpoint after 1024kb or 5 minutes, 123for example), this does not checkpoint every 5 minutes as you may think. 124The explanation from Howard is: 125 126'In OpenLDAP 2.1 and 2.2 the checkpoint directive acts as follows - *when there 127is a write operation*, and more than <check> minutes have occurred since the 128last checkpoint, perform the checkpoint. If more than <check> minutes pass after 129a write without any other write operations occurring, no checkpoint is performed, 130so it's possible to lose the last write that occurred.'' 131 132In other words, a write operation occurring less than "check" minutes after the 133last checkpoint will not be checkpointed until the next write occurs after "check" 134minutes have passed since the checkpoint. 135 136This has been modified in 2.3 to indeed checkpoint every so often; in the meantime 137a workaround is to invoke "db_checkpoint" from a cron script every so often, say 5 minutes. 138 139H2: Migration 140 141The simplest steps needed to migrate between versions or upgrade, depending on your deployment 142type are: 143 144.{{S: }} 145^{{B: Stop the current server when convenient}} 146 147.{{S: }} 148+{{B: slapcat the current data out}} 149 150.{{S: }} 151+{{B: Clear out the current data directory (/usr/local/var/openldap-data/) leaving DB_CONFIG in place}} 152 153.{{S: }} 154+{{B: Perform the software upgrades}} 155 156.{{S: }} 157+{{B: slapadd the exported data back into the directory}} 158 159.{{S: }} 160+{{B: Start the server}} 161 162Obviously this doesn't cater for any complicated deployments like {{SECT: MirrorMode}} or {{SECT: N-Way Multi-Master}}, 163but following the above sections and using either commercial support or community support should help. Also check the 164{{SECT: Troubleshooting}} section. 165 166 167