root/trunk/omnipitr/doc/install.pod

Revision 178, 4.6 kB (checked in by depesz, 4 years ago)

add more info about requirements, and important notices about usage

Line 
1 =head1 OmniPITR - Installation
2
3 =head2 INSTALLATION
4
5 You can get the OmniPITR project from L<https://labs.omniti.com/pgsoltools/trunk/omnipitr>. Within this directory you will find set of directories:
6
7 =over
8
9 =item * bin/
10
11 This is where the scripts reside - usually this is the only place you need to
12 look into.
13
14 =item * doc/
15
16 Documentation. In Plain Old Documentation format, so you can view it practically
17 everywhere Perl is with I<perldoc> command.
18
19 =item * lib/
20
21 Here be dragons. Don't look. Don't touch. Be afraid.
22
23 =back
24
25 After fetching the omnipitr project/directory, put it in any place in your
26 filesystem you'd want. Usually you will keep all of these together, but you can
27 always remove the docs, put the scripts in some system bin/ directory, and put
28 libs anyplace you want - just make sure that path to them is in I<PERL5LIB>
29 environment variable.
30
31 In case you will not decide to split the distribution - i.e. you will have
32 someplace in your system I<omnipitr> directory, which will contain I<bin/> and
33 I<lib/> directories (just like it is distributed) - you don't have to set
34 I<PERL5LIB> - scripts will automatically find their libs.
35
36 =head2 REQUIREMENTS
37
38 Standard Perl distribution should be enough. On some Linux systems (Debian,
39 Ubuntu) core Perl modules have been packaged separately - in such case you need
40 to install also perl-modules package.
41
42 Additionally, you will need some programs installed:
43
44 =over
45
46 =item * nice
47
48 =item * rsync
49
50 =item * tar (it has to be GNU tar version 1.20 or newer)
51
52 =back
53
54 Additionally, you might want to use compression, in which case you need I<gzip>,
55 I<bzip2> or I<lzma> compression programs.
56
57 Please note that you can use I<pigz> to get faster, but gzip-compatible,
58 compression. To do so, specify all destinations/sources using I<gzip> prefix,
59 but add --gzip-path option with value pointing to I<pigz> program.
60
61 =head2 SANITY CHECK
62
63 After installation it's good to run I<sanity-check.sh> script (from I<bin/>)
64 directory - it will check if all prerequisites are available.
65
66 Output might look like this:
67
68     postgres@server:~$ omnipitr/bin/sanity-check.sh
69     Checking:
70     - /var/lib/postgres/omnipitr/bin
71     - /var/lib/postgres/omnipitr/lib
72     5 programs, 7 libraries.
73     All checked, and looks ok.
74
75 or like this:
76
77     postgres@server:~$ omnipitr/bin/sanity-check.sh
78     Checking:
79     - /var/lib/postgres/omnipitr/bin
80     - /var/lib/postgres/omnipitr/lib
81     5 programs, 7 libraries.
82     Warnings:
83     - you don't have ssh program available
84     - you don't have rsync program available
85     - your Perl is old (we support only 5.8 or newer. OmniPITR might work, but was not tested on your version of Perl)
86     Errors:
87     - you don't have any of programs used to transmit WAL files (ssh, rsync)
88     - you don't have POSIX Perl library (should be installed together with Perl)
89     All checked. 3 warnings, 2 errors.
90
91 Depending on your particular usecase even the errors don't have to be fatal -
92 for example, if your I<rsync>/I<ssh> binary is in directory that is not in
93 I<$PATH> - it will not be found by sanity-check.sh, but you can always provide
94 paths to them via I<--rsync-binary> or I<--ssh-binary> options to I<omnipitr-*>
95 scripts.
96
97 After I<sanity-check.sh> returned C<All checked, and looks ok.> you should be
98 good with starting using the scripts.
99
100 =head2 INITIAL SETUP
101
102 To start Wal replication you will need to:
103
104 =over
105
106 =item 1. Start archiving wal segments: I<omnipitr-archive>
107
108 =item 2. Make initial hot backup on master: I<omnipitr-master-backup>
109
110 =item 3. Transfer the backup to slave server(s)
111
112 =item 4. Start PostgreSQL recovery from hot-backup: I<omnipitr-restore>
113
114 =back
115
116 Afterwards you can/should monitor replication parameters with
117 I<omnipitr-monitor>, and that would be all. Of course you can do hot-backups on
118 slave (with I<omnipitr-slave-backup>) at any moment - just remember that doing
119 them on slave requires more disc space - details in
120 I<omnipitr-slave-backup.pod>.
121
122 =head2 HINTS
123
124 It is technically possible, and suggested to use the same logfiles for all
125 programs running on given server.
126
127 That is - you can setup archival to log to "archive.log" and backup to log to
128 "backup.log", but you can make them both log to "omnipitr.log" - it will not
129 break anything, and makes it simpler to manage log files.
130
131 Same thing applies to state directories - these can be the same between various
132 programs from I<OmniPITR> package.
133
134 When creating any files I<OmniPITR> obeys ulimit, but doesn't enforce any
135 additional restrictions. So, if you'd like it to create files that are readable
136 only to owner, simply run it like this:
137
138     umask 0077; omnipitr-something ....
139
140 =head2 COPYRIGHT
141
142 The OmniPITR project is Copyright (c) 2009-2010 OmniTI. All rights reserved.
143
Note: See TracBrowser for help on using the browser.