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

Revision 82, 5.5 kB (checked in by depesz, 4 years ago)

while reminding myself of the code, I found out that datadir can be easily defaulted to '.'

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