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