root/trunk/omnipitr/doc/omnipitr-master-backup.pod

Revision 91, 6.8 kB (checked in by depesz, 4 years ago)

change the strftime % marker to - also to avoid clash with postgresql % usage

Line 
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 --temp-dir (-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. Unfortunately due to the %x usage by PostgreSQL, We cannot use %%
59 macros directly. Instead - any occurence of ^ character in log dir will be first
60 changed to %, and later on passed to strftime.
61
62 =item --filename-template (-f)
63
64 Template for naming output files. Check L<FILENAMES> section for details.
65
66 =item --pid-file
67
68 Name of file to use for pidfile. If it is specified, than only one copy of
69 I<omnipitr-master-backup> (with this pidfile) can run at the same time.
70
71 Trying to run second copy of I<omnipitr-master-backup> will result in an error.
72
73 =item --verbose (-v)
74
75 Log verbosely what is happening.
76
77 =back
78
79 =head2 DESCRIPTION
80
81 Running this program should be done by cronjob, or manually by database
82 administrator.
83
84 As a result of running it there are 2 files, usually named
85 HOST-data-YYYY-MM-DD.tar and HOST-xlog-YYYY-MM-DD.tar. These files can be
86 optionally compressed and delivered to many places - both local (on the same
87 server) or remote (via rsync).
88
89 Which options should be given depends only on installation, but generally you
90 will need at least:
91
92 =over
93
94 =item * --data-dir
95
96 Backup will process files in this directory.
97
98 =item * --log
99
100 to make sure that information is logged someplace about archiving progress
101
102 =item * one of --dst-local or --dst-remote
103
104 to specify where to send the backup files to
105
106 =back
107
108 Of course you can provide many --dst-local or many --dst-remote or many mix of
109 these.
110
111 Generally omnipitr-master-backup will try to deliver WAL segment to all
112 destinations. In case remote destination will fail, omnipitr-master-backup will
113 retry 3 times, with 5 minute delay between tries.
114
115 In case of errors when writing to local destination - it is skipped, and error
116 is logged.
117
118 Backups will be transferred to destinations in this order:
119
120 =over
121
122 =item 1. All B<local> destinations, in order provided in command line
123
124 =item 2. All B<remote> destinations, in order provided in command line
125
126 =back
127
128 =head3 Remote destination specification
129
130 I<omnipitr-master-backup> delivers backup files to destination using rsync
131 program.  Both direct-rsync and rsync-over-ssh are supported (it's better to use
132 direct rsync - it uses less resources due to lack of encryption.
133
134 Destination url/location should be in a format that is usable by I<rsync>
135 program.
136
137 For example you can use:
138
139 =over
140
141 =item * rsync://user@remote_host/module/path/
142
143 =item * host:/path/
144
145 =back
146
147 To allow remote delivery you need to have rsync program. In case you're using
148 rsync over ssh, I<ssh> program has also to be available.
149
150 In case your rsync/ssh programs are in custom directories simply set I<$PATH>
151 environemnt variable before starting PostgreSQL.
152
153 =head2 COMPRESSION
154
155 Every destination can have specified compression. To use it you should prefix
156 destination path/url with compression type followed by '=' sign.
157
158 Allowed compression types:
159
160 =over
161
162 =item * gzip
163
164 Compresses with gzip program, used file extension is .gz
165
166 =item * bzip2
167
168 Compresses with bzip2 program, used file extension is .bz2
169
170 =item * lzma
171
172 Compresses with lzma program, used file extension is .lzma
173
174 =back
175
176 All compressions are done I<on B<NICE>> to make the operation as unobtrusive as
177 possible.
178
179 If you want to pass any extra arguments to compression program, you can either:
180
181 =over
182
183 =item * make a wrapper
184
185 Write a program/script that will be named in the same way your actual
186 compression program is named, but adding some parameters to call
187
188 =item * use environment variables
189
190 All of supported compression programs use environment variables:
191
192 =over
193
194 =item * gzip - GZIP
195
196 =item * bzip2 - BZIP2
197
198 =item * lzma - XZ_OPT
199
200 =back
201
202 For details - please consult manual to your choosen compression tool.
203
204 =back
205
206 B<It is strongly suggest to use only 1 compression method for all destinations>
207
208 =head2 FILENAMES
209
210 Naming of files for backups might be important depending on deployment.
211
212 Generally, generated filenames are named using templates, with default template
213 being:
214
215     __HOSTNAME__-__FILETYPE__-^Y-^m-^d.tar__CEXT__
216
217 Within template (specified with --filename-template option) you can use
218 following markers:
219
220 =over
221
222 =item * __HOSTNAME__
223
224 Name of server backup is made on - as reported by L<hostname(1)> program.
225
226 =item * __FILETYPE__
227
228 It is actually required to have __FILETYPE__ - it specifies whether the file
229 contains data (data) or xlog segments (xlog)
230
231 =item * __CEXT__
232
233 Based on compression algorithm choosen for given delivery. Can be empty (no
234 compression), or contains dot (.) and literal extension associated with choosen
235 compression program.
236
237 =item * any ^? markers
238
239 like in L<strftime(3)> call, but ^ will be changed to % first.
240
241 =back
242
243 Filename template is evaluated at start, so any timestamp (^? markers) will
244 relate to date/time of beginning of backup process.
245
246 =head2 EXAMPLES
247
248 =head3 Minimal setup, with copying file to local directory:
249
250     /.../omnipitr-master-backup -D /mnt/data -l /var/log/omnipitr/backup.log -dl /mnt/backups/
251
252 =head3 Minimal setup, with compression, and copying file to remote directory over rsync:
253
254     /.../omnipitr-master-backup -D /mnt/data/ -l /var/log/omnipitr/backup.log -dr bzip2=rsync://slave/postgres/backups/
255
256 =head3 2 remote, compressed destinations, 1 local, with auto rotated logfile,
257 and modified filenames
258
259     /.../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__"
260
261 =head2 COPYRIGHT
262
263 The OmniPITR project is Copyright (c) 2009 OmniTI. All rights reserved.
264
Note: See TracBrowser for help on using the browser.