1 |
dpavlin |
1 |
=head1 BackupPC Introduction |
2 |
|
|
|
3 |
dpavlin |
316 |
This documentation describes BackupPC version 2.1.2, |
4 |
|
|
released on 5 Sep 2005. |
5 |
dpavlin |
1 |
|
6 |
|
|
=head2 Overview |
7 |
|
|
|
8 |
|
|
BackupPC is a high-performance, enterprise-grade system for backing up |
9 |
|
|
Unix, Linux and WinXX PCs, desktops and laptops to a server's disk. |
10 |
|
|
BackupPC is highly configurable and easy to install and maintain. |
11 |
|
|
|
12 |
|
|
Given the ever decreasing cost of disks and raid systems, it is now |
13 |
|
|
practical and cost effective to backup a large number of machines onto |
14 |
|
|
a server's local disk or network storage. For some sites this might be |
15 |
|
|
the complete backup solution. For other sites additional permanent |
16 |
|
|
archives could be created by periodically backing up the server to tape. |
17 |
|
|
|
18 |
|
|
Features include: |
19 |
|
|
|
20 |
|
|
=over 4 |
21 |
|
|
|
22 |
|
|
=item * |
23 |
|
|
|
24 |
|
|
A clever pooling scheme minimizes disk storage and disk I/O. |
25 |
|
|
Identical files across multiple backups of the same or different PC |
26 |
|
|
are stored only once (using hard links), resulting in substantial |
27 |
|
|
savings in disk storage and disk writes. |
28 |
|
|
|
29 |
|
|
=item * |
30 |
|
|
|
31 |
|
|
Optional compression provides additional reductions in storage |
32 |
|
|
(around 40%). The CPU impact of compression is low since only |
33 |
|
|
new files (those not already in the pool) need to be compressed. |
34 |
|
|
|
35 |
|
|
=item * |
36 |
|
|
|
37 |
|
|
A powerful http/cgi user interface allows administrators to view log |
38 |
|
|
files, configuration, current status and allows users to initiate and |
39 |
|
|
cancel backups and browse and restore files from backups. |
40 |
|
|
|
41 |
|
|
=item * |
42 |
|
|
|
43 |
|
|
The http/cgi user interface has internationalization (i18n) support, |
44 |
|
|
currently providing English, French, German, Spanish, Italian |
45 |
|
|
and Dutch. |
46 |
|
|
|
47 |
|
|
=item * |
48 |
|
|
|
49 |
|
|
No client-side software is needed. On WinXX the standard smb |
50 |
|
|
protocol is used to extract backup data. On linux or unix clients, |
51 |
|
|
rsync or tar (over ssh/rsh/nfs) is used to extract backup data. |
52 |
|
|
Alternatively, rsync can also be used on WinXX (using cygwin), |
53 |
|
|
and Samba could be installed on the linux or unix client to |
54 |
|
|
provide smb shares). |
55 |
|
|
|
56 |
|
|
=item * |
57 |
|
|
|
58 |
|
|
Flexible restore options. Single files can be downloaded from |
59 |
|
|
any backup directly from the CGI interface. Zip or Tar archives |
60 |
|
|
for selected files or directories from any backup can also be |
61 |
|
|
downloaded from the CGI interface. Finally, direct restore to |
62 |
|
|
the client machine (using smb or tar) for selected files or |
63 |
|
|
directories is also supported from the CGI interface. |
64 |
|
|
|
65 |
|
|
=item * |
66 |
|
|
|
67 |
|
|
BackupPC supports mobile environments where laptops are only |
68 |
|
|
intermittently connected to the network and have dynamic IP addresses |
69 |
|
|
(DHCP). Configuration settings allow machines connected via slower WAN |
70 |
|
|
connections (eg: dial up, DSL, cable) to not be backed up, even if they |
71 |
|
|
use the same fixed or dynamic IP address as when they are connected |
72 |
|
|
directly to the LAN. |
73 |
|
|
|
74 |
|
|
=item * |
75 |
|
|
|
76 |
|
|
Flexible configuration parameters allow multiple backups to be performed |
77 |
|
|
in parallel, specification of which shares to backup, which directories |
78 |
|
|
to backup or not backup, various schedules for full and incremental |
79 |
|
|
backups, schedules for email reminders to users and so on. Configuration |
80 |
|
|
parameters can be set system-wide or also on a per-PC basis. |
81 |
|
|
|
82 |
|
|
=item * |
83 |
|
|
|
84 |
|
|
Users are sent periodic email reminders if their PC has not |
85 |
|
|
recently been backed up. Email content, timing and policies |
86 |
|
|
are configurable. |
87 |
|
|
|
88 |
|
|
=item * |
89 |
|
|
|
90 |
|
|
BackupPC is Open Source software hosted by SourceForge. |
91 |
|
|
|
92 |
|
|
=back |
93 |
|
|
|
94 |
|
|
=head2 Backup basics |
95 |
|
|
|
96 |
|
|
=over 4 |
97 |
|
|
|
98 |
|
|
=item Full Backup |
99 |
|
|
|
100 |
|
|
A full backup is a complete backup of a share. BackupPC can be |
101 |
|
|
configured to do a full backup at a regular interval (typically |
102 |
|
|
weekly). BackupPC can be configured to keep a certain number |
103 |
|
|
of full backups. Exponential expiry is also supported, allowing |
104 |
|
|
full backups with various vintages to be kept (for example, a |
105 |
|
|
settable number of most recent weekly fulls, plus a settable |
106 |
|
|
number of older fulls that are 2, 4, 8, or 16 weeks apart). |
107 |
|
|
|
108 |
|
|
=item Incremental Backup |
109 |
|
|
|
110 |
|
|
An incremental backup is a backup of files that have changed (based on |
111 |
|
|
their modification time) since the last successful full backup. For |
112 |
|
|
SMB and tar, BackupPC backups all files that have changed since one |
113 |
|
|
hour prior to the start of the last successful full backup. Rsync is |
114 |
|
|
more clever: any files whose attributes have changed (ie: uid, gid, |
115 |
|
|
mtime, modes, size) since the last full are backed up. Deleted, new |
116 |
|
|
files and renamed files are detected by Rsync incrementals. |
117 |
|
|
In constrast, SMB and tar incrementals are not able to detect deleted |
118 |
|
|
files, renamed files or new files whose modification time is prior to |
119 |
|
|
the last full dump. |
120 |
|
|
|
121 |
|
|
BackupPC can also be configured to keep a certain number of incremental |
122 |
|
|
backups, and to keep a smaller number of very old incremental backups. |
123 |
|
|
(BackupPC does not support multi-level incremental backups, although it |
124 |
|
|
will in a future version.) |
125 |
|
|
|
126 |
|
|
BackupPC's CGI interface "fills-in" incremental backups based on the |
127 |
|
|
last full backup, giving every backup a "full" appearance. This makes |
128 |
|
|
browsing and restoring backups easier. |
129 |
|
|
|
130 |
|
|
=item Partial Backup |
131 |
|
|
|
132 |
|
|
When a full backup fails or is canceled, and some files have already |
133 |
|
|
been backed up, BackupPC keeps a partial backup containing just the |
134 |
|
|
files that were backed up successfully. The partial backup is removed |
135 |
|
|
when the next successful backup completes, or if another full backup |
136 |
|
|
fails resulting in a newer partial backup. A failed full backup |
137 |
|
|
that has not backed up any files, or any failed incremental backup, |
138 |
|
|
is removed; no partial backup is saved in these cases. |
139 |
|
|
|
140 |
|
|
The partial backup may be browsed or used to restore files just like |
141 |
|
|
a successful full or incremental backup. |
142 |
|
|
|
143 |
|
|
With the rsync transfer method the partial backup is used to resume |
144 |
|
|
the next full backup, avoiding the need to retransfer the file data |
145 |
|
|
already in the partial backup. |
146 |
|
|
|
147 |
|
|
=item Identical Files |
148 |
|
|
|
149 |
|
|
BackupPC pools identical files using hardlinks. By "identical |
150 |
|
|
files" we mean files with identical contents, not necessary the |
151 |
|
|
same permissions, ownership or modification time. Two files might |
152 |
|
|
have different permissions, ownership, or modification time but |
153 |
|
|
will still be pooled whenever the contents are identical. This |
154 |
|
|
is possible since BackupPC stores the file meta-data (permissions, |
155 |
|
|
ownership, and modification time) separately from the file contents. |
156 |
|
|
|
157 |
|
|
=item Backup Policy |
158 |
|
|
|
159 |
|
|
Based on your site's requirements you need to decide what your backup |
160 |
|
|
policy is. BackupPC is not designed to provide exact re-imaging of |
161 |
|
|
failed disks. See L<Limitations|limitations> for more information. |
162 |
|
|
However, the addition of tar transport for linux/unix clients, plus |
163 |
|
|
full support for special file types and unix attributes in v1.4.0 |
164 |
|
|
likely means an exact image of a linux/unix file system can be made. |
165 |
|
|
|
166 |
|
|
BackupPC saves backups onto disk. Because of pooling you can relatively |
167 |
|
|
economically keep several weeks of old backups. |
168 |
|
|
|
169 |
|
|
At some sites the disk-based backup will be adequate, without a |
170 |
|
|
secondary tape backup. This system is robust to any single failure: if a |
171 |
|
|
client disk fails or loses files, the BackupPC server can be used to |
172 |
|
|
restore files. If the server disk fails, BackupPC can be restarted on a |
173 |
|
|
fresh file system, and create new backups from the clients. The chance |
174 |
|
|
of the server disk failing can be made very small by spending more money |
175 |
|
|
on increasingly better RAID systems. However, there is still the risk |
176 |
|
|
of catastrophic events like fires or earthquakes that can destroy |
177 |
|
|
both the BackupPC server and the clients it is backing up if they |
178 |
|
|
are physically nearby. |
179 |
|
|
|
180 |
|
|
Some sites might choose to do periodic backups to tape or cd/dvd. |
181 |
|
|
This backup can be done perhaps weekly using the archive function of |
182 |
|
|
BackupPC. |
183 |
|
|
|
184 |
|
|
Other users have reported success with removable disks to rotate the |
185 |
|
|
BackupPC data drives, or using rsync to mirror the BackupPC data pool |
186 |
|
|
offsite. |
187 |
|
|
|
188 |
|
|
=back |
189 |
|
|
|
190 |
|
|
=head2 Resources |
191 |
|
|
|
192 |
|
|
=over 4 |
193 |
|
|
|
194 |
|
|
=item BackupPC home page |
195 |
|
|
|
196 |
|
|
The BackupPC Open Source project is hosted on SourceForge. The |
197 |
|
|
home page can be found at: |
198 |
|
|
|
199 |
|
|
http://backuppc.sourceforge.net |
200 |
|
|
|
201 |
|
|
This page has links to the current documentation, the SourceForge |
202 |
|
|
project page and general information. |
203 |
|
|
|
204 |
|
|
=item SourceForge project |
205 |
|
|
|
206 |
|
|
The SourceForge project page is at: |
207 |
|
|
|
208 |
|
|
http://sourceforge.net/projects/backuppc |
209 |
|
|
|
210 |
|
|
This page has links to the current releases of BackupPC. |
211 |
|
|
|
212 |
|
|
=item BackupPC FAQ |
213 |
|
|
|
214 |
|
|
BackupPC has a FAQ at L<http://backuppc.sourceforge.net/faq>. |
215 |
|
|
|
216 |
|
|
=item Mail lists |
217 |
|
|
|
218 |
|
|
Three BackupPC mailing lists exist for announcements (backuppc-announce), |
219 |
|
|
developers (backuppc-devel), and a general user list for support, asking |
220 |
|
|
questions or any other topic relevant to BackupPC (backuppc-users). |
221 |
|
|
|
222 |
|
|
The lists are archived on SourceForge and Gmane. The SourceForge lists |
223 |
|
|
are not always up to date and the searching is limited, so Gmane is |
224 |
|
|
a good alternative. See: |
225 |
|
|
|
226 |
|
|
http://news.gmane.org/index.php?prefix=gmane.comp.sysutils.backup.backuppc |
227 |
|
|
http://sourceforge.net/mailarchive/forum.php?forum_id=503 |
228 |
|
|
|
229 |
|
|
You can subscribe to these lists by visiting: |
230 |
|
|
|
231 |
|
|
http://lists.sourceforge.net/lists/listinfo/backuppc-announce |
232 |
|
|
http://lists.sourceforge.net/lists/listinfo/backuppc-users |
233 |
|
|
http://lists.sourceforge.net/lists/listinfo/backuppc-devel |
234 |
|
|
|
235 |
|
|
The backuppc-announce list is moderated and is used only for |
236 |
|
|
important announcements (eg: new versions). It is low traffic. |
237 |
|
|
You only need to subscribe to one of backuppc-announce and |
238 |
|
|
backuppc-users: backuppc-users also receives any messages on |
239 |
|
|
backuppc-announce. |
240 |
|
|
|
241 |
|
|
The backuppc-devel list is only for developers who are working on BackupPC. |
242 |
|
|
Do not post questions or support requests there. But detailed technical |
243 |
|
|
discussions should happen on this list. |
244 |
|
|
|
245 |
|
|
To post a message to the backuppc-users list, send an email to |
246 |
|
|
|
247 |
|
|
backuppc-users@lists.sourceforge.net |
248 |
|
|
|
249 |
|
|
Do not send subscription requests to this address! |
250 |
|
|
|
251 |
|
|
=item Other Programs of Interest |
252 |
|
|
|
253 |
|
|
If you want to mirror linux or unix files or directories to a remote server |
254 |
|
|
you should consider rsync, L<http://rsync.samba.org>. BackupPC now uses |
255 |
|
|
rsync as a transport mechanism; if you are already an rsync user you |
256 |
|
|
can think of BackupPC as adding efficient storage (compression and |
257 |
|
|
pooling) and a convenient user interface to rsync. |
258 |
|
|
|
259 |
|
|
Unison is a utility that can do two-way, interactive, synchronization. |
260 |
|
|
See L<http://www.cis.upenn.edu/~bcpierce/unison>. |
261 |
|
|
|
262 |
|
|
Three popular open source packages that do tape backup are |
263 |
|
|
Amanda (L<http://www.amanda.org>), |
264 |
|
|
afbackup (L<http://sourceforge.net/projects/afbackup>), and |
265 |
|
|
Bacula (L<http://www.bacula.org>). |
266 |
|
|
Amanda can also backup WinXX machines to tape using samba. |
267 |
|
|
These packages can be used as back ends to BackupPC to backup the |
268 |
|
|
BackupPC server data to tape. |
269 |
|
|
|
270 |
|
|
Various programs and scripts use rsync to provide hardlinked backups. |
271 |
|
|
See, for example, Mike Rubel's site (L<http://www.mikerubel.org/computers/rsync_snapshots>), |
272 |
dpavlin |
316 |
JW Schultz's dirvish (L<http://www.dirvish.org>), |
273 |
dpavlin |
1 |
Ben Escoto's rdiff-backup (L<http://rdiff-backup.stanford.edu>), |
274 |
|
|
and John Bowman's rlbackup (L<http://www.math.ualberta.ca/imaging/rlbackup>). |
275 |
|
|
|
276 |
|
|
BackupPC provides many additional features, such as compressed storage, |
277 |
|
|
hardlinking any matching files (rather than just files with the same name), |
278 |
|
|
and storing special files without root privileges. But these other scripts |
279 |
|
|
provide simple and effective solutions and are worthy of consideration. |
280 |
|
|
|
281 |
|
|
=back |
282 |
|
|
|
283 |
|
|
=head2 Road map |
284 |
|
|
|
285 |
|
|
The new features planned for future releases of BackupPC |
286 |
|
|
are at L<http://backuppc.sourceforge.net/faq/roadMap.html>. |
287 |
|
|
|
288 |
|
|
Comments and suggestions are welcome. |
289 |
|
|
|
290 |
|
|
=head2 You can help |
291 |
|
|
|
292 |
|
|
BackupPC is free. I work on BackupPC because I enjoy doing it and I like |
293 |
|
|
to contribute to the open source community. |
294 |
|
|
|
295 |
|
|
BackupPC already has more than enough features for my own needs. The |
296 |
|
|
main compensation for continuing to work on BackupPC is knowing that |
297 |
|
|
more and more people find it useful. So feedback is certainly |
298 |
|
|
appreciated, both positive and negative. |
299 |
|
|
|
300 |
|
|
Beyond being a satisfied user and telling other people about it, everyone |
301 |
|
|
is encouraged to add links to L<http://backuppc.sourceforge.net> |
302 |
dpavlin |
316 |
(I'll see them via Google) or otherwise publicize BackupPC. Unlike |
303 |
dpavlin |
1 |
the commercial products in this space, I have a zero budget (in both |
304 |
|
|
time and money) for marketing, PR and advertising, so it's up to |
305 |
|
|
all of you! Feel free to vote for BackupPC at |
306 |
|
|
L<http://freshmeat.net/projects/backuppc>. |
307 |
|
|
|
308 |
|
|
Also, everyone is encouraged to contribute patches, bug reports, feature |
309 |
|
|
and design suggestions, new code, FAQs, and documentation corrections or |
310 |
|
|
improvements. Answering questions on the mail list is a big help too. |
311 |
|
|
|
312 |
|
|
=head1 Installing BackupPC |
313 |
|
|
|
314 |
|
|
=head2 Requirements |
315 |
|
|
|
316 |
|
|
BackupPC requires: |
317 |
|
|
|
318 |
|
|
=over 4 |
319 |
|
|
|
320 |
|
|
=item * |
321 |
|
|
|
322 |
|
|
A linux, solaris, or unix based server with a substantial amount of free |
323 |
|
|
disk space (see the next section for what that means). The CPU and disk |
324 |
|
|
performance on this server will determine how many simultaneous backups |
325 |
|
|
you can run. You should be able to run 4-8 simultaneous backups on a |
326 |
|
|
moderately configured server. |
327 |
|
|
|
328 |
|
|
Several users have reported significantly better performance using |
329 |
|
|
reiser compared to ext3 for the BackupPC data file system. It is |
330 |
|
|
also recommended you consider either an LVM or raid setup (either |
331 |
|
|
in HW or SW; eg: 3Ware RAID5) so that you can expand the |
332 |
|
|
file system as necessary. |
333 |
|
|
|
334 |
|
|
When BackupPC starts with an empty pool, all the backup data will be |
335 |
|
|
written to the pool on disk. After more backups are done, a higher |
336 |
|
|
percentage of incoming files will already be in the pool. BackupPC is |
337 |
|
|
able to avoid writing to disk new files that are already in the pool. |
338 |
|
|
So over time disk writes will reduce significantly (by perhaps a factor |
339 |
|
|
of 20 or more), since eventually 95% or more of incoming backup files |
340 |
|
|
are typically in the pool. Disk reads from the pool are still needed to |
341 |
|
|
do file compares to verify files are an exact match. So, with a mature |
342 |
|
|
pool, if a relatively fast client generates data at say 1MB/sec, and you |
343 |
|
|
run 4 simultaneous backups, there will be an average server disk load of |
344 |
|
|
about 4MB/sec reads and 0.2MB/sec writes (assuming 95% of the incoming |
345 |
|
|
files are in the pool). These rates will be perhaps 40% lower if |
346 |
|
|
compression is on. |
347 |
|
|
|
348 |
|
|
=item * |
349 |
|
|
|
350 |
|
|
Perl version 5.6.0 or later. BackupPC has been tested with |
351 |
|
|
version 5.6.x, and 5.8.x. If you don't have perl, please |
352 |
|
|
see L<http://www.cpan.org>. |
353 |
|
|
|
354 |
|
|
=item * |
355 |
|
|
|
356 |
|
|
Perl modules Compress::Zlib, Archive::Zip and File::RsyncP. Try "perldoc |
357 |
|
|
Compress::Zlib" and "perldoc Archive::Zip" to see if you have these |
358 |
|
|
modules. If not, fetch them from L<http://www.cpan.org> and see the |
359 |
|
|
instructions below for how to build and install them. |
360 |
|
|
|
361 |
|
|
The File::RsyncP module is available from L<http://perlrsync.sourceforge.net> |
362 |
|
|
or CPAN. You'll need to install the File::RsyncP module if you want to use |
363 |
|
|
Rsync as a transport method. |
364 |
|
|
|
365 |
|
|
=item * |
366 |
|
|
|
367 |
|
|
If you are using smb to backup WinXX machines you need smbclient and |
368 |
|
|
nmblookup from the samba package. You will also need nmblookup if |
369 |
|
|
you are backing up linux/unix DHCP machines. See L<http://www.samba.org>. |
370 |
|
|
Version 2.2.0 or later of Samba is required. |
371 |
|
|
Samba versions 3.x are stable and now recommended instead of 2.x. |
372 |
|
|
|
373 |
|
|
See L<http://www.samba.org> for source and binaries. It's pretty easy to |
374 |
|
|
fetch and compile samba, and just grab smbclient and nmblookup, without |
375 |
|
|
doing the installation. Alternatively, L<http://www.samba.org> has binary |
376 |
|
|
distributions for most platforms. |
377 |
|
|
|
378 |
|
|
=item * |
379 |
|
|
|
380 |
|
|
If you are using tar to backup linux/unix machines you should have version |
381 |
|
|
1.13.7 at a minimum, with version 1.13.20 or higher recommended. Use |
382 |
|
|
"tar --version" to check your version. Various GNU mirrors have the newest |
383 |
|
|
versions of tar, see for example L<http://www.funet.fi/pub/gnu/alpha/gnu/tar>. |
384 |
|
|
As of June 2003 the latest version is 1.13.25. |
385 |
|
|
|
386 |
|
|
=item * |
387 |
|
|
|
388 |
|
|
If you are using rsync to backup linux/unix machines you should have |
389 |
|
|
version 2.5.5 or higher on each client machine. See |
390 |
|
|
L<http://rsync.samba.org>. Use "rsync --version" to check your version. |
391 |
|
|
|
392 |
|
|
For BackupPC to use Rsync you will also need to install the perl |
393 |
|
|
File::RsyncP module, which is available from |
394 |
|
|
L<http://perlrsync.sourceforge.net>. |
395 |
|
|
Version 0.52 or later is required. |
396 |
|
|
|
397 |
|
|
=item * |
398 |
|
|
|
399 |
|
|
The Apache web server, see L<http://www.apache.org>, preferably built |
400 |
|
|
with mod_perl support. |
401 |
|
|
|
402 |
|
|
=back |
403 |
|
|
|
404 |
|
|
=head2 How much disk space do I need? |
405 |
|
|
|
406 |
|
|
Here's one real example for an environment that is backing up 65 laptops |
407 |
|
|
with compression off. Each full backup averages 3.2GB. Each incremental |
408 |
|
|
backup averages about 0.2GB. Storing one full backup and two incremental |
409 |
|
|
backups per laptop is around 240GB of raw data. But because of the |
410 |
|
|
pooling of identical files, only 87GB is used. This is without |
411 |
|
|
compression. |
412 |
|
|
|
413 |
|
|
Another example, with compression on: backing up 95 laptops, where |
414 |
|
|
each backup averages 3.6GB and each incremental averages about 0.3GB. |
415 |
|
|
Keeping three weekly full backups, and six incrementals is around |
416 |
|
|
1200GB of raw data. Because of pooling and compression, only 150GB |
417 |
|
|
is needed. |
418 |
|
|
|
419 |
|
|
Here's a rule of thumb. Add up the disk usage of all the machines you |
420 |
|
|
want to backup (210GB in the first example above). This is a rough |
421 |
|
|
minimum space estimate that should allow a couple of full backups and at |
422 |
|
|
least half a dozen incremental backups per machine. If compression is on |
423 |
|
|
you can reduce the storage requirements by maybe 30-40%. Add some margin |
424 |
|
|
in case you add more machines or decide to keep more old backups. |
425 |
|
|
|
426 |
|
|
Your actual mileage will depend upon the types of clients, operating |
427 |
|
|
systems and applications you have. The more uniform the clients and |
428 |
|
|
applications the bigger the benefit from pooling common files. |
429 |
|
|
|
430 |
|
|
For example, the Eudora email tool stores each mail folder in a separate |
431 |
|
|
file, and attachments are extracted as separate files. So in the sadly |
432 |
|
|
common case of a large attachment emailed to many recipients, Eudora |
433 |
|
|
will extract the attachment into a new file. When these machines are |
434 |
|
|
backed up, only one copy of the file will be stored on the server, even |
435 |
|
|
though the file appears in many different full or incremental backups. In |
436 |
|
|
this sense Eudora is a "friendly" application from the point of view of |
437 |
|
|
backup storage requirements. |
438 |
|
|
|
439 |
|
|
An example at the other end of the spectrum is Outlook. Everything |
440 |
|
|
(email bodies, attachments, calendar, contact lists) is stored in a |
441 |
|
|
single file, which often becomes huge. Any change to this file requires |
442 |
|
|
a separate copy of the file to be saved during backup. Outlook is even |
443 |
|
|
more troublesome, since it keeps this file locked all the time, so it |
444 |
|
|
cannot be read by smbclient whenever Outlook is running. See the |
445 |
|
|
L<Limitations|limitations> section for more discussion of this problem. |
446 |
|
|
|
447 |
|
|
In addition to total disk space, you shold make sure you have |
448 |
|
|
plenty of inodes on your BackupPC data partition. Some users have |
449 |
|
|
reported running out of inodes on their BackupPC data partition. |
450 |
|
|
So even if you have plenty of disk space, BackupPC will report |
451 |
|
|
failures when the inodes are exhausted. This is a particular |
452 |
|
|
problem with ext2/ext3 file systems that have a fixed number of |
453 |
|
|
inodes when the file system is built. Use "df -i" to see your |
454 |
|
|
inode usage. |
455 |
|
|
|
456 |
|
|
=head2 Step 1: Getting BackupPC |
457 |
|
|
|
458 |
|
|
Some linux distributions now include BackupPC. The Debian |
459 |
|
|
distribution, supprted by Ludovic Drolez, can be found at |
460 |
|
|
L<http://packages.debian.org/backuppc>; it should be included |
461 |
|
|
in the next stable Debian release. On Debian, BackupPC can |
462 |
|
|
be installed with the command: |
463 |
|
|
|
464 |
|
|
apt-get install backuppc |
465 |
|
|
|
466 |
|
|
In the future there might be packages for Gentoo and other |
467 |
|
|
linux flavors. If the packaged version is older than the |
468 |
|
|
released version then you will probably want to install the |
469 |
|
|
lastest version as described below. |
470 |
|
|
|
471 |
|
|
Otherwise, manually fetching and installing BackupPC is easy. |
472 |
|
|
Start by downloading the latest version from |
473 |
|
|
L<http://backuppc.sourceforge.net>. Hit the "Code" button, |
474 |
|
|
then select the "backuppc" or "backuppc-beta" package and |
475 |
|
|
download the latest version. |
476 |
|
|
|
477 |
|
|
=head2 Step 2: Installing the distribution |
478 |
|
|
|
479 |
|
|
First off, there are three perl modules you should install. |
480 |
|
|
These are all optional, but highly recommended: |
481 |
|
|
|
482 |
|
|
=over 4 |
483 |
|
|
|
484 |
|
|
=item Compress::Zlib |
485 |
|
|
|
486 |
|
|
To enable compression, you will need to install Compress::Zlib |
487 |
|
|
from L<http://www.cpan.org>. |
488 |
|
|
You can run "perldoc Compress::Zlib" to see if this module is installed. |
489 |
|
|
|
490 |
|
|
=item Archive::Zip |
491 |
|
|
|
492 |
|
|
To support restore via Zip archives you will need to install |
493 |
|
|
Archive::Zip, also from L<http://www.cpan.org>. |
494 |
|
|
You can run "perldoc Archive::Zip" to see if this module is installed. |
495 |
|
|
|
496 |
|
|
=item File::RsyncP |
497 |
|
|
|
498 |
|
|
To use rsync and rsyncd with BackupPC you will need to install File::RsyncP. |
499 |
|
|
You can run "perldoc File::RsyncP" to see if this module is installed. |
500 |
|
|
File::RsyncP is available from L<http://perlrsync.sourceforge.net>. |
501 |
|
|
Version 0.52 or later is required. |
502 |
|
|
|
503 |
|
|
=back |
504 |
|
|
|
505 |
|
|
To build and install these packages, fetch the tar.gz file and |
506 |
|
|
then run these commands: |
507 |
|
|
|
508 |
|
|
tar zxvf Archive-Zip-1.01.tar.gz |
509 |
|
|
cd Archive-Zip-1.01 |
510 |
|
|
perl Makefile.PL |
511 |
|
|
make |
512 |
|
|
make test |
513 |
|
|
make install |
514 |
|
|
|
515 |
|
|
The same sequence of commands can be used for each module. |
516 |
|
|
|
517 |
|
|
Now let's move onto BackupPC itself. After fetching |
518 |
dpavlin |
316 |
BackupPC-2.1.2.tar.gz, run these commands as root: |
519 |
dpavlin |
1 |
|
520 |
dpavlin |
316 |
tar zxf BackupPC-2.1.2.tar.gz |
521 |
|
|
cd BackupPC-2.1.2 |
522 |
dpavlin |
1 |
perl configure.pl |
523 |
|
|
|
524 |
|
|
In the future this release might also have patches available on the |
525 |
|
|
SourceForge site. These patch files are text files, with a name of |
526 |
|
|
the form |
527 |
|
|
|
528 |
dpavlin |
316 |
BackupPC-2.1.2plN.diff |
529 |
dpavlin |
1 |
|
530 |
|
|
where N is the patch level, eg: pl5 is patch-level 5. These |
531 |
|
|
patch files are cumulative: you only need apply the last patch |
532 |
|
|
file, not all the earlier patch files. If a patch file is |
533 |
dpavlin |
316 |
available, eg: BackupPC-2.1.2pl5.diff, you should apply |
534 |
dpavlin |
1 |
the patch after extracting the tar file: |
535 |
|
|
|
536 |
dpavlin |
316 |
# fetch BackupPC-2.1.2.tar.gz |
537 |
|
|
# fetch BackupPC-2.1.2pl5.diff |
538 |
|
|
tar zxf BackupPC-2.1.2.tar.gz |
539 |
|
|
cd BackupPC-2.1.2 |
540 |
|
|
patch -p0 < ../BackupPC-2.1.2pl5.diff |
541 |
dpavlin |
1 |
perl configure.pl |
542 |
|
|
|
543 |
|
|
A patch file includes comments that describe that bug fixes |
544 |
|
|
and changes. Feel free to review it before you apply the patch. |
545 |
|
|
|
546 |
|
|
The configure.pl script also accepts command-line options if you |
547 |
|
|
wish to run it in a non-interactive manner. It has self-contained |
548 |
|
|
documentation for all the command-line options, which you can |
549 |
|
|
read with perldoc: |
550 |
|
|
|
551 |
|
|
perldoc configure.pl |
552 |
|
|
|
553 |
|
|
When you run configure.pl you will be prompted for the full paths |
554 |
|
|
of various executables, and you will be prompted for the following |
555 |
|
|
information: |
556 |
|
|
|
557 |
|
|
=over 4 |
558 |
|
|
|
559 |
|
|
=item BackupPC User |
560 |
|
|
|
561 |
|
|
It is best if BackupPC runs as a special user, eg backuppc, that has |
562 |
|
|
limited privileges. It is preferred that backuppc belongs to a system |
563 |
|
|
administrator group so that sys admin members can browse backuppc files, |
564 |
|
|
edit the configuration files and so on. Although configurable, the |
565 |
|
|
default settings leave group read permission on pool files, so make |
566 |
|
|
sure the BackupPC user's group is chosen restrictively. |
567 |
|
|
|
568 |
|
|
On this installation, this is __BACKUPPCUSER__. |
569 |
|
|
|
570 |
|
|
=item Data Directory |
571 |
|
|
|
572 |
|
|
You need to decide where to put the data directory, below which |
573 |
|
|
all the BackupPC data is stored. This needs to be a big file system. |
574 |
|
|
|
575 |
|
|
On this installation, this is __TOPDIR__. |
576 |
|
|
|
577 |
|
|
=item Install Directory |
578 |
|
|
|
579 |
|
|
You should decide where the BackupPC scripts, libraries and documentation |
580 |
|
|
should be installed, eg: /opt/local/BackupPC. |
581 |
|
|
|
582 |
|
|
On this installation, this is __INSTALLDIR__. |
583 |
|
|
|
584 |
|
|
=item CGI bin Directory |
585 |
|
|
|
586 |
|
|
You should decide where the BackupPC CGI script resides. This will |
587 |
|
|
usually below Apache's cgi-bin directory. |
588 |
|
|
|
589 |
|
|
On this installation, this is __CGIDIR__. |
590 |
|
|
|
591 |
|
|
=item Apache image directory |
592 |
|
|
|
593 |
|
|
A directory where BackupPC's images are stored so that Apache can |
594 |
|
|
serve them. This should be somewhere under Apache's DocumentRoot |
595 |
|
|
directory. |
596 |
|
|
|
597 |
|
|
=back |
598 |
|
|
|
599 |
|
|
=head2 Step 3: Setting up config.pl |
600 |
|
|
|
601 |
|
|
After running configure.pl, browse through the config file, |
602 |
dpavlin |
316 |
__TOPDIR__/conf/config.pl, and make sure all the default settings |
603 |
dpavlin |
1 |
are correct. In particular, you will need to decide whether to use |
604 |
|
|
smb, tar or rsync transport (or whether to set it on a per-PC basis) |
605 |
|
|
and set the relevant parameters for that transport method. |
606 |
|
|
See the section L<Client Setup|step 5: client setup> for more details. |
607 |
|
|
|
608 |
|
|
=head2 Step 4: Setting up the hosts file |
609 |
|
|
|
610 |
|
|
The file __TOPDIR__/conf/hosts contains the list of clients to backup. |
611 |
|
|
BackupPC reads this file in three cases: |
612 |
|
|
|
613 |
|
|
=over 4 |
614 |
|
|
|
615 |
|
|
=item * |
616 |
|
|
|
617 |
|
|
Upon startup. |
618 |
|
|
|
619 |
|
|
=item * |
620 |
|
|
|
621 |
|
|
When BackupPC is sent a HUP (-1) signal. Assuming you installed the |
622 |
|
|
init.d script, you can also do this with "/etc/init.d/backuppc reload". |
623 |
|
|
|
624 |
|
|
=item * |
625 |
|
|
|
626 |
|
|
When the modification time of the hosts file changes. BackupPC |
627 |
|
|
checks the modification time once during each regular wakeup. |
628 |
|
|
|
629 |
|
|
=back |
630 |
|
|
|
631 |
|
|
Whenever you change the hosts file (to add or remove a host) you can |
632 |
|
|
either do a kill -HUP BackupPC_pid or simply wait until the next regular |
633 |
|
|
wakeup period. |
634 |
|
|
|
635 |
|
|
Each line in the hosts file contains three fields, separated |
636 |
|
|
by white space: |
637 |
|
|
|
638 |
|
|
=over 4 |
639 |
|
|
|
640 |
|
|
=item Host name |
641 |
|
|
|
642 |
|
|
This is typically the host name or NetBios name of the client machine |
643 |
|
|
and should be in lower case. The host name can contain spaces (escape |
644 |
|
|
with a backslash), but it is not recommended. |
645 |
|
|
|
646 |
|
|
Please read the section L<How BackupPC Finds Hosts|how backuppc finds hosts>. |
647 |
|
|
|
648 |
|
|
In certain cases you might want several distinct clients to refer |
649 |
|
|
to the same physical machine. For example, you might have a database |
650 |
|
|
you want to backup, and you want to bracket the backup of the database |
651 |
|
|
with shutdown/restart using $Conf{DumpPreUserCmd} and $Conf{DumpPostUserCmd}. |
652 |
|
|
But you also want to backup the rest of the machine while the database |
653 |
|
|
is still running. In the case you can specify two different clients in |
654 |
|
|
the host file, using any mnemonic name (eg: myhost_mysql and myhost), and |
655 |
|
|
use $Conf{ClientNameAlias} in myhost_mysql's config.pl to specify the |
656 |
|
|
real host name of the machine. |
657 |
|
|
|
658 |
|
|
=item DHCP flag |
659 |
|
|
|
660 |
|
|
Starting with v2.0.0 the way hosts are discovered has changed and now |
661 |
|
|
in most cases you should specify 0 for the DHCP flag, even if the host |
662 |
|
|
has a dynamically assigned IP address. |
663 |
|
|
Please read the section L<How BackupPC Finds Hosts|how backuppc finds hosts> |
664 |
|
|
to understand whether you need to set the DHCP flag. |
665 |
|
|
|
666 |
|
|
You only need to set DHCP to 1 if your client machine doesn't |
667 |
|
|
respond to the NetBios multicast request: |
668 |
|
|
|
669 |
|
|
nmblookup myHost |
670 |
|
|
|
671 |
|
|
but does respond to a request directed to its IP address: |
672 |
|
|
|
673 |
|
|
nmblookup -A W.X.Y.Z |
674 |
|
|
|
675 |
|
|
If you do set DHCP to 1 on any client you will need to specify the range of |
676 |
|
|
DHCP addresses to search is specified in $Conf{DHCPAddressRanges}. |
677 |
|
|
|
678 |
|
|
Note also that the $Conf{ClientNameAlias} feature does not work for |
679 |
|
|
clients with DHCP set to 1. |
680 |
|
|
|
681 |
|
|
=item User name |
682 |
|
|
|
683 |
|
|
This should be the unix login/email name of the user who "owns" or uses |
684 |
|
|
this machine. This is the user who will be sent email about this |
685 |
|
|
machine, and this user will have permission to stop/start/browse/restore |
686 |
|
|
backups for this host. Leave this blank if no specific person should |
687 |
|
|
receive email or be allowed to stop/start/browse/restore backups |
688 |
|
|
for this host. Administrators will still have full permissions. |
689 |
|
|
|
690 |
|
|
=item More users |
691 |
|
|
|
692 |
|
|
Additional user names, separate by commas and with no white space, |
693 |
|
|
can be specified. These users will also have full permission in |
694 |
|
|
the CGI interface to stop/start/browse/restore backups for this host. |
695 |
|
|
These users will not be sent email about this host. |
696 |
|
|
|
697 |
|
|
=back |
698 |
|
|
|
699 |
|
|
The first non-comment line of the hosts file is special: it contains |
700 |
|
|
the names of the columns and should not be edited. |
701 |
|
|
|
702 |
|
|
Here's a simple example of a hosts file: |
703 |
|
|
|
704 |
|
|
host dhcp user moreUsers |
705 |
|
|
farside 0 craig jim,dave |
706 |
|
|
larson 1 gary andy |
707 |
|
|
|
708 |
|
|
=head2 Step 5: Client Setup |
709 |
|
|
|
710 |
|
|
Two methods for getting backup data from a client are supported: smb and |
711 |
|
|
tar. Smb or rsync are the preferred methods for WinXX clients and rsync or |
712 |
|
|
tar are the preferred methods for linux/unix clients. |
713 |
|
|
|
714 |
|
|
The transfer method is set using the $Conf{XferMethod} configuration |
715 |
|
|
setting. If you have a mixed environment (ie: you will use smb for some |
716 |
|
|
clients and tar for others), you will need to pick the most common |
717 |
|
|
choice for $Conf{XferMethod} for the main config.pl file, and then |
718 |
|
|
override it in the per-PC config file for those hosts that will use |
719 |
|
|
the other method. (Or you could run two completely separate instances |
720 |
|
|
of BackupPC, with different data directories, one for WinXX and the |
721 |
|
|
other for linux/unix, but then common files between the different |
722 |
|
|
machine types will duplicated.) |
723 |
|
|
|
724 |
|
|
Here are some brief client setup notes: |
725 |
|
|
|
726 |
|
|
=over 4 |
727 |
|
|
|
728 |
|
|
=item WinXX |
729 |
|
|
|
730 |
|
|
The preferred setup for WinXX clients is to set $Conf{XferMethod} to "smb". |
731 |
|
|
(Actually, for v2.0.0, rsyncd is the better method for WinXX if you are |
732 |
|
|
prepared to run rsync/cygwin on your WinXX client. More information |
733 |
|
|
about this will be provided via the FAQ.) |
734 |
|
|
|
735 |
|
|
If you want to use rsyncd for WinXX clients you can find a pre-packaged |
736 |
|
|
zip file on L<http://backuppc.sourceforge.net>. The package is called |
737 |
|
|
cygwin-rsync. It contains rsync.exe, template setup files and the |
738 |
|
|
minimal set of cygwin libraries for everything to run. The README file |
739 |
|
|
contains instructions for running rsync as a service, so it starts |
740 |
|
|
automatically everytime you boot your machine. |
741 |
|
|
|
742 |
|
|
If you build your own rsync, for rsync 2.6.2 it is strongly |
743 |
|
|
recommended you apply the patch in the cygwin-rsync package on |
744 |
|
|
L<http://backuppc.sourceforge.net>. This patch adds the --checksum-seed |
745 |
|
|
option for checksum caching, and also sends all errors to the client, |
746 |
|
|
which is important so BackupPC can log all file access errors. |
747 |
|
|
|
748 |
|
|
Otherwise, to use SMB, you need to create shares for the data you want |
749 |
|
|
to backup. Open "My Computer", right click on the drive (eg: C), and |
750 |
|
|
select "Sharing..." (or select "Properties" and select the "Sharing" |
751 |
|
|
tab). In this dialog box you can enable sharing, select the share name |
752 |
|
|
and permissions. Many machines will be configured by default to share |
753 |
|
|
the entire C drive as C$ using the administrator password. |
754 |
|
|
|
755 |
|
|
If this machine uses DHCP you will also need to make sure the |
756 |
|
|
NetBios name is set. Go to Control Panel|System|Network Identification |
757 |
|
|
(on Win2K) or Control Panel|System|Computer Name (on WinXP). |
758 |
|
|
Also, you should go to Control Panel|Network Connections|Local Area |
759 |
|
|
Connection|Properties|Internet Protocol (TCP/IP)|Properties|Advanced|WINS |
760 |
|
|
and verify that NetBios is not disabled. |
761 |
|
|
|
762 |
|
|
The relevant configuration settings are $Conf{SmbShareName}, |
763 |
|
|
$Conf{SmbShareUserName}, $Conf{SmbSharePasswd}, $Conf{SmbClientPath}, |
764 |
|
|
$Conf{SmbClientFullCmd}, $Conf{SmbClientIncrCmd} and |
765 |
|
|
$Conf{SmbClientRestoreCmd}. |
766 |
|
|
|
767 |
|
|
BackupPC needs to know the smb share user name and password for a |
768 |
|
|
client machine that uses smb. The user name is specified in |
769 |
|
|
$Conf{SmbShareUserName}. There are four ways to tell BackupPC the |
770 |
|
|
smb share password: |
771 |
|
|
|
772 |
|
|
=over 4 |
773 |
|
|
|
774 |
|
|
=item * |
775 |
|
|
|
776 |
|
|
As an environment variable BPC_SMB_PASSWD set before BackupPC starts. |
777 |
|
|
If you start BackupPC manually the BPC_SMB_PASSWD variable must be set |
778 |
|
|
manually first. For backward compatibility for v1.5.0 and prior, the |
779 |
|
|
environment variable PASSWD can be used if BPC_SMB_PASSWD is not set. |
780 |
|
|
Warning: on some systems it is possible to see environment variables of |
781 |
|
|
running processes. |
782 |
|
|
|
783 |
|
|
=item * |
784 |
|
|
|
785 |
|
|
Alternatively the BPC_SMB_PASSWD setting can be included in |
786 |
|
|
/etc/init.d/backuppc, in which case you must make sure this file |
787 |
|
|
is not world (other) readable. |
788 |
|
|
|
789 |
|
|
=item * |
790 |
|
|
|
791 |
|
|
As a configuration variable $Conf{SmbSharePasswd} in |
792 |
|
|
__TOPDIR__/conf/config.pl. If you put the password |
793 |
|
|
here you must make sure this file is not world (other) readable. |
794 |
|
|
|
795 |
|
|
=item * |
796 |
|
|
|
797 |
|
|
As a configuration variable $Conf{SmbSharePasswd} in the per-PC |
798 |
|
|
configuration file, __TOPDIR__/pc/$host/config.pl. You will have to |
799 |
|
|
use this option if the smb share password is different for each host. |
800 |
|
|
If you put the password here you must make sure this file is not |
801 |
|
|
world (other) readable. |
802 |
|
|
|
803 |
|
|
=back |
804 |
|
|
|
805 |
|
|
Placement and protection of the smb share password is a possible |
806 |
|
|
security risk, so please double-check the file and directory |
807 |
|
|
permissions. In a future version there might be support for |
808 |
|
|
encryption of this password, but a private key will still have to |
809 |
|
|
be stored in a protected place. Suggestions are welcome. |
810 |
|
|
|
811 |
|
|
As an alternative to setting $Conf{XferMethod} to "smb" (using |
812 |
|
|
smbclient) for WinXX clients, you can use an smb network filesystem (eg: |
813 |
|
|
ksmbfs or similar) on your linux/unix server to mount the share, |
814 |
|
|
and then set $Conf{XferMethod} to "tar" (use tar on the network |
815 |
|
|
mounted file system). |
816 |
|
|
|
817 |
|
|
Also, to make sure that file names with 8-bit characters are correctly |
818 |
|
|
transferred by smbclient you should add this to samba's smb.conf file |
819 |
|
|
for samba 2.x: |
820 |
|
|
|
821 |
|
|
[global] |
822 |
|
|
# Accept the windows charset |
823 |
|
|
client code page = 850 |
824 |
|
|
character set = ISO8859-1 |
825 |
|
|
|
826 |
|
|
For samba 3.x this should instead be: |
827 |
|
|
|
828 |
|
|
[global] |
829 |
|
|
unix charset = ISO8859-1 |
830 |
|
|
|
831 |
|
|
This setting should work for western europe. |
832 |
|
|
See L<http://www.oreilly.com/catalog/samba/chapter/book/ch08_03.html> |
833 |
|
|
for more information about settings for other languages. |
834 |
|
|
|
835 |
|
|
=item Linux/Unix |
836 |
|
|
|
837 |
|
|
The preferred setup for linux/unix clients is to set $Conf{XferMethod} |
838 |
|
|
to "rsync", "rsyncd" or "tar". |
839 |
|
|
|
840 |
|
|
You can use either rsync, smb, or tar for linux/unix machines. Smb requires |
841 |
|
|
that the Samba server (smbd) be run to provide the shares. Since the smb |
842 |
|
|
protocol can't represent special files like symbolic links and fifos, |
843 |
|
|
tar and rsync are the better transport methods for linux/unix machines. |
844 |
|
|
(In fact, by default samba makes symbolic links look like the file or |
845 |
|
|
directory that they point to, so you could get an infinite loop if a |
846 |
|
|
symbolic link points to the current or parent directory. If you really |
847 |
|
|
need to use Samba shares for linux/unix backups you should turn off the |
848 |
|
|
"follow symlinks" samba config setting. See the smb.conf manual page.) |
849 |
|
|
|
850 |
|
|
The requirements for each Xfer Method are: |
851 |
|
|
|
852 |
|
|
=over 4 |
853 |
|
|
|
854 |
|
|
=item tar |
855 |
|
|
|
856 |
|
|
You must have GNU tar on the client machine. Use "tar --version" |
857 |
|
|
or "gtar --version" to verify. The version should be at least |
858 |
|
|
1.13.7, and 1.13.20 or greater is recommended. Tar is run on |
859 |
|
|
the client machine via rsh or ssh. |
860 |
|
|
|
861 |
|
|
The relevant configuration settings are $Conf{TarClientPath}, |
862 |
|
|
$Conf{TarShareName}, $Conf{TarClientCmd}, $Conf{TarFullArgs}, |
863 |
|
|
$Conf{TarIncrArgs}, and $Conf{TarClientRestoreCmd}. |
864 |
|
|
|
865 |
|
|
=item rsync |
866 |
|
|
|
867 |
|
|
You should have at least rsync 2.5.5, and the latest version 2.5.6 |
868 |
|
|
is recommended. Rsync is run on the remote client via rsh or ssh. |
869 |
|
|
|
870 |
|
|
The relevant configuration settings are $Conf{RsyncClientPath}, |
871 |
|
|
$Conf{RsyncClientCmd}, $Conf{RsyncClientRestoreCmd}, $Conf{RsyncShareName}, |
872 |
|
|
$Conf{RsyncArgs}, and $Conf{RsyncRestoreArgs}. |
873 |
|
|
|
874 |
|
|
=item rsyncd |
875 |
|
|
|
876 |
|
|
You should have at least rsync 2.5.5, and the latest version 2.6.2 |
877 |
|
|
is recommended. In this case the rsync daemon should be running on |
878 |
|
|
the client machine and BackupPC connects directly to it. |
879 |
|
|
|
880 |
|
|
The relevant configuration settings are $Conf{RsyncdClientPort}, |
881 |
|
|
$Conf{RsyncdUserName}, $Conf{RsyncdPasswd}, $Conf{RsyncdAuthRequired}, |
882 |
|
|
$Conf{RsyncShareName}, $Conf{RsyncArgs}, and $Conf{RsyncRestoreArgs}. |
883 |
|
|
$Conf{RsyncShareName} is the name of an rsync module (ie: the thing |
884 |
|
|
in square brackets in rsyncd's conf file -- see rsyncd.conf), not a |
885 |
|
|
file system path. |
886 |
|
|
|
887 |
|
|
Be aware that rsyncd will remove the leading '/' from path names in |
888 |
|
|
symbolic links if you specify "use chroot = no" in the rsynd.conf file. |
889 |
|
|
See the rsyncd.conf manual page for more information. |
890 |
|
|
|
891 |
|
|
=back |
892 |
|
|
|
893 |
|
|
For linux/unix machines you should not backup "/proc". This directory |
894 |
|
|
contains a variety of files that look like regular files but they are |
895 |
|
|
special files that don't need to be backed up (eg: /proc/kcore is a |
896 |
|
|
regular file that contains physical memory). See $Conf{BackupFilesExclude}. |
897 |
|
|
It is safe to back up /dev since it contains mostly character-special |
898 |
|
|
and block-special files, which are correctly handed by BackupPC |
899 |
|
|
(eg: backing up /dev/hda5 just saves the block-special file information, |
900 |
|
|
not the contents of the disk). |
901 |
|
|
|
902 |
|
|
Alternatively, rather than backup all the file systems as a single |
903 |
|
|
share ("/"), it is easier to restore a single file system if you backup |
904 |
|
|
each file system separately. To do this you should list each file system |
905 |
|
|
mount point in $Conf{TarShareName} or $Conf{RsyncShareName}, and add the |
906 |
|
|
--one-file-system option to $Conf{TarClientCmd} or add --one-file-system |
907 |
|
|
(note the different punctuation) to $Conf{RsyncArgs}. In this case there |
908 |
|
|
is no need to exclude /proc explicitly since it looks like a different |
909 |
|
|
file system. |
910 |
|
|
|
911 |
|
|
Next you should decide whether to run tar over ssh, rsh or nfs. Ssh is |
912 |
|
|
the preferred method. Rsh is not secure and therefore not recommended. |
913 |
|
|
Nfs will work, but you need to make sure that the BackupPC user (running |
914 |
|
|
on the server) has sufficient permissions to read all the files below |
915 |
|
|
the nfs mount. |
916 |
|
|
|
917 |
|
|
Ssh allows BackupPC to run as a privileged user on the client (eg: |
918 |
|
|
root), since it needs sufficient permissions to read all the backup |
919 |
|
|
files. Ssh is setup so that BackupPC on the server (an otherwise low |
920 |
|
|
privileged user) can ssh as root on the client, without being prompted |
921 |
|
|
for a password. There are two common versions of ssh: v1 and v2. Here |
922 |
|
|
are some instructions for one way to setup ssh. (Check which version |
923 |
|
|
of SSH you have by typing "ssh" or "man ssh".) |
924 |
|
|
|
925 |
|
|
=item Mac OS X |
926 |
|
|
|
927 |
|
|
In general this should be similar to Linux/Unix machines. |
928 |
dpavlin |
316 |
Many users have reported success using xtar, which also |
929 |
|
|
backs up the Mac OS X resource forks. |
930 |
|
|
|
931 |
|
|
Other choices include rsync and Mark Stosberg reports that you |
932 |
|
|
can also use hfstar. |
933 |
dpavlin |
1 |
See L<http://fink.sourceforge.net/pdb/package.php/hfstar>. |
934 |
|
|
|
935 |
|
|
=item SSH Setup |
936 |
|
|
|
937 |
|
|
SSH is a secure way to run tar or rsync on a backup client to extract |
938 |
|
|
the data. SSH provides strong authentication and encryption of |
939 |
|
|
the network data. |
940 |
|
|
|
941 |
|
|
Note that if you run rsyncd (rsync daemon), ssh is not used. |
942 |
|
|
In this case, rsyncd provides its own authentication, but there |
943 |
|
|
is no encryption of network data. If you want encryption of |
944 |
|
|
network data you can use ssh to create a tunnel, or use a |
945 |
|
|
program like stunnel. If someone submits instructions I |
946 |
|
|
|
947 |
|
|
Setup instructions for ssh are at |
948 |
|
|
L<http://backuppc.sourceforge.net/faq/ssh.html>. |
949 |
|
|
|
950 |
|
|
=item Clients that use DHCP |
951 |
|
|
|
952 |
|
|
If a client machine uses DHCP BackupPC needs some way to find the |
953 |
|
|
IP address given the host name. One alternative is to set dhcp |
954 |
|
|
to 1 in the hosts file, and BackupPC will search a pool of IP |
955 |
|
|
addresses looking for hosts. More efficiently, it is better to |
956 |
|
|
set dhcp = 0 and provide a mechanism for BackupPC to find the |
957 |
|
|
IP address given the host name. |
958 |
|
|
|
959 |
|
|
For WinXX machines BackupPC uses the NetBios name server to determine |
960 |
|
|
the IP address given the host name. |
961 |
|
|
For unix machines you can run nmbd (the NetBios name server) from |
962 |
|
|
the Samba distribution so that the machine responds to a NetBios |
963 |
|
|
name request. See the manual page and Samba documentation for more |
964 |
|
|
information. |
965 |
|
|
|
966 |
|
|
Alternatively, you can set $Conf{NmbLookupFindHostCmd} to any command |
967 |
|
|
that returns the IP address given the host name. |
968 |
|
|
|
969 |
|
|
Please read the section L<How BackupPC Finds Hosts|how backuppc finds hosts> |
970 |
|
|
for more details. |
971 |
|
|
|
972 |
|
|
=back |
973 |
|
|
|
974 |
|
|
=head2 Step 6: Running BackupPC |
975 |
|
|
|
976 |
|
|
The installation contains an init.d backuppc script that can be copied |
977 |
|
|
to /etc/init.d so that BackupPC can auto-start on boot. |
978 |
|
|
See init.d/README for further instructions. |
979 |
|
|
|
980 |
|
|
BackupPC should be ready to start. If you installed the init.d script, |
981 |
|
|
then you should be able to run BackupPC with: |
982 |
|
|
|
983 |
|
|
/etc/init.d/backuppc start |
984 |
|
|
|
985 |
|
|
(This script can also be invoked with "stop" to stop BackupPC and "reload" |
986 |
|
|
to tell BackupPC to reload config.pl and the hosts file.) |
987 |
|
|
|
988 |
|
|
Otherwise, just run |
989 |
|
|
|
990 |
|
|
__INSTALLDIR__/bin/BackupPC -d |
991 |
|
|
|
992 |
|
|
as user __BACKUPPCUSER__. The -d option tells BackupPC to run as a daemon |
993 |
|
|
(ie: it does an additional fork). |
994 |
|
|
|
995 |
|
|
Any immediate errors will be printed to stderr and BackupPC will quit. |
996 |
|
|
Otherwise, look in __TOPDIR__/log/LOG and verify that BackupPC reports |
997 |
|
|
it has started and all is ok. |
998 |
|
|
|
999 |
|
|
=head2 Step 7: Talking to BackupPC |
1000 |
|
|
|
1001 |
|
|
Note: as of version 1.5.0, BackupPC no longer supports telnet |
1002 |
|
|
to its TCP port. First off, a unix domain socket is used |
1003 |
|
|
instead of a TCP port. (The TCP port can still be re-enabled |
1004 |
|
|
if your installation has apache and BackupPC running on different |
1005 |
|
|
machines.) Secondly, even if you still use the TCP port, the |
1006 |
|
|
messages exchanged over this interface are now protected by |
1007 |
|
|
an MD5 digest based on a shared secret (see $Conf{ServerMesgSecret}) |
1008 |
|
|
as well as sequence numbers and per-session unique keys, preventing |
1009 |
|
|
forgery and replay attacks. |
1010 |
|
|
|
1011 |
|
|
You should verify that BackupPC is running by using BackupPC_serverMesg. |
1012 |
|
|
This sends a message to BackupPC via the unix (or TCP) socket and prints |
1013 |
|
|
the response. |
1014 |
|
|
|
1015 |
|
|
You can request status information and start and stop backups using this |
1016 |
|
|
interface. This socket interface is mainly provided for the CGI interface |
1017 |
|
|
(and some of the BackupPC sub-programs use it too). But right now we just |
1018 |
|
|
want to make sure BackupPC is happy. Each of these commands should |
1019 |
|
|
produce some status output: |
1020 |
|
|
|
1021 |
|
|
__INSTALLDIR__/bin/BackupPC_serverMesg status info |
1022 |
|
|
__INSTALLDIR__/bin/BackupPC_serverMesg status jobs |
1023 |
|
|
__INSTALLDIR__/bin/BackupPC_serverMesg status hosts |
1024 |
|
|
|
1025 |
|
|
The output should be some hashes printed with Data::Dumper. If it |
1026 |
|
|
looks cryptic and confusing, and doesn't look like an error message, |
1027 |
|
|
then all is ok. |
1028 |
|
|
|
1029 |
|
|
The jobs status should initially show just BackupPC_trashClean. |
1030 |
|
|
The hosts status should produce a list of every host you have listed |
1031 |
|
|
in __TOPDIR__/conf/hosts as part of a big cryptic output line. |
1032 |
|
|
|
1033 |
|
|
You can also request that all hosts be queued: |
1034 |
|
|
|
1035 |
|
|
__INSTALLDIR__/bin/BackupPC_serverMesg backup all |
1036 |
|
|
|
1037 |
|
|
At this point you should make sure the CGI interface works since |
1038 |
|
|
it will be much easier to see what is going on. That's our |
1039 |
|
|
next subject. |
1040 |
|
|
|
1041 |
|
|
=head2 Step 8: CGI interface |
1042 |
|
|
|
1043 |
|
|
The CGI interface script, BackupPC_Admin, is a powerful and flexible |
1044 |
|
|
way to see and control what BackupPC is doing. It is written for an |
1045 |
|
|
Apache server. If you don't have Apache, see L<http://www.apache.org>. |
1046 |
|
|
|
1047 |
|
|
There are two options for setting up the CGI interface: standard |
1048 |
|
|
mode and using mod_perl. Mod_perl provides much higher performance |
1049 |
|
|
(around 15x) and is the best choice if your Apache was built with |
1050 |
|
|
mod_perl support. To see if your apache was built with mod_perl |
1051 |
|
|
run this command: |
1052 |
|
|
|
1053 |
|
|
httpd -l | egrep mod_perl |
1054 |
|
|
|
1055 |
|
|
If this prints mod_perl.c then your Apache supports mod_perl. |
1056 |
|
|
|
1057 |
|
|
Using mod_perl with BackupPC_Admin requires a dedicated Apache |
1058 |
|
|
to be run as the BackupPC user (__BACKUPPCUSER__). This is |
1059 |
|
|
because BackupPC_Admin needs permission to access various files |
1060 |
|
|
in BackupPC's data directories. In contrast, the standard |
1061 |
|
|
installation (without mod_perl) solves this problem by having |
1062 |
|
|
BackupPC_Admin installed as setuid to the BackupPC user, so that |
1063 |
|
|
BackupPC_Admin runs as the BackuPC user. |
1064 |
|
|
|
1065 |
|
|
Here are some specifics for each setup: |
1066 |
|
|
|
1067 |
|
|
=over 4 |
1068 |
|
|
|
1069 |
|
|
=item Standard Setup |
1070 |
|
|
|
1071 |
|
|
The CGI interface should have been installed by the configure.pl script |
1072 |
|
|
in __CGIDIR__/BackupPC_Admin. BackupPC_Admin should have been installed |
1073 |
|
|
as setuid to the BackupPC user (__BACKUPPCUSER__), in addition to user |
1074 |
|
|
and group execute permission. |
1075 |
|
|
|
1076 |
|
|
You should be very careful about permissions on BackupPC_Admin and |
1077 |
|
|
the directory __CGIDIR__: it is important that normal users cannot |
1078 |
|
|
directly execute or change BackupPC_Admin, otherwise they can access |
1079 |
|
|
backup files for any PC. You might need to change the group ownership |
1080 |
|
|
of BackupPC_Admin to a group that Apache belongs to so that Apache |
1081 |
|
|
can execute it (don't add "other" execute permission!). |
1082 |
|
|
The permissions should look like this: |
1083 |
|
|
|
1084 |
|
|
ls -l __CGIDIR__/BackupPC_Admin |
1085 |
|
|
-swxr-x--- 1 __BACKUPPCUSER__ web 82406 Jun 17 22:58 __CGIDIR__/BackupPC_Admin |
1086 |
|
|
|
1087 |
|
|
The setuid script won't work unless perl on your machine was installed |
1088 |
|
|
with setuid emulation. This is likely the problem if you get an error |
1089 |
|
|
saying such as "Wrong user: my userid is 25, instead of 150", meaning |
1090 |
|
|
the script is running as the httpd user, not the BackupPC user. |
1091 |
|
|
This is because setuid scripts are disabled by the kernel in most |
1092 |
|
|
flavors of unix and linux. |
1093 |
|
|
|
1094 |
|
|
To see if your perl has setuid emulation, see if there is a program |
1095 |
|
|
called sperl5.6.0 (or sperl5.8.2 etc, based on your perl version) |
1096 |
|
|
in the place where perl is installed. If you can't find this program, |
1097 |
|
|
then you have two options: rebuild and reinstall perl with the setuid |
1098 |
|
|
emulation turned on (answer "y" to the question "Do you want to do |
1099 |
|
|
setuid/setgid emulation?" when you run perl's configure script), or |
1100 |
|
|
switch to the mod_perl alternative for the CGI script (which doesn't |
1101 |
|
|
need setuid to work). |
1102 |
|
|
|
1103 |
|
|
=item Mod_perl Setup |
1104 |
|
|
|
1105 |
|
|
The advantage of the mod_perl setup is that no setuid script is needed, |
1106 |
|
|
and there is a huge performance advantage. Not only does all the perl |
1107 |
|
|
code need to be parsed just once, the config.pl and hosts files, plus |
1108 |
|
|
the connection to the BackupPC server are cached between requests. The |
1109 |
|
|
typical speedup is around 15 times. |
1110 |
|
|
|
1111 |
|
|
To use mod_perl you need to run Apache as user __BACKUPPCUSER__. |
1112 |
|
|
If you need to run multiple Apache's for different services then |
1113 |
|
|
you need to create multiple top-level Apache directories, each |
1114 |
|
|
with their own config file. You can make copies of /etc/init.d/httpd |
1115 |
|
|
and use the -d option to httpd to point each http to a different |
1116 |
|
|
top-level directory. Or you can use the -f option to explicitly |
1117 |
|
|
point to the config file. Multiple Apache's will run on different |
1118 |
|
|
Ports (eg: 80 is standard, 8080 is a typical alternative port accessed |
1119 |
|
|
via http://yourhost.com:8080). |
1120 |
|
|
|
1121 |
|
|
Inside BackupPC's Apache http.conf file you should check the |
1122 |
|
|
settings for ServerRoot, DocumentRoot, User, Group, and Port. See |
1123 |
|
|
L<http://httpd.apache.org/docs/server-wide.html> for more details. |
1124 |
|
|
|
1125 |
|
|
For mod_perl, BackupPC_Admin should not have setuid permission, so |
1126 |
|
|
you should turn it off: |
1127 |
|
|
|
1128 |
|
|
chmod u-s __CGIDIR__/BackupPC_Admin |
1129 |
|
|
|
1130 |
|
|
To tell Apache to use mod_perl to execute BackupPC_Admin, add this |
1131 |
|
|
to Apache's 1.x httpd.conf file: |
1132 |
|
|
|
1133 |
|
|
<IfModule mod_perl.c> |
1134 |
|
|
PerlModule Apache::Registry |
1135 |
|
|
PerlTaintCheck On |
1136 |
|
|
<Location /cgi-bin/BackupPC/BackupPC_Admin> # <--- change path as needed |
1137 |
|
|
SetHandler perl-script |
1138 |
|
|
PerlHandler Apache::Registry |
1139 |
|
|
Options ExecCGI |
1140 |
|
|
PerlSendHeader On |
1141 |
|
|
</Location> |
1142 |
|
|
</IfModule> |
1143 |
|
|
|
1144 |
|
|
Apache 2.0.44 with Perl 5.8.0 on RedHat 7.1, Don Silvia reports that |
1145 |
|
|
this works (with tweaks from Michael Tuzi): |
1146 |
|
|
|
1147 |
|
|
LoadModule perl_module modules/mod_perl.so |
1148 |
|
|
PerlModule Apache2 |
1149 |
|
|
|
1150 |
|
|
<Directory /path/to/cgi/> |
1151 |
|
|
SetHandler perl-script |
1152 |
|
|
PerlResponseHandler ModPerl::Registry |
1153 |
|
|
PerlOptions +ParseHeaders |
1154 |
|
|
Options +ExecCGI |
1155 |
|
|
Order deny,allow |
1156 |
|
|
Deny from all |
1157 |
|
|
Allow from 192.168.0 |
1158 |
|
|
AuthName "Backup Admin" |
1159 |
|
|
AuthType Basic |
1160 |
|
|
AuthUserFile /path/to/user_file |
1161 |
|
|
Require valid-user |
1162 |
|
|
</Directory> |
1163 |
|
|
|
1164 |
|
|
There are other optimizations and options with mod_perl. For |
1165 |
|
|
example, you can tell mod_perl to preload various perl modules, |
1166 |
|
|
which saves memory compared to loading separate copies in every |
1167 |
|
|
Apache process after they are forked. See Stas's definitive |
1168 |
|
|
mod_perl guide at L<http://perl.apache.org/guide>. |
1169 |
|
|
|
1170 |
|
|
=back |
1171 |
|
|
|
1172 |
|
|
BackupPC_Admin requires that users are authenticated by Apache. |
1173 |
|
|
Specifically, it expects that Apache sets the REMOTE_USER environment |
1174 |
|
|
variable when it runs. There are several ways to do this. One way |
1175 |
|
|
is to create a .htaccess file in the cgi-bin directory that looks like: |
1176 |
|
|
|
1177 |
|
|
AuthGroupFile /etc/httpd/conf/group # <--- change path as needed |
1178 |
|
|
AuthUserFile /etc/http/conf/passwd # <--- change path as needed |
1179 |
|
|
AuthType basic |
1180 |
|
|
AuthName "access" |
1181 |
|
|
require valid-user |
1182 |
|
|
|
1183 |
|
|
You will also need "AllowOverride Indexes AuthConfig" in the Apache |
1184 |
|
|
httpd.conf file to enable the .htaccess file. Alternatively, everything |
1185 |
|
|
can go in the Apache httpd.conf file inside a Location directive. The |
1186 |
|
|
list of users and password file above can be extracted from the NIS |
1187 |
|
|
passwd file. |
1188 |
|
|
|
1189 |
|
|
One alternative is to use LDAP. In Apache's http.conf add these lines: |
1190 |
|
|
|
1191 |
|
|
LoadModule auth_ldap_module modules/auth_ldap.so |
1192 |
|
|
AddModule auth_ldap.c |
1193 |
|
|
|
1194 |
|
|
# cgi-bin - auth via LDAP (for BackupPC) |
1195 |
|
|
<Location /cgi-binBackupPC/BackupPC_Admin> # <--- change path as needed |
1196 |
|
|
AuthType Basic |
1197 |
|
|
AuthName "BackupPC login" |
1198 |
|
|
# replace MYDOMAIN, PORT, ORG and CO as needed |
1199 |
|
|
AuthLDAPURL ldap://ldap.MYDOMAIN.com:PORT/o=ORG,c=CO?uid?sub?(objectClass=*) |
1200 |
|
|
require valid-user |
1201 |
|
|
</Location> |
1202 |
|
|
|
1203 |
|
|
If you want to disable the user authentication you can set |
1204 |
|
|
$Conf{CgiAdminUsers} to '*', which allows any user to have |
1205 |
|
|
full access to all hosts and backups. In this case the REMOTE_USER |
1206 |
|
|
environment variable does not have to be set by Apache. |
1207 |
|
|
|
1208 |
|
|
Alternatively, you can force a particular user name by getting Apache |
1209 |
|
|
to set REMOTE_USER, eg, to hardcode the user to www you could add |
1210 |
|
|
this to Apache's httpd.conf: |
1211 |
|
|
|
1212 |
|
|
<Location /cgi-bin/BackupPC/BackupPC_Admin> # <--- change path as needed |
1213 |
|
|
Setenv REMOTE_USER www |
1214 |
|
|
</Location> |
1215 |
|
|
|
1216 |
|
|
Finally, you should also edit the config.pl file and adjust, as necessary, |
1217 |
|
|
the CGI-specific settings. They're near the end of the config file. In |
1218 |
|
|
particular, you should specify which users or groups have administrator |
1219 |
|
|
(privileged) access: see the config settings $Conf{CgiAdminUserGroup} |
1220 |
|
|
and $Conf{CgiAdminUsers}. Also, the configure.pl script placed various |
1221 |
|
|
images into $Conf{CgiImageDir} that BackupPC_Admin needs to serve |
1222 |
|
|
up. You should make sure that $Conf{CgiImageDirURL} is the correct |
1223 |
|
|
URL for the image directory. |
1224 |
|
|
|
1225 |
|
|
See the section L<Fixing installation problems|fixing installation problems> for suggestions on debugging the Apache authentication setup. |
1226 |
|
|
|
1227 |
|
|
=head2 How BackupPC Finds Hosts |
1228 |
|
|
|
1229 |
|
|
Starting with v2.0.0 the way hosts are discovered has changed. In most |
1230 |
|
|
cases you should specify 0 for the DHCP flag in the conf/hosts file, |
1231 |
|
|
even if the host has a dynamically assigned IP address. |
1232 |
|
|
|
1233 |
|
|
BackupPC (starting with v2.0.0) looks up hosts with DHCP = 0 in this manner: |
1234 |
|
|
|
1235 |
|
|
=over 4 |
1236 |
|
|
|
1237 |
|
|
=item * |
1238 |
|
|
|
1239 |
|
|
First DNS is used to lookup the IP address given the client's name |
1240 |
|
|
using perl's gethostbyname() function. This should succeed for machines |
1241 |
|
|
that have fixed IP addresses that are known via DNS. You can manually |
1242 |
|
|
see whether a given host have a DNS entry according to perls' |
1243 |
|
|
gethostbyname function with this command: |
1244 |
|
|
|
1245 |
|
|
perl -e 'print(gethostbyname("myhost") ? "ok\n" : "not found\n");' |
1246 |
|
|
|
1247 |
|
|
=item * |
1248 |
|
|
|
1249 |
|
|
If gethostbyname() fails, BackupPC then attempts a NetBios multicast to |
1250 |
|
|
find the host. Provided your client machine is configured properly, |
1251 |
|
|
it should respond to this NetBios multicast request. Specifically, |
1252 |
|
|
BackupPC runs a command of this form: |
1253 |
|
|
|
1254 |
|
|
nmblookup myhost |
1255 |
|
|
|
1256 |
|
|
If this fails you will see output like: |
1257 |
|
|
|
1258 |
|
|
querying myhost on 10.10.255.255 |
1259 |
|
|
name_query failed to find name myhost |
1260 |
|
|
|
1261 |
|
|
If this success you will see output like: |
1262 |
|
|
|
1263 |
|
|
querying myhost on 10.10.255.255 |
1264 |
|
|
10.10.1.73 myhost<00> |
1265 |
|
|
|
1266 |
|
|
Depending on your netmask you might need to specify the -B option to |
1267 |
|
|
nmblookup. For example: |
1268 |
|
|
|
1269 |
|
|
nmblookup -B 10.10.1.255 myhost |
1270 |
|
|
|
1271 |
|
|
If necessary, experiment on the nmblookup command that will return the |
1272 |
|
|
IP address of the client given its name. Then update |
1273 |
|
|
$Conf{NmbLookupFindHostCmd} with any necessary options to nmblookup. |
1274 |
|
|
|
1275 |
|
|
=back |
1276 |
|
|
|
1277 |
|
|
For hosts that have the DHCP flag set to 1, these machines are |
1278 |
|
|
discovered as follows: |
1279 |
|
|
|
1280 |
|
|
=over 4 |
1281 |
|
|
|
1282 |
|
|
=item * |
1283 |
|
|
|
1284 |
|
|
A DHCP address pool ($Conf{DHCPAddressRanges}) needs to be specified. |
1285 |
|
|
BackupPC will check the NetBIOS name of each machine in the range using |
1286 |
|
|
a command of the form: |
1287 |
|
|
|
1288 |
|
|
nmblookup -A W.X.Y.Z |
1289 |
|
|
|
1290 |
|
|
where W.X.Y.Z is each candidate address from $Conf{DHCPAddressRanges}. |
1291 |
|
|
Any host that has a valid NetBIOS name returned by this command (ie: |
1292 |
|
|
matching an entry in the hosts file) will be backed up. You can |
1293 |
|
|
modify the specific nmblookup command if necessary via $Conf{NmbLookupCmd}. |
1294 |
|
|
|
1295 |
|
|
=item * |
1296 |
|
|
|
1297 |
|
|
You only need to use this DHCP feature if your client machine doesn't |
1298 |
|
|
respond to the NetBios multicast request: |
1299 |
|
|
|
1300 |
|
|
nmblookup myHost |
1301 |
|
|
|
1302 |
|
|
but does respond to a request directed to its IP address: |
1303 |
|
|
|
1304 |
|
|
nmblookup -A W.X.Y.Z |
1305 |
|
|
|
1306 |
|
|
=back |
1307 |
|
|
|
1308 |
|
|
=head2 Other installation topics |
1309 |
|
|
|
1310 |
|
|
=over 4 |
1311 |
|
|
|
1312 |
|
|
=item Removing a client |
1313 |
|
|
|
1314 |
|
|
If there is a machine that no longer needs to be backed up (eg: a retired |
1315 |
|
|
machine) you have two choices. First, you can keep the backups accessible |
1316 |
|
|
and browsable, but disable all new backups. Alternatively, you can |
1317 |
|
|
completely remove the client and all its backups. |
1318 |
|
|
|
1319 |
|
|
To disable backups for a client there are two special values for |
1320 |
|
|
$Conf{FullPeriod} in that client's per-PC config.pl file: |
1321 |
|
|
|
1322 |
|
|
=over 4 |
1323 |
|
|
|
1324 |
|
|
=item -1 |
1325 |
|
|
|
1326 |
|
|
Don't do any regular backups on this machine. Manually |
1327 |
|
|
requested backups (via the CGI interface) will still occur. |
1328 |
|
|
|
1329 |
|
|
=item -2 |
1330 |
|
|
|
1331 |
|
|
Don't do any backups on this machine. Manually requested |
1332 |
|
|
backups (via the CGI interface) will be ignored. |
1333 |
|
|
|
1334 |
|
|
=back |
1335 |
|
|
|
1336 |
|
|
This will still allow that client's old backups to be browsable |
1337 |
|
|
and restorable. |
1338 |
|
|
|
1339 |
|
|
To completely remove a client and all its backups, you should remove its |
1340 |
|
|
entry in the conf/hosts file, and then delete the __TOPDIR__/pc/$host |
1341 |
|
|
directory. Whenever you change the hosts file, you should send |
1342 |
|
|
BackupPC a HUP (-1) signal so that it re-reads the hosts file. |
1343 |
|
|
If you don't do this, BackupPC will automatically re-read the |
1344 |
|
|
hosts file at the next regular wakeup. |
1345 |
|
|
|
1346 |
|
|
Note that when you remove a client's backups you won't initially recover |
1347 |
|
|
a lot of disk space. That's because the client's files are still in |
1348 |
|
|
the pool. Overnight, when BackupPC_nightly next runs, all the unused |
1349 |
|
|
pool files will be deleted and this will recover the disk space used |
1350 |
|
|
by the client's backups. |
1351 |
|
|
|
1352 |
|
|
=item Copying the pool |
1353 |
|
|
|
1354 |
|
|
If the pool disk requirements grow you might need to copy the entire |
1355 |
|
|
data directory to a new (bigger) file system. Hopefully you are lucky |
1356 |
|
|
enough to avoid this by having the data directory on a RAID file system |
1357 |
|
|
or LVM that allows the capacity to be grown in place by adding disks. |
1358 |
|
|
|
1359 |
|
|
The backup data directories contain large numbers of hardlinks. If |
1360 |
|
|
you try to copy the pool the target directory will occupy a lot more |
1361 |
|
|
space if the hardlinks aren't re-established. |
1362 |
|
|
|
1363 |
|
|
The GNU cp program with the -a option is aware of hardlinks and knows |
1364 |
|
|
to re-establish them. So GNU cp -a is the recommended way to copy |
1365 |
|
|
the data directory and pool. Don't forget to stop BackupPC while |
1366 |
|
|
the copy runs. |
1367 |
|
|
|
1368 |
|
|
=item Compressing an existing pool |
1369 |
|
|
|
1370 |
|
|
If you are upgrading BackupPC and want to turn compression on you have |
1371 |
|
|
two choices: |
1372 |
|
|
|
1373 |
|
|
=over 4 |
1374 |
|
|
|
1375 |
|
|
=item * |
1376 |
|
|
|
1377 |
|
|
Simply turn on compression. All new backups will be compressed. Both old |
1378 |
|
|
(uncompressed) and new (compressed) backups can be browsed and viewed. |
1379 |
|
|
Eventually, the old backups will expire and all the pool data will be |
1380 |
|
|
compressed. However, until the old backups expire, this approach could |
1381 |
|
|
require 60% or more additional pool storage space to store both |
1382 |
|
|
uncompressed and compressed versions of the backup files. |
1383 |
|
|
|
1384 |
|
|
=item * |
1385 |
|
|
|
1386 |
|
|
Convert all the uncompressed pool files and backups to compressed. |
1387 |
|
|
The script __INSTALLDIR__/bin/BackupPC_compressPool does this. |
1388 |
|
|
BackupPC must not be running when you run BackupPC_compressPool. |
1389 |
|
|
Also, there must be no existing compressed backups when you |
1390 |
|
|
run BackupPC_compressPool. |
1391 |
|
|
|
1392 |
|
|
BackupPC_compressPool compresses all the files in the uncompressed pool |
1393 |
|
|
(__TOPDIR__/pool) and moves them to the compressed pool |
1394 |
|
|
(__TOPDIR__/cpool). It rewrites the files in place, so that the |
1395 |
|
|
existing hardlinks are not disturbed. |
1396 |
|
|
|
1397 |
|
|
=back |
1398 |
|
|
|
1399 |
|
|
The rest of this section discusses how to run BackupPC_compressPool. |
1400 |
|
|
|
1401 |
|
|
BackupPC_compressPool takes three command line options: |
1402 |
|
|
|
1403 |
|
|
=over 4 |
1404 |
|
|
|
1405 |
|
|
=item -t |
1406 |
|
|
|
1407 |
|
|
Test mode: do everything except actually replace the pool files. |
1408 |
|
|
Useful for estimating total run time without making any real |
1409 |
|
|
changes. |
1410 |
|
|
|
1411 |
|
|
=item -r |
1412 |
|
|
|
1413 |
|
|
Read check: re-read the compressed file and compare it against |
1414 |
|
|
the original uncompressed file. Can only be used in test mode. |
1415 |
|
|
|
1416 |
|
|
=item -c # |
1417 |
|
|
|
1418 |
|
|
Number of children to fork. BackupPC_compressPool can take a long time |
1419 |
|
|
to run, so to speed things up it spawns four children, each working on a |
1420 |
|
|
different part of the pool. You can change the number of children with |
1421 |
|
|
the -c option. |
1422 |
|
|
|
1423 |
|
|
=back |
1424 |
|
|
|
1425 |
|
|
Here are the recommended steps for running BackupPC_compressPool: |
1426 |
|
|
|
1427 |
|
|
=over 4 |
1428 |
|
|
|
1429 |
|
|
=item * |
1430 |
|
|
|
1431 |
|
|
Stop BackupPC (eg: "/etc/init.d/backuppc stop"). |
1432 |
|
|
|
1433 |
|
|
=item * |
1434 |
|
|
|
1435 |
|
|
Set $Conf{CompressLevel} to a non-zero number (eg: 3). |
1436 |
|
|
|
1437 |
|
|
=item * |
1438 |
|
|
|
1439 |
|
|
Do a dry run of BackupPC_compressPool. Make sure you run this as |
1440 |
|
|
the BackupPC user (__BACKUPPCUSER__): |
1441 |
|
|
|
1442 |
|
|
BackupPC_compressPool -t -r |
1443 |
|
|
|
1444 |
|
|
The -t option (test mode) makes BackupPC_compressPool do all the steps, |
1445 |
|
|
but not actually change anything. The -r option re-reads the compressed |
1446 |
|
|
file and compares it against the original. |
1447 |
|
|
|
1448 |
|
|
BackupPC_compressPool gives a status as it completes each 1% of the job. |
1449 |
|
|
It also shows the cumulative compression ratio and estimated completion |
1450 |
|
|
time. Once you are comfortable that things look ok, you can kill |
1451 |
|
|
BackupPC_compressPool or wait for it to finish. |
1452 |
|
|
|
1453 |
|
|
=item * |
1454 |
|
|
|
1455 |
|
|
Now you are ready to run BackupPC_compressPool for real. Once again, |
1456 |
|
|
as the BackupPC user (__BACKUPPCUSER__), run: |
1457 |
|
|
|
1458 |
|
|
BackupPC_compressPool |
1459 |
|
|
|
1460 |
|
|
You should put the output into a file and tail this file. (The running |
1461 |
|
|
time could be twice as long as the test mode since the test mode file |
1462 |
|
|
writes are immediately followed by an unlink, so in test mode it is |
1463 |
|
|
likely the file writes never make it to disk.) |
1464 |
|
|
|
1465 |
|
|
It is B<critical> that BackupPC_compressPool runs to completion before |
1466 |
|
|
re-starting BackupPC. Before BackupPC_compressPool completes, none of |
1467 |
|
|
the existing backups will be in a consistent state. If you must stop |
1468 |
|
|
BackupPC_compressPool for some reason, send it an INT or TERM signal |
1469 |
|
|
and give it several seconds (or more) to clean up gracefully. |
1470 |
|
|
After that, you can re-run BackupPC_compressPool and it will start |
1471 |
|
|
again where it left off. Once again, it is critical that it runs |
1472 |
|
|
to 100% completion. |
1473 |
|
|
|
1474 |
|
|
=back |
1475 |
|
|
|
1476 |
|
|
After BackupPC_compressPool completes you should have a complete set |
1477 |
|
|
of compressed backups (and your disk usage should be lower). You |
1478 |
|
|
can now re-start BackupPC. |
1479 |
|
|
|
1480 |
|
|
=back |
1481 |
|
|
|
1482 |
|
|
=head2 Fixing installation problems |
1483 |
|
|
|
1484 |
|
|
Please see the FAQ at L<http://backuppc.sourceforge.net/faq> for |
1485 |
|
|
debugging suggestions. |
1486 |
|
|
|
1487 |
|
|
=head1 Restore functions |
1488 |
|
|
|
1489 |
|
|
BackupPC supports several different methods for restoring files. The |
1490 |
|
|
most convenient restore options are provided via the CGI interface. |
1491 |
|
|
Alternatively, backup files can be restored using manual commands. |
1492 |
|
|
|
1493 |
|
|
=head2 CGI restore options |
1494 |
|
|
|
1495 |
|
|
By selecting a host in the CGI interface, a list of all the backups |
1496 |
|
|
for that machine will be displayed. By selecting the backup number |
1497 |
|
|
you can navigate the shares and directory tree for that backup. |
1498 |
|
|
|
1499 |
|
|
BackupPC's CGI interface automatically fills incremental backups |
1500 |
|
|
with the corresponding full backup, which means each backup has |
1501 |
|
|
a filled appearance. Therefore, there is no need to do multiple |
1502 |
|
|
restores from the incremental and full backups: BackupPC does all |
1503 |
|
|
the hard work for you. You simply select the files and directories |
1504 |
|
|
you want from the correct backup vintage in one step. |
1505 |
|
|
|
1506 |
|
|
You can download a single backup file at any time simply by selecting |
1507 |
|
|
it. Your browser should prompt you with the file name and ask you |
1508 |
|
|
whether to open the file or save it to disk. |
1509 |
|
|
|
1510 |
|
|
Alternatively, you can select one or more files or directories in |
1511 |
|
|
the currently selected directory and select "Restore selected files". |
1512 |
|
|
(If you need to restore selected files and directories from several |
1513 |
|
|
different parent directories you will need to do that in multiple |
1514 |
|
|
steps.) |
1515 |
|
|
|
1516 |
|
|
If you select all the files in a directory, BackupPC will replace |
1517 |
|
|
the list of files with the parent directory. You will be presented |
1518 |
|
|
with a screen that has three options: |
1519 |
|
|
|
1520 |
|
|
=over 4 |
1521 |
|
|
|
1522 |
|
|
=item Option 1: Direct Restore |
1523 |
|
|
|
1524 |
|
|
With this option the selected files and directories are restored |
1525 |
|
|
directly back onto the host, by default in their original location. |
1526 |
|
|
Any old files with the same name will be overwritten, so use caution. |
1527 |
|
|
You can optionally change the target host name, target share name, |
1528 |
|
|
and target path prefix for the restore, allowing you to restore the |
1529 |
|
|
files to a different location. |
1530 |
|
|
|
1531 |
|
|
Once you select "Start Restore" you will be prompted one last time |
1532 |
|
|
with a summary of the exact source and target files and directories |
1533 |
|
|
before you commit. When you give the final go ahead the restore |
1534 |
|
|
operation will be queued like a normal backup job, meaning that it |
1535 |
|
|
will be deferred if there is a backup currently running for that host. |
1536 |
|
|
When the restore job is run, smbclient, tar, rsync or rsyncd is used |
1537 |
|
|
(depending upon $Conf{XferMethod}) to actually restore the files. |
1538 |
|
|
Sorry, there is currently no option to cancel a restore that has been |
1539 |
|
|
started. |
1540 |
|
|
|
1541 |
|
|
A record of the restore request, including the result and list of |
1542 |
|
|
files and directories, is kept. It can be browsed from the host's |
1543 |
|
|
home page. $Conf{RestoreInfoKeepCnt} specifies how many old restore |
1544 |
|
|
status files to keep. |
1545 |
|
|
|
1546 |
|
|
Note that for direct restore to work, the $Conf{XferMethod} must |
1547 |
|
|
be able to write to the client. For example, that means an SMB |
1548 |
|
|
share for smbclient needs to be writable, and the rsyncd module |
1549 |
dpavlin |
316 |
needs "read only" set to "false". This creates additional security |
1550 |
dpavlin |
1 |
risks. If you only create read-only SMB shares (which is a good |
1551 |
|
|
idea), then the direct restore will fail. You can disable the |
1552 |
|
|
direct restore option by setting $Conf{SmbClientRestoreCmd}, |
1553 |
|
|
$Conf{TarClientRestoreCmd} and $Conf{RsyncRestoreArgs} to undef. |
1554 |
|
|
|
1555 |
|
|
=item Option 2: Download Zip archive |
1556 |
|
|
|
1557 |
|
|
With this option a zip file containing the selected files and directories |
1558 |
|
|
is downloaded. The zip file can then be unpacked or individual files |
1559 |
|
|
extracted as necessary on the host machine. The compression level can be |
1560 |
|
|
specified. A value of 0 turns off compression. |
1561 |
|
|
|
1562 |
|
|
When you select "Download Zip File" you should be prompted where to |
1563 |
|
|
save the restore.zip file. |
1564 |
|
|
|
1565 |
|
|
BackupPC does not consider downloading a zip file as an actual |
1566 |
|
|
restore operation, so the details are not saved for later browsing |
1567 |
|
|
as in the first case. However, a mention that a zip file was |
1568 |
|
|
downloaded by a particular user, and a list of the files, does |
1569 |
|
|
appear in BackupPC's log file. |
1570 |
|
|
|
1571 |
|
|
=item Option 3: Download Tar archive |
1572 |
|
|
|
1573 |
|
|
This is identical to the previous option, except a tar file is downloaded |
1574 |
|
|
rather than a zip file (and there is currently no compression option). |
1575 |
|
|
|
1576 |
|
|
=back |
1577 |
|
|
|
1578 |
|
|
=head2 Command-line restore options |
1579 |
|
|
|
1580 |
|
|
Apart from the CGI interface, BackupPC allows you to restore files |
1581 |
|
|
and directories from the command line. The following programs can |
1582 |
|
|
be used: |
1583 |
|
|
|
1584 |
|
|
=over 4 |
1585 |
|
|
|
1586 |
|
|
=item BackupPC_zcat |
1587 |
|
|
|
1588 |
|
|
For each file name argument it inflates (uncompresses) the file and |
1589 |
|
|
writes it to stdout. To use BackupPC_zcat you could give it the |
1590 |
|
|
full file name, eg: |
1591 |
|
|
|
1592 |
|
|
__INSTALLDIR__/bin/BackupPC_zcat __TOPDIR__/pc/host/5/fc/fcraig/fexample.txt > example.txt |
1593 |
|
|
|
1594 |
|
|
It's your responsibility to make sure the file is really compressed: |
1595 |
|
|
BackupPC_zcat doesn't check which backup the requested file is from. |
1596 |
|
|
BackupPC_zcat returns a non-zero status if it fails to uncompress |
1597 |
|
|
a file. |
1598 |
|
|
|
1599 |
|
|
=item BackupPC_tarCreate |
1600 |
|
|
|
1601 |
|
|
BackupPC_tarCreate creates a tar file for any files or directories in |
1602 |
|
|
a particular backup. Merging of incrementals is done automatically, |
1603 |
|
|
so you don't need to worry about whether certain files appear in the |
1604 |
|
|
incremental or full backup. |
1605 |
|
|
|
1606 |
|
|
The usage is: |
1607 |
|
|
|
1608 |
|
|
BackupPC_tarCreate [-t] [-h host] [-n dumpNum] [-s shareName] |
1609 |
|
|
[-r pathRemove] [-p pathAdd] [-b BLOCKS] [-w writeBufSz] |
1610 |
|
|
files/directories... |
1611 |
|
|
|
1612 |
|
|
The command-line files and directories are relative to the specified |
1613 |
|
|
shareName. The tar file is written to stdout. |
1614 |
|
|
|
1615 |
|
|
The required options are: |
1616 |
|
|
|
1617 |
|
|
=over 4 |
1618 |
|
|
|
1619 |
|
|
=item -h host |
1620 |
|
|
|
1621 |
|
|
host from which the tar archive is created |
1622 |
|
|
|
1623 |
|
|
=item -n dumpNum |
1624 |
|
|
|
1625 |
|
|
dump number from which the tar archive is created |
1626 |
|
|
|
1627 |
|
|
=item -s shareName |
1628 |
|
|
|
1629 |
|
|
share name from which the tar archive is created |
1630 |
|
|
|
1631 |
|
|
=back |
1632 |
|
|
|
1633 |
|
|
Other options are: |
1634 |
|
|
|
1635 |
|
|
=over 4 |
1636 |
|
|
|
1637 |
|
|
=item -t |
1638 |
|
|
|
1639 |
|
|
print summary totals |
1640 |
|
|
|
1641 |
|
|
=item -r pathRemove |
1642 |
|
|
|
1643 |
|
|
path prefix that will be replaced with pathAdd |
1644 |
|
|
|
1645 |
|
|
=item -p pathAdd |
1646 |
|
|
|
1647 |
|
|
new path prefix |
1648 |
|
|
|
1649 |
|
|
=item -b BLOCKS |
1650 |
|
|
|
1651 |
|
|
the tar block size, default is 20, meaning tar writes data in 20 * 512 |
1652 |
|
|
bytes chunks. |
1653 |
|
|
|
1654 |
|
|
=item -w writeBufSz |
1655 |
|
|
|
1656 |
|
|
write buffer size, default 1048576 (1MB). You can increase this if |
1657 |
|
|
you are trying to stream to a fast tape device. |
1658 |
|
|
|
1659 |
|
|
=back |
1660 |
|
|
|
1661 |
|
|
The -h, -n and -s options specify which dump is used to generate |
1662 |
|
|
the tar archive. The -r and -p options can be used to relocate |
1663 |
|
|
the paths in the tar archive so extracted files can be placed |
1664 |
|
|
in a location different from their original location. |
1665 |
|
|
|
1666 |
|
|
=item BackupPC_zipCreate |
1667 |
|
|
|
1668 |
|
|
BackupPC_zipCreate creates a zip file for any files or directories in |
1669 |
|
|
a particular backup. Merging of incrementals is done automatically, |
1670 |
|
|
so you don't need to worry about whether certain files appear in the |
1671 |
|
|
incremental or full backup. |
1672 |
|
|
|
1673 |
|
|
The usage is: |
1674 |
|
|
|
1675 |
|
|
BackupPC_zipCreate [-t] [-h host] [-n dumpNum] [-s shareName] |
1676 |
|
|
[-r pathRemove] [-p pathAdd] [-c compressionLevel] |
1677 |
|
|
files/directories... |
1678 |
|
|
|
1679 |
|
|
The command-line files and directories are relative to the specified |
1680 |
|
|
shareName. The zip file is written to stdout. |
1681 |
|
|
|
1682 |
|
|
The required options are: |
1683 |
|
|
|
1684 |
|
|
=over 4 |
1685 |
|
|
|
1686 |
|
|
=item -h host |
1687 |
|
|
|
1688 |
|
|
host from which the zip archive is created |
1689 |
|
|
|
1690 |
|
|
=item -n dumpNum |
1691 |
|
|
|
1692 |
|
|
dump number from which the zip archive is created |
1693 |
|
|
|
1694 |
|
|
=item -s shareName |
1695 |
|
|
|
1696 |
|
|
share name from which the zip archive is created |
1697 |
|
|
|
1698 |
|
|
=back |
1699 |
|
|
|
1700 |
|
|
Other options are: |
1701 |
|
|
|
1702 |
|
|
=over 4 |
1703 |
|
|
|
1704 |
|
|
=item -t |
1705 |
|
|
|
1706 |
|
|
print summary totals |
1707 |
|
|
|
1708 |
|
|
=item -r pathRemove |
1709 |
|
|
|
1710 |
|
|
path prefix that will be replaced with pathAdd |
1711 |
|
|
|
1712 |
|
|
=item -p pathAdd |
1713 |
|
|
|
1714 |
|
|
new path prefix |
1715 |
|
|
|
1716 |
|
|
=item -c level |
1717 |
|
|
|
1718 |
|
|
compression level (default is 0, no compression) |
1719 |
|
|
|
1720 |
|
|
=back |
1721 |
|
|
|
1722 |
|
|
The -h, -n and -s options specify which dump is used to generate |
1723 |
|
|
the zip archive. The -r and -p options can be used to relocate |
1724 |
|
|
the paths in the zip archive so extracted files can be placed |
1725 |
|
|
in a location different from their original location. |
1726 |
|
|
|
1727 |
|
|
=back |
1728 |
|
|
|
1729 |
|
|
Each of these programs reside in __INSTALLDIR__/bin. |
1730 |
|
|
|
1731 |
|
|
=head1 Archive functions |
1732 |
|
|
|
1733 |
|
|
BackupPC supports archiving to removable media. For users that require |
1734 |
|
|
offsite backups, BackupPC can create archives that stream to tape |
1735 |
|
|
devices, or create files of specified sizes to fit onto cd or dvd media. |
1736 |
|
|
|
1737 |
|
|
Each archive type is specified by a BackupPC host with its XferMethod |
1738 |
|
|
set to 'archive'. This allows for multiple configurations at sites where |
1739 |
|
|
there might be a combination of tape and cd/dvd backups being made. |
1740 |
|
|
|
1741 |
|
|
BackupPC provides a menu that allows one or more hosts to be archived. |
1742 |
|
|
The most recent backup of each host is archived using BackupPC_tarCreate, |
1743 |
|
|
and the output is optionally compressed and split into fixed-sized |
1744 |
|
|
files (eg: 650MB). |
1745 |
|
|
|
1746 |
|
|
The archive for each host is done by default using |
1747 |
|
|
__INSTALLDIR__/BackupPC_archiveHost. This script can be copied |
1748 |
|
|
and customized as needed. |
1749 |
|
|
|
1750 |
|
|
=head2 Configuring an Archive Host |
1751 |
|
|
|
1752 |
|
|
To create an Archive Host, add it to the hosts file just as any other host |
1753 |
|
|
and call it a name that best describes the type of archive, e.g. ArchiveDLT |
1754 |
|
|
|
1755 |
|
|
To tell BackupPC that the Host is for Archives, create a config.pl file in |
1756 |
|
|
the Archive Hosts's pc directory, adding the following line: |
1757 |
|
|
|
1758 |
|
|
$Conf{XferMethod} = 'archive'; |
1759 |
|
|
|
1760 |
|
|
To further customise the archive's parameters you can adding the changed |
1761 |
|
|
parameters in the host's config.pl file. The parameters are explained in |
1762 |
|
|
the config.pl file. Parameters may be fixed or the user can be allowed |
1763 |
|
|
to change them (eg: output device). |
1764 |
|
|
|
1765 |
|
|
The per-host archive command is $Conf{ArchiveClientCmd}. By default |
1766 |
|
|
this invokes |
1767 |
|
|
|
1768 |
|
|
__INSTALLDIR__/BackupPC_archiveHost |
1769 |
|
|
|
1770 |
|
|
which you can copy and customize as necessary. |
1771 |
|
|
|
1772 |
|
|
=head2 Starting an Archive |
1773 |
|
|
|
1774 |
|
|
In the web interface, click on the Archive Host you wish to use. You will see a |
1775 |
|
|
list of previous archives and a summary on each. By clicking the "Start Archive" |
1776 |
|
|
button you are presented with the list of hosts and the approximate backup size |
1777 |
|
|
(note this is raw size, not projected compressed size) Select the hosts you wish |
1778 |
|
|
to archive and press the "Archive Selected Hosts" button. |
1779 |
|
|
|
1780 |
|
|
The next screen allows you to adjust the parameters for this archive run. |
1781 |
|
|
Press the "Start the Archive" to start archiving the selected hosts with the |
1782 |
|
|
parameters displayed. |
1783 |
|
|
|
1784 |
|
|
=head1 BackupPC Design |
1785 |
|
|
|
1786 |
|
|
=head2 Some design issues |
1787 |
|
|
|
1788 |
|
|
=over 4 |
1789 |
|
|
|
1790 |
|
|
=item Pooling common files |
1791 |
|
|
|
1792 |
|
|
To quickly see if a file is already in the pool, an MD5 digest of the |
1793 |
|
|
file length and contents is used as the file name in the pool. This |
1794 |
|
|
can't guarantee a file is identical: it just reduces the search to |
1795 |
|
|
often a single file or handful of files. A complete file comparison |
1796 |
|
|
is always done to verify if two files are really the same. |
1797 |
|
|
|
1798 |
|
|
Identical files on multiples backups are represented by hard links. |
1799 |
|
|
Hardlinks are used so that identical files all refer to the same |
1800 |
|
|
physical file on the server's disk. Also, hard links maintain |
1801 |
|
|
reference counts so that BackupPC knows when to delete unused files |
1802 |
|
|
from the pool. |
1803 |
|
|
|
1804 |
|
|
For the computer-science majors among you, you can think of the pooling |
1805 |
|
|
system used by BackupPC as just a chained hash table stored on a (big) |
1806 |
|
|
file system. |
1807 |
|
|
|
1808 |
|
|
=item The hashing function |
1809 |
|
|
|
1810 |
|
|
There is a tradeoff between how much of file is used for the MD5 digest |
1811 |
|
|
and the time taken comparing all the files that have the same hash. |
1812 |
|
|
|
1813 |
|
|
Using the file length and just the first 4096 bytes of the file for the |
1814 |
|
|
MD5 digest produces some repetitions. One example: with 900,000 unique |
1815 |
|
|
files in the pool, this hash gives about 7,000 repeated files, and in |
1816 |
|
|
the worst case 500 files have the same hash. That's not bad: we only |
1817 |
|
|
have to do a single file compare 99.2% of the time. But in the worst |
1818 |
|
|
case we have to compare as many as 500 files checking for a match. |
1819 |
|
|
|
1820 |
|
|
With a modest increase in CPU time, if we use the file length and the |
1821 |
|
|
first 256K of the file we now only have 500 repeated files and in the |
1822 |
|
|
worst case around 20 files have the same hash. Furthermore, if we |
1823 |
|
|
instead use the first and last 128K of the file (more specifically, the |
1824 |
|
|
first and eighth 128K chunks for files larger than 1MB) we get only 300 |
1825 |
|
|
repeated files and in the worst case around 20 files have the same hash. |
1826 |
|
|
|
1827 |
|
|
Based on this experimentation, this is the hash function used by BackupPC. |
1828 |
|
|
It is important that you don't change the hash function after files |
1829 |
|
|
are already in the pool. Otherwise your pool will grow to twice the |
1830 |
|
|
size until all the old backups (and all the old files with old hashes) |
1831 |
|
|
eventually expire. |
1832 |
|
|
|
1833 |
|
|
=item Compression |
1834 |
|
|
|
1835 |
|
|
BackupPC supports compression. It uses the deflate and inflate methods |
1836 |
|
|
in the Compress::Zlib module, which is based on the zlib compression |
1837 |
|
|
library (see L<http://www.gzip.org/zlib/>). |
1838 |
|
|
|
1839 |
|
|
The $Conf{CompressLevel} setting specifies the compression level to use. |
1840 |
|
|
Zero (0) means no compression. Compression levels can be from 1 (least |
1841 |
|
|
cpu time, slightly worse compression) to 9 (most cpu time, slightly |
1842 |
|
|
better compression). The recommended value is 3. Changing it to 5, for |
1843 |
|
|
example, will take maybe 20% more cpu time and will get another 2-3% |
1844 |
|
|
additional compression. Diminishing returns set in above 5. See the zlib |
1845 |
|
|
documentation for more information about compression levels. |
1846 |
|
|
|
1847 |
|
|
BackupPC implements compression with minimal CPU load. Rather than |
1848 |
|
|
compressing every incoming backup file and then trying to match it |
1849 |
|
|
against the pool, BackupPC computes the MD5 digest based on the |
1850 |
|
|
uncompressed file, and matches against the candidate pool files by |
1851 |
|
|
comparing each uncompressed pool file against the incoming backup file. |
1852 |
|
|
Since inflating a file takes roughly a factor of 10 less CPU time than |
1853 |
|
|
deflating there is a big saving in CPU time. |
1854 |
|
|
|
1855 |
|
|
The combination of pooling common files and compression can yield |
1856 |
|
|
a factor of 8 or more overall saving in backup storage. |
1857 |
|
|
|
1858 |
|
|
=back |
1859 |
|
|
|
1860 |
|
|
=head2 BackupPC operation |
1861 |
|
|
|
1862 |
|
|
BackupPC reads the configuration information from |
1863 |
|
|
__TOPDIR__/conf/config.pl. It then runs and manages all the backup |
1864 |
|
|
activity. It maintains queues of pending backup requests, user backup |
1865 |
|
|
requests and administrative commands. Based on the configuration various |
1866 |
|
|
requests will be executed simultaneously. |
1867 |
|
|
|
1868 |
|
|
As specified by $Conf{WakeupSchedule}, BackupPC wakes up periodically |
1869 |
|
|
to queue backups on all the PCs. This is a four step process: |
1870 |
|
|
|
1871 |
|
|
=over 4 |
1872 |
|
|
|
1873 |
|
|
=item 1 |
1874 |
|
|
|
1875 |
|
|
For each host and DHCP address backup requests are queued on the |
1876 |
|
|
background command queue. |
1877 |
|
|
|
1878 |
|
|
=item 2 |
1879 |
|
|
|
1880 |
|
|
For each PC, BackupPC_dump is forked. Several of these may be run in |
1881 |
|
|
parallel, based on the configuration. First a ping is done to see if |
1882 |
|
|
the machine is alive. If this is a DHCP address, nmblookup is run to |
1883 |
|
|
get the netbios name, which is used as the host name. If DNS lookup |
1884 |
|
|
fails, $Conf{NmbLookupFindHostCmd} is run to find the IP address from |
1885 |
|
|
the host name. The file __TOPDIR__/pc/$host/backups is read to decide |
1886 |
|
|
whether a full or incremental backup needs to be run. If no backup is |
1887 |
|
|
scheduled, or the ping to $host fails, then BackupPC_dump exits. |
1888 |
|
|
|
1889 |
|
|
The backup is done using the specified XferMethod. Either samba's smbclient |
1890 |
|
|
or tar over ssh/rsh/nfs piped into BackupPC_tarExtract, or rsync over ssh/rsh |
1891 |
|
|
is run, or rsyncd is connected to, with the incoming data |
1892 |
|
|
extracted to __TOPDIR__/pc/$host/new. The XferMethod output is put |
1893 |
|
|
into __TOPDIR__/pc/$host/XferLOG. |
1894 |
|
|
|
1895 |
|
|
The letter in the XferLOG file shows the type of object, similar to the |
1896 |
|
|
first letter of the modes displayed by ls -l: |
1897 |
|
|
|
1898 |
|
|
d -> directory |
1899 |
|
|
l -> symbolic link |
1900 |
|
|
b -> block special file |
1901 |
|
|
c -> character special file |
1902 |
|
|
p -> pipe file (fifo) |
1903 |
|
|
nothing -> regular file |
1904 |
|
|
|
1905 |
|
|
The words mean: |
1906 |
|
|
|
1907 |
|
|
=over 4 |
1908 |
|
|
|
1909 |
|
|
=item create |
1910 |
|
|
|
1911 |
|
|
new for this backup (ie: directory or file not in pool) |
1912 |
|
|
|
1913 |
|
|
=item pool |
1914 |
|
|
|
1915 |
|
|
found a match in the pool |
1916 |
|
|
|
1917 |
|
|
=item same |
1918 |
|
|
|
1919 |
|
|
file is identical to previous backup (contents were |
1920 |
|
|
checksummed and verified during full dump). |
1921 |
|
|
|
1922 |
|
|
=item skip |
1923 |
|
|
|
1924 |
|
|
file skipped in incremental because attributes are the |
1925 |
|
|
same (only displayed if $Conf{XferLogLevel} >= 2). |
1926 |
|
|
|
1927 |
|
|
=back |
1928 |
|
|
|
1929 |
|
|
As BackupPC_tarExtract extracts the files from smbclient or tar, or as |
1930 |
|
|
rsync runs, it checks each file in the backup to see if it is identical |
1931 |
|
|
to an existing file from any previous backup of any PC. It does this |
1932 |
|
|
without needed to write the file to disk. If the file matches an |
1933 |
|
|
existing file, a hardlink is created to the existing file in the pool. |
1934 |
|
|
If the file does not match any existing files, the file is written to |
1935 |
|
|
disk and the file name is saved in __TOPDIR__/pc/$host/NewFileList for |
1936 |
|
|
later processing by BackupPC_link. BackupPC_tarExtract and rsync can handle |
1937 |
|
|
arbitrarily large files and multiple candidate matching files without |
1938 |
|
|
needing to write the file to disk in the case of a match. This |
1939 |
|
|
significantly reduces disk writes (and also reads, since the pool file |
1940 |
|
|
comparison is done disk to memory, rather than disk to disk). |
1941 |
|
|
|
1942 |
|
|
Based on the configuration settings, BackupPC_dump checks each |
1943 |
|
|
old backup to see if any should be removed. Any expired backups |
1944 |
|
|
are moved to __TOPDIR__/trash for later removal by BackupPC_trashClean. |
1945 |
|
|
|
1946 |
|
|
=item 3 |
1947 |
|
|
|
1948 |
|
|
For each complete, good, backup, BackupPC_link is run. |
1949 |
|
|
To avoid race conditions as new files are linked into the |
1950 |
|
|
pool area, only a single BackupPC_link program runs |
1951 |
|
|
at a time and the rest are queued. |
1952 |
|
|
|
1953 |
|
|
BackupPC_link reads the NewFileList written by BackupPC_dump and |
1954 |
|
|
inspects each new file in the backup. It re-checks if there is a |
1955 |
|
|
matching file in the pool (another BackupPC_link |
1956 |
|
|
could have added the file since BackupPC_dump checked). If so, the file |
1957 |
|
|
is removed and replaced by a hard link to the existing file. If the file |
1958 |
|
|
is new, a hard link to the file is made in the pool area, so that this |
1959 |
|
|
file is available for checking against each new file and new backup. |
1960 |
|
|
|
1961 |
|
|
Then, if $Conf{IncrFill} is set (note that the default setting is |
1962 |
|
|
off), for each incremental backup, hard links are made in the new |
1963 |
|
|
backup to all files that were not extracted during the incremental |
1964 |
|
|
backups. The means the incremental backup looks like a complete |
1965 |
|
|
image of the PC (with the exception that files that were removed on |
1966 |
|
|
the PC since the last full backup will still appear in the backup |
1967 |
|
|
directory tree). |
1968 |
|
|
|
1969 |
|
|
The CGI interface knows how to merge unfilled incremental backups will |
1970 |
|
|
the most recent prior filled (full) backup, giving the incremental |
1971 |
|
|
backups a filled appearance. The default for $Conf{IncrFill} is off, |
1972 |
|
|
since there is no need to fill incremental backups. This saves |
1973 |
|
|
some level of disk activity, since lots of extra hardlinks are no |
1974 |
|
|
longer needed (and don't have to be deleted when the backup expires). |
1975 |
|
|
|
1976 |
|
|
=item 4 |
1977 |
|
|
|
1978 |
|
|
BackupPC_trashClean is always run in the background to remove any |
1979 |
|
|
expired backups. Every 5 minutes it wakes up and removes all the files |
1980 |
|
|
in __TOPDIR__/trash. |
1981 |
|
|
|
1982 |
|
|
Also, once each night, BackupPC_nightly is run to complete some additional |
1983 |
|
|
administrative tasks, such as cleaning the pool. This involves removing |
1984 |
|
|
any files in the pool that only have a single hard link (meaning no backups |
1985 |
|
|
are using that file). Again, to avoid race conditions, BackupPC_nightly |
1986 |
|
|
is only run when there are no BackupPC_dump or BackupPC_link processes |
1987 |
|
|
running. Therefore, when it is time to run BackupPC_nightly, no new |
1988 |
|
|
backups are started and BackupPC waits until all backups have finished. |
1989 |
|
|
Then BackupPC_nightly is run, and until it finishes no new backups are |
1990 |
dpavlin |
316 |
started. If BackupPC_nightly takes too long to run, the settings |
1991 |
|
|
$Conf{MaxBackupPCNightlyJobs} and $Conf{BackupPCNightlyPeriod} can |
1992 |
|
|
be used to run several BackupPC_nightly processes in parallel, and |
1993 |
|
|
to split its job over several nights. |
1994 |
dpavlin |
1 |
|
1995 |
|
|
=back |
1996 |
|
|
|
1997 |
|
|
BackupPC also listens for TCP connections on $Conf{ServerPort}, which |
1998 |
|
|
is used by the CGI script BackupPC_Admin for status reporting and |
1999 |
|
|
user-initiated backup or backup cancel requests. |
2000 |
|
|
|
2001 |
|
|
=head2 Storage layout |
2002 |
|
|
|
2003 |
|
|
BackupPC resides in three directories: |
2004 |
|
|
|
2005 |
|
|
=over 4 |
2006 |
|
|
|
2007 |
|
|
=item __INSTALLDIR__ |
2008 |
|
|
|
2009 |
|
|
Perl scripts comprising BackupPC reside in __INSTALLDIR__/bin, |
2010 |
|
|
libraries are in __INSTALLDIR__/lib and documentation |
2011 |
|
|
is in __INSTALLDIR__/doc. |
2012 |
|
|
|
2013 |
|
|
=item __CGIDIR__ |
2014 |
|
|
|
2015 |
|
|
The CGI script BackupPC_Admin resides in this cgi binary directory. |
2016 |
|
|
|
2017 |
|
|
=item __TOPDIR__ |
2018 |
|
|
|
2019 |
|
|
All of BackupPC's data (PC backup images, logs, configuration information) |
2020 |
|
|
is stored below this directory. |
2021 |
|
|
|
2022 |
|
|
=back |
2023 |
|
|
|
2024 |
|
|
Below __TOPDIR__ are several directories: |
2025 |
|
|
|
2026 |
|
|
=over 4 |
2027 |
|
|
|
2028 |
|
|
=item __TOPDIR__/conf |
2029 |
|
|
|
2030 |
|
|
The directory __TOPDIR__/conf contains: |
2031 |
|
|
|
2032 |
|
|
=over 4 |
2033 |
|
|
|
2034 |
|
|
=item config.pl |
2035 |
|
|
|
2036 |
|
|
Configuration file. See L<Configuration file|configuration file> |
2037 |
|
|
below for more details. |
2038 |
|
|
|
2039 |
|
|
=item hosts |
2040 |
|
|
|
2041 |
|
|
Hosts file, which lists all the PCs to backup. |
2042 |
|
|
|
2043 |
|
|
=back |
2044 |
|
|
|
2045 |
|
|
=item __TOPDIR__/log |
2046 |
|
|
|
2047 |
|
|
The directory __TOPDIR__/log contains: |
2048 |
|
|
|
2049 |
|
|
=over 4 |
2050 |
|
|
|
2051 |
|
|
=item LOG |
2052 |
|
|
|
2053 |
|
|
Current (today's) log file output from BackupPC. |
2054 |
|
|
|
2055 |
|
|
=item LOG.0 or LOG.0.z |
2056 |
|
|
|
2057 |
|
|
Yesterday's log file output. Log files are aged daily and compressed |
2058 |
|
|
(if compression is enabled), and old LOG files are deleted. |
2059 |
|
|
|
2060 |
|
|
=item BackupPC.pid |
2061 |
|
|
|
2062 |
|
|
Contains BackupPC's process id. |
2063 |
|
|
|
2064 |
|
|
=item status.pl |
2065 |
|
|
|
2066 |
|
|
A summary of BackupPC's status written periodically by BackupPC so |
2067 |
|
|
that certain state information can be maintained if BackupPC is |
2068 |
|
|
restarted. Should not be edited. |
2069 |
|
|
|
2070 |
|
|
=item UserEmailInfo.pl |
2071 |
|
|
|
2072 |
|
|
A summary of what email was last sent to each user, and when the |
2073 |
|
|
last email was sent. Should not be edited. |
2074 |
|
|
|
2075 |
|
|
=back |
2076 |
|
|
|
2077 |
|
|
=item __TOPDIR__/trash |
2078 |
|
|
|
2079 |
|
|
Any directories and files below this directory are periodically deleted |
2080 |
|
|
whenever BackupPC_trashClean checks. When a backup is aborted or when an |
2081 |
|
|
old backup expires, BackupPC_dump simply moves the directory to |
2082 |
|
|
__TOPDIR__/trash for later removal by BackupPC_trashClean. |
2083 |
|
|
|
2084 |
|
|
=item __TOPDIR__/pool |
2085 |
|
|
|
2086 |
|
|
All uncompressed files from PC backups are stored below __TOPDIR__/pool. |
2087 |
|
|
Each file's name is based on the MD5 hex digest of the file contents. |
2088 |
|
|
Specifically, for files less than 256K, the file length and the entire |
2089 |
|
|
file is used. For files up to 1MB, the file length and the first and |
2090 |
|
|
last 128K are used. Finally, for files longer than 1MB, the file length, |
2091 |
|
|
and the first and eighth 128K chunks for the file are used. |
2092 |
|
|
|
2093 |
|
|
Each file is stored in a subdirectory X/Y/Z, where X, Y, Z are the |
2094 |
|
|
first 3 hex digits of the MD5 digest. |
2095 |
|
|
|
2096 |
|
|
For example, if a file has an MD5 digest of 123456789abcdef0, |
2097 |
|
|
the file is stored in __TOPDIR__/pool/1/2/3/123456789abcdef0. |
2098 |
|
|
|
2099 |
|
|
The MD5 digest might not be unique (especially since not all the file's |
2100 |
|
|
contents are used for files bigger than 256K). Different files that have |
2101 |
|
|
the same MD5 digest are stored with a trailing suffix "_n" where n is |
2102 |
|
|
an incrementing number starting at 0. So, for example, if two additional |
2103 |
|
|
files were identical to the first, except the last byte was different, |
2104 |
|
|
and assuming the file was larger than 1MB (so the MD5 digests are the |
2105 |
|
|
same but the files are actually different), the three files would be |
2106 |
|
|
stored as: |
2107 |
|
|
|
2108 |
|
|
__TOPDIR__/pool/1/2/3/123456789abcdef0 |
2109 |
|
|
__TOPDIR__/pool/1/2/3/123456789abcdef0_0 |
2110 |
|
|
__TOPDIR__/pool/1/2/3/123456789abcdef0_1 |
2111 |
|
|
|
2112 |
|
|
Both BackupPC_dump (actually, BackupPC_tarExtract) and BackupPC_link are |
2113 |
|
|
responsible for checking newly backed up files against the pool. For |
2114 |
|
|
each file, the MD5 digest is used to generate a file name in the pool |
2115 |
|
|
directory. If the file exists in the pool, the contents are compared. |
2116 |
|
|
If there is no match, additional files ending in "_n" are checked. |
2117 |
|
|
(Actually, BackupPC_tarExtract compares multiple candidate files in |
2118 |
|
|
parallel.) If the file contents exactly match, the file is created by |
2119 |
|
|
simply making a hard link to the pool file (this is done by |
2120 |
|
|
BackupPC_tarExtract as the backup proceeds). Otherwise, |
2121 |
|
|
BackupPC_tarExtract writes the new file to disk and a new hard link is |
2122 |
|
|
made in the pool to the file (this is done later by BackupPC_link). |
2123 |
|
|
|
2124 |
|
|
Therefore, every file in the pool will have at least 2 hard links |
2125 |
|
|
(one for the pool file and one for the backup file below __TOPDIR__/pc). |
2126 |
|
|
Identical files from different backups or PCs will all be linked to |
2127 |
|
|
the same file. When old backups are deleted, some files in the pool |
2128 |
|
|
might only have one link. BackupPC_nightly checks the entire pool |
2129 |
|
|
and removes all files that have only a single link, thereby recovering |
2130 |
|
|
the storage for that file. |
2131 |
|
|
|
2132 |
|
|
One other issue: zero length files are not pooled, since there are a lot |
2133 |
|
|
of these files and on most file systems it doesn't save any disk space |
2134 |
|
|
to turn these files into hard links. |
2135 |
|
|
|
2136 |
|
|
=item __TOPDIR__/cpool |
2137 |
|
|
|
2138 |
|
|
All compressed files from PC backups are stored below __TOPDIR__/cpool. |
2139 |
|
|
Its layout is the same as __TOPDIR__/pool, and the hashing function |
2140 |
|
|
is the same (and, importantly, based on the uncompressed file, not |
2141 |
|
|
the compressed file). |
2142 |
|
|
|
2143 |
|
|
=item __TOPDIR__/pc/$host |
2144 |
|
|
|
2145 |
|
|
For each PC $host, all the backups for that PC are stored below |
2146 |
|
|
the directory __TOPDIR__/pc/$host. This directory contains the |
2147 |
|
|
following files: |
2148 |
|
|
|
2149 |
|
|
=over 4 |
2150 |
|
|
|
2151 |
|
|
=item LOG |
2152 |
|
|
|
2153 |
|
|
Current log file for this PC from BackupPC_dump. |
2154 |
|
|
|
2155 |
|
|
=item LOG.0 or LOG.0.z |
2156 |
|
|
|
2157 |
|
|
Last month's log file. Log files are aged monthly and compressed |
2158 |
|
|
(if compression is enabled), and old LOG files are deleted. |
2159 |
|
|
|
2160 |
|
|
=item XferERR or XferERR.z |
2161 |
|
|
|
2162 |
|
|
Output from the transport program (ie: smbclient, tar or rsync) |
2163 |
|
|
for the most recent failed backup. |
2164 |
|
|
|
2165 |
|
|
=item new |
2166 |
|
|
|
2167 |
|
|
Subdirectory in which the current backup is stored. This |
2168 |
|
|
directory is renamed if the backup succeeds. |
2169 |
|
|
|
2170 |
|
|
=item XferLOG or XferLOG.z |
2171 |
|
|
|
2172 |
|
|
Output from the transport program (ie: smbclient, tar or rsync) |
2173 |
|
|
for the current backup. |
2174 |
|
|
|
2175 |
|
|
=item nnn (an integer) |
2176 |
|
|
|
2177 |
|
|
Successful backups are in directories numbered sequentially starting at 0. |
2178 |
|
|
|
2179 |
|
|
=item XferLOG.nnn or XferLOG.nnn.z |
2180 |
|
|
|
2181 |
|
|
Output from the transport program (ie: smbclient, tar or rsync) |
2182 |
|
|
corresponding to backup number nnn. |
2183 |
|
|
|
2184 |
|
|
=item RestoreInfo.nnn |
2185 |
|
|
|
2186 |
|
|
Information about restore request #nnn including who, what, when, and |
2187 |
|
|
why. This file is in Data::Dumper format. (Note that the restore |
2188 |
|
|
numbers are not related to the backup number.) |
2189 |
|
|
|
2190 |
|
|
=item RestoreLOG.nnn.z |
2191 |
|
|
|
2192 |
|
|
Output from smbclient, tar or rsync during restore #nnn. (Note that the restore |
2193 |
|
|
numbers are not related to the backup number.) |
2194 |
|
|
|
2195 |
|
|
=item ArchiveInfo.nnn |
2196 |
|
|
|
2197 |
|
|
Information about archive request #nnn including who, what, when, and |
2198 |
|
|
why. This file is in Data::Dumper format. (Note that the archive |
2199 |
|
|
numbers are not related to the restore or backup number.) |
2200 |
|
|
|
2201 |
|
|
=item ArchiveLOG.nnn.z |
2202 |
|
|
|
2203 |
|
|
Output from archive #nnn. (Note that the archive numbers are not related |
2204 |
|
|
to the backup or restore number.) |
2205 |
|
|
|
2206 |
|
|
=item config.pl |
2207 |
|
|
|
2208 |
|
|
Optional configuration settings specific to this host. Settings in this |
2209 |
|
|
file override the main configuration file. |
2210 |
|
|
|
2211 |
|
|
=item backups |
2212 |
|
|
|
2213 |
|
|
A tab-delimited ascii table listing information about each successful |
2214 |
|
|
backup, one per row. The columns are: |
2215 |
|
|
|
2216 |
|
|
=over 4 |
2217 |
|
|
|
2218 |
|
|
=item num |
2219 |
|
|
|
2220 |
|
|
The backup number, an integer that starts at 0 and increments |
2221 |
|
|
for each successive backup. The corresponding backup is stored |
2222 |
|
|
in the directory num (eg: if this field is 5, then the backup is |
2223 |
|
|
stored in __TOPDIR__/pc/$host/5). |
2224 |
|
|
|
2225 |
|
|
=item type |
2226 |
|
|
|
2227 |
|
|
Set to "full" or "incr" for full or incremental backup. |
2228 |
|
|
|
2229 |
|
|
=item startTime |
2230 |
|
|
|
2231 |
|
|
Start time of the backup in unix seconds. |
2232 |
|
|
|
2233 |
|
|
=item endTime |
2234 |
|
|
|
2235 |
|
|
Stop time of the backup in unix seconds. |
2236 |
|
|
|
2237 |
|
|
=item nFiles |
2238 |
|
|
|
2239 |
|
|
Number of files backed up (as reported by smbclient, tar or rsync). |
2240 |
|
|
|
2241 |
|
|
=item size |
2242 |
|
|
|
2243 |
|
|
Total file size backed up (as reported by smbclient, tar or rsync). |
2244 |
|
|
|
2245 |
|
|
=item nFilesExist |
2246 |
|
|
|
2247 |
|
|
Number of files that were already in the pool |
2248 |
|
|
(as determined by BackupPC_dump and BackupPC_link). |
2249 |
|
|
|
2250 |
|
|
=item sizeExist |
2251 |
|
|
|
2252 |
|
|
Total size of files that were already in the pool |
2253 |
|
|
(as determined by BackupPC_dump and BackupPC_link). |
2254 |
|
|
|
2255 |
|
|
=item nFilesNew |
2256 |
|
|
|
2257 |
|
|
Number of files that were not in the pool |
2258 |
|
|
(as determined by BackupPC_link). |
2259 |
|
|
|
2260 |
|
|
=item sizeNew |
2261 |
|
|
|
2262 |
|
|
Total size of files that were not in the pool |
2263 |
|
|
(as determined by BackupPC_link). |
2264 |
|
|
|
2265 |
|
|
=item xferErrs |
2266 |
|
|
|
2267 |
|
|
Number of errors or warnings from smbclient, tar or rsync. |
2268 |
|
|
|
2269 |
|
|
=item xferBadFile |
2270 |
|
|
|
2271 |
|
|
Number of errors from smbclient that were bad file errors (zero otherwise). |
2272 |
|
|
|
2273 |
|
|
=item xferBadShare |
2274 |
|
|
|
2275 |
|
|
Number of errors from smbclient that were bad share errors (zero otherwise). |
2276 |
|
|
|
2277 |
|
|
=item tarErrs |
2278 |
|
|
|
2279 |
|
|
Number of errors from BackupPC_tarExtract. |
2280 |
|
|
|
2281 |
|
|
=item compress |
2282 |
|
|
|
2283 |
|
|
The compression level used on this backup. Zero or empty means no |
2284 |
|
|
compression. |
2285 |
|
|
|
2286 |
|
|
=item sizeExistComp |
2287 |
|
|
|
2288 |
|
|
Total compressed size of files that were already in the pool |
2289 |
|
|
(as determined by BackupPC_dump and BackupPC_link). |
2290 |
|
|
|
2291 |
|
|
=item sizeNewComp |
2292 |
|
|
|
2293 |
|
|
Total compressed size of files that were not in the pool |
2294 |
|
|
(as determined by BackupPC_link). |
2295 |
|
|
|
2296 |
|
|
=item noFill |
2297 |
|
|
|
2298 |
|
|
Set if this backup has not been filled in with the most recent |
2299 |
|
|
previous filled or full backup. See $Conf{IncrFill}. |
2300 |
|
|
|
2301 |
|
|
=item fillFromNum |
2302 |
|
|
|
2303 |
|
|
If this backup was filled (ie: noFill is 0) then this is the |
2304 |
|
|
number of the backup that it was filled from |
2305 |
|
|
|
2306 |
|
|
=item mangle |
2307 |
|
|
|
2308 |
|
|
Set if this backup has mangled file names and attributes. Always |
2309 |
|
|
true for backups in v1.4.0 and above. False for all backups prior |
2310 |
|
|
to v1.4.0. |
2311 |
|
|
|
2312 |
|
|
=item xferMethod |
2313 |
|
|
|
2314 |
|
|
Set to the value of $Conf{XferMethod} when this dump was done. |
2315 |
|
|
|
2316 |
|
|
=item level |
2317 |
|
|
|
2318 |
|
|
The level of this dump. A full dump is level 0. Currently incrementals |
2319 |
|
|
are 1. But when multi-level incrementals are supported this will reflect |
2320 |
|
|
each dump's incremental level. |
2321 |
|
|
|
2322 |
|
|
=back |
2323 |
|
|
|
2324 |
|
|
=item restores |
2325 |
|
|
|
2326 |
|
|
A tab-delimited ascii table listing information about each requested |
2327 |
|
|
restore, one per row. The columns are: |
2328 |
|
|
|
2329 |
|
|
=over 4 |
2330 |
|
|
|
2331 |
|
|
=item num |
2332 |
|
|
|
2333 |
|
|
Restore number (matches the suffix of the RestoreInfo.nnn and |
2334 |
|
|
RestoreLOG.nnn.z file), unrelated to the backup number. |
2335 |
|
|
|
2336 |
|
|
=item startTime |
2337 |
|
|
|
2338 |
|
|
Start time of the restore in unix seconds. |
2339 |
|
|
|
2340 |
|
|
=item endTime |
2341 |
|
|
|
2342 |
|
|
End time of the restore in unix seconds. |
2343 |
|
|
|
2344 |
|
|
=item result |
2345 |
|
|
|
2346 |
|
|
Result (ok or failed). |
2347 |
|
|
|
2348 |
|
|
=item errorMsg |
2349 |
|
|
|
2350 |
|
|
Error message if restore failed. |
2351 |
|
|
|
2352 |
|
|
=item nFiles |
2353 |
|
|
|
2354 |
|
|
Number of files restored. |
2355 |
|
|
|
2356 |
|
|
=item size |
2357 |
|
|
|
2358 |
|
|
Size in bytes of the restored files. |
2359 |
|
|
|
2360 |
|
|
=item tarCreateErrs |
2361 |
|
|
|
2362 |
|
|
Number of errors from BackupPC_tarCreate during restore. |
2363 |
|
|
|
2364 |
|
|
=item xferErrs |
2365 |
|
|
|
2366 |
|
|
Number of errors from smbclient, tar or rsync during restore. |
2367 |
|
|
|
2368 |
|
|
=back |
2369 |
|
|
|
2370 |
|
|
=item archives |
2371 |
|
|
|
2372 |
|
|
A tab-delimited ascii table listing information about each requested |
2373 |
|
|
archive, one per row. The columns are: |
2374 |
|
|
|
2375 |
|
|
=over 4 |
2376 |
|
|
|
2377 |
|
|
=item num |
2378 |
|
|
|
2379 |
|
|
Archive number (matches the suffix of the ArchiveInfo.nnn and |
2380 |
|
|
ArchiveLOG.nnn.z file), unrelated to the backup or restore number. |
2381 |
|
|
|
2382 |
|
|
=item startTime |
2383 |
|
|
|
2384 |
|
|
Start time of the restore in unix seconds. |
2385 |
|
|
|
2386 |
|
|
=item endTime |
2387 |
|
|
|
2388 |
|
|
End time of the restore in unix seconds. |
2389 |
|
|
|
2390 |
|
|
=item result |
2391 |
|
|
|
2392 |
|
|
Result (ok or failed). |
2393 |
|
|
|
2394 |
|
|
=item errorMsg |
2395 |
|
|
|
2396 |
|
|
Error message if archive failed. |
2397 |
|
|
|
2398 |
|
|
=back |
2399 |
|
|
|
2400 |
|
|
=back |
2401 |
|
|
|
2402 |
|
|
=back |
2403 |
|
|
|
2404 |
|
|
=head2 Compressed file format |
2405 |
|
|
|
2406 |
|
|
The compressed file format is as generated by Compress::Zlib::deflate |
2407 |
|
|
with one minor, but important, tweak. Since Compress::Zlib::inflate |
2408 |
|
|
fully inflates its argument in memory, it could take large amounts of |
2409 |
|
|
memory if it was inflating a highly compressed file. For example, a |
2410 |
|
|
200MB file of 0x0 bytes compresses to around 200K bytes. If |
2411 |
|
|
Compress::Zlib::inflate was called with this single 200K buffer, it |
2412 |
|
|
would need to allocate 200MB of memory to return the result. |
2413 |
|
|
|
2414 |
|
|
BackupPC watches how efficiently a file is compressing. If a big file |
2415 |
|
|
has very high compression (meaning it will use too much memory when it |
2416 |
|
|
is inflated), BackupPC calls the flush() method, which gracefully |
2417 |
|
|
completes the current compression. BackupPC then starts another |
2418 |
|
|
deflate and simply appends the output file. So the BackupPC compressed |
2419 |
|
|
file format is one or more concatenated deflations/flushes. The specific |
2420 |
|
|
ratios that BackupPC uses is that if a 6MB chunk compresses to less |
2421 |
|
|
than 64K then a flush will be done. |
2422 |
|
|
|
2423 |
|
|
Back to the example of the 200MB file of 0x0 bytes. Adding flushes |
2424 |
|
|
every 6MB adds only 200 or so bytes to the 200K output. So the |
2425 |
|
|
storage cost of flushing is negligible. |
2426 |
|
|
|
2427 |
|
|
To easily decompress a BackupPC compressed file, the script |
2428 |
|
|
BackupPC_zcat can be found in __INSTALLDIR__/bin. For each |
2429 |
|
|
file name argument it inflates the file and writes it to stdout. |
2430 |
|
|
|
2431 |
|
|
=head2 Rsync checksum caching |
2432 |
|
|
|
2433 |
|
|
An incremental backup with rsync compares attributes on the client |
2434 |
|
|
with the last full backup. Any files with identical attributes |
2435 |
|
|
are skipped. A full backup with rsync sets the --ignore-times |
2436 |
|
|
option, which causes every file to be examined independent of |
2437 |
|
|
attributes. |
2438 |
|
|
|
2439 |
|
|
Each file is examined by generating block checksums (default 2K |
2440 |
|
|
blocks) on the receiving side (that's the BackupPC side), sending |
2441 |
|
|
those checksums to the client, where the remote rsync matches those |
2442 |
|
|
checksums with the corresponding file. The matching blocks and new |
2443 |
|
|
data is sent back, allowing the client file to be reassembled. |
2444 |
|
|
A checksum for the entire file is sent to as an extra check the |
2445 |
|
|
the reconstructed file is correct. |
2446 |
|
|
|
2447 |
|
|
This results in significant disk IO and computation for BackupPC: |
2448 |
|
|
every file in a full backup, or any file with non-matching attributes |
2449 |
|
|
in an incremental backup, needs to be uncompressed, block checksums |
2450 |
|
|
computed and sent. Then the receiving side reassembles the file and |
2451 |
|
|
has to verify the whole-file checksum. Even if the file is identical, |
2452 |
|
|
prior to 2.1.0, BackupPC had to read and uncompress the file twice, |
2453 |
|
|
once to compute the block checksums and later to verify the whole-file |
2454 |
|
|
checksum. |
2455 |
|
|
|
2456 |
|
|
Starting in 2.1.0, BackupPC supports optional checksum caching, |
2457 |
|
|
which means the block and file checksums only need to be computed |
2458 |
|
|
once for each file. This results in a significant performance |
2459 |
|
|
improvement. This only works for compressed pool files. |
2460 |
|
|
It is enabled by adding |
2461 |
|
|
|
2462 |
|
|
'--checksum-seed=32761', |
2463 |
|
|
|
2464 |
|
|
to $Conf{RsyncArgs} and $Conf{RsyncRestoreArgs}. |
2465 |
|
|
|
2466 |
|
|
Rsync versions prior to and including rsync-2.6.2 need a small patch to |
2467 |
|
|
add support for the --checksum-seed option. This patch is available in |
2468 |
|
|
the cygwin-rsyncd package at L<http://backuppc.sourceforge.net>. |
2469 |
|
|
This patch is already included in rsync CVS, so it will be standard |
2470 |
|
|
in future versions of rsync. |
2471 |
|
|
|
2472 |
|
|
When this option is present, BackupPC will add block and file checksums |
2473 |
|
|
to the compressed pool file the next time a pool file is used and it |
2474 |
|
|
doesn't already have cached checksums. The first time a new file is |
2475 |
|
|
written to the pool, the checksums are not appended. The next time |
2476 |
|
|
checksums are needed for a file, they are computed and added. So the |
2477 |
|
|
full performance benefit of checksum caching won't be noticed until the |
2478 |
|
|
third time a pool file is used (eg: the third full backup). |
2479 |
|
|
|
2480 |
|
|
With checksum caching enabled, there is a risk that should a file's contents |
2481 |
|
|
in the pool be corrupted due to a disk problem, but the cached checksums |
2482 |
|
|
are still correct, the corruption will not be detected by a full backup, |
2483 |
|
|
since the file contents are no longer read and compared. To reduce the |
2484 |
|
|
chance that this remains undetected, BackupPC can recheck cached checksums |
2485 |
|
|
for a fraction of the files. This fraction is set with the |
2486 |
|
|
$Conf{RsyncCsumCacheVerifyProb} setting. The default value of 0.01 means |
2487 |
|
|
that 1% of the time a file's checksums are read, the checksums are verified. |
2488 |
|
|
This reduces performance slightly, but, over time, ensures that files |
2489 |
|
|
contents are in sync with the cached checksums. |
2490 |
|
|
|
2491 |
|
|
The format of the cached checksum data can be discovered by looking at |
2492 |
|
|
the code. Basically, the first byte of the compressed file is changed |
2493 |
|
|
to denote that checksums are appended. The block and file checksum |
2494 |
|
|
data, plus some other information and magic word, are appended to the |
2495 |
|
|
compressed file. This allows the cache update to be done in-place. |
2496 |
|
|
|
2497 |
|
|
=head2 File name mangling |
2498 |
|
|
|
2499 |
|
|
Backup file names are stored in "mangled" form. Each node of |
2500 |
|
|
a path is preceded by "f" (mnemonic: file), and special characters |
2501 |
|
|
(\n, \r, % and /) are URI-encoded as "%xx", where xx is the ascii |
2502 |
|
|
character's hex value. So c:/craig/example.txt is now stored as |
2503 |
|
|
fc/fcraig/fexample.txt. |
2504 |
|
|
|
2505 |
|
|
This was done mainly so meta-data could be stored alongside the backup |
2506 |
|
|
files without name collisions. In particular, the attributes for the |
2507 |
|
|
files in a directory are stored in a file called "attrib", and mangling |
2508 |
|
|
avoids file name collisions (I discarded the idea of having a duplicate |
2509 |
|
|
directory tree for every backup just to store the attributes). Other |
2510 |
|
|
meta-data (eg: rsync checksums) could be stored in file names preceded |
2511 |
|
|
by, eg, "c". There are two other benefits to mangling: the share name |
2512 |
|
|
might contain "/" (eg: "/home/craig" for tar transport), and I wanted |
2513 |
|
|
that represented as a single level in the storage tree. Secondly, as |
2514 |
|
|
files are written to NewFileList for later processing by BackupPC_link, |
2515 |
|
|
embedded newlines in the file's path will cause problems which are |
2516 |
|
|
avoided by mangling. |
2517 |
|
|
|
2518 |
|
|
The CGI script undoes the mangling, so it is invisible to the user. |
2519 |
|
|
Old (unmangled) backups are still supported by the CGI |
2520 |
|
|
interface. |
2521 |
|
|
|
2522 |
|
|
=head2 Special files |
2523 |
|
|
|
2524 |
|
|
Linux/unix file systems support several special file types: symbolic |
2525 |
|
|
links, character and block device files, fifos (pipes) and unix-domain |
2526 |
|
|
sockets. All except unix-domain sockets are supported by BackupPC |
2527 |
|
|
(there's no point in backing up or restoring unix-domain sockets since |
2528 |
|
|
they only have meaning after a process creates them). Symbolic links are |
2529 |
|
|
stored as a plain file whose contents are the contents of the link (not |
2530 |
|
|
the file it points to). This file is compressed and pooled like any |
2531 |
|
|
normal file. Character and block device files are also stored as plain |
2532 |
|
|
files, whose contents are two integers separated by a comma; the numbers |
2533 |
|
|
are the major and minor device number. These files are compressed and |
2534 |
|
|
pooled like any normal file. Fifo files are stored as empty plain files |
2535 |
|
|
(which are not pooled since they have zero size). In all cases, the |
2536 |
|
|
original file type is stored in the attrib file so it can be correctly |
2537 |
|
|
restored. |
2538 |
|
|
|
2539 |
|
|
Hardlinks are also supported. When GNU tar first encounters a file with |
2540 |
|
|
more than one link (ie: hardlinks) it dumps it as a regular file. When |
2541 |
|
|
it sees the second and subsequent hardlinks to the same file, it dumps |
2542 |
|
|
just the hardlink information. BackupPC correctly recognizes these |
2543 |
|
|
hardlinks and stores them just like symlinks: a regular text file |
2544 |
|
|
whose contents is the path of the file linked to. The CGI script |
2545 |
|
|
will download the original file when you click on a hardlink. |
2546 |
|
|
|
2547 |
|
|
Also, BackupPC_tarCreate has enough magic to re-create the hardlinks |
2548 |
|
|
dynamically based on whether or not the original file and hardlinks |
2549 |
|
|
are both included in the tar file. For example, imagine a/b/x is a |
2550 |
|
|
hardlink to a/c/y. If you use BackupPC_tarCreate to restore directory |
2551 |
|
|
a, then the tar file will include a/b/x as the original file and a/c/y |
2552 |
|
|
will be a hardlink to a/b/x. If, instead you restore a/c, then the |
2553 |
|
|
tar file will include a/c/y as the original file, not a hardlink. |
2554 |
|
|
|
2555 |
|
|
=head2 Attribute file format |
2556 |
|
|
|
2557 |
|
|
The unix attributes for the contents of a directory (all the files and |
2558 |
|
|
directories in that directory) are stored in a file called attrib. |
2559 |
|
|
There is a single attrib file for each directory in a backup. |
2560 |
|
|
For example, if c:/craig contains a single file c:/craig/example.txt, |
2561 |
|
|
that file would be stored as fc/fcraig/fexample.txt and there would be an |
2562 |
|
|
attribute file in fc/fcraig/attrib (and also fc/attrib and ./attrib). |
2563 |
|
|
The file fc/fcraig/attrib would contain a single entry containing the |
2564 |
|
|
attributes for fc/fcraig/fexample.txt. |
2565 |
|
|
|
2566 |
|
|
The attrib file starts with a magic number, followed by the |
2567 |
|
|
concatenation of the following information for each file: |
2568 |
|
|
|
2569 |
|
|
=over 4 |
2570 |
|
|
|
2571 |
|
|
=item * |
2572 |
|
|
|
2573 |
|
|
File name length in perl's pack "w" format (variable length base 128). |
2574 |
|
|
|
2575 |
|
|
=item * |
2576 |
|
|
|
2577 |
|
|
File name. |
2578 |
|
|
|
2579 |
|
|
=item * |
2580 |
|
|
|
2581 |
|
|
The unix file type, mode, uid, gid and file size divided by 4GB and |
2582 |
|
|
file size modulo 4GB (type mode uid gid sizeDiv4GB sizeMod4GB), |
2583 |
|
|
in perl's pack "w" format (variable length base 128). |
2584 |
|
|
|
2585 |
|
|
=item * |
2586 |
|
|
|
2587 |
|
|
The unix mtime (unix seconds) in perl's pack "N" format (32 bit integer). |
2588 |
|
|
|
2589 |
|
|
=back |
2590 |
|
|
|
2591 |
|
|
The attrib file is also compressed if compression is enabled. |
2592 |
|
|
See the lib/BackupPC/Attrib.pm module for full details. |
2593 |
|
|
|
2594 |
|
|
Attribute files are pooled just like normal backup files. This saves |
2595 |
|
|
space if all the files in a directory have the same attributes across |
2596 |
|
|
multiple backups, which is common. |
2597 |
|
|
|
2598 |
|
|
=head2 Optimizations |
2599 |
|
|
|
2600 |
|
|
BackupPC doesn't care about the access time of files in the pool |
2601 |
|
|
since it saves attribute meta-data separate from the files. Since |
2602 |
|
|
BackupPC mostly does reads from disk, maintaining the access time of |
2603 |
|
|
files generates a lot of unnecessary disk writes. So, provided |
2604 |
|
|
BackupPC has a dedicated data disk, you should consider mounting |
2605 |
|
|
BackupPC's data directory with the noatime attribute (see mount(1)). |
2606 |
|
|
|
2607 |
|
|
=head2 Limitations |
2608 |
|
|
|
2609 |
|
|
BackupPC isn't perfect (but it is getting better). Please see |
2610 |
|
|
L<http://backuppc.sourceforge.net/faq/limitations.html> for a |
2611 |
|
|
discussion of some of BackupPC's limitations. |
2612 |
|
|
|
2613 |
|
|
=head2 Security issues |
2614 |
|
|
|
2615 |
|
|
Please see L<http://backuppc.sourceforge.net/faq/security.html> for a |
2616 |
|
|
discussion of some of various security issues. |
2617 |
|
|
|
2618 |
|
|
=head1 Configuration File |
2619 |
|
|
|
2620 |
|
|
The BackupPC configuration file resides in __TOPDIR__/conf/config.pl. |
2621 |
|
|
Optional per-PC configuration files reside in __TOPDIR__/pc/$host/config.pl. |
2622 |
|
|
This file can be used to override settings just for a particular PC. |
2623 |
|
|
|
2624 |
|
|
=head2 Modifying the main configuration file |
2625 |
|
|
|
2626 |
|
|
The configuration file is a perl script that is executed by BackupPC, so |
2627 |
|
|
you should be careful to preserve the file syntax (punctuation, quotes |
2628 |
|
|
etc) when you edit it. It is recommended that you use CVS, RCS or some |
2629 |
|
|
other method of source control for changing config.pl. |
2630 |
|
|
|
2631 |
|
|
BackupPC reads or re-reads the main configuration file and |
2632 |
|
|
the hosts file in three cases: |
2633 |
|
|
|
2634 |
|
|
=over 4 |
2635 |
|
|
|
2636 |
|
|
=item * |
2637 |
|
|
|
2638 |
|
|
Upon startup. |
2639 |
|
|
|
2640 |
|
|
=item * |
2641 |
|
|
|
2642 |
|
|
When BackupPC is sent a HUP (-1) signal. Assuming you installed the |
2643 |
|
|
init.d script, you can also do this with "/etc/init.d/backuppc reload". |
2644 |
|
|
|
2645 |
|
|
=item * |
2646 |
|
|
|
2647 |
|
|
When the modification time of config.pl file changes. BackupPC |
2648 |
|
|
checks the modification time once during each regular wakeup. |
2649 |
|
|
|
2650 |
|
|
=back |
2651 |
|
|
|
2652 |
|
|
Whenever you change the configuration file you can either do |
2653 |
|
|
a kill -HUP BackupPC_pid or simply wait until the next regular |
2654 |
|
|
wakeup period. |
2655 |
|
|
|
2656 |
|
|
Each time the configuration file is re-read a message is reported in the |
2657 |
|
|
LOG file, so you can tail it (or view it via the CGI interface) to make |
2658 |
|
|
sure your kill -HUP worked. Errors in parsing the configuration file are |
2659 |
|
|
also reported in the LOG file. |
2660 |
|
|
|
2661 |
|
|
The optional per-PC configuration file (__TOPDIR__/pc/$host/config.pl) |
2662 |
|
|
is read whenever it is needed by BackupPC_dump, BackupPC_link and others. |
2663 |
|
|
|
2664 |
|
|
=head2 Configuration file includes |
2665 |
|
|
|
2666 |
|
|
If you have a heterogeneous set of clients (eg: a variety of WinXX and |
2667 |
|
|
linux/unix machines) you will need to create host-specific config.pl files |
2668 |
|
|
for some or all of these machines to customize the default settings from |
2669 |
|
|
the master config.pl file (at a minimum to set $Conf{XferMethod}). |
2670 |
|
|
|
2671 |
|
|
Since the config.pl file is just regular perl code, you can include |
2672 |
|
|
one config file from another. For example, imagine you had three general |
2673 |
|
|
classes of machines: WinXX desktops, linux machines in the DMZ and |
2674 |
|
|
linux desktops. You could create three config files in __TOPDIR__/conf: |
2675 |
|
|
|
2676 |
|
|
__TOPDIR__/conf/ConfigWinDesktop.pl |
2677 |
|
|
__TOPDIR__/conf/ConfigLinuxDMZ.pl |
2678 |
|
|
__TOPDIR__/conf/ConfigLinuxDesktop.pl |
2679 |
|
|
|
2680 |
|
|
From each client's directory you can either add a symbolic link to |
2681 |
|
|
the appropriate config file: |
2682 |
|
|
|
2683 |
|
|
cd __TOPDIR__/pc/$host |
2684 |
|
|
ln -s ../../conf/ConfigWinDesktop.pl config.pl |
2685 |
|
|
|
2686 |
|
|
or, better yet, create a config.pl file in __TOPDIR__/pc/$host |
2687 |
|
|
that includes the default config.pl file using perl's "do" |
2688 |
|
|
command: |
2689 |
|
|
|
2690 |
|
|
do "__TOPDIR__/conf/ConfigWinDesktop.pl"; |
2691 |
|
|
|
2692 |
|
|
This alternative allows you to set other configuration options |
2693 |
|
|
specific to each host after the "do" command (perhaps even |
2694 |
|
|
overriding the settings in the included file). |
2695 |
|
|
|
2696 |
|
|
Note that you could also include snippets of configuration settings |
2697 |
|
|
from the main configuration file. However, be aware that the |
2698 |
|
|
modification-time checking that BackupPC does only applies to the |
2699 |
|
|
main configuration file: if you change one of the included files, |
2700 |
|
|
BackupPC won't notice. You will need to either touch the main |
2701 |
|
|
configuration file too, or send BackupPC a HUP (-1) signal. |
2702 |
|
|
|
2703 |
|
|
=head1 Configuration Parameters |
2704 |
|
|
|
2705 |
|
|
The configuration parameters are divided into five general groups. |
2706 |
|
|
The first group (general server configuration) provides general |
2707 |
|
|
configuration for BackupPC. The next two groups describe what to |
2708 |
|
|
backup, when to do it, and how long to keep it. The fourth group |
2709 |
|
|
are settings for email reminders, and the final group contains |
2710 |
|
|
settings for the CGI interface. |
2711 |
|
|
|
2712 |
|
|
All configuration settings in the second through fifth groups can |
2713 |
|
|
be overridden by the per-PC config.pl file. |
2714 |
|
|
|
2715 |
|
|
=head2 General server configuration |
2716 |
|
|
|
2717 |
|
|
=over 4 |
2718 |
|
|
|
2719 |
|
|
=item $Conf{ServerHost} = ''; |
2720 |
|
|
|
2721 |
|
|
Host name on which the BackupPC server is running. |
2722 |
|
|
|
2723 |
|
|
=item $Conf{ServerPort} = -1; |
2724 |
|
|
|
2725 |
|
|
TCP port number on which the BackupPC server listens for and accepts |
2726 |
|
|
connections. Normally this should be disabled (set to -1). The TCP |
2727 |
|
|
port is only needed if apache runs on a different machine from BackupPC. |
2728 |
|
|
In that case, set this to any spare port number over 1024 (eg: 2359). |
2729 |
|
|
If you enable the TCP port, make sure you set $Conf{ServerMesgSecret} |
2730 |
|
|
too! |
2731 |
|
|
|
2732 |
|
|
=item $Conf{ServerMesgSecret} = ''; |
2733 |
|
|
|
2734 |
|
|
Shared secret to make the TCP port secure. Set this to a hard to guess |
2735 |
|
|
string if you enable the TCP port (ie: $Conf{ServerPort} > 0). |
2736 |
|
|
|
2737 |
|
|
To avoid possible attacks via the TCP socket interface, every client |
2738 |
|
|
message is protected by an MD5 digest. The MD5 digest includes four |
2739 |
|
|
items: |
2740 |
|
|
- a seed that is sent to the client when the connection opens |
2741 |
|
|
- a sequence number that increments for each message |
2742 |
|
|
- a shared secret that is stored in $Conf{ServerMesgSecret} |
2743 |
|
|
- the message itself. |
2744 |
|
|
|
2745 |
|
|
The message is sent in plain text preceded by the MD5 digest. A |
2746 |
|
|
snooper can see the plain-text seed sent by BackupPC and plain-text |
2747 |
|
|
message from the client, but cannot construct a valid MD5 digest since |
2748 |
|
|
the secret $Conf{ServerMesgSecret} is unknown. A replay attack is |
2749 |
|
|
not possible since the seed changes on a per-connection and |
2750 |
|
|
per-message basis. |
2751 |
|
|
|
2752 |
|
|
=item $Conf{MyPath} = '/bin'; |
2753 |
|
|
|
2754 |
|
|
PATH setting for BackupPC. An explicit value is necessary |
2755 |
|
|
for taint mode. Value shouldn't matter too much since |
2756 |
|
|
all execs use explicit paths. However, taint mode in perl |
2757 |
|
|
will complain if this directory is world writable. |
2758 |
|
|
|
2759 |
|
|
=item $Conf{UmaskMode} = 027; |
2760 |
|
|
|
2761 |
|
|
Permission mask for directories and files created by BackupPC. |
2762 |
|
|
Default value prevents any access from group other, and prevents |
2763 |
|
|
group write. |
2764 |
|
|
|
2765 |
|
|
=item $Conf{WakeupSchedule} = [1..23]; |
2766 |
|
|
|
2767 |
|
|
Times at which we wake up, check all the PCs, and schedule necessary |
2768 |
|
|
backups. Times are measured in hours since midnight. Can be |
2769 |
|
|
fractional if necessary (eg: 4.25 means 4:15am). |
2770 |
|
|
|
2771 |
|
|
If the hosts you are backing up are always connected to the network |
2772 |
|
|
you might have only one or two wakeups each night. This will keep |
2773 |
|
|
the backup activity after hours. On the other hand, if you are backing |
2774 |
|
|
up laptops that are only intermittently connected to the network you |
2775 |
|
|
will want to have frequent wakeups (eg: hourly) to maximized the chance |
2776 |
|
|
that each laptop is backed up. |
2777 |
|
|
|
2778 |
|
|
Examples: |
2779 |
|
|
|
2780 |
|
|
$Conf{WakeupSchedule} = [22.5]; # once per day at 10:30 pm. |
2781 |
|
|
$Conf{WakeupSchedule} = [1..23]; # every hour except midnight |
2782 |
|
|
$Conf{WakeupSchedule} = [2,4,6,8,10,12,14,16,18,20,22]; # every 2 hours |
2783 |
|
|
|
2784 |
|
|
The default value is every hour except midnight. |
2785 |
|
|
|
2786 |
|
|
The first entry of $Conf{WakeupSchedule} is when BackupPC_nightly |
2787 |
|
|
is run. No other backups can run while BackupPC_nightly is |
2788 |
|
|
running. You might want to re-arrange the entries in |
2789 |
|
|
$Conf{WakeupSchedule} (they don't have to be ascending) so that |
2790 |
|
|
the first entry is when you want BackupPC_nightly to run |
2791 |
|
|
(eg: when you don't expect a lot of regular backups to run). |
2792 |
|
|
|
2793 |
|
|
=item $Conf{MaxBackups} = 4; |
2794 |
|
|
|
2795 |
|
|
Maximum number of simultaneous backups to run. If there |
2796 |
|
|
are no user backup requests then this is the maximum number |
2797 |
|
|
of simultaneous backups. |
2798 |
|
|
|
2799 |
|
|
=item $Conf{MaxUserBackups} = 4; |
2800 |
|
|
|
2801 |
|
|
Additional number of simultaneous backups that users can run. |
2802 |
|
|
As many as $Conf{MaxBackups} + $Conf{MaxUserBackups} requests can |
2803 |
|
|
run at the same time. |
2804 |
|
|
|
2805 |
|
|
=item $Conf{MaxPendingCmds} = 10; |
2806 |
|
|
|
2807 |
|
|
Maximum number of pending link commands. New backups will only be |
2808 |
|
|
started if there are no more than $Conf{MaxPendingCmds} plus |
2809 |
|
|
$Conf{MaxBackups} number of pending link commands, plus running jobs. |
2810 |
|
|
This limit is to make sure BackupPC doesn't fall too far behind in |
2811 |
|
|
running BackupPC_link commands. |
2812 |
|
|
|
2813 |
|
|
=item $Conf{MaxBackupPCNightlyJobs} = 2; |
2814 |
|
|
|
2815 |
|
|
How many BackupPC_nightly processes to run in parallel. |
2816 |
|
|
|
2817 |
|
|
Each night, at the first wakeup listed in $Conf{WakeupSchedule}, |
2818 |
|
|
BackupPC_nightly is run. Its job is to remove unneeded files |
2819 |
|
|
in the pool, ie: files that only have one link. To avoid race |
2820 |
|
|
conditions, BackupPC_nightly runs only when there are no backups |
2821 |
|
|
running, and no backups will start while it runs. |
2822 |
|
|
|
2823 |
|
|
So to reduce the elapsed time, you might want to increase this |
2824 |
|
|
setting to run several BackupPC_nightly processes in parallel |
2825 |
|
|
(eg: 4, or even 8). |
2826 |
|
|
|
2827 |
|
|
=item $Conf{BackupPCNightlyPeriod} = 1; |
2828 |
|
|
|
2829 |
|
|
How many days (runs) it takes BackupPC_nightly to traverse the |
2830 |
|
|
entire pool. Normally this is 1, which means every night it runs, |
2831 |
|
|
it does traverse the entire pool removing unused pool files. |
2832 |
|
|
|
2833 |
|
|
Other valid values are 2, 4, 8, 16. This causes BackupPC_nightly to |
2834 |
|
|
traverse 1/2, 1/4, 1/8 or 1/16th of the pool each night, meaning it |
2835 |
|
|
takes 2, 4, 8 or 16 days to completely traverse the pool. The |
2836 |
|
|
advantage is that each night the running time of BackupPC_nightly |
2837 |
|
|
is reduced roughly in proportion, since the total job is split |
2838 |
|
|
over multiple days. The disadvantage is that unused pool files |
2839 |
|
|
take longer to get deleted, which will slightly increase disk |
2840 |
|
|
usage. |
2841 |
|
|
|
2842 |
|
|
Note that even when $Conf{BackupPCNightlyPeriod} > 1, BackupPC_nightly |
2843 |
|
|
still runs every night. It just does less work each time it runs. |
2844 |
|
|
|
2845 |
|
|
Examples: |
2846 |
|
|
|
2847 |
|
|
|
2848 |
|
|
$Conf{BackupPCNightlyPeriod} = 1; # entire pool is checked every night |
2849 |
|
|
|
2850 |
|
|
$Conf{BackupPCNightlyPeriod} = 2; # two days to complete pool check |
2851 |
|
|
# (different half each night) |
2852 |
|
|
|
2853 |
|
|
$Conf{BackupPCNightlyPeriod} = 4; # four days to complete pool check |
2854 |
|
|
# (different quarter each night) |
2855 |
|
|
|
2856 |
|
|
=item $Conf{MaxOldLogFiles} = 14; |
2857 |
|
|
|
2858 |
|
|
Maximum number of log files we keep around in log directory. |
2859 |
|
|
These files are aged nightly. A setting of 14 means the log |
2860 |
|
|
directory will contain about 2 weeks of old log files, in |
2861 |
|
|
particular at most the files LOG, LOG.0, LOG.1, ... LOG.13 |
2862 |
|
|
(except today's LOG, these files will have a .z extension if |
2863 |
|
|
compression is on). |
2864 |
|
|
|
2865 |
|
|
If you decrease this number after BackupPC has been running for a |
2866 |
|
|
while you will have to manually remove the older log files. |
2867 |
|
|
|
2868 |
|
|
=item $Conf{DfPath} = '/bin/df'; |
2869 |
|
|
|
2870 |
|
|
Full path to the df command. Security caution: normal users |
2871 |
|
|
should not allowed to write to this file or directory. |
2872 |
|
|
|
2873 |
|
|
=item $Conf{DfCmd} = '$dfPath $topDir'; |
2874 |
|
|
|
2875 |
|
|
Command to run df. The following variables are substituted at run-time: |
2876 |
|
|
|
2877 |
|
|
$dfPath path to df ($Conf{DfPath}) |
2878 |
|
|
$topDir top-level BackupPC data directory |
2879 |
|
|
|
2880 |
|
|
=item $Conf{DfMaxUsagePct} = 95; |
2881 |
|
|
|
2882 |
|
|
Maximum threshold for disk utilization on the __TOPDIR__ filesystem. |
2883 |
|
|
If the output from $Conf{DfPath} reports a percentage larger than |
2884 |
|
|
this number then no new regularly scheduled backups will be run. |
2885 |
|
|
However, user requested backups (which are usually incremental and |
2886 |
|
|
tend to be small) are still performed, independent of disk usage. |
2887 |
|
|
Also, currently running backups will not be terminated when the disk |
2888 |
|
|
usage exceeds this number. |
2889 |
|
|
|
2890 |
|
|
=item $Conf{TrashCleanSleepSec} = 300; |
2891 |
|
|
|
2892 |
|
|
How long BackupPC_trashClean sleeps in seconds between each check |
2893 |
|
|
of the trash directory. Once every 5 minutes should be reasonable. |
2894 |
|
|
|
2895 |
|
|
=item $Conf{DHCPAddressRanges} = []; |
2896 |
|
|
|
2897 |
|
|
List of DHCP address ranges we search looking for PCs to backup. |
2898 |
|
|
This is an array of hashes for each class C address range. |
2899 |
|
|
This is only needed if hosts in the conf/hosts file have the |
2900 |
|
|
dhcp flag set. |
2901 |
|
|
|
2902 |
|
|
Examples: |
2903 |
|
|
|
2904 |
|
|
# to specify 192.10.10.20 to 192.10.10.250 as the DHCP address pool |
2905 |
|
|
$Conf{DHCPAddressRanges} = [ |
2906 |
|
|
{ |
2907 |
|
|
ipAddrBase => '192.10.10', |
2908 |
|
|
first => 20, |
2909 |
|
|
last => 250, |
2910 |
|
|
}, |
2911 |
|
|
]; |
2912 |
|
|
# to specify two pools (192.10.10.20-250 and 192.10.11.10-50) |
2913 |
|
|
$Conf{DHCPAddressRanges} = [ |
2914 |
|
|
{ |
2915 |
|
|
ipAddrBase => '192.10.10', |
2916 |
|
|
first => 20, |
2917 |
|
|
last => 250, |
2918 |
|
|
}, |
2919 |
|
|
{ |
2920 |
|
|
ipAddrBase => '192.10.11', |
2921 |
|
|
first => 10, |
2922 |
|
|
last => 50, |
2923 |
|
|
}, |
2924 |
|
|
]; |
2925 |
|
|
|
2926 |
|
|
=item $Conf{BackupPCUser} = ''; |
2927 |
|
|
|
2928 |
|
|
=item $Conf{CgiDir} = ''; |
2929 |
|
|
|
2930 |
|
|
=item $Conf{InstallDir} = ''; |
2931 |
|
|
|
2932 |
|
|
These configuration settings aren't used by BackupPC, but simply |
2933 |
|
|
remember a few settings used by configure.pl during installation. |
2934 |
|
|
These are used by configure.pl when upgrading to new versions of |
2935 |
|
|
BackupPC. |
2936 |
|
|
|
2937 |
|
|
=item $Conf{BackupPCUserVerify} = 1; |
2938 |
|
|
|
2939 |
|
|
Whether BackupPC and the CGI script BackupPC_Admin verify that they |
2940 |
|
|
are really running as user $Conf{BackupPCUser}. If this flag is set |
2941 |
|
|
and the effective user id (euid) differs from $Conf{BackupPCUser} |
2942 |
|
|
then both scripts exit with an error. This catches cases where |
2943 |
|
|
BackupPC might be accidently started as root or the wrong user, |
2944 |
|
|
or if the CGI script is not installed correctly. |
2945 |
|
|
|
2946 |
|
|
=item $Conf{HardLinkMax} = 31999; |
2947 |
|
|
|
2948 |
|
|
Maximum number of hardlinks supported by the $TopDir file system |
2949 |
|
|
that BackupPC uses. Most linux or unix file systems should support |
2950 |
|
|
at least 32000 hardlinks per file, or 64000 in other cases. If a pool |
2951 |
|
|
file already has this number of hardlinks, a new pool file is created |
2952 |
|
|
so that new hardlinks can be accommodated. This limit will only |
2953 |
|
|
be hit if an identical file appears at least this number of times |
2954 |
|
|
across all the backups. |
2955 |
|
|
|
2956 |
|
|
=back |
2957 |
|
|
|
2958 |
|
|
=head2 What to backup and when to do it |
2959 |
|
|
|
2960 |
|
|
=over 4 |
2961 |
|
|
|
2962 |
|
|
=item $Conf{SmbShareName} = 'C$'; |
2963 |
|
|
|
2964 |
|
|
Name of the host share that is backed up when using SMB. This can be a |
2965 |
|
|
string or an array of strings if there are multiple shares per host. |
2966 |
|
|
Examples: |
2967 |
|
|
|
2968 |
|
|
|
2969 |
|
|
$Conf{SmbShareName} = 'c'; # backup 'c' share |
2970 |
|
|
$Conf{SmbShareName} = ['c', 'd']; # backup 'c' and 'd' shares |
2971 |
|
|
|
2972 |
|
|
This setting only matters if $Conf{XferMethod} = 'smb'. |
2973 |
|
|
|
2974 |
|
|
=item $Conf{SmbShareUserName} = ''; |
2975 |
|
|
|
2976 |
|
|
Smbclient share user name. This is passed to smbclient's -U argument. |
2977 |
|
|
|
2978 |
|
|
This setting only matters if $Conf{XferMethod} = 'smb'. |
2979 |
|
|
|
2980 |
|
|
=item $Conf{SmbSharePasswd} = ''; |
2981 |
|
|
|
2982 |
|
|
Smbclient share password. This is passed to smbclient via its PASSWD |
2983 |
|
|
environment variable. There are several ways you can tell BackupPC |
2984 |
|
|
the smb share password. In each case you should be very careful about |
2985 |
|
|
security. If you put the password here, make sure that this file is |
2986 |
|
|
not readable by regular users! See the "Setting up config.pl" section |
2987 |
|
|
in the documentation for more information. |
2988 |
|
|
|
2989 |
|
|
This setting only matters if $Conf{XferMethod} = 'smb'. |
2990 |
|
|
|
2991 |
|
|
=item $Conf{TarShareName} = '/'; |
2992 |
|
|
|
2993 |
|
|
Which host directories to backup when using tar transport. This can be a |
2994 |
|
|
string or an array of strings if there are multiple directories to |
2995 |
|
|
backup per host. Examples: |
2996 |
|
|
|
2997 |
|
|
|
2998 |
|
|
$Conf{TarShareName} = '/'; # backup everything |
2999 |
|
|
$Conf{TarShareName} = '/home'; # only backup /home |
3000 |
|
|
$Conf{TarShareName} = ['/home', '/src']; # backup /home and /src |
3001 |
|
|
|
3002 |
|
|
The fact this parameter is called 'TarShareName' is for historical |
3003 |
|
|
consistency with the Smb transport options. You can use any valid |
3004 |
|
|
directory on the client: there is no need for it to correspond to |
3005 |
|
|
any Smb share or device mount point. |
3006 |
|
|
|
3007 |
|
|
Note also that you can also use $Conf{BackupFilesOnly} to specify |
3008 |
|
|
a specific list of directories to backup. It's more efficient to |
3009 |
|
|
use this option instead of $Conf{TarShareName} since a new tar is |
3010 |
|
|
run for each entry in $Conf{TarShareName}. |
3011 |
|
|
|
3012 |
|
|
On the other hand, if you add --one-file-system to $Conf{TarClientCmd} |
3013 |
|
|
you can backup each file system separately, which makes restoring one |
3014 |
|
|
bad file system easier. In this case you would list all of the mount |
3015 |
|
|
points here, since you can't get the same result with |
3016 |
|
|
$Conf{BackupFilesOnly}: |
3017 |
|
|
|
3018 |
|
|
$Conf{TarShareName} = ['/', '/var', '/data', '/boot']; |
3019 |
|
|
|
3020 |
|
|
This setting only matters if $Conf{XferMethod} = 'tar'. |
3021 |
|
|
|
3022 |
|
|
=item $Conf{FullPeriod} = 6.97; |
3023 |
|
|
|
3024 |
|
|
Minimum period in days between full backups. A full dump will only be |
3025 |
|
|
done if at least this much time has elapsed since the last full dump, |
3026 |
|
|
and at least $Conf{IncrPeriod} days has elapsed since the last |
3027 |
|
|
successful dump. |
3028 |
|
|
|
3029 |
|
|
Typically this is set slightly less than an integer number of days. The |
3030 |
|
|
time taken for the backup, plus the granularity of $Conf{WakeupSchedule} |
3031 |
|
|
will make the actual backup interval a bit longer. |
3032 |
|
|
|
3033 |
|
|
There are two special values for $Conf{FullPeriod}: |
3034 |
|
|
|
3035 |
|
|
-1 Don't do any regular backups on this machine. Manually |
3036 |
|
|
requested backups (via the CGI interface) will still occur. |
3037 |
|
|
|
3038 |
|
|
-2 Don't do any backups on this machine. Manually requested |
3039 |
|
|
backups (via the CGI interface) will be ignored. |
3040 |
|
|
|
3041 |
|
|
These special settings are useful for a client that is no longer |
3042 |
|
|
being backed up (eg: a retired machine), but you wish to keep the |
3043 |
|
|
last backups available for browsing or restoring to other machines. |
3044 |
|
|
|
3045 |
|
|
=item $Conf{IncrPeriod} = 0.97; |
3046 |
|
|
|
3047 |
|
|
Minimum period in days between incremental backups (a user requested |
3048 |
|
|
incremental backup will be done anytime on demand). |
3049 |
|
|
|
3050 |
|
|
Typically this is set slightly less than an integer number of days. The |
3051 |
|
|
time taken for the backup, plus the granularity of $Conf{WakeupSchedule} |
3052 |
|
|
will make the actual backup interval a bit longer. |
3053 |
|
|
|
3054 |
|
|
=item $Conf{FullKeepCnt} = 1; |
3055 |
|
|
|
3056 |
|
|
Number of full backups to keep. Must be >= 1. |
3057 |
|
|
|
3058 |
|
|
In the steady state, each time a full backup completes successfully |
3059 |
|
|
the oldest one is removed. If this number is decreased, the |
3060 |
|
|
extra old backups will be removed. |
3061 |
|
|
|
3062 |
|
|
If filling of incremental dumps is off the oldest backup always |
3063 |
|
|
has to be a full (ie: filled) dump. This might mean one or two |
3064 |
|
|
extra full dumps are kept until the oldest incremental backups expire. |
3065 |
|
|
|
3066 |
|
|
Exponential backup expiry is also supported. This allows you to specify: |
3067 |
|
|
|
3068 |
|
|
- num fulls to keep at intervals of 1 * $Conf{FullPeriod}, followed by |
3069 |
|
|
- num fulls to keep at intervals of 2 * $Conf{FullPeriod}, |
3070 |
|
|
- num fulls to keep at intervals of 4 * $Conf{FullPeriod}, |
3071 |
|
|
- num fulls to keep at intervals of 8 * $Conf{FullPeriod}, |
3072 |
|
|
- num fulls to keep at intervals of 16 * $Conf{FullPeriod}, |
3073 |
|
|
|
3074 |
|
|
and so on. This works by deleting every other full as each expiry |
3075 |
|
|
boundary is crossed. |
3076 |
|
|
|
3077 |
|
|
Exponential expiry is specified using an array for $Conf{FullKeepCnt}: |
3078 |
|
|
|
3079 |
|
|
$Conf{FullKeepCnt} = [4, 2, 3]; |
3080 |
|
|
|
3081 |
|
|
Entry #n specifies how many fulls to keep at an interval of |
3082 |
|
|
2^n * $Conf{FullPeriod} (ie: 1, 2, 4, 8, 16, 32, ...). |
3083 |
|
|
|
3084 |
|
|
The example above specifies keeping 4 of the most recent full backups |
3085 |
|
|
(1 week interval) two full backups at 2 week intervals, and 3 full |
3086 |
|
|
backups at 4 week intervals, eg: |
3087 |
|
|
|
3088 |
|
|
full 0 19 weeks old \ |
3089 |
|
|
full 1 15 weeks old >--- 3 backups at 4 * $Conf{FullPeriod} |
3090 |
|
|
full 2 11 weeks old / |
3091 |
|
|
full 3 7 weeks old \____ 2 backups at 2 * $Conf{FullPeriod} |
3092 |
|
|
full 4 5 weeks old / |
3093 |
|
|
full 5 3 weeks old \ |
3094 |
|
|
full 6 2 weeks old \___ 4 backups at 1 * $Conf{FullPeriod} |
3095 |
|
|
full 7 1 week old / |
3096 |
|
|
full 8 current / |
3097 |
|
|
|
3098 |
|
|
On a given week the spacing might be less than shown as each backup |
3099 |
|
|
ages through each expiry period. For example, one week later, a |
3100 |
|
|
new full is completed and the oldest is deleted, giving: |
3101 |
|
|
|
3102 |
|
|
full 0 16 weeks old \ |
3103 |
|
|
full 1 12 weeks old >--- 3 backups at 4 * $Conf{FullPeriod} |
3104 |
|
|
full 2 8 weeks old / |
3105 |
|
|
full 3 6 weeks old \____ 2 backups at 2 * $Conf{FullPeriod} |
3106 |
|
|
full 4 4 weeks old / |
3107 |
|
|
full 5 3 weeks old \ |
3108 |
|
|
full 6 2 weeks old \___ 4 backups at 1 * $Conf{FullPeriod} |
3109 |
|
|
full 7 1 week old / |
3110 |
|
|
full 8 current / |
3111 |
|
|
|
3112 |
|
|
You can specify 0 as a count (except in the first entry), and the |
3113 |
|
|
array can be as long as you wish. For example: |
3114 |
|
|
|
3115 |
|
|
|
3116 |
|
|
$Conf{FullKeepCnt} = [4, 0, 4, 0, 0, 2]; |
3117 |
|
|
|
3118 |
|
|
This will keep 10 full dumps, 4 most recent at 1 * $Conf{FullPeriod}, |
3119 |
|
|
followed by 4 at an interval of 4 * $Conf{FullPeriod} (approx 1 month |
3120 |
|
|
apart), and then 2 at an interval of 32 * $Conf{FullPeriod} (approx |
3121 |
|
|
7-8 months apart). |
3122 |
|
|
|
3123 |
|
|
Example: these two settings are equivalent and both keep just |
3124 |
|
|
the four most recent full dumps: |
3125 |
|
|
|
3126 |
|
|
$Conf{FullKeepCnt} = 4; |
3127 |
|
|
$Conf{FullKeepCnt} = [4]; |
3128 |
|
|
|
3129 |
|
|
=item $Conf{FullKeepCntMin} = 1; |
3130 |
|
|
|
3131 |
|
|
=item $Conf{FullAgeMax} = 90; |
3132 |
|
|
|
3133 |
|
|
Very old full backups are removed after $Conf{FullAgeMax} days. However, |
3134 |
|
|
we keep at least $Conf{FullKeepCntMin} full backups no matter how old |
3135 |
|
|
they are. |
3136 |
|
|
|
3137 |
|
|
Note that $Conf{FullAgeMax} will be increased to $Conf{FullAgeMax} |
3138 |
|
|
times $Conf{FullPeriod} if $Conf{FullAgeMax} specifies enough |
3139 |
|
|
full backups to exceed $Conf{FullAgeMax}. |
3140 |
|
|
|
3141 |
|
|
=item $Conf{IncrKeepCnt} = 6; |
3142 |
|
|
|
3143 |
|
|
Number of incremental backups to keep. Must be >= 1. |
3144 |
|
|
|
3145 |
|
|
In the steady state, each time an incr backup completes successfully |
3146 |
|
|
the oldest one is removed. If this number is decreased, the |
3147 |
|
|
extra old backups will be removed. |
3148 |
|
|
|
3149 |
|
|
=item $Conf{IncrKeepCntMin} = 1; |
3150 |
|
|
|
3151 |
|
|
=item $Conf{IncrAgeMax} = 30; |
3152 |
|
|
|
3153 |
|
|
Very old incremental backups are removed after $Conf{IncrAgeMax} days. |
3154 |
|
|
However, we keep at least $Conf{IncrKeepCntMin} incremental backups no |
3155 |
|
|
matter how old they are. |
3156 |
|
|
|
3157 |
|
|
=item $Conf{PartialAgeMax} = 3; |
3158 |
|
|
|
3159 |
|
|
A failed full backup is saved as a partial backup. The rsync |
3160 |
|
|
XferMethod can take advantage of the partial full when the next |
3161 |
|
|
backup is run. This parameter sets the age of the partial full |
3162 |
|
|
in days: if the partial backup is older than this number of |
3163 |
|
|
days, then rsync will ignore (not use) the partial full when |
3164 |
|
|
the next backup is run. If you set this to a negative value |
3165 |
|
|
then no partials will be saved. If you set this to 0, partials |
3166 |
|
|
will be saved, but will not be used by the next backup. |
3167 |
|
|
|
3168 |
|
|
The default setting of 3 days means that a partial older than |
3169 |
|
|
3 days is ignored when the next full backup is done. |
3170 |
|
|
|
3171 |
|
|
=item $Conf{IncrFill} = 0; |
3172 |
|
|
|
3173 |
|
|
Whether incremental backups are filled. "Filling" means that the |
3174 |
|
|
most recent full (or filled) dump is merged into the new incremental |
3175 |
|
|
dump using hardlinks. This makes an incremental dump look like a |
3176 |
|
|
full dump. Prior to v1.03 all incremental backups were filled. |
3177 |
|
|
In v1.4.0 and later the default is off. |
3178 |
|
|
|
3179 |
|
|
BackupPC, and the cgi interface in particular, do the right thing on |
3180 |
|
|
un-filled incremental backups. It will correctly display the merged |
3181 |
|
|
incremental backup with the most recent filled backup, giving the |
3182 |
|
|
un-filled incremental backups a filled appearance. That means it |
3183 |
|
|
invisible to the user whether incremental dumps are filled or not. |
3184 |
|
|
|
3185 |
|
|
Filling backups takes a little extra disk space, and it does cost |
3186 |
|
|
some extra disk activity for filling, and later removal. Filling |
3187 |
|
|
is no longer useful, since file mangling and compression doesn't |
3188 |
|
|
make a filled backup very useful. It's likely the filling option |
3189 |
|
|
will be removed from future versions: filling will be delegated to |
3190 |
|
|
the display and extraction of backup data. |
3191 |
|
|
|
3192 |
|
|
If filling is off, BackupPC makes sure that the oldest backup is |
3193 |
|
|
a full, otherwise the following incremental backups will be |
3194 |
|
|
incomplete. This might mean an extra full backup has to be |
3195 |
|
|
kept until the following incremental backups expire. |
3196 |
|
|
|
3197 |
|
|
The default is off. You can turn this on or off at any |
3198 |
|
|
time without affecting existing backups. |
3199 |
|
|
|
3200 |
|
|
=item $Conf{RestoreInfoKeepCnt} = 10; |
3201 |
|
|
|
3202 |
|
|
Number of restore logs to keep. BackupPC remembers information about |
3203 |
|
|
each restore request. This number per client will be kept around before |
3204 |
|
|
the oldest ones are pruned. |
3205 |
|
|
|
3206 |
|
|
Note: files/dirs delivered via Zip or Tar downloads don't count as |
3207 |
|
|
restores. Only the first restore option (where the files and dirs |
3208 |
|
|
are written to the host) count as restores that are logged. |
3209 |
|
|
|
3210 |
|
|
=item $Conf{ArchiveInfoKeepCnt} = 10; |
3211 |
|
|
|
3212 |
|
|
Number of archive logs to keep. BackupPC remembers information |
3213 |
|
|
about each archive request. This number per archive client will |
3214 |
|
|
be kept around before the oldest ones are pruned. |
3215 |
|
|
|
3216 |
|
|
=item $Conf{BackupFilesOnly} = undef; |
3217 |
|
|
|
3218 |
|
|
List of directories or files to backup. If this is defined, only these |
3219 |
|
|
directories or files will be backed up. |
3220 |
|
|
|
3221 |
|
|
For Smb, only one of $Conf{BackupFilesExclude} and $Conf{BackupFilesOnly} |
3222 |
|
|
can be specified per share. If both are set for a particular share, then |
3223 |
|
|
$Conf{BackupFilesOnly} takes precedence and $Conf{BackupFilesExclude} |
3224 |
|
|
is ignored. |
3225 |
|
|
|
3226 |
|
|
This can be set to a string, an array of strings, or, in the case |
3227 |
|
|
of multiple shares, a hash of strings or arrays. A hash is used |
3228 |
|
|
to give a list of directories or files to backup for each share |
3229 |
|
|
(the share name is the key). If this is set to just a string or |
3230 |
|
|
array, and $Conf{SmbShareName} contains multiple share names, then |
3231 |
|
|
the setting is assumed to apply all shares. |
3232 |
|
|
|
3233 |
|
|
Examples: |
3234 |
|
|
|
3235 |
|
|
$Conf{BackupFilesOnly} = '/myFiles'; |
3236 |
|
|
$Conf{BackupFilesOnly} = ['/myFiles']; # same as first example |
3237 |
|
|
$Conf{BackupFilesOnly} = ['/myFiles', '/important']; |
3238 |
|
|
$Conf{BackupFilesOnly} = { |
3239 |
|
|
'c' => ['/myFiles', '/important'], # these are for 'c' share |
3240 |
|
|
'd' => ['/moreFiles', '/archive'], # these are for 'd' share |
3241 |
|
|
}; |
3242 |
|
|
|
3243 |
|
|
=item $Conf{BackupFilesExclude} = undef; |
3244 |
|
|
|
3245 |
|
|
List of directories or files to exclude from the backup. For Smb, |
3246 |
|
|
only one of $Conf{BackupFilesExclude} and $Conf{BackupFilesOnly} |
3247 |
|
|
can be specified per share. If both are set for a particular share, |
3248 |
|
|
then $Conf{BackupFilesOnly} takes precedence and |
3249 |
|
|
$Conf{BackupFilesExclude} is ignored. |
3250 |
|
|
|
3251 |
|
|
This can be set to a string, an array of strings, or, in the case |
3252 |
|
|
of multiple shares, a hash of strings or arrays. A hash is used |
3253 |
|
|
to give a list of directories or files to exclude for each share |
3254 |
|
|
(the share name is the key). If this is set to just a string or |
3255 |
|
|
array, and $Conf{SmbShareName} contains multiple share names, then |
3256 |
|
|
the setting is assumed to apply to all shares. |
3257 |
|
|
|
3258 |
|
|
The exact behavior is determined by the underlying transport program, |
3259 |
|
|
smbclient or tar. For smbclient the exlclude file list is passed into |
3260 |
|
|
the X option. Simple shell wild-cards using "*" or "?" are allowed. |
3261 |
|
|
|
3262 |
|
|
For tar, if the exclude file contains a "/" it is assumed to be anchored |
3263 |
|
|
at the start of the string. Since all the tar paths start with "./", |
3264 |
|
|
BackupPC prepends a "." if the exclude file starts with a "/". Note |
3265 |
|
|
that GNU tar version >= 1.13.7 is required for the exclude option to |
3266 |
|
|
work correctly. For linux or unix machines you should add |
3267 |
|
|
"/proc" to $Conf{BackupFilesExclude} unless you have specified |
3268 |
|
|
--one-file-system in $Conf{TarClientCmd} or --one-file-system in |
3269 |
|
|
$Conf{RsyncArgs}. Also, for tar, do not use a trailing "/" in |
3270 |
|
|
the directory name: a trailing "/" causes the name to not match |
3271 |
|
|
and the directory will not be excluded. |
3272 |
|
|
|
3273 |
|
|
Users report that for smbclient you should specify a directory |
3274 |
|
|
followed by "/*", eg: "/proc/*", instead of just "/proc". |
3275 |
|
|
|
3276 |
|
|
Examples: |
3277 |
|
|
|
3278 |
|
|
$Conf{BackupFilesExclude} = '/temp'; |
3279 |
|
|
$Conf{BackupFilesExclude} = ['/temp']; # same as first example |
3280 |
|
|
$Conf{BackupFilesExclude} = ['/temp', '/winnt/tmp']; |
3281 |
|
|
$Conf{BackupFilesExclude} = { |
3282 |
|
|
'c' => ['/temp', '/winnt/tmp'], # these are for 'c' share |
3283 |
|
|
'd' => ['/junk', '/dont_back_this_up'], # these are for 'd' share |
3284 |
|
|
}; |
3285 |
|
|
|
3286 |
|
|
=item $Conf{BlackoutBadPingLimit} = 3; |
3287 |
|
|
|
3288 |
|
|
=item $Conf{BlackoutGoodCnt} = 7; |
3289 |
|
|
|
3290 |
|
|
PCs that are always or often on the network can be backed up after |
3291 |
|
|
hours, to reduce PC, network and server load during working hours. For |
3292 |
|
|
each PC a count of consecutive good pings is maintained. Once a PC has |
3293 |
|
|
at least $Conf{BlackoutGoodCnt} consecutive good pings it is subject |
3294 |
|
|
to "blackout" and not backed up during hours and days specified by |
3295 |
|
|
$Conf{BlackoutPeriods}. |
3296 |
|
|
|
3297 |
|
|
To allow for periodic rebooting of a PC or other brief periods when a |
3298 |
|
|
PC is not on the network, a number of consecutive bad pings is allowed |
3299 |
|
|
before the good ping count is reset. This parameter is |
3300 |
|
|
$Conf{BlackoutBadPingLimit}. |
3301 |
|
|
|
3302 |
|
|
Note that bad and good pings don't occur with the same interval. If a |
3303 |
|
|
machine is always on the network, it will only be pinged roughly once |
3304 |
|
|
every $Conf{IncrPeriod} (eg: once per day). So a setting for |
3305 |
|
|
$Conf{BlackoutGoodCnt} of 7 means it will take around 7 days for a |
3306 |
|
|
machine to be subject to blackout. On the other hand, if a ping is |
3307 |
|
|
failed, it will be retried roughly every time BackupPC wakes up, eg, |
3308 |
|
|
every one or two hours. So a setting for $Conf{BlackoutBadPingLimit} of |
3309 |
|
|
3 means that the PC will lose its blackout status after 3-6 hours of |
3310 |
|
|
unavailability. |
3311 |
|
|
|
3312 |
|
|
To disable the blackout feature set $Conf{BlackoutGoodCnt} to a negative |
3313 |
|
|
value. A value of 0 will make all machines subject to blackout. But |
3314 |
|
|
if you don't want to do any backups during the day it would be easier |
3315 |
|
|
to just set $Conf{WakeupSchedule} to a restricted schedule. |
3316 |
|
|
|
3317 |
|
|
=item $Conf{BlackoutPeriods} = [ ... ]; |
3318 |
|
|
|
3319 |
|
|
One or more blackout periods can be specified. If a client is |
3320 |
|
|
subject to blackout then no regular (non-manual) backups will |
3321 |
|
|
be started during any of these periods. hourBegin and hourEnd |
3322 |
|
|
specify hours fro midnight and weekDays is a list of days of |
3323 |
|
|
the week where 0 is Sunday, 1 is Monday etc. |
3324 |
|
|
|
3325 |
|
|
For example: |
3326 |
|
|
|
3327 |
|
|
|
3328 |
|
|
$Conf{BlackoutPeriods} = [ |
3329 |
|
|
{ |
3330 |
|
|
hourBegin => 7.0, |
3331 |
|
|
hourEnd => 19.5, |
3332 |
|
|
weekDays => [1, 2, 3, 4, 5], |
3333 |
|
|
}, |
3334 |
|
|
]; |
3335 |
|
|
|
3336 |
|
|
specifies one blackout period from 7:00am to 7:30pm local time |
3337 |
|
|
on Mon-Fri. |
3338 |
|
|
|
3339 |
|
|
The blackout period can also span midnight by setting |
3340 |
|
|
hourBegin > hourEnd, eg: |
3341 |
|
|
|
3342 |
|
|
$Conf{BlackoutPeriods} = [ |
3343 |
|
|
{ |
3344 |
|
|
hourBegin => 7.0, |
3345 |
|
|
hourEnd => 19.5, |
3346 |
|
|
weekDays => [1, 2, 3, 4, 5], |
3347 |
|
|
}, |
3348 |
|
|
{ |
3349 |
|
|
hourBegin => 23, |
3350 |
|
|
hourEnd => 5, |
3351 |
|
|
weekDays => [5, 6], |
3352 |
|
|
}, |
3353 |
|
|
]; |
3354 |
|
|
|
3355 |
|
|
This specifies one blackout period from 7:00am to 7:30pm local time |
3356 |
|
|
on Mon-Fri, and a second period from 11pm to 5am on Friday and |
3357 |
|
|
Saturday night. |
3358 |
|
|
|
3359 |
|
|
=item $Conf{BackupZeroFilesIsFatal} = 1; |
3360 |
|
|
|
3361 |
|
|
A backup of a share that has zero files is considered fatal. This is |
3362 |
|
|
used to catch miscellaneous Xfer errors that result in no files being |
3363 |
|
|
backed up. If you have shares that might be empty (and therefore an |
3364 |
|
|
empty backup is valid) you should set this flag to 0. |
3365 |
|
|
|
3366 |
|
|
=back |
3367 |
|
|
|
3368 |
|
|
=head2 General per-PC configuration settings |
3369 |
|
|
|
3370 |
|
|
=over 4 |
3371 |
|
|
|
3372 |
|
|
=item $Conf{XferMethod} = 'smb'; |
3373 |
|
|
|
3374 |
|
|
What transport method to use to backup each host. If you have |
3375 |
|
|
a mixed set of WinXX and linux/unix hosts you will need to override |
3376 |
|
|
this in the per-PC config.pl. |
3377 |
|
|
|
3378 |
|
|
The valid values are: |
3379 |
|
|
|
3380 |
|
|
- 'smb': backup and restore via smbclient and the SMB protocol. |
3381 |
|
|
Easiest choice for WinXX. |
3382 |
|
|
|
3383 |
|
|
- 'rsync': backup and restore via rsync (via rsh or ssh). |
3384 |
|
|
Best choice for linux/unix. Good choice also for WinXX. |
3385 |
|
|
|
3386 |
dpavlin |
316 |
- 'rsyncd': backup and restore via rsync daemon on the client. |
3387 |
dpavlin |
1 |
Best choice for linux/unix if you have rsyncd running on |
3388 |
|
|
the client. Good choice also for WinXX. |
3389 |
|
|
|
3390 |
|
|
- 'tar': backup and restore via tar, tar over ssh, rsh or nfs. |
3391 |
|
|
Good choice for linux/unix. |
3392 |
|
|
|
3393 |
|
|
- 'archive': host is a special archive host. Backups are not done. |
3394 |
|
|
An archive host is used to archive other host's backups |
3395 |
|
|
to permanent media, such as tape, CDR or DVD. |
3396 |
|
|
|
3397 |
|
|
|
3398 |
|
|
=item $Conf{XferLogLevel} = 1; |
3399 |
|
|
|
3400 |
|
|
Level of verbosity in Xfer log files. 0 means be quiet, 1 will give |
3401 |
|
|
will give one line per file, 2 will also show skipped files on |
3402 |
|
|
incrementals, higher values give more output. |
3403 |
|
|
|
3404 |
|
|
=item $Conf{SmbClientPath} = '/usr/bin/smbclient'; |
3405 |
|
|
|
3406 |
|
|
Full path for smbclient. Security caution: normal users should not |
3407 |
|
|
allowed to write to this file or directory. |
3408 |
|
|
|
3409 |
|
|
smbclient is from the Samba distribution. smbclient is used to |
3410 |
|
|
actually extract the incremental or full dump of the share filesystem |
3411 |
|
|
from the PC. |
3412 |
|
|
|
3413 |
|
|
This setting only matters if $Conf{XferMethod} = 'smb'. |
3414 |
|
|
|
3415 |
|
|
=item $Conf{SmbClientFullCmd} = '$smbClientPath \\\\$host\\$shareName' ... |
3416 |
|
|
|
3417 |
|
|
Command to run smbclient for a full dump. |
3418 |
|
|
This setting only matters if $Conf{XferMethod} = 'smb'. |
3419 |
|
|
|
3420 |
|
|
The following variables are substituted at run-time: |
3421 |
|
|
|
3422 |
|
|
$smbClientPath same as $Conf{SmbClientPath} |
3423 |
|
|
$host host to backup/restore |
3424 |
|
|
$hostIP host IP address |
3425 |
|
|
$shareName share name |
3426 |
|
|
$userName user name |
3427 |
|
|
$fileList list of files to backup (based on exclude/include) |
3428 |
|
|
$I_option optional -I option to smbclient |
3429 |
|
|
$X_option exclude option (if $fileList is an exclude list) |
3430 |
|
|
$timeStampFile start time for incremental dump |
3431 |
|
|
|
3432 |
|
|
=item $Conf{SmbClientIncrCmd} = '$smbClientPath \\\\$host\\$shareName' ... |
3433 |
|
|
|
3434 |
|
|
Command to run smbclient for an incremental dump. |
3435 |
|
|
This setting only matters if $Conf{XferMethod} = 'smb'. |
3436 |
|
|
|
3437 |
|
|
Same variable substitutions are applied as $Conf{SmbClientFullCmd}. |
3438 |
|
|
|
3439 |
|
|
=item $Conf{SmbClientRestoreCmd} = '$smbClientPath \\\\$host\\$shareName' ... |
3440 |
|
|
|
3441 |
|
|
Command to run smbclient for a restore. |
3442 |
|
|
This setting only matters if $Conf{XferMethod} = 'smb'. |
3443 |
|
|
|
3444 |
|
|
Same variable substitutions are applied as $Conf{SmbClientFullCmd}. |
3445 |
|
|
|
3446 |
|
|
If your smb share is read-only then direct restores will fail. |
3447 |
|
|
You should set $Conf{SmbClientRestoreCmd} to undef and the |
3448 |
|
|
corresponding CGI restore option will be removed. |
3449 |
|
|
|
3450 |
|
|
=item $Conf{TarClientCmd} = '$sshPath -q -x -n -l root $host' ... |
3451 |
|
|
|
3452 |
|
|
Full command to run tar on the client. GNU tar is required. You will |
3453 |
|
|
need to fill in the correct paths for ssh2 on the local host (server) |
3454 |
|
|
and GNU tar on the client. Security caution: normal users should not |
3455 |
|
|
allowed to write to these executable files or directories. |
3456 |
|
|
|
3457 |
|
|
See the documentation for more information about setting up ssh2 keys. |
3458 |
|
|
|
3459 |
|
|
If you plan to use NFS then tar just runs locally and ssh2 is not needed. |
3460 |
|
|
For example, assuming the client filesystem is mounted below /mnt/hostName, |
3461 |
|
|
you could use something like: |
3462 |
|
|
|
3463 |
|
|
$Conf{TarClientCmd} = '$tarPath -c -v -f - -C /mnt/$host/$shareName' |
3464 |
|
|
. ' --totals'; |
3465 |
|
|
|
3466 |
|
|
In the case of NFS or rsh you need to make sure BackupPC's privileges |
3467 |
|
|
are sufficient to read all the files you want to backup. Also, you |
3468 |
|
|
will probably want to add "/proc" to $Conf{BackupFilesExclude}. |
3469 |
|
|
|
3470 |
|
|
The following variables are substituted at run-time: |
3471 |
|
|
|
3472 |
|
|
$host host name |
3473 |
|
|
$hostIP host's IP address |
3474 |
|
|
$incrDate newer-than date for incremental backups |
3475 |
|
|
$shareName share name to backup (ie: top-level directory path) |
3476 |
|
|
$fileList specific files to backup or exclude |
3477 |
|
|
$tarPath same as $Conf{TarClientPath} |
3478 |
|
|
$sshPath same as $Conf{SshPath} |
3479 |
|
|
|
3480 |
|
|
If a variable is followed by a "+" it is shell escaped. This is |
3481 |
|
|
necessary for the command part of ssh or rsh, since it ends up |
3482 |
|
|
getting passed through the shell. |
3483 |
|
|
|
3484 |
|
|
This setting only matters if $Conf{XferMethod} = 'tar'. |
3485 |
|
|
|
3486 |
|
|
=item $Conf{TarFullArgs} = '$fileList+'; |
3487 |
|
|
|
3488 |
|
|
Extra tar arguments for full backups. Several variables are substituted at |
3489 |
|
|
run-time. See $Conf{TarClientCmd} for the list of variable substitutions. |
3490 |
|
|
|
3491 |
|
|
If you are running tar locally (ie: without rsh or ssh) then remove the |
3492 |
|
|
"+" so that the argument is no longer shell escaped. |
3493 |
|
|
|
3494 |
|
|
This setting only matters if $Conf{XferMethod} = 'tar'. |
3495 |
|
|
|
3496 |
|
|
=item $Conf{TarIncrArgs} = '--newer=$incrDate+ $fileList+'; |
3497 |
|
|
|
3498 |
|
|
Extra tar arguments for incr backups. Several variables are substituted at |
3499 |
|
|
run-time. See $Conf{TarClientCmd} for the list of variable substitutions. |
3500 |
|
|
|
3501 |
|
|
Note that GNU tar has several methods for specifying incremental backups, |
3502 |
|
|
including: |
3503 |
|
|
|
3504 |
|
|
--newer-mtime $incrDate+ |
3505 |
|
|
This causes a file to be included if the modification time is |
3506 |
|
|
later than $incrDate (meaning its contents might have changed). |
3507 |
|
|
But changes in the ownership or modes will not qualify the |
3508 |
|
|
file to be included in an incremental. |
3509 |
|
|
|
3510 |
|
|
--newer=$incrDate+ |
3511 |
|
|
This causes the file to be included if any attribute of the |
3512 |
|
|
file is later than $incrDate, meaning either attributes or |
3513 |
|
|
the modification time. This is the default method. Do |
3514 |
|
|
not use --atime-preserve in $Conf{TarClientCmd} above, |
3515 |
|
|
otherwise resetting the atime (access time) counts as an |
3516 |
|
|
attribute change, meaning the file will always be included |
3517 |
|
|
in each new incremental dump. |
3518 |
|
|
|
3519 |
|
|
If you are running tar locally (ie: without rsh or ssh) then remove the |
3520 |
|
|
"+" so that the argument is no longer shell escaped. |
3521 |
|
|
|
3522 |
|
|
This setting only matters if $Conf{XferMethod} = 'tar'. |
3523 |
|
|
|
3524 |
|
|
=item $Conf{TarClientRestoreCmd} = '$sshPath -q -x -l root $host' ... |
3525 |
|
|
|
3526 |
|
|
Full command to run tar for restore on the client. GNU tar is required. |
3527 |
|
|
This can be the same as $Conf{TarClientCmd}, with tar's -c replaced by -x |
3528 |
|
|
and ssh's -n removed. |
3529 |
|
|
|
3530 |
|
|
See $Conf{TarClientCmd} for full details. |
3531 |
|
|
|
3532 |
|
|
This setting only matters if $Conf{XferMethod} = "tar". |
3533 |
|
|
|
3534 |
|
|
If you want to disable direct restores using tar, you should set |
3535 |
|
|
$Conf{TarClientRestoreCmd} to undef and the corresponding CGI |
3536 |
|
|
restore option will be removed. |
3537 |
|
|
|
3538 |
|
|
=item $Conf{TarClientPath} = '/bin/tar'; |
3539 |
|
|
|
3540 |
|
|
Full path for tar on the client. Security caution: normal users should not |
3541 |
|
|
allowed to write to this file or directory. |
3542 |
|
|
|
3543 |
|
|
This setting only matters if $Conf{XferMethod} = 'tar'. |
3544 |
|
|
|
3545 |
|
|
=item $Conf{RsyncClientPath} = '/bin/rsync'; |
3546 |
|
|
|
3547 |
|
|
Path to rsync executable on the client |
3548 |
|
|
|
3549 |
|
|
=item $Conf{RsyncClientCmd} = '$sshPath -q -x -l root $host $rsyncPath $argList+'; |
3550 |
|
|
|
3551 |
|
|
Full command to run rsync on the client machine. The following variables |
3552 |
|
|
are substituted at run-time: |
3553 |
|
|
|
3554 |
|
|
$host host name being backed up |
3555 |
|
|
$hostIP host's IP address |
3556 |
|
|
$shareName share name to backup (ie: top-level directory path) |
3557 |
|
|
$rsyncPath same as $Conf{RsyncClientPath} |
3558 |
|
|
$sshPath same as $Conf{SshPath} |
3559 |
|
|
$argList argument list, built from $Conf{RsyncArgs}, |
3560 |
|
|
$shareName, $Conf{BackupFilesExclude} and |
3561 |
|
|
$Conf{BackupFilesOnly} |
3562 |
|
|
|
3563 |
|
|
This setting only matters if $Conf{XferMethod} = 'rsync'. |
3564 |
|
|
|
3565 |
|
|
=item $Conf{RsyncClientRestoreCmd} = '$sshPath -q -x -l root $host $rsyncPath $argList+'; |
3566 |
|
|
|
3567 |
|
|
Full command to run rsync for restore on the client. The following |
3568 |
|
|
variables are substituted at run-time: |
3569 |
|
|
|
3570 |
|
|
$host host name being backed up |
3571 |
|
|
$hostIP host's IP address |
3572 |
|
|
$shareName share name to backup (ie: top-level directory path) |
3573 |
|
|
$rsyncPath same as $Conf{RsyncClientPath} |
3574 |
|
|
$sshPath same as $Conf{SshPath} |
3575 |
|
|
$argList argument list, built from $Conf{RsyncArgs}, |
3576 |
|
|
$shareName, $Conf{BackupFilesExclude} and |
3577 |
|
|
$Conf{BackupFilesOnly} |
3578 |
|
|
|
3579 |
|
|
This setting only matters if $Conf{XferMethod} = 'rsync'. |
3580 |
|
|
|
3581 |
|
|
=item $Conf{RsyncShareName} = '/'; |
3582 |
|
|
|
3583 |
|
|
Share name to backup. For $Conf{XferMethod} = "rsync" this should |
3584 |
|
|
be a file system path, eg '/' or '/home'. |
3585 |
|
|
|
3586 |
|
|
For $Conf{XferMethod} = "rsyncd" this should be the name of the module |
3587 |
|
|
to backup (ie: the name from /etc/rsynd.conf). |
3588 |
|
|
|
3589 |
|
|
This can also be a list of multiple file system paths or modules. |
3590 |
|
|
For example, by adding --one-file-system to $Conf{RsyncArgs} you |
3591 |
|
|
can backup each file system separately, which makes restoring one |
3592 |
|
|
bad file system easier. In this case you would list all of the mount |
3593 |
|
|
points: |
3594 |
|
|
|
3595 |
|
|
$Conf{RsyncShareName} = ['/', '/var', '/data', '/boot']; |
3596 |
|
|
|
3597 |
|
|
=item $Conf{RsyncdClientPort} = 873; |
3598 |
|
|
|
3599 |
|
|
Rsync daemon port on the client, for $Conf{XferMethod} = "rsyncd". |
3600 |
|
|
|
3601 |
|
|
=item $Conf{RsyncdUserName} = ''; |
3602 |
|
|
|
3603 |
|
|
Rsync daemon user name on client, for $Conf{XferMethod} = "rsyncd". |
3604 |
|
|
The user name and password are stored on the client in whatever file |
3605 |
|
|
the "secrets file" parameter in rsyncd.conf points to |
3606 |
|
|
(eg: /etc/rsyncd.secrets). |
3607 |
|
|
|
3608 |
|
|
=item $Conf{RsyncdPasswd} = ''; |
3609 |
|
|
|
3610 |
|
|
Rsync daemon user name on client, for $Conf{XferMethod} = "rsyncd". |
3611 |
|
|
The user name and password are stored on the client in whatever file |
3612 |
|
|
the "secrets file" parameter in rsyncd.conf points to |
3613 |
|
|
(eg: /etc/rsyncd.secrets). |
3614 |
|
|
|
3615 |
|
|
=item $Conf{RsyncdAuthRequired} = 1; |
3616 |
|
|
|
3617 |
|
|
Whether authentication is mandatory when connecting to the client's |
3618 |
|
|
rsyncd. By default this is on, ensuring that BackupPC will refuse to |
3619 |
|
|
connect to an rsyncd on the client that is not password protected. |
3620 |
|
|
Turn off at your own risk. |
3621 |
|
|
|
3622 |
|
|
=item $Conf{RsyncCsumCacheVerifyProb} = 0.01; |
3623 |
|
|
|
3624 |
|
|
When rsync checksum caching is enabled (by adding the |
3625 |
|
|
--checksum-seed=32761 option to $Conf{RsyncArgs}), the cached |
3626 |
|
|
checksums can be occaisonally verified to make sure the file |
3627 |
|
|
contents matches the cached checksums. This is to avoid the |
3628 |
|
|
risk that disk problems might cause the pool file contents to |
3629 |
|
|
get corrupted, but the cached checksums would make BackupPC |
3630 |
|
|
think that the file still matches the client. |
3631 |
|
|
|
3632 |
|
|
This setting is the probability (0 means never and 1 means always) |
3633 |
|
|
that a file will be rechecked. Setting it to 0 means the checksums |
3634 |
|
|
will not be rechecked (unless there is a phase 0 failure). Setting |
3635 |
|
|
it to 1 (ie: 100%) means all files will be checked, but that is |
3636 |
|
|
not a desirable setting since you are better off simply turning |
3637 |
|
|
caching off (ie: remove the --checksum-seed option). |
3638 |
|
|
|
3639 |
|
|
The default of 0.01 means 1% (on average) of the files during a full |
3640 |
|
|
backup will have their cached checksum re-checked. |
3641 |
|
|
|
3642 |
|
|
This setting has no effect unless checksum caching is turned on. |
3643 |
|
|
|
3644 |
|
|
=item $Conf{RsyncArgs} = [ ... ]; |
3645 |
|
|
|
3646 |
|
|
Arguments to rsync for backup. Do not edit the first set unless you |
3647 |
|
|
have a thorough understanding of how File::RsyncP works. |
3648 |
|
|
|
3649 |
|
|
Examples of additional arguments that should work are --exclude/--include, |
3650 |
|
|
eg: |
3651 |
|
|
|
3652 |
|
|
$Conf{RsyncArgs} = [ |
3653 |
|
|
# original arguments here |
3654 |
|
|
'-v', |
3655 |
|
|
'--exclude', '/proc', |
3656 |
|
|
'--exclude', '*.tmp', |
3657 |
|
|
]; |
3658 |
|
|
|
3659 |
|
|
=item $Conf{RsyncRestoreArgs} = [ ... ]; |
3660 |
|
|
|
3661 |
|
|
Arguments to rsync for restore. Do not edit the first set unless you |
3662 |
|
|
have a thorough understanding of how File::RsyncP works. |
3663 |
|
|
|
3664 |
|
|
If you want to disable direct restores using rsync (eg: is the module |
3665 |
|
|
is read-only), you should set $Conf{RsyncRestoreArgs} to undef and |
3666 |
|
|
the corresponding CGI restore option will be removed. |
3667 |
|
|
|
3668 |
|
|
=item $Conf{ArchiveDest} = '/tmp'; |
3669 |
|
|
|
3670 |
|
|
Archive Destination |
3671 |
|
|
|
3672 |
|
|
The Destination of the archive |
3673 |
|
|
e.g. /tmp for file archive or /dev/nst0 for device archive |
3674 |
|
|
|
3675 |
|
|
=item $Conf{ArchiveComp} = 'gzip'; |
3676 |
|
|
|
3677 |
|
|
Archive Compression type |
3678 |
|
|
|
3679 |
|
|
The valid values are: |
3680 |
|
|
|
3681 |
|
|
- 'none': No Compression |
3682 |
|
|
|
3683 |
|
|
- 'gzip': Medium Compression. Recommended. |
3684 |
|
|
|
3685 |
|
|
- 'bzip2': High Compression but takes longer. |
3686 |
|
|
|
3687 |
|
|
=item $Conf{ArchivePar} = 0; |
3688 |
|
|
|
3689 |
|
|
Archive Parity Files |
3690 |
|
|
|
3691 |
|
|
The amount of Parity data to generate, as a percentage |
3692 |
|
|
of the archive size. |
3693 |
|
|
Uses the commandline par2 (par2cmdline) available from |
3694 |
|
|
http://parchive.sourceforge.net |
3695 |
|
|
|
3696 |
|
|
Only useful for file dumps. |
3697 |
|
|
|
3698 |
|
|
Set to 0 to disable this feature. |
3699 |
|
|
|
3700 |
|
|
=item $Conf{ArchiveSplit} = 0; |
3701 |
|
|
|
3702 |
|
|
Archive Size Split |
3703 |
|
|
|
3704 |
|
|
Only for file archives. Splits the output into |
3705 |
|
|
the specified size * 1,000,000. |
3706 |
|
|
e.g. to split into 650,000,000 bytes, specify 650 below. |
3707 |
|
|
|
3708 |
|
|
If the value is 0, or if $Conf{ArchiveDest} is an existing file or |
3709 |
|
|
device (e.g. a streaming tape drive), this feature is disabled. |
3710 |
|
|
|
3711 |
|
|
=item $Conf{ArchiveClientCmd} = '$Installdir/bin/BackupPC_archiveHost' ... |
3712 |
|
|
|
3713 |
|
|
Archive Command |
3714 |
|
|
|
3715 |
|
|
This is the command that is called to actually run the archive process |
3716 |
|
|
for each host. The following variables are substituted at run-time: |
3717 |
|
|
|
3718 |
|
|
$Installdir The installation directory of BackupPC |
3719 |
|
|
$tarCreatePath The path to BackupPC_tarCreate |
3720 |
|
|
$splitpath The path to the split program |
3721 |
|
|
$parpath The path to the par2 program |
3722 |
|
|
$host The host to archive |
3723 |
|
|
$backupnumber The backup number of the host to archive |
3724 |
|
|
$compression The path to the compression program |
3725 |
|
|
$compext The extension assigned to the compression type |
3726 |
|
|
$splitsize The number of bytes to split archives into |
3727 |
|
|
$archiveloc The location to put the archive |
3728 |
|
|
$parfile The amount of parity data to create (percentage) |
3729 |
|
|
|
3730 |
|
|
=item $Conf{SshPath} = '/usr/bin/ssh'; |
3731 |
|
|
|
3732 |
|
|
Full path for ssh. Security caution: normal users should not |
3733 |
|
|
allowed to write to this file or directory. |
3734 |
|
|
|
3735 |
|
|
=item $Conf{NmbLookupPath} = '/usr/bin/nmblookup'; |
3736 |
|
|
|
3737 |
|
|
Full path for nmblookup. Security caution: normal users should not |
3738 |
|
|
allowed to write to this file or directory. |
3739 |
|
|
|
3740 |
|
|
nmblookup is from the Samba distribution. nmblookup is used to get the |
3741 |
|
|
netbios name, necessary for DHCP hosts. |
3742 |
|
|
|
3743 |
|
|
=item $Conf{NmbLookupCmd} = '$nmbLookupPath -A $host'; |
3744 |
|
|
|
3745 |
|
|
NmbLookup command. Given an IP address, does an nmblookup on that |
3746 |
|
|
IP address. The following variables are substituted at run-time: |
3747 |
|
|
|
3748 |
|
|
$nmbLookupPath path to nmblookup ($Conf{NmbLookupPath}) |
3749 |
|
|
$host IP address |
3750 |
|
|
|
3751 |
|
|
This command is only used for DHCP hosts: given an IP address, this |
3752 |
|
|
command should try to find its NetBios name. |
3753 |
|
|
|
3754 |
|
|
=item $Conf{NmbLookupFindHostCmd} = '$nmbLookupPath $host'; |
3755 |
|
|
|
3756 |
|
|
NmbLookup command. Given a netbios name, finds that host by doing |
3757 |
|
|
a NetBios lookup. Several variables are substituted at run-time: |
3758 |
|
|
|
3759 |
|
|
$nmbLookupPath path to nmblookup ($Conf{NmbLookupPath}) |
3760 |
|
|
$host NetBios name |
3761 |
|
|
|
3762 |
|
|
In some cases you might need to change the broadcast address, for |
3763 |
|
|
example if nmblookup uses 192.168.255.255 by default and you find |
3764 |
|
|
that doesn't work, try 192.168.1.255 (or your equivalent class C |
3765 |
|
|
address) using the -B option: |
3766 |
|
|
|
3767 |
|
|
$Conf{NmbLookupFindHostCmd} = '$nmbLookupPath -B 192.168.1.255 $host'; |
3768 |
|
|
|
3769 |
|
|
If you use a WINS server and your machines don't respond to |
3770 |
|
|
multicast NetBios requests you can use this (replace 1.2.3.4 |
3771 |
|
|
with the IP address of your WINS server): |
3772 |
|
|
|
3773 |
|
|
$Conf{NmbLookupFindHostCmd} = '$nmbLookupPath -R -U 1.2.3.4 $host'; |
3774 |
|
|
|
3775 |
|
|
This is preferred over multicast since it minimizes network traffic. |
3776 |
|
|
|
3777 |
|
|
Experiment manually for your site to see what form of nmblookup command |
3778 |
|
|
works. |
3779 |
|
|
|
3780 |
|
|
=item $Conf{FixedIPNetBiosNameCheck} = 0; |
3781 |
|
|
|
3782 |
|
|
For fixed IP address hosts, BackupPC_dump can also verify the netbios |
3783 |
|
|
name to ensure it matches the host name. An error is generated if |
3784 |
|
|
they do not match. Typically this flag is off. But if you are going |
3785 |
|
|
to transition a bunch of machines from fixed host addresses to DHCP, |
3786 |
|
|
setting this flag is a great way to verify that the machines have |
3787 |
|
|
their netbios name set correctly before turning on DCHP. |
3788 |
|
|
|
3789 |
|
|
=item $Conf{PingPath} = '/bin/ping'; |
3790 |
|
|
|
3791 |
|
|
Full path to the ping command. Security caution: normal users |
3792 |
|
|
should not be allowed to write to this file or directory. |
3793 |
|
|
|
3794 |
|
|
If you want to disable ping checking, set this to some program |
3795 |
|
|
that exits with 0 status, eg: |
3796 |
|
|
|
3797 |
|
|
$Conf{PingPath} = '/bin/echo'; |
3798 |
|
|
|
3799 |
|
|
=item $Conf{PingCmd} = '$pingPath -c 1 $host'; |
3800 |
|
|
|
3801 |
|
|
Ping command. The following variables are substituted at run-time: |
3802 |
|
|
|
3803 |
|
|
$pingPath path to ping ($Conf{PingPath}) |
3804 |
|
|
$host host name |
3805 |
|
|
|
3806 |
|
|
Wade Brown reports that on solaris 2.6 and 2.7 ping -s returns the wrong |
3807 |
|
|
exit status (0 even on failure). Replace with "ping $host 1", which |
3808 |
|
|
gets the correct exit status but we don't get the round-trip time. |
3809 |
|
|
|
3810 |
|
|
=item $Conf{ServerInitdPath} = ''; |
3811 |
|
|
|
3812 |
|
|
=item $Conf{ServerInitdStartCmd} = ''; |
3813 |
|
|
|
3814 |
|
|
Path to init.d script and command to use that script to start the |
3815 |
|
|
server from the CGI interface. The following variables are substituted |
3816 |
|
|
at run-time: |
3817 |
|
|
|
3818 |
|
|
$sshPath path to ssh ($Conf{SshPath}) |
3819 |
|
|
$serverHost same as $Conf{ServerHost} |
3820 |
|
|
$serverInitdPath path to init.d script ($Conf{ServerInitdPath}) |
3821 |
|
|
|
3822 |
|
|
Example: |
3823 |
|
|
|
3824 |
|
|
|
3825 |
|
|
$Conf{ServerInitdPath} = '/etc/init.d/backuppc'; |
3826 |
|
|
$Conf{ServerInitdStartCmd} = '$sshPath -q -x -l root $serverHost' |
3827 |
|
|
. ' $serverInitdPath start' |
3828 |
|
|
. ' < /dev/null >& /dev/null'; |
3829 |
|
|
|
3830 |
|
|
=item $Conf{CompressLevel} = 0; |
3831 |
|
|
|
3832 |
|
|
Compression level to use on files. 0 means no compression. Compression |
3833 |
|
|
levels can be from 1 (least cpu time, slightly worse compression) to |
3834 |
|
|
9 (most cpu time, slightly better compression). The recommended value |
3835 |
|
|
is 3. Changing to 5, for example, will take maybe 20% more cpu time |
3836 |
|
|
and will get another 2-3% additional compression. See the zlib |
3837 |
|
|
documentation for more information about compression levels. |
3838 |
|
|
|
3839 |
|
|
Changing compression on or off after backups have already been done |
3840 |
|
|
will require both compressed and uncompressed pool files to be stored. |
3841 |
|
|
This will increase the pool storage requirements, at least until all |
3842 |
|
|
the old backups expire and are deleted. |
3843 |
|
|
|
3844 |
|
|
It is ok to change the compression value (from one non-zero value to |
3845 |
|
|
another non-zero value) after dumps are already done. Since BackupPC |
3846 |
|
|
matches pool files by comparing the uncompressed versions, it will still |
3847 |
|
|
correctly match new incoming files against existing pool files. The |
3848 |
|
|
new compression level will take effect only for new files that are |
3849 |
|
|
newly compressed and added to the pool. |
3850 |
|
|
|
3851 |
|
|
If compression was off and you are enabling compression for the first |
3852 |
|
|
time you can use the BackupPC_compressPool utility to compress the |
3853 |
|
|
pool. This avoids having the pool grow to accommodate both compressed |
3854 |
|
|
and uncompressed backups. See the documentation for more information. |
3855 |
|
|
|
3856 |
|
|
Note: compression needs the Compress::Zlib perl library. If the |
3857 |
|
|
Compress::Zlib library can't be found then $Conf{CompressLevel} is |
3858 |
|
|
forced to 0 (compression off). |
3859 |
|
|
|
3860 |
|
|
=item $Conf{PingMaxMsec} = 20; |
3861 |
|
|
|
3862 |
|
|
Maximum round-trip ping time in milliseconds. This threshold is set |
3863 |
|
|
to avoid backing up PCs that are remotely connected through WAN or |
3864 |
|
|
dialup connections. The output from ping -s (assuming it is supported |
3865 |
|
|
on your system) is used to check the round-trip packet time. On your |
3866 |
|
|
local LAN round-trip times should be much less than 20msec. On most |
3867 |
|
|
WAN or dialup connections the round-trip time will be typically more |
3868 |
|
|
than 20msec. Tune if necessary. |
3869 |
|
|
|
3870 |
dpavlin |
316 |
=item $Conf{ClientTimeout} = 72000; |
3871 |
dpavlin |
1 |
|
3872 |
|
|
Timeout in seconds when listening for the transport program's |
3873 |
|
|
(smbclient, tar etc) stdout. If no output is received during this |
3874 |
|
|
time, then it is assumed that something has wedged during a backup, |
3875 |
|
|
and the backup is terminated. |
3876 |
|
|
|
3877 |
|
|
Note that stdout buffering combined with huge files being backed up |
3878 |
|
|
could cause longish delays in the output from smbclient that |
3879 |
|
|
BackupPC_dump sees, so in rare cases you might want to increase |
3880 |
|
|
this value. |
3881 |
|
|
|
3882 |
|
|
Despite the name, this parameter sets the timeout for all transport |
3883 |
|
|
methods (tar, smb etc). |
3884 |
|
|
|
3885 |
|
|
=item $Conf{MaxOldPerPCLogFiles} = 12; |
3886 |
|
|
|
3887 |
|
|
Maximum number of log files we keep around in each PC's directory |
3888 |
|
|
(ie: pc/$host). These files are aged monthly. A setting of 12 |
3889 |
|
|
means there will be at most the files LOG, LOG.0, LOG.1, ... LOG.11 |
3890 |
|
|
in the pc/$host directory (ie: about a years worth). (Except this |
3891 |
|
|
month's LOG, these files will have a .z extension if compression |
3892 |
|
|
is on). |
3893 |
|
|
|
3894 |
|
|
If you decrease this number after BackupPC has been running for a |
3895 |
|
|
while you will have to manually remove the older log files. |
3896 |
|
|
|
3897 |
|
|
=item $Conf{DumpPreUserCmd} = undef; |
3898 |
|
|
|
3899 |
|
|
=item $Conf{DumpPostUserCmd} = undef; |
3900 |
|
|
|
3901 |
|
|
=item $Conf{RestorePreUserCmd} = undef; |
3902 |
|
|
|
3903 |
|
|
=item $Conf{RestorePostUserCmd} = undef; |
3904 |
|
|
|
3905 |
|
|
=item $Conf{ArchivePreUserCmd} = undef; |
3906 |
|
|
|
3907 |
|
|
=item $Conf{ArchivePostUserCmd} = undef; |
3908 |
|
|
|
3909 |
|
|
Optional commands to run before and after dumps and restores. |
3910 |
|
|
Stdout from these commands will be written to the Xfer (or Restore) |
3911 |
|
|
log file. One example of using these commands would be to |
3912 |
|
|
shut down and restart a database server, or to dump a database |
3913 |
|
|
to files for backup. Example: |
3914 |
|
|
|
3915 |
|
|
|
3916 |
|
|
$Conf{DumpPreUserCmd} = '$sshPath -q -x -l root $host /usr/bin/dumpMysql'; |
3917 |
|
|
|
3918 |
|
|
The following variable substitutions are made at run time for |
3919 |
|
|
$Conf{DumpPreUserCmd} and $Conf{DumpPostUserCmd}: |
3920 |
|
|
|
3921 |
|
|
$type type of dump (incr or full) |
3922 |
|
|
$xferOK 1 if the dump succeeded, 0 if it didn't |
3923 |
|
|
$client client name being backed up |
3924 |
|
|
$host host name (could be different from client name if |
3925 |
|
|
$Conf{ClientNameAlias} is set) |
3926 |
|
|
$hostIP IP address of host |
3927 |
|
|
$user user name from the hosts file |
3928 |
|
|
$moreUsers list of additional users from the hosts file |
3929 |
|
|
$share the first share name |
3930 |
|
|
$shares list of all the share names |
3931 |
|
|
$XferMethod value of $Conf{XferMethod} (eg: tar, rsync, smb) |
3932 |
|
|
$sshPath value of $Conf{SshPath}, |
3933 |
|
|
$cmdType set to DumpPreUserCmd or DumpPostUserCmd |
3934 |
|
|
|
3935 |
|
|
The following variable substitutions are made at run time for |
3936 |
|
|
$Conf{RestorePreUserCmd} and $Conf{RestorePostUserCmd}: |
3937 |
|
|
|
3938 |
|
|
$client client name being backed up |
3939 |
|
|
$xferOK 1 if the restore succeeded, 0 if it didn't |
3940 |
|
|
$host host name (could be different from client name if |
3941 |
|
|
$Conf{ClientNameAlias} is set) |
3942 |
|
|
$hostIP IP address of host |
3943 |
|
|
$user user name from the hosts file |
3944 |
|
|
$moreUsers list of additional users from the hosts file |
3945 |
|
|
$share the first share name |
3946 |
|
|
$XferMethod value of $Conf{XferMethod} (eg: tar, rsync, smb) |
3947 |
|
|
$sshPath value of $Conf{SshPath}, |
3948 |
|
|
$type set to "restore" |
3949 |
|
|
$bkupSrcHost host name of the restore source |
3950 |
|
|
$bkupSrcShare share name of the restore source |
3951 |
|
|
$bkupSrcNum backup number of the restore source |
3952 |
|
|
$pathHdrSrc common starting path of restore source |
3953 |
|
|
$pathHdrDest common starting path of destination |
3954 |
|
|
$fileList list of files being restored |
3955 |
|
|
$cmdType set to RestorePreUserCmd or RestorePostUserCmd |
3956 |
|
|
|
3957 |
|
|
The following variable substitutions are made at run time for |
3958 |
|
|
$Conf{ArchivePreUserCmd} and $Conf{ArchivePostUserCmd}: |
3959 |
|
|
|
3960 |
|
|
$client client name being backed up |
3961 |
|
|
$xferOK 1 if the archive succeeded, 0 if it didn't |
3962 |
|
|
$host Name of the archive host |
3963 |
|
|
$user user name from the hosts file |
3964 |
|
|
$share the first share name |
3965 |
|
|
$XferMethod value of $Conf{XferMethod} (eg: tar, rsync, smb) |
3966 |
|
|
$HostList list of hosts being archived |
3967 |
|
|
$BackupList list of backup numbers for the hosts being archived |
3968 |
|
|
$archiveloc location where the archive is sent to |
3969 |
|
|
$parfile amount of parity data being generated (percentage) |
3970 |
|
|
$compression compression program being used (eg: cat, gzip, bzip2) |
3971 |
|
|
$compext extension used for compression type (eg: raw, gz, bz2) |
3972 |
|
|
$splitsize size of the files that the archive creates |
3973 |
|
|
$sshPath value of $Conf{SshPath}, |
3974 |
|
|
$type set to "archive" |
3975 |
|
|
$cmdType set to ArchivePreUserCmd or ArchivePostUserCmd |
3976 |
|
|
|
3977 |
|
|
=item $Conf{ClientNameAlias} = undef; |
3978 |
|
|
|
3979 |
|
|
Override the client's host name. This allows multiple clients |
3980 |
|
|
to all refer to the same physical host. This should only be |
3981 |
|
|
set in the per-PC config file and is only used by BackupPC at |
3982 |
|
|
the last moment prior to generating the command used to backup |
3983 |
|
|
that machine (ie: the value of $Conf{ClientNameAlias} is invisible |
3984 |
|
|
everywhere else in BackupPC). The setting can be a host name or |
3985 |
|
|
IP address, eg: |
3986 |
|
|
|
3987 |
|
|
$Conf{ClientNameAlias} = 'realHostName'; |
3988 |
|
|
$Conf{ClientNameAlias} = '192.1.1.15'; |
3989 |
|
|
|
3990 |
|
|
will cause the relevant smb/tar/rsync backup/restore commands to be |
3991 |
|
|
directed to realHostName, not the client name. |
3992 |
|
|
|
3993 |
|
|
Note: this setting doesn't work for hosts with DHCP set to 1. |
3994 |
|
|
|
3995 |
|
|
=item $Conf{PerlModuleLoad} = undef; |
3996 |
|
|
|
3997 |
|
|
Advanced option for asking BackupPC to load additional perl modules. |
3998 |
|
|
Can be a list (array ref) of module names to load at startup. |
3999 |
|
|
|
4000 |
|
|
=back |
4001 |
|
|
|
4002 |
|
|
=head2 Email reminders, status and messages |
4003 |
|
|
|
4004 |
|
|
=over 4 |
4005 |
|
|
|
4006 |
|
|
=item $Conf{SendmailPath} = '/usr/sbin/sendmail'; |
4007 |
|
|
|
4008 |
|
|
Full path to the sendmail command. Security caution: normal users |
4009 |
|
|
should not allowed to write to this file or directory. |
4010 |
|
|
|
4011 |
|
|
=item $Conf{EMailNotifyMinDays} = 2.5; |
4012 |
|
|
|
4013 |
|
|
Minimum period between consecutive emails to a single user. |
4014 |
|
|
This tries to keep annoying email to users to a reasonable |
4015 |
|
|
level. Email checks are done nightly, so this number is effectively |
4016 |
|
|
rounded up (ie: 2.5 means a user will never receive email more |
4017 |
|
|
than once every 3 days). |
4018 |
|
|
|
4019 |
|
|
=item $Conf{EMailFromUserName} = ''; |
4020 |
|
|
|
4021 |
|
|
Name to use as the "from" name for email. Depending upon your mail |
4022 |
|
|
handler this is either a plain name (eg: "admin") or a fully-qualified |
4023 |
|
|
name (eg: "admin@mydomain.com"). |
4024 |
|
|
|
4025 |
|
|
=item $Conf{EMailAdminUserName} = ''; |
4026 |
|
|
|
4027 |
|
|
Destination address to an administrative user who will receive a |
4028 |
|
|
nightly email with warnings and errors. If there are no warnings |
4029 |
|
|
or errors then no email will be sent. Depending upon your mail |
4030 |
|
|
handler this is either a plain name (eg: "admin") or a fully-qualified |
4031 |
|
|
name (eg: "admin@mydomain.com"). |
4032 |
|
|
|
4033 |
|
|
=item $Conf{EMailUserDestDomain} = ''; |
4034 |
|
|
|
4035 |
|
|
Destination domain name for email sent to users. By default |
4036 |
|
|
this is empty, meaning email is sent to plain, unqualified |
4037 |
|
|
addresses. Otherwise, set it to the destintation domain, eg: |
4038 |
|
|
|
4039 |
|
|
$Cong{EMailUserDestDomain} = '@mydomain.com'; |
4040 |
|
|
|
4041 |
|
|
With this setting user email will be set to 'user@mydomain.com'. |
4042 |
|
|
|
4043 |
|
|
=item $Conf{EMailNoBackupEverSubj} = undef; |
4044 |
|
|
|
4045 |
|
|
=item $Conf{EMailNoBackupEverMesg} = undef; |
4046 |
|
|
|
4047 |
|
|
This subject and message is sent to a user if their PC has never been |
4048 |
|
|
backed up. |
4049 |
|
|
|
4050 |
|
|
These values are language-dependent. The default versions can be |
4051 |
|
|
found in the language file (eg: lib/BackupPC/Lang/en.pm). If you |
4052 |
|
|
need to change the message, copy it here and edit it, eg: |
4053 |
|
|
|
4054 |
|
|
$Conf{EMailNoBackupEverMesg} = <<'EOF'; |
4055 |
|
|
To: $user$domain |
4056 |
|
|
cc: |
4057 |
|
|
Subject: $subj |
4058 |
dpavlin |
316 |
$headers |
4059 |
dpavlin |
1 |
Dear $userName, |
4060 |
|
|
|
4061 |
|
|
This is a site-specific email message. |
4062 |
|
|
EOF |
4063 |
|
|
|
4064 |
|
|
=item $Conf{EMailNotifyOldBackupDays} = 7.0; |
4065 |
|
|
|
4066 |
|
|
How old the most recent backup has to be before notifying user. |
4067 |
|
|
When there have been no backups in this number of days the user |
4068 |
|
|
is sent an email. |
4069 |
|
|
|
4070 |
|
|
=item $Conf{EMailNoBackupRecentSubj} = undef; |
4071 |
|
|
|
4072 |
|
|
=item $Conf{EMailNoBackupRecentMesg} = undef; |
4073 |
|
|
|
4074 |
|
|
This subject and message is sent to a user if their PC has not recently |
4075 |
|
|
been backed up (ie: more than $Conf{EMailNotifyOldBackupDays} days ago). |
4076 |
|
|
|
4077 |
|
|
These values are language-dependent. The default versions can be |
4078 |
|
|
found in the language file (eg: lib/BackupPC/Lang/en.pm). If you |
4079 |
|
|
need to change the message, copy it here and edit it, eg: |
4080 |
|
|
|
4081 |
|
|
$Conf{EMailNoBackupRecentMesg} = <<'EOF'; |
4082 |
|
|
To: $user$domain |
4083 |
|
|
cc: |
4084 |
|
|
Subject: $subj |
4085 |
dpavlin |
316 |
$headers |
4086 |
dpavlin |
1 |
Dear $userName, |
4087 |
|
|
|
4088 |
|
|
This is a site-specific email message. |
4089 |
|
|
EOF |
4090 |
|
|
|
4091 |
|
|
=item $Conf{EMailNotifyOldOutlookDays} = 5.0; |
4092 |
|
|
|
4093 |
|
|
How old the most recent backup of Outlook files has to be before |
4094 |
|
|
notifying user. |
4095 |
|
|
|
4096 |
|
|
=item $Conf{EMailOutlookBackupSubj} = undef; |
4097 |
|
|
|
4098 |
|
|
=item $Conf{EMailOutlookBackupMesg} = undef; |
4099 |
|
|
|
4100 |
|
|
This subject and message is sent to a user if their Outlook files have |
4101 |
|
|
not recently been backed up (ie: more than $Conf{EMailNotifyOldOutlookDays} |
4102 |
|
|
days ago). |
4103 |
|
|
|
4104 |
|
|
These values are language-dependent. The default versions can be |
4105 |
|
|
found in the language file (eg: lib/BackupPC/Lang/en.pm). If you |
4106 |
|
|
need to change the message, copy it here and edit it, eg: |
4107 |
|
|
|
4108 |
|
|
$Conf{EMailOutlookBackupMesg} = <<'EOF'; |
4109 |
|
|
To: $user$domain |
4110 |
|
|
cc: |
4111 |
|
|
Subject: $subj |
4112 |
dpavlin |
316 |
$headers |
4113 |
dpavlin |
1 |
Dear $userName, |
4114 |
|
|
|
4115 |
|
|
This is a site-specific email message. |
4116 |
|
|
EOF |
4117 |
|
|
|
4118 |
|
|
=back |
4119 |
|
|
|
4120 |
|
|
=head2 CGI user interface configuration settings |
4121 |
|
|
|
4122 |
|
|
=over 4 |
4123 |
|
|
|
4124 |
|
|
=item $Conf{CgiAdminUserGroup} = ''; |
4125 |
|
|
|
4126 |
|
|
=item $Conf{CgiAdminUsers} = ''; |
4127 |
|
|
|
4128 |
|
|
Normal users can only access information specific to their host. |
4129 |
|
|
They can start/stop/browse/restore backups. |
4130 |
|
|
|
4131 |
|
|
Administrative users have full access to all hosts, plus overall |
4132 |
|
|
status and log information. |
4133 |
|
|
|
4134 |
|
|
The administrative users are the union of the unix/linux group |
4135 |
|
|
$Conf{CgiAdminUserGroup} and the manual list of users, separated |
4136 |
|
|
by spaces, in $Conf{CgiAdminUsers}. If you don't want a group or |
4137 |
|
|
manual list of users set the corresponding configuration setting |
4138 |
|
|
to undef or an empty string. |
4139 |
|
|
|
4140 |
|
|
If you want every user to have admin privileges (careful!), set |
4141 |
|
|
$Conf{CgiAdminUsers} = '*'. |
4142 |
|
|
|
4143 |
|
|
Examples: |
4144 |
|
|
|
4145 |
|
|
$Conf{CgiAdminUserGroup} = 'admin'; |
4146 |
|
|
$Conf{CgiAdminUsers} = 'craig celia'; |
4147 |
|
|
--> administrative users are the union of group admin, plus |
4148 |
|
|
craig and celia. |
4149 |
|
|
|
4150 |
|
|
$Conf{CgiAdminUserGroup} = ''; |
4151 |
|
|
$Conf{CgiAdminUsers} = 'craig celia'; |
4152 |
|
|
--> administrative users are only craig and celia'. |
4153 |
|
|
|
4154 |
|
|
=item $Conf{CgiURL} = undef; |
4155 |
|
|
|
4156 |
|
|
URL of the BackupPC_Admin CGI script. Used for email messages. |
4157 |
|
|
|
4158 |
|
|
=item $Conf{Language} = 'en'; |
4159 |
|
|
|
4160 |
|
|
Language to use. See lib/BackupPC/Lang for the list of supported |
4161 |
|
|
languages, which include English (en), French (fr), Spanish (es), |
4162 |
|
|
German (de), Italian (it) and Dutch (nl). |
4163 |
|
|
|
4164 |
|
|
Currently the Language setting applies to the CGI interface and email |
4165 |
|
|
messages sent to users. Log files and other text are still in English. |
4166 |
|
|
|
4167 |
|
|
=item $Conf{CgiUserHomePageCheck} = ''; |
4168 |
|
|
|
4169 |
|
|
=item $Conf{CgiUserUrlCreate} = 'mailto:%s'; |
4170 |
|
|
|
4171 |
|
|
User names that are rendered by the CGI interface can be turned |
4172 |
|
|
into links into their home page or other information about the |
4173 |
|
|
user. To set this up you need to create two sprintf() strings, |
4174 |
|
|
that each contain a single '%s' that will be replaced by the user |
4175 |
|
|
name. The default is a mailto: link. |
4176 |
|
|
|
4177 |
|
|
$Conf{CgiUserHomePageCheck} should be an absolute file path that |
4178 |
|
|
is used to check (via "-f") that the user has a valid home page. |
4179 |
|
|
Set this to undef or an empty string to turn off this check. |
4180 |
|
|
|
4181 |
|
|
$Conf{CgiUserUrlCreate} should be a full URL that points to the |
4182 |
|
|
user's home page. Set this to undef or an empty string to turn |
4183 |
|
|
off generation of URLs for user names. |
4184 |
|
|
|
4185 |
|
|
Example: |
4186 |
|
|
|
4187 |
|
|
$Conf{CgiUserHomePageCheck} = '/var/www/html/users/%s.html'; |
4188 |
|
|
$Conf{CgiUserUrlCreate} = 'http://myhost/users/%s.html'; |
4189 |
|
|
--> if /var/www/html/users/craig.html exists, then 'craig' will |
4190 |
|
|
be rendered as a link to http://myhost/users/craig.html. |
4191 |
|
|
|
4192 |
|
|
=item $Conf{CgiDateFormatMMDD} = 1; |
4193 |
|
|
|
4194 |
|
|
Date display format for CGI interface. True for US-style dates (MM/DD) |
4195 |
|
|
and zero for international dates (DD/MM). |
4196 |
|
|
|
4197 |
|
|
=item $Conf{CgiNavBarAdminAllHosts} = 1; |
4198 |
|
|
|
4199 |
|
|
If set, the complete list of hosts appears in the left navigation |
4200 |
|
|
bar pull-down for administrators. Otherwise, just the hosts for which |
4201 |
|
|
the user is listed in the host file (as either the user or in moreUsers) |
4202 |
|
|
are displayed. |
4203 |
|
|
|
4204 |
|
|
=item $Conf{CgiSearchBoxEnable} = 1; |
4205 |
|
|
|
4206 |
|
|
Enable/disable the search box in the navigation bar. |
4207 |
|
|
|
4208 |
|
|
=item $Conf{CgiNavBarLinks} = [ ... ]; |
4209 |
|
|
|
4210 |
|
|
Additional navigation bar links. These appear for both regular users |
4211 |
|
|
and administrators. This is a list of hashes giving the link (URL) |
4212 |
|
|
and the text (name) for the link. Specifying lname instead of name |
4213 |
|
|
uses the language specific string (ie: $Lang->{lname}) instead of |
4214 |
|
|
just literally displaying name. |
4215 |
|
|
|
4216 |
|
|
=item $Conf{CgiStatusHilightColor} = { ... |
4217 |
|
|
|
4218 |
|
|
Hilight colors based on status that are used in the PC summary page. |
4219 |
|
|
|
4220 |
|
|
=item $Conf{CgiHeaders} = '<meta http-equiv="pragma" content="no-cache">'; |
4221 |
|
|
|
4222 |
|
|
Additional CGI header text. |
4223 |
|
|
|
4224 |
|
|
=item $Conf{CgiImageDir} = ''; |
4225 |
|
|
|
4226 |
|
|
Directory where images are stored. This directory should be below |
4227 |
|
|
Apache's DocumentRoot. This value isn't used by BackupPC but is |
4228 |
|
|
used by configure.pl when you upgrade BackupPC. |
4229 |
|
|
|
4230 |
|
|
Example: |
4231 |
|
|
|
4232 |
|
|
$Conf{CgiImageDir} = '/usr/local/apache/htdocs/BackupPC'; |
4233 |
|
|
|
4234 |
|
|
=item $Conf{CgiExt2ContentType} = { }; |
4235 |
|
|
|
4236 |
|
|
Additional mappings of file name extenions to Content-Type for |
4237 |
|
|
individual file restore. See $Ext2ContentType in BackupPC_Admin |
4238 |
|
|
for the default setting. You can add additional settings here, |
4239 |
|
|
or override any default settings. Example: |
4240 |
|
|
|
4241 |
|
|
|
4242 |
|
|
$Conf{CgiExt2ContentType} = { |
4243 |
|
|
'pl' => 'text/plain', |
4244 |
|
|
}; |
4245 |
|
|
|
4246 |
|
|
=item $Conf{CgiImageDirURL} = ''; |
4247 |
|
|
|
4248 |
|
|
URL (without the leading http://host) for BackupPC's image directory. |
4249 |
|
|
The CGI script uses this value to serve up image files. |
4250 |
|
|
|
4251 |
|
|
Example: |
4252 |
|
|
|
4253 |
|
|
$Conf{CgiImageDirURL} = '/BackupPC'; |
4254 |
|
|
|
4255 |
|
|
=item $Conf{CgiCSSFile} = 'BackupPC_stnd.css'; |
4256 |
|
|
|
4257 |
|
|
CSS stylesheet for the CGI interface. It is stored in the |
4258 |
|
|
$Conf{CgiImageDir} directory and accessed via the |
4259 |
|
|
$Conf{CgiImageDirURL} URL. |
4260 |
|
|
|
4261 |
|
|
=back |
4262 |
|
|
|
4263 |
|
|
|
4264 |
|
|
=head1 Version Numbers |
4265 |
|
|
|
4266 |
|
|
Starting with v1.4.0 BackupPC uses a X.Y.Z version numbering system, |
4267 |
|
|
instead of X.0Y. The first digit is for major new releases, the middle |
4268 |
|
|
digit is for significant feature releases and improvements (most of |
4269 |
|
|
the releases have been in this category), and the last digit is for |
4270 |
|
|
bug fixes. You should think of the old 1.00, 1.01, 1.02 and 1.03 as |
4271 |
|
|
1..0, 1.1.0, 1.2.0 and 1.3.0. |
4272 |
|
|
|
4273 |
|
|
Additionally, patches might be made available. A patched version |
4274 |
|
|
number is of the form X.Y.ZplN (eg: 2.1.0pl2), where N is the |
4275 |
|
|
patch level. |
4276 |
|
|
|
4277 |
|
|
=head1 Author |
4278 |
|
|
|
4279 |
|
|
Craig Barratt <cbarratt@users.sourceforge.net> |
4280 |
|
|
|
4281 |
|
|
See L<http://backuppc.sourceforge.net>. |
4282 |
|
|
|
4283 |
|
|
=head1 Copyright |
4284 |
|
|
|
4285 |
dpavlin |
316 |
Copyright (C) 2001-2005 Craig Barratt |
4286 |
dpavlin |
1 |
|
4287 |
|
|
=head1 Credits |
4288 |
|
|
|
4289 |
|
|
Ryan Kucera contributed the directory navigation code and images |
4290 |
|
|
for v1.5.0. He contributed the first skeleton of BackupPC_restore. |
4291 |
|
|
He also added a significant revision to the CGI interface, including |
4292 |
|
|
CSS tags, in v2.1.0, and designed the BackupPC logo. |
4293 |
|
|
|
4294 |
|
|
Xavier Nicollet, with additions from Guillaume Filion, added the |
4295 |
|
|
internationalization (i18n) support to the CGI interface for v2.0.0. |
4296 |
|
|
Xavier provided the French translation fr.pm, with additions from |
4297 |
|
|
Guillaume. |
4298 |
|
|
|
4299 |
|
|
Guillaume Filion wrote BackupPC_zipCreate and added the CGI support |
4300 |
|
|
for zip download, in addition to some CGI cleanup, for v1.5.0. |
4301 |
|
|
Guillaume continues to support fr.pm updates for each new version. |
4302 |
|
|
|
4303 |
|
|
Josh Marshall implemented the Archive feature in v2.1.0. |
4304 |
|
|
|
4305 |
|
|
Ludovic Drolez supports the BackupPC Debian package. |
4306 |
|
|
|
4307 |
|
|
Javier Gonzalez provided the Spanish translation, es.pm for v2.0.0. |
4308 |
|
|
|
4309 |
|
|
Manfred Herrmann provided the German translation, de.pm for v2.0.0. |
4310 |
|
|
Manfred continues to support de.pm updates for each new version, |
4311 |
|
|
together with some help frmo Ralph Paßgang. |
4312 |
|
|
|
4313 |
|
|
Lorenzo Cappelletti provided the Italian translation, it.pm for v2.1.0. |
4314 |
|
|
|
4315 |
|
|
Lieven Bridts provided the Dutch translation, nl.pm, for v2.1.0, |
4316 |
|
|
with some tweaks from Guus Houtzager. |
4317 |
|
|
|
4318 |
|
|
Many people have reported bugs, made useful suggestions and helped |
4319 |
|
|
with testing; see the ChangeLog and the mail lists. |
4320 |
|
|
|
4321 |
|
|
Your name could appear here in the next version! |
4322 |
|
|
|
4323 |
|
|
=head1 License |
4324 |
|
|
|
4325 |
|
|
This program is free software; you can redistribute it and/or modify it |
4326 |
|
|
under the terms of the GNU General Public License as published by the |
4327 |
|
|
Free Software Foundation; either version 2 of the License, or (at your |
4328 |
|
|
option) any later version. |
4329 |
|
|
|
4330 |
|
|
This program is distributed in the hope that it will be useful, |
4331 |
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of |
4332 |
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
4333 |
|
|
General Public License for more details. |
4334 |
|
|
|
4335 |
|
|
You should have received a copy of the GNU General Public License in the |
4336 |
|
|
LICENSE file along with this program; if not, write to the Free Software |
4337 |
|
|
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. |