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

Revision 59, 5.2 kB (checked in by depesz, 4 years ago)

update - new doc for new command, and fix for typo in another one

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