root/trunk/omnipitr/doc/omnipitr-archive.pod

Revision 102, 6.3 kB (checked in by depesz, 4 years ago)

add ability to force data dir - required to make archive usable as 'pre-removal-processing' for restore

Line 
1 =head1 OmniPITR - omnipitr-archive
2
3 =head2 USAGE
4
5 /some/path/omnipitr/bin/omnipitr-archive [options] "%p"
6
7 Options:
8
9 =over
10
11 =item --data-dir (-D)
12
13 Where PostgreSQL datadir is located (path)
14
15 =item --force-data-dir (-f)
16
17 Forces usage of given (or default) data dir even if it doesn't look like
18 PostgreSQL data directory.
19
20 =item --dst-local (-dl)
21
22 Where to copy the wal segment on current server (path) (you can provide many of
23 these).
24
25 You can also specify compression per-destination. Check L<COMPRESSION>
26 section of the doc.
27
28 =item --dst-remote (-dr)
29
30 Where to copy the wal segment on remote server. Supported ways to transport
31 files are rsync and rsync over ssh. Please see L<DESCRIPTION> for more
32 information (you can provide many of these)
33
34 You can also specify compression per-destination. Check L<COMPRESSION>
35 section of the doc.
36
37 =item --temp-dir (-t)
38
39 Where to create temporary files (defaults to /tmp or I<$TMPDIR> environment
40 variable location)
41
42 =item --log (-l)
43
44 Name of logfile (actually template, as it supports %% L<strftime(3)>
45 markers. Unfortunately due to the %x usage by PostgreSQL, We cannot use %%
46 macros directly. Instead - any occurence of ^ character in log dir will be first
47 changed to %, and later on passed to strftime.
48
49 =item --state-dir (-s)
50
51 Name of directory to use as state-directory to handle errors when sending wal
52 segments to many locations.
53
54 =item --pid-file
55
56 Name of file to use for pidfile. If it is specified, than only one copy of
57 I<omnipitr-archive> (with this pidfile) can run at the same time.
58
59 Trying to run second copy of I<omnipitr-archive> will result in an error.
60
61 =item --verbose (-v)
62
63 Log verbosely what is happening.
64
65 =item --gzip-path (-gp)
66
67 Full path to gzip program - in case you can't set proper PATH environment
68 variable.
69
70 =item --bzip2-path (-bp)
71
72 Full path to bzip2 program - in case you can't set proper PATH environment
73 variable.
74
75 =item --lzma-path (-lp)
76
77 Full path to lzma program - in case you can't set proper PATH environment
78 variable.
79
80 =back
81
82 =head2 DESCRIPTION
83
84 Call to I<omnipitr-archive> should be in I<archive_command> GUC in
85 I<postgresql.conf>.
86
87 Which options should be given depends only on installation, but generally you
88 will need at least:
89
90 =over
91
92 =item * --data-dir
93
94 PostgreSQL "%p" passed file path relative to I<DATADIR>, so it is required to
95 know it. If not provided, it is assumed to be "." ( which is perfectly in line
96 with PostgreSQL assumptions about archive_command ).
97
98 =item * --log
99
100 to make sure that information is logged someplace about archiving progress
101
102 =item * one of --dst-local or --dst-remote
103
104 to specify where to send the WAL segments to
105
106 =back
107
108 If you'll specify more than 1 destination, you will also need to specify
109 I<--state-dir>
110
111 Of couse you can provide many --dst-local or many --dst-remote or many mix of
112 these.
113
114 Generally omnipitr-archive will try to deliver WAL segment to all destinations,
115 and will fail if B<any> of them will not accept new segment.
116
117 Segments will be transferred to destinations in this order:
118
119 =over
120
121 =item 1. All B<local> destinations, in order provided in command line
122
123 =item 2. All B<remote> destinations, in order provided in command line
124
125 =back
126
127 In case any destination will fail, I<omnipitr-archive> will save state (which
128 destinations it delivered the file to) and return error to PostgreSQL - which
129 will cause PostgrerSQL to call I<omnipitr-archive> again for the same WAL
130 segment after some time.
131
132 State directory will be cleared after every successfull file send, so it should
133 stay small in size (expect 1 file of under 500 bytes).
134
135 When constructing command line to put in I<archive_command> PostgreSQL GUC,
136 please remember that while providing C<"%p" "%f"> will work, I<omnipitr-archive>
137 requires only "%p"
138
139 =head3 Remote destination specification
140
141 I<omnipitr-archive> delivers WAL segments to destination using rsync program.
142 Both direct-rsync and rsync-over-ssh are supported (it's better to use direct
143 rsync - it uses less resources due to lack of encryption.
144
145 Destination url/location should be in a format that is usable by I<rsync>
146 program.
147
148 For example you can use:
149
150 =over
151
152 =item * rsync://user@remote_host/module/path/
153
154 =item * host:/path/
155
156 =back
157
158 To allow remote delivery you need to have rsync program. In case you're using
159 rsync over ssh, I<ssh> program has also to be available.
160
161 In case your rsync/ssh programs are in custom directories simply set I<$PATH>
162 environemnt variable before starting PostgreSQL.
163
164 =head2 COMPRESSION
165
166 Every destination can have specified compression. To use it you should prefix
167 destination path/url with compression type followed by '=' sign.
168
169 Allowed compression types:
170
171 =over
172
173 =item * gzip
174
175 Compresses with gzip program, used file extension is .gz
176
177 =item * bzip2
178
179 Compresses with bzip2 program, used file extension is .bz2
180
181 =item * lzma
182
183 Compresses with lzma program, used file extension is .lzma
184
185 =back
186
187 All compressions are done I<on B<NICE>> to make the operation as unobtrusive as
188 possible.
189
190 All programs are passed I<--stdout> option to compress without modifying source file.
191
192 If you want to pass any extra arguments to compression program, you can either:
193
194 =over
195
196 =item * make a wrapper
197
198 Write a program/script that will be named in the same way your actual
199 compression program is named, but adding some parameters to call
200
201 =item * use environment variables
202
203 All of supported compression programs use environment variables:
204
205 =over
206
207 =item * gzip - GZIP
208
209 =item * bzip2 - BZIP2
210
211 =item * lzma - XZ_OPT
212
213 =back
214
215 For details - please consult manual to your choosen compression tool.
216
217 =back
218
219 =head2 EXAMPLES
220
221 =head3 Minimal setup, with copying file to local directory:
222
223     archive_command='/.../omnipitr-archive -D /mnt/data/ -l /var/log/omnipitr/archive.log -dl /mnt/wal_archive/ "%p"'
224
225 =head3 Minimal setup, with copying file to remote directory over rsync:
226
227     archive_command='/.../omnipitr-archive -D /mnt/data/ -l /var/log/omnipitr/archive.log -dr rsync://slave/postgres/wal_archive/ "%p"'
228
229 =head3 2 remote, compressed destinations, 1 local, with auto rotated logfile:
230
231     archive_command='/.../omnipitr-archive -D /mnt/data/ -l /var/log/omnipitr/archive-^Y-^m-^d.log -dr gzip=rsync://slave/postgres/wal_archive/ -dr bzip2=backups@backupserver:/mnt/backups/wal_archive/ -dl /mnt/wal_archive/ -s /var/lib/postgres/.omnipitr/ "%p"'
232
233 =head2 COPYRIGHT
234
235 The OmniPITR project is Copyright (c) 2009 OmniTI. All rights reserved.
236
Note: See TracBrowser for help on using the browser.