<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Back-up and Restore — Bazaar 2.7.0 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/bzr.ico"/>
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Upgrades" href="upgrade.html" />
<link rel="prev" title="Security" href="security.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="upgrade.html" title="Upgrades"
accesskey="N">next</a></li>
<li class="right" >
<a href="security.html" title="Security"
accesskey="P">previous</a> |</li>
<li><a href="http://bazaar.canonical.com/">
<img src="../_static/bzr icon 16.png" /> Home</a> | </li>
<a href="http://doc.bazaar.canonical.com/en/">Documentation</a> | </li>
<li class="nav-item nav-item-0"><a href="../index.html">Table of Contents (2.7.0)</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Bazaar System Administrator’s Guide</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="back-up-and-restore">
<h1>Back-up and Restore<a class="headerlink" href="#back-up-and-restore" title="Permalink to this headline">¶</a></h1>
<p>Backing up Bazaar branches can be done in two different ways. If an existing
filesystem-based backup scheme already exists, then it can easily be used
where the Bazaar branches reside. Alternately, Bazaar itself can be used to
mirror the desired branches to or from another location for backup purposes.</p>
<div class="section" id="filesystem-backups">
<h2>Filesystem Backups<a class="headerlink" href="#filesystem-backups" title="Permalink to this headline">¶</a></h2>
<p>Bazaar transactions are atomic in the sense that the disk format is such that
it is in a valid state at any instant in time. However, for a backup process
that takes a finite amount of time to complete, it is possible to have
inconsistencies between different on-disk structures when backing up a live
branch or repository. (Bazaar itself manages this concurrency issue by only
<em>reading</em> those structures in a well-defined order.) Tools such as LVM that
allow instantaneous snapshots of the contents of a disk can be used to take
filesystem backups of live Bazaar branches and repositories.</p>
<p>For other backup methods, it is necessary to take the branch or repository
offline while the backup is being done in order to guarantee consistency
between the various files that comprise a Bazaar branch’s history. This
requirement can be alleviated by using Bazaar as its own backup client,
since it follows an order for reading that is designed to manage concurrent
access (see the next section for details). Depending on the different
access methods that are being used for a branch, there are different ways to
take the branch “offline”. For <code class="docutils literal notranslate"><span class="pre">bzr+ssh://</span></code> access, it is possible to
temporarily change the filesystem permissions to prevent write access from
any users. For <code class="docutils literal notranslate"><span class="pre">http://</span></code> access, changing permissions, shutting down
the HTTP server or switching the server to a separate configuration that
disallows access are all possible ways to take a branch offline for backup.
Finally, for direct filesystem access, it is necessary to make the branch
directories un-writable.</p>
<p>Because this sort of downtime can be very disruptive, we strongly encourage
using Bazaar itself as a backup client, where branches are copied and
updated using Bazaar directly.</p>
</div>
<div class="section" id="bazaar-as-its-own-backup">
<h2>Bazaar as its own backup<a class="headerlink" href="#bazaar-as-its-own-backup" title="Permalink to this headline">¶</a></h2>
<p>The features that make Bazaar a good distributed version control system also
make it a good choice for backing itself up. In particular, complete and
consistent copies of any branch can easily be obtained with the <code class="docutils literal notranslate"><span class="pre">branch</span></code> and
<code class="docutils literal notranslate"><span class="pre">pull</span></code> commands. As a result, a backup process can simply run <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">pull</span></code>
on a copy of the main branch to fully update that copy. If this backup
process runs periodically, then the backups will be as current as the last
time that <code class="docutils literal notranslate"><span class="pre">pull</span></code> was run. (This is in addition to the fact
that revisions are immutable in Bazaar so that a prior revision of a branch is
always recoverable from that branch when the revision id is known.)</p>
<p>As an example, consider a separate backup server that stores backups in
<code class="docutils literal notranslate"><span class="pre">/var/backup</span></code>. On that server, we could initially run</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cd /var/backup
$ bzr branch bzr+ssh://server.example.com/srv/bzr/trunk
$ bzr branch bzr+ssh://server.example.com/srv/bzr/feature-gui
</pre></div>
</div>
<p>to create the branches on the backup server. Then, we could regularly (for
example from <code class="docutils literal notranslate"><span class="pre">cron</span></code>) do</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cd /var/backup/trunk
$ bzr pull # the location to pull from is remembered
$ cd ../var/backup/feature-gui
$ bzr pull # again, the parent location is remembered
</pre></div>
</div>
<p>The action of pulling from the parent for all branches in some directory is
common enough that there is a plugin to do it. The <a class="reference external" href="http://launchpad.net/bzrtools">bzrtools</a> plugin
contains a <code class="docutils literal notranslate"><span class="pre">multi-pull</span></code> command that does a <code class="docutils literal notranslate"><span class="pre">pull</span></code> in all branches under a
specified directory.</p>
<p>With this plugin installed, the above periodically run commands would be</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cd /var/backup
$ bzr multi-pull
</pre></div>
</div>
<p>Note that <code class="docutils literal notranslate"><span class="pre">multi-pull</span></code> does a pull in <em>every</em> branch in the specified
directory (the current directory by default) and care should be taken that
this is the desired effect. A simple script could also substitute for the
multi-pull command while also offering greater flexibility.</p>
<div class="section" id="bound-branch-backups">
<h3>Bound Branch Backups<a class="headerlink" href="#bound-branch-backups" title="Permalink to this headline">¶</a></h3>
<p>When <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">pull</span></code> is run regularly to keep a backup copy up to date, then it
is possible that there are new revisions in the original branch that have not
yet been pulled into the backup branch. To alleviate this problem, we can set
the branches up so that new revisions are <em>pushed</em> to the backup rather than
periodically pulling. One way to do this is using Bazaar’s concept of bound
branches, where a commit in one branch happens only when the same commit
succeeds in the branch to which it is <cite>bound</cite>. As a push-type technology, it
is set up on the server itself rather than on the backup machine. For each
branch that should be backed up, you just need to use the <code class="docutils literal notranslate"><span class="pre">bind</span></code> command to
set the URL for the backup branch. In our example, we first need to create
the branches on the backup server (we’ll use <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">push</span></code>, but we could as
easily have used <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">branch</span></code> from the backup server)</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cd /srv/bzr/projectx/trunk
$ bzr push bzr+ssh://backup.example.com/var/backup/trunk
$ cd ../feature-gui
$ bzr push bzr+ssh://backup.example.com/var/backup/feature-gui
</pre></div>
</div>
<p>and then we need to bind the main branches to their backups</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cd ../trunk
$ bzr bind bzr+ssh://backup.example.com/var/backup/trunk
$ cd ../feature-gui
$ bzr bind bzr+ssh://backup.example.com/var/backup/feature-gui
</pre></div>
</div>
<p>A branch can only be bound to a single location, so multiple backups cannot
be created using this method.</p>
<p>Using the <a class="reference external" href="http://launchpad.net/bzr-automirror">automirror</a> plugin mentioned under <a class="reference external" href="hooks-plugins.html">Hooks and Plugins</a>, one can
also make a push-type backup system that more naturally handles mutliple
backups. Simply set the <code class="docutils literal notranslate"><span class="pre">post_commit_mirror</span></code> option to multiple URLs
separated by commas. In order to backup to the backup server and a
remote location, one could do</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cd /srv/bzr/trunk
$ echo "post_commit_mirror=bzr+ssh://backup.example.com/var/backup/trunk,\
bzr+ssh://offsite.example.org/projectx-corp/backup/trunk" >> .bzr/branch/branch.conf
$ cd ../feature-gui
$ echo "post_commit_mirror=bzr+ssh://backup.example.com/var/backup/feature-gui,\
bzr+ssh://offsite.example.org/projectx-corp/backup/feature-gui" >> .bzr/branch/branch.conf
</pre></div>
</div>
<p>As for any push-type backup strategy that maintains consistency, the downside
of this method is that all of the backup commits must succeed before the
initial commit can succeed. If there is a many mirror branches or if the bound
branch has a slow network connection, then the delay in the original commit may
be unacceptably long. In this case, pull-type backups, or a mixed system may
be preferable.</p>
</div>
</div>
<div class="section" id="restoring-from-backups">
<h2>Restoring from Backups<a class="headerlink" href="#restoring-from-backups" title="Permalink to this headline">¶</a></h2>
<div class="section" id="checking-backup-consistency">
<h3>Checking backup consistency<a class="headerlink" href="#checking-backup-consistency" title="Permalink to this headline">¶</a></h3>
<p>Many a system administrator has been bitten by having a backup process,
but when it came time to restore from backups, finding out that the backups
themselves were flawed. As such, it is important to check the quality of the
backups periodically. In Bazaar, there are two ways to do this: using the
<code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">check</span></code> command and by simply making a new branch from the backup. The
<code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">check</span></code> command goes through all of the revisions in a branch and checks
them for validity according to Bazaar’s internal invariants. Since it goes
through every revision, it can be quite slow for large branches. The other
way to ensure that the backups can be restored from is to perform a test
restoration. This means performing the restoration process in a temporary
directory. After the restoration process, <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">check</span></code> may again be relevant
for testing the validity of the restored branches. The following two sections
present two restoration recipes.</p>
</div>
<div class="section" id="restoring-filesystem-backups">
<h3>Restoring Filesystem Backups<a class="headerlink" href="#restoring-filesystem-backups" title="Permalink to this headline">¶</a></h3>
<p>There are many different backup tools with different ways of accessing the
backup data, so we can’t cover them all here. What we will say is that
restoring the contents of the <code class="docutils literal notranslate"><span class="pre">/srv/bzr</span></code> directory completely will restore
all branches stored there to their state at the time of the backup (see
<a class="reference internal" href="#filesystem-backups">Filesystem Backups</a> for concerns on backing up live branches.) For
example, if the backups were mounted at <code class="docutils literal notranslate"><span class="pre">/mnt/backup/bzr</span></code> then we could
restore using simply:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cd /srv
$ mv bzr bzr.old
$ cp -r /mnt/backup/bzr bzr
</pre></div>
</div>
<p>Of course, to restore only a single branch from backup, it is sufficient to
copy only that branch. Until the restored backup has been successfully used
in practice, we recommend keeping the original directory available.</p>
</div>
<div class="section" id="restoring-bazaar-based-backups">
<h3>Restoring Bazaar-based Backups<a class="headerlink" href="#restoring-bazaar-based-backups" title="Permalink to this headline">¶</a></h3>
<p>In order to restore from backup branches, we can simply branch them into the
appropriate location:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cd /srv
$ mv bzr bzr.old
$ cd bzr
$ bzr branch bzr+ssh://backup.example.com/var/backup/trunk
$ bzr branch bzr+ssh://backup.example.com/var/backup/feature-gui
</pre></div>
</div>
<p>If there are multiple backups, then change the URL above to restore from the
other backups.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Back-up and Restore</a><ul>
<li><a class="reference internal" href="#filesystem-backups">Filesystem Backups</a></li>
<li><a class="reference internal" href="#bazaar-as-its-own-backup">Bazaar as its own backup</a><ul>
<li><a class="reference internal" href="#bound-branch-backups">Bound Branch Backups</a></li>
</ul>
</li>
<li><a class="reference internal" href="#restoring-from-backups">Restoring from Backups</a><ul>
<li><a class="reference internal" href="#checking-backup-consistency">Checking backup consistency</a></li>
<li><a class="reference internal" href="#restoring-filesystem-backups">Restoring Filesystem Backups</a></li>
<li><a class="reference internal" href="#restoring-bazaar-based-backups">Restoring Bazaar-based Backups</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="security.html"
title="previous chapter">Security</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="upgrade.html"
title="next chapter">Upgrades</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/admin-guide/backup.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="upgrade.html" title="Upgrades"
>next</a></li>
<li class="right" >
<a href="security.html" title="Security"
>previous</a> |</li>
<li><a href="http://bazaar.canonical.com/">
<img src="../_static/bzr icon 16.png" /> Home</a> | </li>
<a href="http://doc.bazaar.canonical.com/en/">Documentation</a> | </li>
<li class="nav-item nav-item-0"><a href="../index.html">Table of Contents (2.7.0)</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" >Bazaar System Administrator’s Guide</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2009-2011 Canonical Ltd.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
</div>
</body>
</html>
