trunk/doc/Search.pm

=head1 BackupPC search and archival extension

BackupPC search and archival extension is used to:

=over 4

=item *

find files in C<pool> by substring of filename

=item *

see state of one or all of your shares in some particular point in time
(file creation date on clients or backup date is supported as filter)

=item *

archive selected backups (per host, share and increment) to archival
medium (CD, DVD, tape etc.) with rich descriptions, archival locations,
multiple copies and so on.

=back

=head2 Requirements

This extension is based on PostgreSQL RDBMS and HyperEstraier full-text
search engine (and it's perl bindings).

If you are using Debian, you are in luck. All required packages are
allready part of C<unstable> distribution and can be installed with:

  # apt-get install postgresql
  # apt-get install hyperestraier libestraier-dev libqdbm-dev

Now you can skip to installation of L<HyperEstraier perl bindings> below.

If you don't have pre-packaged binaries for your installation, you will
need to install additional packages by hand.

=head3 PostgreSQL

You can use packages provided by your distribution or follow installation
instructions on PostgreSQL site.

=head3 QDBM

First, you need qdbm on which HyperEstraier depends. Installation is simple.

  $ tar xvfz qdbm-1.8.31.tar.gz 
  $ cd qdbm-1.8.31
  $ ./configure --enable-zlib
  $ make
  $ sudo make install

=head3 HyperEstraier

Also quite simple.

  $ tar xvfz hyperestraier-0.5.4.tar.gz
  $ cd hyperestraier-0.5.4
  $ ./configure
  $ make
  $ sudo make install

Then you will have to install perl bindings for HyperEstraier.

=head3 HyperEstraier perl bindings

This might take a bit more work. You will need to have C<swig> and C<g++> installed
before you can install perl bindings.

  $ tar xvfz hyper_estraier_wrappers-0.0.10.tar.gz 
  $ cd swig_hest/perl/
  $ swig -c++ -perl5 -o HyperEstraier_wrap.cpp  ../HyperEstraier.i
  $ cp ../HyperEstraierWrapper.cpp ./
  $ perl Makefile.PL

You might need to remove C<estconfig --mtlibs> from C<Makefile.PL> if it
fails to run with following message:

 Unrecognized argument in LIBS ignored: 'configuration'
 Unrecognized argument in LIBS ignored: 'helper'
 Unrecognized argument in LIBS ignored: 'for'
 Unrecognized argument in LIBS ignored: 'Hyper'
 Unrecognized argument in LIBS ignored: 'Estraier'
 Writing Makefile for HyperEstraier

Working C<Makefile.PL> for my particular installation is:

 # File : Makefile.PL
 use ExtUtils::MakeMaker;
 WriteMakefile(
        NAME    => 'HyperEstraier',
        INC     => sprintf('%s', `pkg-config --cflags hyperestraier`),
        LIBS    => [sprintf('-lstdc++ %s %s' , `pkg-config --libs hyperestraier`)],
        OBJECT  => 'HyperEstraierWrapper.o HyperEstraier_wrap.o'
 );

After succesfull C<perl Makefile.pl>, you can compile and install it.

  $ make
  $ sudo make install

=head3 CPAN modules

You will also need a few additional cpan modules

=over 4

=item File::Pid

=back

Easiest way to install them is using C<cpan> shell.

  $ sudo cpan File::Pid

=head1 Creation of initial database

Once you have all components installed, you should initially create data
about increments in RDBMS and full-text search engine index.

First, edit C<config.pl> and setup C<SearchDSN> to valid perl DSN (for example,
C<dbi:Pg:dbname=backuppc> and C<SearchUser> to database user which has priviledges
over that database. You might need to add additional directives in PostgreSQL's
C<pg_hba.conf> so that selected user can be connected without password (I know, it's not
perfect, but I trust local users on backuppc machine).

Then, create new database for backuppc.

  $ createdb backuppc

Then invoke C<BackupPC_updatedb> for the first time with argument to create database
schema:

  $ sudo -u backuppc /data/backuppc/bin/BackupPC_updatedb -c

You can also force full-text reindex by C<-i> flag. This will add all files which are in
database but for some reason are missing in full-text index.

Now, you can setup cron job which will daily check your backups and update database
and full-text index. This is as simple as invoking

  /data/backuppc/bin/BackupPC_updatedb

As C<backuppc> user and redirecting output to log file.

B<Documentation is still incomplete>.

Now that you finished installation, you can select new options from
menu on the left and example search and archival.

=head1 Related projects

BackupPC allready has archival host which might suit your needs better (and
it's quite easier to install).

=over 4

=item PostgreSQL

L<http://www.postgresql.org/>

=item HyperEstraier

L<http://hyperestraier.sourceforge.net/>

=back

=head1 Authors

Ivan Klaric C<< <iklaric@gmail.com> >>

Dobrica Pavlinusic C<< <dpavlin@rot13.org> >>

=head1 Licence

This extension is released under GPL licence, same as BackupPC.

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 HyperEstraier 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<HyperEstraier 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 HyperEstraier 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 HyperEstraier
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 HyperEstraier.
66
67	=head3 HyperEstraier perl bindings
68
69	This might take a bit more work. You will need to have C<swig> and C<g++> installed
70	before you can install perl bindings.
71
72	$ tar xvfz hyper_estraier_wrappers-0.0.10.tar.gz
73	$ cd swig_hest/perl/
74	$ swig -c++ -perl5 -o HyperEstraier_wrap.cpp ../HyperEstraier.i
75	$ cp ../HyperEstraierWrapper.cpp ./
76	$ perl Makefile.PL
77
78	You might need to remove C<estconfig --mtlibs> from C<Makefile.PL> if it
79	fails to run with following message:
80
81	Unrecognized argument in LIBS ignored: 'configuration'
82	Unrecognized argument in LIBS ignored: 'helper'
83	Unrecognized argument in LIBS ignored: 'for'
84	Unrecognized argument in LIBS ignored: 'Hyper'
85	Unrecognized argument in LIBS ignored: 'Estraier'
86	Writing Makefile for HyperEstraier
87
88	Working C<Makefile.PL> for my particular installation is:
89
90	# File : Makefile.PL
91	use ExtUtils::MakeMaker;
92	WriteMakefile(
93	NAME => 'HyperEstraier',
94	INC => sprintf('%s', `pkg-config --cflags hyperestraier`),
95	LIBS => [sprintf('-lstdc++ %s %s' , `pkg-config --libs hyperestraier`)],
96	OBJECT => 'HyperEstraierWrapper.o HyperEstraier_wrap.o'
97	);
98
99	After succesfull C<perl Makefile.pl>, you can compile and install it.
100
101	$ make
102	$ sudo make install
103
104	=head3 CPAN modules
105
106	You will also need a few additional cpan modules
107
108	=over 4
109
110	=item File::Pid
111
112	=back
113
114	Easiest way to install them is using C<cpan> shell.
115
116	$ sudo cpan File::Pid
117
118	=head1 Creation of initial database
119
120	Once you have all components installed, you should initially create data
121	about increments in RDBMS and full-text search engine index.
122
123	First, edit C<config.pl> and setup C<SearchDSN> to valid perl DSN (for example,
124	C<dbi:Pg:dbname=backuppc> and C<SearchUser> to database user which has priviledges
125	over that database. You might need to add additional directives in PostgreSQL's
126	C<pg_hba.conf> so that selected user can be connected without password (I know, it's not
127	perfect, but I trust local users on backuppc machine).
128
129	Then, create new database for backuppc.
130
131	$ createdb backuppc
132
133	Then invoke C<BackupPC_updatedb> for the first time with argument to create database
134	schema:
135
136	$ sudo -u backuppc /data/backuppc/bin/BackupPC_updatedb -c
137
138	You can also force full-text reindex by C<-i> flag. This will add all files which are in
139	database but for some reason are missing in full-text index.
140
141	Now, you can setup cron job which will daily check your backups and update database
142	and full-text index. This is as simple as invoking
143
144	/data/backuppc/bin/BackupPC_updatedb
145
146	As C<backuppc> user and redirecting output to log file.
147
148	B<Documentation is still incomplete>.
149
150	Now that you finished installation, you can select new options from
151	menu on the left and example search and archival.
152
153	=head1 Related projects
154
155	BackupPC allready has archival host which might suit your needs better (and
156	it's quite easier to install).
157
158	=over 4
159
160	=item PostgreSQL
161
162	L<http://www.postgresql.org/>
163
164	=item HyperEstraier
165
166	L<http://hyperestraier.sourceforge.net/>
167
168	=back
169
170	=head1 Authors
171
172	Ivan Klaric C<< <iklaric@gmail.com> >>
173
174	Dobrica Pavlinusic C<< <dpavlin@rot13.org> >>
175
176	=head1 Licence
177
178	This extension is released under GPL licence, same as BackupPC.
179