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

Revision 59, 6.3 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-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
Note: See TracBrowser for help on using the browser.