root/trunk/omnipitr/doc/howto.pod

Revision 148, 11.4 kB (checked in by depesz, 4 years ago)

fix typos sigtes by Susan and Denish

Line 
1 =head1 OmniPITR - how to setup.
2
3 =head2 OVERVIEW
4
5 Following documentation walks you through installation, setup and running of
6 master-slave replication of PostgreSQL database using WAL segment files (also
7 known as PiTR Replication.
8
9 It will also cover methods of making backups, both from master and slave
10 servers, and methods for monitoring replication status.
11
12 =head2 SETUP OVERVIEW
13
14 Following document provides information about setting replication/backup
15 scenario, on 3 machines, with following responsibilities:
16
17 =over
18
19 =item * master server - server (both hardware and software) that contains the working,
20 writable PostgreSQL instance
21
22 =item * slave server - server (both hardware and software) that contains secondary,
23 warm or hot standby server. With PostgreSQL pre 9.0 it's not readable, but from
24 9.0 you can send read-only queries to it.
25
26 =item * backup server - additional machine that is being used as storage for
27 backup files - both full-database backups and/or backup of currently generated
28 xlog files (WAL segments)
29
30 =back
31
32 Before setting replication it is required that you have PostgreSQL installed on
33 both master and slave servers, and working PostgreSQL cluster on master.
34
35 Paths should be the same on master and slave - at least to data directory.
36
37 For the purpose of example, I assume following paths on each servers - you are
38 in no way obliged to use the same paths - these are just explanations if
39 something wouldn't be clear from examples later on:
40
41 =head3 Master server paths
42
43 =over
44
45 =item * /home/postgres - home directory of postgres user - user that is used to
46 run PostgreSQL
47
48 =item * /home/postgres/data - data directory for PostgreSQL
49
50 =item * /home/postgres/data/postgresql.conf - PostgreSQL configuration file for
51 master
52
53 =item * /var/tmp - temporary directory that can be freely used
54
55 =back
56
57 =head3 Slave server paths
58
59 =over
60
61 =item * /home/postgres - home directory of postgres user - user that is used to
62 run PostgreSQL
63
64 =item * /var/tmp - temporary directory that can be freely used
65
66 =back
67
68 =head3 Backup server paths
69
70 =over
71
72 =item * /var/backups - backups directory - all backups should arrive in here.
73
74 =back
75
76 =head2 PREPARATION
77
78 To make everything working we need a way to copy files from master to slave and
79 backup, and from slave to backup.
80
81 Since I<OmniPITR> is using RSync for all transfers, we can effectively use two
82 ways of communication:
83
84 =over
85
86 =item * rsync over ssh
87
88 =item * direct rsync
89
90 =back
91
92 First method is usually easier to setup - as you most likely have ssh daemon on
93 all machines, so it is enough to install rsync program, and you're virtually
94 good to go.
95
96 Second method is a bit more complex, as you need additinally to setup rsync
97 daemon, but it pays off in increased security, faster transfers and less
98 resource-intensive work. The biggest drawback is that data being sent are not
99 encrypted. Which might, or might not be an issue, depending on distance, and
100 trust for connection - i.e. using encrypted vpn and then plain rsync is (in my
101 opinion) favorable over rsync-over-ssh, due to extra security steps we can have
102 when using rsync as daemon.
103
104 In any way, we need to make some extra directories:
105
106 =over
107
108 =item * On master server:
109
110 =over
111
112 =item * /home/postgres/omnipitr - this is where omnipitr will store it's
113 internal datafiles (rather small)
114
115 =item * /home/postgres/omnipitr/log - place for omnipitr log
116
117 =item * /home/postgres/omnipitr/state - place for omnipitr state files
118
119 =item * /var/tmp/omnipitr - place for temporary files (larger) created and used
120 by omnipitr
121
122 =back
123
124 =item * On slave server:
125
126 =over
127
128 =item * /home/postgres/wal_archive - this is where master will send xlog
129 segments to be used for replication
130
131 =item * /home/postgres/omnipitr - this is where omnipitr will store it's
132 internal datafiles (rather small)
133
134 =item * /home/postgres/omnipitr/log - place for omnipitr log
135
136 =item * /home/postgres/omnipitr/state - place for omnipitr state files
137
138 =item * /var/tmp/omnipitr - place for temporary files (larger) created and used
139 by omnipitr
140
141 =back
142
143 =item * On backup server:
144
145 =over
146
147 =item * /var/backups/database - top level directory for database backups
148
149 =item * /var/backups/database/hot_backup - directory to put hot backup files in
150
151 =item * /var/backups/database/xlog - directory to put xlog segments in
152
153 =back
154
155 =back
156
157 And then we need to allow uploads to them.
158
159 For this - you'd rather consult your sysadmins. For the sake of this document, I
160 assume that the chosen method was direct rsync, and we have working following
161 rsync paths:
162
163 =over
164
165 =item * rsync://slave/wal_archive/ - points to /home/postgres/wal_archive/, with
166 write access for master, without password
167
168 =item * rsync://backup/database/ - points to /var/backups/database, with write
169 access for master and slave, without password
170
171 =back
172
173 =head2 ACTUAL INSTALLATION AND CONFIGURATION
174
175 On both master and slave machines, please install omnipitr to /opt/omnipitr
176 directory, for example using:
177
178     $ svn co https://labs.omniti.com/pgtreats/trunk/omnipitr /opt/omnipitr
179
180 Now, on both machines, check if the installation is OK, that is run sanity
181 check:
182
183     $ /opt/omnipitr/bin/sanity-check.sh
184     Checking:
185     - /opt/omnipitr/bin
186     - /opt/omnipitr/lib
187     5 programs, 9 libraries.
188     All checked, and looks ok.
189
190 if there are any errors/warnings - do whatever you can to fix them.
191
192 Now. If this works well, we can move on to setting up all subsequent steps.
193
194 =head3 Archival of XLOGs from master
195
196 In /home/postgres/data/postgresql.conf find section "WRITE AHEAD LOG" ->
197 "Archiving". Usually it contains lines like these:
198
199     #archive_mode = off    # allows archiving to be done
200     #archive_command = ''  # command to use to archive a logfile segment
201     #archive_timeout = 0   # force a logfile segment switch after this
202
203 You need to enable archive_mode:
204
205     archive_mode = on
206
207 (in older versions ( pre 8.2 ) there is no archive_mode. It's ok - just don't
208 add it).
209
210 Set archive_command to:
211
212     archive_command = '/opt/omnipitr/bin/omnipitr-archive -l /home/postgres/omnipitr/log/omnipitr-^Y^m^d.log -s /home/postgres/omnipitr/state -dr gzip=rsync://slave/wal_archive/ -dr gzip=rsync://backup/database/xlog/ -db /var/tmp/omnipitr/dstbackup -t /var/tmp/omnipitr/ -v "%p"'
213
214 and archive_timeout to:
215
216     archive_timeout = 60
217
218 This will make sure that in worst case you have 1 minute lag.
219
220 Meaning of options:
221
222 =over
223
224 =item * -l /home/postgres/omnipitr/log/omnipitr-^Y^m^d.log : Path to logfile,
225 will be automatically rotated on date change.
226
227 =item * -s /home/postgres/omnipitr/state : Directory to keep state information,
228 internal stuff, not really interesting, small files only, but it is required if
229 we have more than 1 destination
230
231 =item * -dr gzip=rsync://slave/wal_archive/ : sends gzip compressed wal segments
232 to slave to appropriate path
233
234 =item * -dr gzip=rsync://backup/database/xlog/ : sends the same gzip compressed
235 wal segments to backup server for long term storage
236
237 =item * -db /var/tmp/omnipitr/dstbackup : it is important that this path
238 shouldn't exist - it's a directory, that (if it exists) will be used as
239 additional local destination - for the purposes of omnipitr-backup-master program
240
241 =item * -t /var/tmp/omnipitr/ : where to keep temporary files (when needed)
242
243 =item * -v : log verbose information - mostly timings.
244
245 =back
246
247 Afterwards you need to restart PostgreSQL (or reload if you changed only
248 archive_command and/or archive_timeout).
249
250 Archiving should work nicely now, which you can see after couple of minutes
251 (assuming you set archive_timeout to 60 seconds, like I showed above).
252
253 You should start seeing compressed files showing on slave and backup servers,
254 and appropriate information in logfile.
255
256 =head3 Creation of hot backup on master
257
258 This is actually pretty simple - assuming you have working archiving (described
259 in previous section of this howto.
260
261 You simply run this command:
262
263     /opt/omnipitr/bin/omnipitr-backup-master -D /home/postgres/data -l /home/postgres/omnipitr/log/omnipitr-^Y^m^d.log -x /var/tmp/omnipitr/dstbackup -dr gzip=rsync://backup/database/hot_backup/ -t /var/tmp/omnipitr/ --pid-file /home/postgres/omnipitr/backup-master.pid -v
264
265 Meaning of options:
266
267 =over
268
269 =item * -D /home/postgres/data : Where is data directory for PostgreSQL instance
270
271 =item * -l /home/postgres/omnipitr/log/omnipitr-^Y^m^d.log : Where to log
272 information - logfile will be daily rotated. Logfile can be shared between
273 OmniPITR programs as each line contains identifier of program that wrote it
274
275 =item * -x /var/tmp/omnipitr/dstbackup : Should be the same path as in I<-db>
276 option to omnipitr-archive, and it shouldn't exist - omnipitr-backup-master will
277 create it, and later on remove.
278
279 =item * -dr gzip=rsync://backup/database/hot_backup/ : Will send gzip compressed
280 backups to backup server to appropriate directory.
281
282 =item * -t /var/tmp/omnipitr/ : Where to create temporary files
283
284 =item * --pid-file /home/postgres/omnipitr/backup-master.pid : When running
285 manually, it's not needed, but when the same command will be put in cronjob -
286 it's nice to be sure that only 1 backup can run at the same time
287
288 =item * -v : Log verbosely - mostly add timings.
289
290 =back
291
292 After running, on backup server you will get 2 files:
293
294 =over
295
296 =item * master-data-YYYY-MM-DD.tar.gz
297
298 =item * master-xlog-YYYY-MM-DD.tar.gz
299
300 =back
301
302 which together form backup for master database.
303
304 =head3 Starting up slave
305
306 First you need to obtain master-data backup file from backup server. Xlog file
307 is only used if you want to start the server as fully working r/w server and not
308 replication slave.
309
310 So, get the .tar.gz file to /home/postgres, and uncompress it.
311
312 It will create /home/postgres/data directory which contains copy of PostgreSQL
313 files from master.
314
315 Now, edit /home/postgres/data/postgresql.conf (this, like any other file
316 mentioned in this section - on slave), and change archive_command to:
317
318     archive_command = '/bin/true'
319
320 To make sure that slave will not try to archive xlog files.
321
322 Afterwards, in /home/postgres/data directory make I<recovery.conf> file with
323 single line:
324
325     restore_command = ' /opt/omnipitr/bin/omnipitr-restore -l /var/tmp/omnipitr-^Y^m^d.log -s gzip=/home/postgres/wal_archive -f /home/postgres/omnipitr/finish.recovery -r -p /home/postgres/omnipitr/pause.removal -v -t /var/tmp/omnipitr/ -w 900 %f %p'
326
327 Meaning of options:
328
329 =over
330
331 =item * -l /var/tmp/omnipitr-^Y^m^d.log : Where to log information - logfile
332 will be daily rotated. Logfile can be shared between OmniPITR programs as each
333 line contains identifier of program that wrote it
334
335 =item * -s gzip=/home/postgres/wal_archive : Where to find xlog segments sent in
336 from master, and how are they compressed
337
338 =item * -f /home/postgres/omnipitr/finish.recovery : Trigger file - if it will
339 exist - recovery will be stopped.
340
341 =item * -r : remove no longer needed xlog segments - it's a bit more tricky than
342 'segments that have been already applied', but we can be sure it's safe
343 operation - even in cases like stopping slave recovery for days.
344
345 =item * -p /home/postgres/omnipitr/pause.removal : trigger file - if it exists -
346 segments will no longer be removed when no longer needed - this is useful for
347 omnipitr-backup-slave
348
349 =item * -v : log verbosely
350
351 =item * -t /var/tmp/omnipitr/ : where to create temporary files, if needed.
352
353 =item * -w 900 : wait 15 minutes between xlog arrival and application - this is
354 to be able to stop recovery in case of catastrophic query being run on master
355 (think: I<truncate table users>)
356
357 =back
358
359 Afterwards - just start PostgreSQL on slave, and check generated logs for
360 information about progress, but everything should be working just fine now.
361
362 =head2 COPYRIGHT
363
364 The OmniPITR project is Copyright (c) 2009 OmniTI. All rights reserved.
Note: See TracBrowser for help on using the browser.