51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! CCPL HEADER START
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! This work is licensed under the Creative Commons
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! To view a copy of this license, visit
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! or send a letter to Creative Commons, 444 Castro Street,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Suite 900, Mountain View, California, 94041, USA.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! You can also obtain a copy of the license at
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! See the License for the specific language governing permissions
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! and limitations under the License.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! If applicable, add the following below this CCPL HEADER, with the fields
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! enclosed by brackets "[]" replaced with your own identifying information:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Portions Copyright [yyyy] [name of copyright owner]
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! CCPL HEADER END
57d6342a74476c0bf2200992e778229d62ab1fa6mark ! Copyright 2011-2015 ForgeRock AS.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ lets you backup and restore your data either in compressed,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark binary format, or in LDAP Data Interchange Format. This chapter shows you how
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to backup and to restore OpenDJ data from archives, and explains portability
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark of backup archives, as well as backing up server configuration
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark information.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>A <filename>bak/</filename> directory is provided when you install
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark OpenDJ, as a location to save binary backups. When you create a backup,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the <filename>bak/backup.info</filename> contains information about the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark archive.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Archives produced by the <command>backup</command> command contain
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark backups only of the directory data. Backups of server configuration are
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark found in <filename>config/archived-configs/</filename>.</para>
04b5143b280e4c9c0831a2cb0049a7716f849ebcmark This section includes the following procedures:
04b5143b280e4c9c0831a2cb0049a7716f849ebcmark <itemizedlist>
04b5143b280e4c9c0831a2cb0049a7716f849ebcmark <listitem>
04b5143b280e4c9c0831a2cb0049a7716f849ebcmark </listitem>
04b5143b280e4c9c0831a2cb0049a7716f849ebcmark <listitem>
04b5143b280e4c9c0831a2cb0049a7716f849ebcmark </listitem>
04b5143b280e4c9c0831a2cb0049a7716f849ebcmark <listitem>
04b5143b280e4c9c0831a2cb0049a7716f849ebcmark </listitem>
04b5143b280e4c9c0831a2cb0049a7716f849ebcmark </itemizedlist>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To perform online backup, you start backup as a task by connecting to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the administrative port and authenticating as a user with the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>backend-backup</literal> privilege, and also setting a start time
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark for the task by using the <option>--start</option> option.</para>
ec40cc0dc62425cea5d63fd9d984f8614479de25mark To perform offline backup when OpenDJ is stopped,
ec40cc0dc62425cea5d63fd9d984f8614479de25mark you run the
ec40cc0dc62425cea5d63fd9d984f8614479de25mark without connecting to the server, authenticating, or requesting a backup task.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <stepalternatives>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Back up only the database for Example.com, where the data
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark is stored in the backend named <literal>userRoot</literal>.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example requests an online backup task that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark starts immediately, backing up only the <literal>userRoot</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark backend.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>backup \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --backendID userRoot \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --start 0</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Backup task 20110613143715983 scheduled to start Jun 13, 2011 2:37:15 PM CEST</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Stop the server to back up Example.com data offline.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example stops OpenDJ, runs offline backup, and
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark starts the server after backup has completed.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Stopping Server...
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[13/Jun/2011:14:31:00 +0200] category=BACKEND severity=NOTICE msgID=9896306
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark msg=The backend userRoot is now taken offline
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[13/Jun/2011:14:31:00 +0200] category=CORE severity=NOTICE msgID=458955
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark msg=The Directory Server is now stopped
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[13/Jun/2011:14:33:48 +0200] category=TOOLS severity=NOTICE msgID=10944792
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark msg=Starting backup for backend userRoot
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[13/Jun/2011:14:33:48 +0200] category=JEB severity=NOTICE msgID=8847446
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark msg=Archived: 00000000.jdb
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[13/Jun/2011:14:33:48 +0200] category=TOOLS severity=NOTICE msgID=10944795
08248b5c5b494aff8d1922e8e0b5777796d7450dmark msg=The backup process completed successfully</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>... The Directory Server has started successfully</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example requests an online backup task that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark starts immediately, backing up all backends.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>backup \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --backUpAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --start 0</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Backup task 20110613143801866 scheduled to start Jun 13, 2011 2:38:01 PM CEST</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </stepalternatives>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can schedule online data backup using <command>crontab</command>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark format.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Back up all user data every night at 2 AM, and notify
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark diradmin@example.com when finished, or on error.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>backup \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --backUpAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --recurringTask "00 02 * * *" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --completionNotify diradmin@example.com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --errorNotify diradmin@example.com</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Recurring Backup task BackupTask-988d6adf-4d65-44bf-8546-6ea74a2480b0
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkscheduled successfully</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
04b5143b280e4c9c0831a2cb0049a7716f849ebcmark You can schedule an incremental backup
04b5143b280e4c9c0831a2cb0049a7716f849ebcmark If you do not set the <option>--incrementalBaseID</option> option,
04b5143b280e4c9c0831a2cb0049a7716f849ebcmark then OpenDJ increments based on the last backup taken.
04b5143b280e4c9c0831a2cb0049a7716f849ebcmark Back up <literal>userRoot</literal> backend data incrementally
04b5143b280e4c9c0831a2cb0049a7716f849ebcmark every night at 3 AM,
04b5143b280e4c9c0831a2cb0049a7716f849ebcmark and notify diradmin@example.com when finished, or on error.
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>backup \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --backendID userRoot \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --incremental \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --recurringTask "00 03 * * *" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --completionNotify diradmin@example.com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --errorNotify diradmin@example.com</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Recurring Backup task BackupTask-6988c19d-9afc-4f50-89b7-d3e167255d3e
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkscheduled successfully</computeroutput>
04b5143b280e4c9c0831a2cb0049a7716f849ebcmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When you restore data, the procedure to follow depends on whether
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the OpenDJ directory server is replicated.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>To restore OpenDJ when the server is online, you start a restore task
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark by connecting to the administrative port and authenticating as a user with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the <literal>backend-restore</literal> privilege, and also setting a start
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark time for the task by using the <option>--start</option> option.</para>
ec40cc0dc62425cea5d63fd9d984f8614479de25mark To restore data when OpenDJ is stopped, you run the
ec40cc0dc62425cea5d63fd9d984f8614479de25mark without connecting to the server, authenticating, or requesting a restore task.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <stepalternatives>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Stop the server to restore data for Example.com.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example stops OpenDJ, restores data offline from
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark one of the available backups, and then starts the server after the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark restore is complete.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Stopping Server...
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[13/Jun/2011:15:44:06 +0200] category=BACKEND severity=NOTICE msgID=9896306
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark msg=The backend userRoot is now taken offline
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[13/Jun/2011:15:44:06 +0200] category=CORE severity=NOTICE msgID=458955
08248b5c5b494aff8d1922e8e0b5777796d7450dmark msg=The Directory Server is now stopped</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>restore --backupDirectory /path/to/opendj/bak --listBackups</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Backup ID: 20110613080032
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkIs Incremental: false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkIs Compressed: false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkIs Encrypted: false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkHas Unsigned Hash: false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkHas Signed Hash: false
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkDependent Upon: none</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>restore --backupDirectory /path/to/opendj/bak --backupID 20110613080032</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>[13/Jun/2011:15:47:41 +0200] category=JEB severity=NOTICE msgID=8847445
08248b5c5b494aff8d1922e8e0b5777796d7450dmark msg=Restored: 00000000.jdb (size 341835)</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>... The Directory Server has started successfully</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Schedule the restore as a task to begin immediately.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example requests an online restore task, scheduled
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to start immediately.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>restore \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --backupID 20110613080032 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --start 0</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Restore task 20110613155052932 scheduled to start Jun 13, 2011 3:50:52 PM CEST</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </stepalternatives>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>After you restore a replica from backup, replication brings the replica
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark up to date with changes that happened after you created the backup. In order
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to bring the replica up to date, replication must apply changes that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark happened after the backup was made. Replication uses internal change log
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark records to determine what changes to apply.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Internal change log records are not kept forever, though. Replication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark is configured to purge the change log of old changes, preventing the log
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark from growing indefinitely. Yet, for replication to determine what changes
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to apply to a restored replica, it must find change log records dating back
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark at least to the last change in the backup. In other words, replication can
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark bring the restored replica up to date <emphasis>as long as the change log
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark records used to determine which changes to apply have not been
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Therefore, when you restore a replicated server from backup, make sure
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the backup you use is newer than the last purge of the replication change
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark log (default: 3 days). If all your backups are older than the replication
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark purge delay, do not restore from a backup, but instead initialize a new
08248b5c5b494aff8d1922e8e0b5777796d7450dmark replica as described in <link
08248b5c5b494aff8d1922e8e0b5777796d7450dmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Initializing
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Restore the server database from the backup archive that you are
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark sure is newer than the last purge of the replication change log.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Stopping Server...
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[13/Jun/2011:15:44:06 +0200] category=BACKEND severity=NOTICE msgID=9896306
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark msg=The backend userRoot is now taken offline
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[13/Jun/2011:15:44:06 +0200] category=CORE severity=NOTICE msgID=458955
08248b5c5b494aff8d1922e8e0b5777796d7450dmark msg=The Directory Server is now stopped</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>restore --backupDirectory /path/to/opendj/bak --listBackups</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Backup ID: 20110613080032
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkIs Incremental: false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkIs Compressed: false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkIs Encrypted: false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkHas Unsigned Hash: false
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkHas Signed Hash: false
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkDependent Upon: none</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>restore --backupDirectory /path/to/opendj/bak --backupID 20110613080032</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>[13/Jun/2011:15:47:41 +0200] category=JEB severity=NOTICE msgID=8847445
08248b5c5b494aff8d1922e8e0b5777796d7450dmark msg=Restored: 00000000.jdb (size 341835)</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>... The Directory Server has started successfully</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </procedure>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>