Changeset 62

Show
Ignore:
Timestamp:
12/10/09 16:57:02 (9 years ago)
Author:
depesz
Message:

looks like ready

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved
  • trunk/omnipitr/doc/omnipitr-slave-backup.pod

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