<?xml version="1.0" encoding="UTF-8"?>
<book>
    <bookinfo>
        <graphic fileref="logo.jpg"/>
        <productname>Open Source Native XML Database</productname>
        <title>eXist - Database Backup / Restore</title>
        <author>
            <firstname>Wolfgang M.</firstname>
            <surname>Meier</surname>
        </author>
    </bookinfo>

    <ci:include xmlns:ci="http://apache.org/cocoon/include/1.0" src="sidebar.xml"/>

    <chapter>
        <title>Database Backup and Restore</title>

        <section>
            <title>Overview</title>
            <para>This section discusses eXist's database backup/restore procedures. Users can use
                either the Java Admin Client or available Unix shell and Windows/DOS batch scripts
                to both backup their entire database onto files, and to restore it from a backup.
                Backups are strongly recommended for data protection in the event you experience a
                system crash or loss of data. Backups are also very useful for exporting data in
                order to re-import all or parts of the data to a different database, e.g. while
                upgrading eXist to a newer version. </para>
            <para>During backup, eXist exports the contents of its database (as standard XML files)
                to a hierarchy of directories on the hard drive. This hierarchy is organized
                according to the organization of collections in the database.</para>
            <para>Other files stored during backup include index configuration files and user
                settings. As well, resource and collection metadata is exported to a special XML
                file, called <filename>__contents__.xml</filename>, which lists information
                including the resource type, owner, modification date and/or the permissions
                assigned to a resource. You will find one <filename>__contents__.xml</filename> file
                in each directory created by the backup.</para>
            <para>Since eXist uses an open XML format rather than a proprietary format for its
                database files, users can manually modify files in the backup directories without
                requiring special software. Any changes made to these files are reflected in the
                database with a restore or once the data is imported to another database system.</para>
            <para>It is even possible to directly edit user data and permissions stored in the file
                    <filename>/db/system/users.xml</filename>. This is particularly useful when
                making global changes to the user database. For example, to reset the passwords for
                all your users, you can simply edit the file <filename>users.xml</filename> by
                removing the <option>password</option> attribute, or set it to a default value and
                restore the document.</para>
            <note>
                <para> When migrating to a new eXist version, take care to use a version of the
                    client corresponding to your server version. Usually, the backup process is
                    backwards compatible. However, using a newer client version to create the backup
                    from a server running an older version may sometimes lead to unexpected
                    problems.</para>
            </note>
        </section>
        <section>
            <title>Backing Up the Database</title>
            <para>You can backup your database either by using the Admin Client menu, or the backup
                command line utility.</para>
            <para>If you are using the Admin Client, do the following:</para>
            <procedure>
                <step>
                    <para>Select either the Backup Icon (arrow pointed upward) in the toolbar OR
                            <guimenuitem>Tools &#187; Backup</guimenuitem> from the menu.</para>
                </step>
                <step>
                    <para>From the <guimenuitem>Collection</guimenuitem> drop-down menu, select the
                        collection to backup. To backup the entire database, select
                        <filename>/db</filename>. Otherwise, select the topmost collection that
                        should be stored. Note, however, that user data and permissions will only be
                        exported if you backup the entire database.</para>
                    <screenshot><graphic fileref="resources/backup1.png"/></screenshot>
                </step>
                <step>
                    <para>In the <command>Backup-Directory</command> field, enter the full directory
                        path to the where you want the backup database files to be stored.</para>
                </step>
                <step>
                    <para>Click <command>OK</command>.</para>
                </step>
            </procedure>

            <para>If you are using the command-line utility for the backup/restore, do the
                following:</para>
            <para>To launch the utility, do ONE of the following:</para>
            <itemizedlist>
                <listitem>
                    <para>start either the <filename>bin/backup.sh</filename> (Unix), OR the
                            <filename>bin/backup.bat</filename> (Windows/DOS) script file</para>
                </listitem>
                <listitem>
                    <para>OR enter on the command-line:</para>
                    <synopsis>java -jar start.jar backup 
                                                            -u <emphasis>[admin_username]</emphasis> 
                                                            -p <emphasis>[admin_password]</emphasis> 
                                                            -b <emphasis>[collection_path]</emphasis> 
                                                            -d <emphasis>[target_path]</emphasis>
                                                            -o uri=<emphasis>[xml_uri]</emphasis></synopsis>
                    <para>To view the all of the available options for this command, use the
                            <parameter>-h</parameter> parameter.</para>
                </listitem>
            </itemizedlist>

            <para>Use the <parameter>-b</parameter> parameter to indicate the <emphasis>collection
                    path</emphasis>, and the <parameter>-d</parameter> parameter to indicate the
                    <emphasis>target directory</emphasis> on your system. You can also specify the
                current admin username using the <parameter>-u</parameter> parameter, and the admin
                password using the <parameter>-p</parameter> parameter. For example, to backup the
                entire database on a Unix system to the target directory
                    <filename>/var/backup/hd060501</filename>, you would enter the following:</para>
            <synopsis>bin/backup.sh -u admin -p admin-pass -b /db -d /var/backup/hd060501</synopsis>
            <para>By default, the utility connects to the database at the URI:
                    <filename>xmldb:exist://localhost:8080/exist/xmlrpc</filename>. If you want to
                backup a database at a different location, specify its <command>XML:DB URI</command>
                (excluding any collection path) using the <parameter>-o</parameter> parameter. For
                example, the following backup on a Unix system specifies the database URI
                    <filename>xmldb:exist://192.168.1.2:8080/exist/xmlrpc</filename></para>
            <synopsis>bin/backup.sh -u admin -p admin-pass -b /db -d /var/backup/hd060501
                                                    -o uri=xmldb:exist://192.168.1.2:8080/exist/xmlrpc</synopsis>

            <note>
                <para>Default settings for the user, password or server URIs can also be set via the
                        <filename>backup.properties</filename> file.</para>
            </note>
        </section>

        <section>
            <title>Restoring the Database</title>
            <para>To restore the database files from a backup, you can again use either the Admin
                Client, or the backup command line utility.</para>
            <para>If you are using the Admin Client, do the following:</para>
            <procedure>
                <step>
                    <para>Select either the Restore Icon (arrow pointed downward) in the toolbar OR
                            <guimenuitem>Tools &#187; Restore</guimenuitem> from the
                    menu.</para>
                </step>
                <step>
                    <para>The dialog box shown below will then prompt you to select the backup file
                            <filename>__contents__.xml</filename> from the topmost directory you
                        want restored. To restore the entire database, select the
                            <filename>__contents__.xml</filename> from the <filename>db/</filename>
                        directory.</para>
                    <screenshot><graphic fileref="resources/backup2.png"/></screenshot>
                </step>
                <step>
                    <para>A second dialog box will then prompt you for an admin password to use for
                        the restore process. This password is required ONLY IF the password of the
                        "admin" user set during the backup differs from the log-in password for the
                        current session. (If you provide an incorrect password, the restore will be
                        aborted.) If the passwords are different, note that restoring the user
                        settings from the backup will cause the current user password to become
                        invalid. </para>
                </step>
                <step>
                    <para>If the restore was accepted, a progress dialog box will display the
                        restored files:</para>
                    <screenshot><graphic fileref="resources/backup3.png"/></screenshot>
                </step>
            </procedure>

            <para>To restore from a backup using the command-line utility, follow the instructions
                above for launching <filename>bin/backup.sh</filename> (Unix), OR the
                    <filename>bin/backup.bat</filename> (Windows/DOS) script files. Include the
                    <parameter>-r</parameter> parameter, and the full path of the
                    <filename>__contents__.xml</filename> file to restore. As with the Admin Client,
                if the backup uses a different password for the "admin" user than the current
                session, you must specify the backup password using the <parameter>-P</parameter>.
                For Example:</para>
            <synopsis>bin/backup.sh -u admin -p admin-pass -P backup-pass 
                                            -r /var/backup/hd060501/db/__contents__.xml</synopsis>

            <note>
                <para>The restore operation will overwrite any existing resource in the database
                    with the same path and name as a resource in the backup. However, resources in
                    the database with different names will not be touched.</para>
            </note>

            <note>
                <para>Whenever the <filename>/db/system</filename> collection is restored, the
                    existing user database is overwritten by the backup database. Consequently, new
                    users added or user setting changes to the old database after a backup will be
                    lost following a database restore. </para>
            </note>

        </section>
    </chapter>
</book>
