~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2009-11-17 03:20:35 UTC
  • mfrom: (4792.4.3 456036)
  • Revision ID: pqm@pqm.ubuntu.com-20091117032035-s3sgtlixj1lrminn
(Gordon Tyler) Fix IndexError during 'bzr ignore /' (#456036)

Show diffs side-by-side

added added

removed removed

Lines of Context:
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.