1 |
=head1 OmniPITR - omnipitr-master-backup |
---|
2 |
|
---|
3 |
=head2 USAGE |
---|
4 |
|
---|
5 |
/some/path/omnipitr/bin/omnipitr-master-backup [options] |
---|
6 |
|
---|
7 |
Options: |
---|
8 |
|
---|
9 |
=over |
---|
10 |
|
---|
11 |
=item --data-dir (-D) |
---|
12 |
|
---|
13 |
Where PostgreSQL datadir is located (path) |
---|
14 |
|
---|
15 |
=item --database (-d) |
---|
16 |
|
---|
17 |
Which database to connect to to issue required SQL queries. Defaults to |
---|
18 |
template1. |
---|
19 |
|
---|
20 |
=item --host (-h) |
---|
21 |
|
---|
22 |
Which host to connect to when connecting to database to backup. Shouldn't really |
---|
23 |
be changed in 99% of cases. Defaults to empty string - i.e. use UNIX sockets. |
---|
24 |
|
---|
25 |
=item --port (-p) |
---|
26 |
|
---|
27 |
Which port to connect to when connecting to database. Defaults to 5432. |
---|
28 |
|
---|
29 |
=item --username (-U) |
---|
30 |
|
---|
31 |
What username to use when connecting to database. Defaults to postgres. |
---|
32 |
|
---|
33 |
=item --dst-local (-dl) |
---|
34 |
|
---|
35 |
Where to copy the hot backup files on current server (you can provide many of |
---|
36 |
these). |
---|
37 |
|
---|
38 |
You can also specify compression per-destination. Check L<COMPRESSION> |
---|
39 |
section of the doc. |
---|
40 |
|
---|
41 |
=item --dst-remote (-dr) |
---|
42 |
|
---|
43 |
Where to copy the hot backup files on remote server. Supported ways to transport |
---|
44 |
files are rsync and rsync over ssh. Please see L<DESCRIPTION> for more |
---|
45 |
information (you can provide many of these) |
---|
46 |
|
---|
47 |
You can also specify compression per-destination. Check L<COMPRESSION> |
---|
48 |
section of the doc. |
---|
49 |
|
---|
50 |
=item --tempdir (-t) |
---|
51 |
|
---|
52 |
Where to create temporary files (defaults to /tmp or I<$TMPDIR> environment |
---|
53 |
variable location) |
---|
54 |
|
---|
55 |
=item --log (-l) |
---|
56 |
|
---|
57 |
Name of logfile (actually template, as it supports %% L<strftime(3)> |
---|
58 |
markers |
---|
59 |
|
---|
60 |
=item --filename-template (-f) |
---|
61 |
|
---|
62 |
Template for naming output files. Check L<FILENAMES> section for details. |
---|
63 |
|
---|
64 |
=item --verbose (-v) |
---|
65 |
|
---|
66 |
Log verbosely what is happening. |
---|
67 |
|
---|
68 |
=back |
---|
69 |
|
---|
70 |
=head2 DESCRIPTION |
---|
71 |
|
---|
72 |
Running this program should be done by cronjob, or manually by database |
---|
73 |
administrator. |
---|
74 |
|
---|
75 |
As a result of running it there are 2 files, usually named |
---|
76 |
HOST-data-YYYY-MM-DD.tar and HOST-xlog-YYYY-MM-DD.tar. These files can be |
---|
77 |
optionally compressed and delivered to many places - both local (on the same |
---|
78 |
server) or remote (via rsync). |
---|
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 |
Backup will process files in this directory. |
---|
88 |
|
---|
89 |
=item * --log |
---|
90 |
|
---|
91 |
to make sure that information is logged someplace about archiving progress |
---|
92 |
|
---|
93 |
=item * one of --dst-local or --dst-remote |
---|
94 |
|
---|
95 |
to specify where to send the backup files to |
---|
96 |
|
---|
97 |
=back |
---|
98 |
|
---|
99 |
Of course you can provide many --dst-local or many --dst-remote or many mix of |
---|
100 |
these. |
---|
101 |
|
---|
102 |
Generally omnipitr-master-backup will try to deliver WAL segment to all |
---|
103 |
destinations. In case remote destination will fail, omnipitr-master-backup will |
---|
104 |
retry 3 times, with 5 minute delay between tries. |
---|
105 |
|
---|
106 |
In case of errors when writing to local destination - it is skipped, and error |
---|
107 |
is logged. |
---|
108 |
|
---|
109 |
Segments will be transferred to destinations in this order: |
---|
110 |
|
---|
111 |
=over |
---|
112 |
|
---|
113 |
=item 1. All B<local> destinations, in order provided in command line |
---|
114 |
|
---|
115 |
=item 2. All B<remote> destinations, in order provided in command line |
---|
116 |
|
---|
117 |
=back |
---|
118 |
|
---|
119 |
=head3 Remote destination specification |
---|
120 |
|
---|
121 |
I<omnipitr-master-backup> delivers backup files to destination using rsync |
---|
122 |
program. Both direct-rsync and rsync-over-ssh are supported (it's better to use |
---|
123 |
direct rsync - it uses less resources due to lack of encryption. |
---|
124 |
|
---|
125 |
Destination url/location should be in a format that is usable by I<rsync> |
---|
126 |
program. |
---|
127 |
|
---|
128 |
For example you can use: |
---|
129 |
|
---|
130 |
=over |
---|
131 |
|
---|
132 |
=item * rsync://user@remote_host/module/path/ |
---|
133 |
|
---|
134 |
=item * host:/path/ |
---|
135 |
|
---|
136 |
=back |
---|
137 |
|
---|
138 |
To allow remote delivery you need to have rsync program. In case you're using |
---|
139 |
rsync over ssh, I<ssh> program has also to be available. |
---|
140 |
|
---|
141 |
In case your rsync/ssh programs are in custom directories simply set I<$PATH> |
---|
142 |
environemnt variable before starting PostgreSQL. |
---|
143 |
|
---|
144 |
=head2 COMPRESSION |
---|
145 |
|
---|
146 |
Every destination can have specified compression. To use it you should prefix |
---|
147 |
destination path/url with compression type followed by '%' sign. |
---|
148 |
|
---|
149 |
Allowed compression types: |
---|
150 |
|
---|
151 |
=over |
---|
152 |
|
---|
153 |
=item * gzip |
---|
154 |
|
---|
155 |
Compresses with gzip program, used file extension is .gz |
---|
156 |
|
---|
157 |
=item * bzip2 |
---|
158 |
|
---|
159 |
Compresses with bzip2 program, used file extension is .bz2 |
---|
160 |
|
---|
161 |
=item * lzma |
---|
162 |
|
---|
163 |
Compresses with lzma program, used file extension is .lzma |
---|
164 |
|
---|
165 |
=back |
---|
166 |
|
---|
167 |
All compressions are done I<on B<NICE>> to make the operation as unobtrusive as |
---|
168 |
possible. |
---|
169 |
|
---|
170 |
If you want to pass any extra arguments to compression program, you can either: |
---|
171 |
|
---|
172 |
=over |
---|
173 |
|
---|
174 |
=item * make a wrapper |
---|
175 |
|
---|
176 |
Write a program/script that will be named in the same way your actual |
---|
177 |
compression program is named, but adding some parameters to call |
---|
178 |
|
---|
179 |
=item * use environment variables |
---|
180 |
|
---|
181 |
All of supported compression programs use environment variables: |
---|
182 |
|
---|
183 |
=over |
---|
184 |
|
---|
185 |
=item * gzip - GZIP |
---|
186 |
|
---|
187 |
=item * bzip2 - BZIP2 |
---|
188 |
|
---|
189 |
=item * lzma - XZ_OPT |
---|
190 |
|
---|
191 |
=back |
---|
192 |
|
---|
193 |
For details - please consult manual to your choosen compression tool. |
---|
194 |
|
---|
195 |
=back |
---|
196 |
|
---|
197 |
B<It is strongly suggest to use only 1 compression method for all destinations> |
---|
198 |
|
---|
199 |
=head2 FILENAMES |
---|
200 |
|
---|
201 |
Naming of files for backups might be important depending on deployment. |
---|
202 |
|
---|
203 |
Generally, generated filenames are named using templates, with default template |
---|
204 |
being: |
---|
205 |
|
---|
206 |
__HOSTNAME__-__FILETYPE__-%Y-%m-%d.tar__CEXT__ |
---|
207 |
|
---|
208 |
Within template (specified with --filename-template option) you can use |
---|
209 |
following markers: |
---|
210 |
|
---|
211 |
=over |
---|
212 |
|
---|
213 |
=item * __HOSTNAME__ |
---|
214 |
|
---|
215 |
Name of server backup is made on - as reported by L<hostname(1)> program. |
---|
216 |
|
---|
217 |
=item * __FILETYPE__ |
---|
218 |
|
---|
219 |
It is actually required to have __FILETYPE__ - it specifies whether the file |
---|
220 |
contains data (data) or xlog segments (xlog) |
---|
221 |
|
---|
222 |
=item * __CEXT__ |
---|
223 |
|
---|
224 |
Based on compression algorithm choosen for given delivery. Can be empty (no |
---|
225 |
compression), or contains dot (.) and literal extension associated with choosen |
---|
226 |
compression program. |
---|
227 |
|
---|
228 |
=item * any %? markers |
---|
229 |
|
---|
230 |
like in L<strftime(3)> call. |
---|
231 |
|
---|
232 |
=back |
---|
233 |
|
---|
234 |
Filename template is evaluated at start, so any timestamp (%? markers) will |
---|
235 |
relate to date/time of beginning of backup process. |
---|
236 |
|
---|
237 |
=head2 EXAMPLES |
---|
238 |
|
---|
239 |
=head3 Minimal setup, with copying file to local directory: |
---|
240 |
|
---|
241 |
/.../omnipitr-master-backup -D /mnt/data -l /var/log/omnipitr/backup.log -dl /mnt/backups/ |
---|
242 |
|
---|
243 |
=head3 Minimal setup, with compression, and copying file to remote directory over rsync: |
---|
244 |
|
---|
245 |
/.../omnipitr-master-backup -D /mnt/data/ -l /var/log/omnipitr/backup.log -dr bzip2%rsync://slave/postgres/backups/ |
---|
246 |
|
---|
247 |
=head3 2 remote, compressed destinations, 1 local, with auto rotated logfile, |
---|
248 |
and modified filenames |
---|
249 |
|
---|
250 |
/.../omnipitr-master-backup -D /mnt/data/ -l /var/log/omnipitr/backup-%Y-%m-%d.log -dr bzip2%rsync://slave/postgres/backups/ -dr gzip%backups:/mnt/hotbackups/ -dl /mnt/backups/ -f "main-__FILETYPE__-%Y%m%d_%H%M%S.tar__CEXT__" |
---|
251 |
|
---|
252 |
=head2 COPYRIGHT |
---|
253 |
|
---|
254 |
The OmniPITR project is Copyright (c) 2009 OmniTI. All rights reserved. |
---|
255 |
|
---|