doc/Search.pod

   1 =head1 BackupPC search and archival extension
   2
   3 BackupPC search and archival extension is used to:
   4
   5 =over 4
   6
   7 =item *
   8
   9 find files in C<pool> by substring of filename
  10
  11 =item *
  12
  13 see state of one or all of your shares in some particular point in time
  14 (file creation date on clients or backup date is supported as filter)
  15
  16 =item *
  17
  18 archive selected backups (per host, share and increment) to archival
  19 medium (CD, DVD, tape etc.) with rich descriptions, archival locations,
  20 multiple copies and so on.
  21
  22 =back
  23
  24 =head2 Requirements
  25
  26 This extension is based on PostgreSQL RDBMS and Hyper Estraier full-text
  27 search engine (and it's perl bindings).
  28
  29 If you are using Debian, you are in luck. All required packages are
  30 allready part of C<unstable> distribution and can be installed with:
  31
  32   # apt-get install postgresql
  33   # apt-get install hyperestraier libestraier-dev libqdbm-dev
  34
  35 Now you can skip to installation of L<Hyper Estraier perl bindings> below.
  36
  37 If you don't have pre-packaged binaries for your installation, you will
  38 need to install additional packages by hand.
  39
  40 =head3 PostgreSQL
  41
  42 You can use packages provided by your distribution or follow installation
  43 instructions on PostgreSQL site.
  44
  45 =head3 QDBM
  46
  47 First, you need qdbm on which Hyper Estraier depends. Installation is simple.
  48
  49   $ tar xvfz qdbm-1.8.31.tar.gz
  50   $ cd qdbm-1.8.31
  51   $ ./configure --enable-zlib
  52   $ make
  53   $ sudo make install
  54
  55 =head3 Hyper Estraier
  56
  57 Also quite simple.
  58
  59   $ tar xvfz hyperestraier-0.5.4.tar.gz
  60   $ cd hyperestraier-0.5.4
  61   $ ./configure
  62   $ make
  63   $ sudo make install
  64
  65 Then you will have to install perl bindings for Hyper Estraier.
  66
  67 =head3 Hyper Estraier perl bindings
  68
  69 Just use C<cpan> shell to install C<Search::Estraier> module
  70
  71   $ sudo cpan Search::Estraier
  72
  73 There was awaful long procedure about installing perl C bindings, but it's all gone now.
  74
  75 =head3 CPAN modules
  76
  77 You will also need a few additional cpan modules
  78
  79 =over 4
  80
  81 =item File::Pid
  82 =item File::Which
  83 =item File::Path
  84 =item File::Slurp
  85 =item Search::Estraier
  86
  87 =item Spreadsheet::WriteExcel
  88
  89 =item Term::Menus
  90 =item XML::Writer
  91 =item Algorithm::Diff
  92 =item Archive::Tar::Stream
  93 =item Filesys::Df
  94
  95 =back
  96
  97 Last module, C<Spreadsheet::WriteExcel> is needed only if you want to use
  98 C<BackupPC_xls_report> to generate Excel reports from your backup data.
  99
 100 Easiest way to install them is using C<cpan> shell.
 101
 102   $ sudo cpan File::Pid Spreadsheet::WriteExcel ...
 103
 104 =head1 Creation of initial database
 105
 106 Once you have all components installed, you should initially create data
 107 about increments in RDBMS and full-text search engine index.
 108
 109 First, edit C<config.pl> and setup C<SearchDSN> to valid perl DSN (for example,
 110 C<dbi:Pg:dbname=backuppc> and C<SearchUser> to database user which has priviledges
 111 over that database. You might need to add additional directives in PostgreSQL's
 112 C<pg_hba.conf> so that selected user can be connected without password (I know, it's not
 113 perfect, but I trust local users on backuppc machine).
 114
 115 Then, create new database for backuppc.
 116
 117   $ createdb backuppc
 118
 119 Then invoke C<BackupPC_updatedb> for the first time with argument to create database
 120 schema:
 121
 122   $ sudo -u backuppc /data/backuppc/bin/BackupPC_updatedb -c
 123
 124 You can also force full-text reindex by C<-i> flag. This will add all files which are in
 125 database but for some reason are missing in full-text index.
 126
 127 Now, you can setup cron job which will daily check your backups and update database
 128 and full-text index. This is as simple as invoking
 129
 130   /data/backuppc/bin/BackupPC_updatedb
 131
 132 As C<backuppc> user and redirecting output to log file.
 133
 134 B<Documentation is still incomplete>.
 135
 136 Now that you finished installation, you can select new options from
 137 menu on the left and example search and archival.
 138
 139 =head1 Reporting in Excel
 140
 141 Often, it is useful to be able to present report about your BackupPC hosts, number
 142 of snapshots, total size and other useful info. While all those information can
 143 be accessed using web browser, for analysis it's useful to have them in spreadsheet
 144 form. With this data, you can monitor changes on your backup cycle, effects of changes
 145 on your server or network to your BackupPC installation and so on.
 146
 147 You can create Excel spreadsheet (which works perfectly with Gnumeric also) using
 148 following command:
 149
 150   $ sudo -u backuppc /data/backuppc/bin/BackupPC_xls_report
 151
 152 =head1 Additional requirements
 153
 154 You will also need several other command-line utilities to make
 155 C<BackupPC_burnArchiveCLI> run. Those include:
 156
 157 =over 4
 158
 159 =item mkisofs
 160
 161 =item cdrecord
 162
 163 Or equivavalent utility, on Debian you might want to use C<dvdrecord>.
 164
 165 =item eject
 166
 167 Please make a symlink from C</dev/cdrom> to you CD/DVD burner.
 168
 169 =item split
 170
 171 =back
 172
 173 =head1 Troubleshoting
 174
 175 =head2 md5sum problems on Debian
 176
 177 If you are running Debian stable and expiriencing error message like
 178
 179  -: No such file or directory
 180
 181 your C<md5sum> comes from C<coreutils> (which doesn't know how to handle C<->
 182 as input) as opposed to C<md5sum> which comes with C<textutils> (which does).
 183
 184 Fix is simple, correct md5sum is allready installed, you just have to do:
 185
 186  sudo cp /usr/bin/md5sum.textutils /usr/bin/md5sum
 187
 188 =head1 Related projects
 189
 190 BackupPC allready has archival host which might suit your needs better (and
 191 it's quite easier to install).
 192
 193 =over 4
 194
 195 =item PostgreSQL
 196
 197 L<http://www.postgresql.org/>
 198
 199 =item HyperEstraier
 200
 201 L<http://hyperestraier.sourceforge.net/>
 202
 203 =back
 204
 205 =head1 Authors
 206
 207 Ivan Klaric C<< <iklaric@gmail.com> >>
 208
 209 Dobrica Pavlinusic C<< <dpavlin@rot13.org> >>
 210
 211 =head1 Licence
 212
 213 This extension is released under GPL licence, same as BackupPC.
 214