← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/admin-guide/backup.txt

  • Committer: Patch Queue Manager
  • Date: 2011-09-22 14:12:18 UTC
  • mfrom: (6155.3.1 jam)
  • Revision ID: pqm@pqm.ubuntu.com-20110922141218-86s4uu6nqvourw4f
(jameinel) Cleanup comments bzrlib/smart/__init__.py (John A Meinel)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/admin-guide/backup.txt
 
1
Back-up and Restore
 
2
===================
 
3
 
 
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.
 
8
 
 
9
Filesystem Backups
 
10
------------------
 
11
 
 
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.
 
20
 
 
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.
 
35
 
 
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.
 
39
 
 
40
 
 
41
Bazaar as its own backup
 
42
------------------------
 
43
 
 
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.)
 
53
 
 
54
As an example, consider a separate backup server that stores backups in
 
55
``/var/backup``.  On that server, we could initially run
 
56
 
 
57
::
 
58
 
 
59
  $ cd /var/backup
 
60
  $ bzr branch bzr+ssh://server.example.com/srv/bzr/trunk
 
61
  $ bzr branch bzr+ssh://server.example.com/srv/bzr/feature-gui
 
62
 
 
63
to create the branches on the backup server.  Then, we could regularly (for
 
64
example from ``cron``) do
 
65
 
 
66
::
 
67
 
 
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
 
72
 
 
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
 
76
specified directory.
 
77
 
 
78
.. _bzrtools: http://launchpad.net/bzrtools
 
79
 
 
80
With this plugin installed, the above periodically run commands would be
 
81
 
 
82
::
 
83
 
 
84
  $ cd /var/backup
 
85
  $ bzr multi-pull
 
86
 
 
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.
 
91
 
 
92
Bound Branch Backups
 
93
~~~~~~~~~~~~~~~~~~~~
 
94
 
 
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)
 
107
 
 
108
::
 
109
 
 
110
  $ cd /srv/bzr/projectx/trunk
 
111
  $ bzr push bzr+ssh://backup.example.com/var/backup/trunk
 
112
  $ cd ../feature-gui
 
113
  $ bzr push bzr+ssh://backup.example.com/var/backup/feature-gui
 
114
 
 
115
and then we need to bind the main branches to their backups
 
116
 
 
117
::
 
118
 
 
119
  $ cd ../trunk
 
120
  $ bzr bind bzr+ssh://backup.example.com/var/backup/trunk
 
121
  $ cd ../feature-gui
 
122
  $ bzr bind bzr+ssh://backup.example.com/var/backup/feature-gui
 
123
 
 
124
A branch can only be bound to a single location, so multiple backups cannot
 
125
be created using this method.  
 
126
 
 
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
 
132
 
 
133
::
 
134
 
 
135
  $ cd /srv/bzr/trunk
 
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
 
138
  $ cd ../feature-gui
 
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
 
141
 
 
142
.. _automirror: http://launchpad.net/bzr-automirror
 
143
 
 
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
 
149
be preferable.
 
150
 
 
151
 
 
152
Restoring from Backups
 
153
----------------------
 
154
 
 
155
Checking backup consistency
 
156
~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
157
 
 
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.
 
171
 
 
172
Restoring Filesystem Backups
 
173
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
174
 
 
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::
 
182
 
 
183
  $ cd /srv
 
184
  $ mv bzr bzr.old
 
185
  $ cp -r /mnt/backup/bzr bzr
 
186
 
 
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.
 
190
 
 
191
Restoring Bazaar-based Backups
 
192
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
193
 
 
194
In order to restore from backup branches, we can simply branch them into the
 
195
appropriate location::
 
196
 
 
197
  $ cd /srv
 
198
  $ mv bzr bzr.old
 
199
  $ cd bzr
 
200
  $ bzr branch bzr+ssh://backup.example.com/var/backup/trunk
 
201
  $ bzr branch bzr+ssh://backup.example.com/var/backup/feature-gui
 
202
 
 
203
If there are multiple backups, then change the URL above to restore from the
 
204
other backups.