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

Revision 91, 6.1 kB (checked in by depesz, 4 years ago)

change the strftime % marker to - also to avoid clash with postgresql % usage

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