restore.xml #1

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section
[
    <!ENTITY % xinclude SYSTEM "../../en/xinclude.mod">
    %xinclude;

    <!-- Add translated specific definitions and snippets -->
    <!ENTITY % language-snippets SYSTEM "../standalone/language-snippets.xml">
    %language-snippets;

    <!-- Fallback to English definitions and snippets (in case of missing translation) -->
    <!ENTITY % language-snippets.default SYSTEM "../../en/standalone/language-snippets.xml">
    %language-snippets.default;
]>
<section id="installation.management.restore">
    <title>Restore</title>

    <para>
        If you need to restore your &product.longname; installation, please use the appropriate
        recipe below. Below, backup files are assumed to be in a path referred to as
        <constant>BACKUPDIR</constant>. <constant>CMSDIR</constant> refers to the root directory of
        your &product.name; installation.
    </para>

    <para>
        The following recipes assume that:
    </para>

    <itemizedlist>
        <listitem>
            You have read through 
            <ulink url="http://www.perforce.com/perforce/doc.current/manuals/p4sag/02_backup.html">Supporting
            Perforce: Backup and Recovery</ulink> in the 
            <ulink url="http://www.perforce.com/perforce/doc.current/manuals/p4sag/">Perforce
            System Administrator's Guide</ulink>.
        </listitem>

        <listitem>
            You have the <command>p4</command> command in your path.
        </listitem>

        <listitem>
            You have the <command>p4d</command> command in your path.
        </listitem>

        <listitem>
            You are logged in as the system's administrator, or <emphasis>root</emphasis> user.
        </listitem>
    </itemizedlist>

    <para>
        First, stop your Apache web server:<?linebreak?>
        <command>apachectl stop</command>
    </para>

    <para>
        Then choose one of the restoration recipes below. At the end of this document are common
        restoration steps.
    </para>

    <section>
        <title>Restore &product.name; with Perforce Server on Same Machine</title>

        <para>
            Backup files are assumed to be in a path referred to as <constant>BACKUPDIR</constant>.
            <constant>CMSDIR</constant> refers to the root directory of your Chronicle installation.
        </para>

        <orderedlist>
            <listitem>
                <para>
                    Change the current working directory:
                </para>

                <para>
                    <command>cd <constant>CMSDIR</constant></command><?linebreak?>
                    <command>cd ..</command>
                </para>
            </listitem>

            <listitem>
                <para>
                    Move the existing installation out of the way:
                </para>

                <para>
                    <command>
                        mv <constant>CMSDIR</constant> <constant>CMSDIR</constant>.old
                    </command>
                </para>
            </listitem>

            <listitem>
                <para>
                    Extract the contents of a previously created TAR archive:
                </para>

                <para>
                    <command>
                        tar -xzf <constant>BACKUPDIR</constant>/&lt;&product.name; backup file&gt;
                    </command>
                </para>
            </listitem>

            <listitem>
                <para>
                    Determine the <replaceable>checkpoint_file</replaceable> and
                    <replaceable>journal_file</replaceable> to restore from:
                </para>

                <para>
                    <command>ls <constant>CMSDIR</constant>/data/perforce/checkpoint*
                    <constant>CMSDIR</constant>/data/perforce/journal*</command>
                </para>
            </listitem>

            <listitem>
                <para>
                    Restore from the checkpoint/journal files identified above:
                </para>

                <para>
                    <command>
                        p4d -r <constant>CMSDIR</constant>/data/perforce -jr
                        <replaceable>checkpoint_file</replaceable>
                        <replaceable>journal_file</replaceable>
                    </command>
                </para>
            </listitem>

            <listitem>
                <para>
                    Verify the integrity of your server:
                </para>

                <para>
                    <command>p4 -p "rsh:p4d -ir <constant>CMSDIR</constant>/data/perforce" -u
                    <constant>ADMINUSER</constant> -P <constant>ADMINPW</constant> verify -q
                    //...</command>
                </para>

                <para>
                    If you encounter errors from this step, please refer to
                    <ulink url="http://kb.perforce.com/article/693">MISSING! errors from p4
                    verify</ulink>, or <ulink url="http://kb.perforce.com/article/961">How to Handle
                    p4 verify BAD Errors</ulink>, from the
                    <ulink url="http://kb.perforce.com/">Perforce Knowledge Base</ulink>.
                </para>
            </listitem>

            <listitem>
                <para>
                    Ensure that the database files are writable by the web server user:
                </para>

                <para>
                    <command>
                        chmod u+w <constant>CMSDIR</constant>/data/perforce/db.*
                        <constant>CMSDIR</constant>/data/perforce/journal*
                    </command><?linebreak?>

                    <command>
                        chown <constant>WEBUSER</constant>
                        <constant>CMSDIR</constant>/data/perforce/db.*
                        <constant>CMSDIR</constant>/data/perforce/journal*
                    </command>
                </para>
            </listitem>

            <listitem>
                Perform the <link linkend="installation.management.restore.common">common
                restoration steps</link>.
            </listitem>
        </orderedlist>
    </section>

    <section>
        <title>Restore &product.name; Using an Existing Chronicle Server</title>

        <para>
            There are two restorations that need to be performed: the Perforce server and the
            &product.name; installation.
        </para>

        <section>
            <title>On the Perforce Server</title>

            <para>
                Please follow the recovery steps presented in
                <ulink url="http://www.perforce.com/perforce/doc.current/manuals/p4sag/02_backup.html">Supporting
                Perforce: Backup and Recovery</ulink>.
            </para>
        </section>

        <section>
            <title>On the &product.name; Server</title>

            <para>
                Before you begin, it is helpful to pick the path where the backup will be stored;
                this path is referred to as <constant>BACKUPDIR</constant> below.
                <constant>CMSDIR</constant> refers to the root directory of your &product.name;
                installation.
            </para>

            <orderedlist>
                <listitem>
                    <para>
                        Change the current working directory:
                    </para>

                    <para>
                        <command>cd <constant>CMSDIR</constant></command><?linebreak?>
                        <command>cd <constant>..</constant></command><?linebreak?>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Move the existing installation out of the way:
                    </para>

                    <para>
                        <command>
                            mv <constant>CMSDIR</constant> <constant>CMSDIR</constant>.old
                        </command>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Extract the contents of a previously created TAR archive:
                    </para>

                    <para>
                        <command>
                            tar -xzf 
                            <constant>BACKUPDIR</constant>/&lt;&product.name; backup file&gt;
                        </command>
                    </para>
                </listitem>
            </orderedlist>
        </section>
    </section>

    <section id="installation.management.restore.common">
        <title>Common Restoration Steps</title>

        <orderedlist>
            <listitem>
                <para>
                    Clear the cache:
                </para>

                <para>
                    <command>cd <constant>CMSDIR</constant>/data/cache</command><?linebreak?>
                    <command>rm -rf default/* global/* page/*</command><?linebreak?>
                    <command>cd <constant>CMSDIR</constant>/data/resources</command><?linebreak?>
                    <command>rm -rf *gz</command>
                </para>
            </listitem>

            <listitem>
                <para>
                    Clear the search indexes, if they exist:
                </para>

                <para>
                    <command>cd <constant>CMSDIR</constant>/data/sites</command><?linebreak?>
                    <command>find . -type d -name 'search-index' | xargs rm -rf</command>
                </para>
            </listitem>

            <listitem>
                <para>
                    Restart Apache:
                </para>

                <para>
                    <command>apachectl start</command>
                </para>
            </listitem>

            <listitem>
                <para>
                    If the Search module is enabled, the search indexes need to be rebuilt:
                </para>

                <orderedlist>
                    <listitem>Login to &product.name;.</listitem>

                    <listitem>
                        Visit <command>Manage &gt; Search Settings</command>. The
                        <emphasis role="screen">Manage Search</emphasis> screen is displayed.
                    </listitem>

                    <listitem>
                        Click <guibutton>Rebuild</guibutton> to rebuild the search indexes.
                    </listitem>
                </orderedlist>
            </listitem>
        </orderedlist>
    </section>
</section>
<!--
vim:se ts=4 sw=4 et:
-->