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

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