Changeset 62

12/10/09 16:57:02 (9 years ago)

looks like ready



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

    r57 r62  
    33=head2 USAGE 
     5/some/path/omnipitr/bin/omnipitr-slave-backup [options] 
     11=item --data-dir (-D) 
     13Where PostgreSQL datadir is located (path) 
     15=item --dst-local (-dl) 
     17Where to copy the hot backup files on current server (you can provide many of 
     20You can also specify compression per-destination. Check L<COMPRESSION> 
     21section of the doc. 
     23=item --dst-remote (-dr) 
     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) 
     29You can also specify compression per-destination. Check L<COMPRESSION> 
     30section of the doc. 
     32=item --temp-dir (-t) 
     34Where to create temporary files (defaults to /tmp or I<$TMPDIR> environment 
     35variable location) 
     37=item --log (-l) 
     39Name of logfile (actually template, as it supports %% L<strftime(3)> 
     42=item --filename-template (-f) 
     44Template for naming output files. Check L<FILENAMES> section for details. 
     46=item --pid-file 
     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. 
     51Trying to run second copy of I<omnipitr-slave-backup> will result in an error. 
     53=item --verbose (-v) 
     55Log verbosely what is happening. 
    559=head2 DESCRIPTION 
     61Running this program should be done by cronjob, or manually by database 
     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). 
     69Which options should be given depends only on installation, but generally you 
     70will need at least: 
     74=item * --data-dir 
     76Backup will process files in this directory. 
     78=item * --log 
     80to make sure that information is logged someplace about archiving progress 
     82=item * one of --dst-local or --dst-remote 
     84to specify where to send the backup files to 
     88Of course you can provide many --dst-local or many --dst-remote or many mix of 
     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. 
     95In case of errors when writing to local destination - it is skipped, and error 
     96is logged. 
     98Backups will be transferred to destinations in this order: 
     102=item 1. All B<local> destinations, in order provided in command line 
     104=item 2. All B<remote> destinations, in order provided in command line 
     108=head3 Remote destination specification 
     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. 
     114Destination url/location should be in a format that is usable by I<rsync> 
     117For example you can use: 
     121=item * rsync://user@remote_host/module/path/ 
     123=item * host:/path/ 
     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. 
     130In case your rsync/ssh programs are in custom directories simply set I<$PATH> 
     131environemnt variable before starting PostgreSQL. 
     133=head2 COMPRESSION 
     135Every destination can have specified compression. To use it you should prefix 
     136destination path/url with compression type followed by '%' sign. 
     138Allowed compression types: 
     142=item * gzip 
     144Compresses with gzip program, used file extension is .gz 
     146=item * bzip2 
     148Compresses with bzip2 program, used file extension is .bz2 
     150=item * lzma 
     152Compresses with lzma program, used file extension is .lzma 
     156If you want to pass any extra arguments to compression program, you can either: 
     160=item * make a wrapper 
     162Write a program/script that will be named in the same way your actual 
     163compression program is named, but adding some parameters to call 
     165=item * use environment variables 
     167All of supported compression programs use environment variables: 
     171=item * gzip - GZIP 
     173=item * bzip2 - BZIP2 
     175=item * lzma - XZ_OPT 
     179For details - please consult manual to your choosen compression tool. 
     183B<It is strongly suggest to use only 1 compression method for all destinations> 
     185=head2 FILENAMES 
     187Naming of files for backups might be important depending on deployment. 
     189Generally, generated filenames are named using templates, with default template 
     192    __HOSTNAME__-__FILETYPE__-%Y-%m-%d.tar__CEXT__ 
     194Within template (specified with --filename-template option) you can use 
     195following markers: 
     199=item * __HOSTNAME__ 
     201Name of server backup is made on - as reported by L<hostname(1)> program. 
     203=item * __FILETYPE__ 
     205It is actually required to have __FILETYPE__ - it specifies whether the file 
     206contains data (data) or xlog segments (xlog) 
     208=item * __CEXT__ 
     210Based on compression algorithm choosen for given delivery. Can be empty (no 
     211compression), or contains dot (.) and literal extension associated with choosen 
     212compression program. 
     214=item * any %? markers 
     216like in L<strftime(3)> call. 
     220Filename template is evaluated at start, so any timestamp (%? markers) will 
     221relate to date/time of beginning of backup process. 
    7223=head2 EXAMPLES 
     225=head3 Minimal setup, with copying file to local directory: 
     227    /.../omnipitr-slave-backup -D /mnt/data -l /var/log/omnipitr/backup.log -dl /mnt/backups/ 
     229=head3 Minimal setup, with compression, and copying file to remote directory over rsync: 
     231    /.../omnipitr-slave-backup -D /mnt/data/ -l /var/log/omnipitr/backup.log -dr bzip2%rsync://slave/postgres/backups/ 
     233=head3 2 remote, compressed destinations, 1 local, with auto rotated logfile, 
     234and modified filenames 
     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__" 
    9238=head2 COPYRIGHT