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

Revision 130, 7.3 kB (checked in by depesz, 4 years ago)

simple todo list to keep track of missing features

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