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

Revision 89, 5.9 kB (checked in by depesz, 4 years ago)

change % to = in compression specification to avoid problems with postgresql expansion in restore or archive commands - changed in other scripts to keep it the same

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