4
Backing up Bazaar branches can be done in two different ways. If an existing
5
filesystem-based backup scheme already exists, then it can easily be used
6
where the Bazaar branches reside. Alternately, Bazaar itself can be used to
7
mirror the desired branches to or from another location for backup purposes.
12
Bazaar transactions are atomic in the sense that the disk format is such that
13
it is in a valid state at any instant in time. However, for a backup process
14
that takes a finite amount of time to complete, it is possible to have
15
inconsistencies between different on-disk structures when backing up a live
16
branch or repository. (Bazaar itself manages this concurrency issue by only
17
*reading* those structures in a well-defined order.) Tools such as LVM that
18
allow instantaneous snapshots of the contents of a disk can be used to take
19
filesystem backups of live Bazaar branches and repositories.
21
For other backup methods, it is necessary to take the branch or repository
22
offline while the backup is being done in order to guarantee consistency
23
between the various files that comprise a Bazaar branch's history. This
24
requirement can be alleviated by using Bazaar as its own backup client,
25
since it follows an order for reading that is designed to manage concurrent
26
access (see the next section for details). Depending on the different
27
access methods that are being used for a branch, there are different ways to
28
take the branch "offline". For ``bzr+ssh://`` access, it is possible to
29
temporarily change the filesystem permissions to prevent write access from
30
any users. For ``http://`` access, changing permissions, shutting down
31
the HTTP server or switching the server to a separate configuration that
32
disallows access are all possible ways to take a branch offline for backup.
33
Finally, for direct filesystem access, it is necessary to make the branch
34
directories un-writable.
36
Because this sort of downtime can be very disruptive, we strongly encourage
37
using Bazaar itself as a backup client, where branches are copied and
38
updated using Bazaar directly.
41
Bazaar as its own backup
42
------------------------
44
The features that make Bazaar a good distributed version control system also
45
make it a good choice for backing itself up. In particular, complete and
46
consistent copies of any branch can easily be obtained with the ``branch`` and
47
``pull`` commands. As a result, a backup process can simply run ``bzr pull``
48
on a copy of the main branch to fully update that copy. If this backup
49
process runs periodically, then the backups will be as current as the last
50
time that ``pull`` was run. (This is in addition to the fact
51
that revisions are immutable in Bazaar so that a prior revision of a branch is
52
always recoverable from that branch when the revision id is known.)
54
As an example, consider a separate backup server that stores backups in
55
``/var/backup``. On that server, we could initially run
60
$ bzr branch bzr+ssh://server.example.com/srv/bzr/trunk
61
$ bzr branch bzr+ssh://server.example.com/srv/bzr/feature-gui
63
to create the branches on the backup server. Then, we could regularly (for
64
example from ``cron``) do
68
$ cd /var/backup/trunk
69
$ bzr pull # the location to pull from is remembered
70
$ cd ../var/backup/feature-gui
71
$ bzr pull # again, the parent location is remembered
73
The action of pulling from the parent for all branches in some directory is
74
common enough that there is a plugin to do it. The `bzrtools`_ plugin
75
contains a ``multi-pull`` command that does a ``pull`` in all branches under a
78
.. _bzrtools: http://launchpad.net/bzrtools
80
With this plugin installed, the above periodically run commands would be
87
Note that ``multi-pull`` does a pull in *every* branch in the specified
88
directory (the current directory by default) and care should be taken that
89
this is the desired effect. A simple script could also substitute for the
90
multi-pull command while also offering greater flexibility.
95
When ``bzr pull`` is run regularly to keep a backup copy up to date, then it
96
is possible that there are new revisions in the original branch that have not
97
yet been pulled into the backup branch. To alleviate this problem, we can set
98
the branches up so that new revisions are *pushed* to the backup rather than
99
periodically pulling. One way to do this is using Bazaar's concept of bound
100
branches, where a commit in one branch happens only when the same commit
101
succeeds in the branch to which it is `bound`. As a push-type technology, it
102
is set up on the server itself rather than on the backup machine. For each
103
branch that should be backed up, you just need to use the ``bind`` command to
104
set the URL for the backup branch. In our example, we first need to create
105
the branches on the backup server (we'll use ``bzr push``, but we could as
106
easily have used ``bzr branch`` from the backup server)
110
$ cd /srv/bzr/projectx/trunk
111
$ bzr push bzr+ssh://backup.example.com/var/backup/trunk
113
$ bzr push bzr+ssh://backup.example.com/var/backup/feature-gui
115
and then we need to bind the main branches to their backups
120
$ bzr bind bzr+ssh://backup.example.com/var/backup/trunk
122
$ bzr bind bzr+ssh://backup.example.com/var/backup/feature-gui
124
A branch can only be bound to a single location, so multiple backups cannot
125
be created using this method.
127
Using the `automirror`_ plugin mentioned under `Hooks and Plugins <hooks-plugins.html>`_, one can
128
also make a push-type backup system that more naturally handles mutliple
129
backups. Simply set the ``post_commit_mirror`` option to multiple URLs
130
separated by commas. In order to backup to the backup server and a
131
remote location, one could do
136
$ echo "post_commit_mirror=bzr+ssh://backup.example.com/var/backup/trunk,\
137
bzr+ssh://offsite.example.org/projectx-corp/backup/trunk" >> .bzr/branch/branch.conf
139
$ echo "post_commit_mirror=bzr+ssh://backup.example.com/var/backup/feature-gui,\
140
bzr+ssh://offsite.example.org/projectx-corp/backup/feature-gui" >> .bzr/branch/branch.conf
142
.. _automirror: http://launchpad.net/bzr-automirror
144
As for any push-type backup strategy that maintains consistency, the downside
145
of this method is that all of the backup commits must succeed before the
146
initial commit can succeed. If there is a many mirror branches or if the bound
147
branch has a slow network connection, then the delay in the original commit may
148
be unacceptably long. In this case, pull-type backups, or a mixed system may
152
Restoring from Backups
153
----------------------
155
Checking backup consistency
156
~~~~~~~~~~~~~~~~~~~~~~~~~~~
158
Many a system administrator has been bitten by having a backup process,
159
but when it came time to restore from backups, finding out that the backups
160
themselves were flawed. As such, it is important to check the quality of the
161
backups periodically. In Bazaar, there are two ways to do this: using the
162
``bzr check`` command and by simply making a new branch from the backup. The
163
``bzr check`` command goes through all of the revisions in a branch and checks
164
them for validity according to Bazaar's internal invariants. Since it goes
165
through every revision, it can be quite slow for large branches. The other
166
way to ensure that the backups can be restored from is to perform a test
167
restoration. This means performing the restoration process in a temporary
168
directory. After the restoration process, ``bzr check`` may again be relevant
169
for testing the validity of the restored branches. The following two sections
170
present two restoration recipes.
172
Restoring Filesystem Backups
173
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
175
There are many different backup tools with different ways of accessing the
176
backup data, so we can't cover them all here. What we will say is that
177
restoring the contents of the ``/srv/bzr`` directory completely will restore
178
all branches stored there to their state at the time of the backup (see
179
`Filesystem Backups`_ for concerns on backing up live branches.) For
180
example, if the backups were mounted at ``/mnt/backup/bzr`` then we could
181
restore using simply::
185
$ cp -r /mnt/backup/bzr bzr
187
Of course, to restore only a single branch from backup, it is sufficient to
188
copy only that branch. Until the restored backup has been successfully used
189
in practice, we recommend keeping the original directory available.
191
Restoring Bazaar-based Backups
192
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
194
In order to restore from backup branches, we can simply branch them into the
195
appropriate location::
200
$ bzr branch bzr+ssh://backup.example.com/var/backup/trunk
201
$ bzr branch bzr+ssh://backup.example.com/var/backup/feature-gui
203
If there are multiple backups, then change the URL above to restore from the
added
removed
doc/en/admin-guide/backup.txt
