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

Revision 128, 6.9 kB (checked in by depesz, 4 years ago)

1. add handling for --rsync-path option
2. add --debug "option"

it's "option", and not option, because it has to be first argument, and it's not documented, as its of *no* use to anybody using omnipitr in normal circumstances.

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