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

Revision 57, 4.1 kB (checked in by depesz, 4 years ago)

initial version of first part of docs of upcoming walreplication/backup system

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 =item --dst-remote (-dr)
21
22 Where to copy the wal segment on remote server. Supported ways to transport
23 files are rsync and rsync over ssh. Please see L<DESCRIPTION> for more
24 information (you can provide many of these)
25
26 =item --rsync-binary (-r)
27
28 Where to find rsync binary (defaults to searching through I<$PATH> environment
29 variable)
30
31 =item --tempdir (-t)
32
33 Where to create temporary files (defaults to /tmp or I<$TMPDIR> environment
34 variable location)
35
36 =item --log (-l)
37
38 Name of logfile (actually template, as it supports %% L<strftime(3)>
39 markers
40
41 =item --state-dir (-s)
42
43 Name of directory to use as state-directory to handle errors when sending wal
44 segments to many locations.
45
46 =item --verbose (-v)
47
48 Log verbosely what is happening.
49
50 =back
51
52 =head2 DESCRIPTION
53
54 Call to I<omnipitr-archive> should be in I<archive_command> GUC in
55 I<postgresql.conf>.
56
57 Which options should be given depends only on installation, but generally you
58 will need at least:
59
60 =over
61
62 =item * --data-dir
63
64 PostgreSQL "%p" passed file path relative to I<DATADIR>, so it is required to
65 know it.
66
67 =item * --log
68
69 to make sure that information is logged someplace about archiving progress
70
71 =item * one of --dst-local or --dst-remote
72
73 to specify where to send the WAL segments to
74
75 =back
76
77 If you'll specify more than 1 destination, you will also need to specify
78 I<--state-dir>
79
80 Of couse you can provide many --dst-local or many --dst-remote or many mix of
81 these.
82
83 Generally omnipitr-archive will try to deliver WAL segment to all destinations,
84 and will fail if B<any> of them will not accept new segment.
85
86 Segments will be transferred to destinations in this order:
87
88 =over
89
90 =item 1. All B<local> destinations, in order provided in command line
91
92 =item 2. All B<remote> destinations, in order provided in command line
93
94 =back
95
96 In case any destination will fail, I<omnipitr-archive> will save state (which
97 destinations it delivered the file to) and return error to PostgreSQL - which
98 will cause PostgrerSQL to call I<omnipitr-archive> again for the same WAL
99 segment after some time.
100
101 State directory will be cleared after every successfull file send, so it should
102 stay small in size (expect 1 file of under 500 bytes).
103
104 When constructing command line to put in I<archive_command> PostgreSQL GUC,
105 please remember that while providing C<"%p" "%f"> will work, I<omnipitr-archive>
106 requires only "%p"
107
108 =head3 Remote destination specification
109
110 I<omnipitr-archive> can deliver WAL segments to remote locations using 2 ways of
111 transporting the file:
112
113 =over
114
115 =item 1. rsync
116
117 Standard rsync via rsync daemon (not via ssh!). You can specify remote url like
118 this: C<rsync://remote_server/module/directory/> or any other syntax I<rsync>
119 program supports as long as it starts with B<rsync://>
120
121 =item 2. rsync over ssh
122
123 Rsync working via ssh. This required passwordless ssh authentication from source
124 account to destination (usually with passwordless ssh keys). Url for remote in
125 this situation should look like this: C<rsync+ssh://server/path/> - this is
126 equivalent to using C<rsync -e ssh SOURCE_FILE server/path/>
127
128 =back
129
130 =head2 EXAMPLES
131
132 =head3 Minimal setup, with copying file to local directory:
133
134     archive_command='/.../omnipitr-archive -D /mnt/data/ -l /var/log/omnipitr/archive.log -dl /mnt/wal_archive/ "%p"'
135
136 =head3 Minimal setup, with copying file to remote directory over rsync:
137
138     archive_command='/.../omnipitr-archive -D /mnt/data/ -l /var/log/omnipitr/archive.log -dr rsync://slave/postgres/wal_archive/ "%p"'
139
140 =head3 2 remote destinations, 1 local, with non-standard rsync binary, and auto
141 rotated logfile:
142
143     archive_command='/.../omnipitr-archive -r /opt/something/bin/rsync -D /mnt/data/ -l /var/log/omnipitr/archive-%Y-%m-%d.log -dr rsync://slave/postgres/wal_archive/ -dr rsync+ssh://backups@backupserver:/mnt/backups/wal_archive/ -s /var/lib/postgres/.omnipitr/ "%p"'
144
145 =head2 COPYRIGHT
146
147 The OmniPITR project is Copyright (c) 2009 OmniTI. All rights reserved.
148
Note: See TracBrowser for help on using the browser.