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