Changeset 59

Show
Ignore:
Timestamp:
12/04/09 18:06:27 (4 years ago)
Author:
depesz
Message:

update - new doc for new command, and fix for typo in another one

Files:

Legend:

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

    r58 r59  
    127127 
    128128To allow remote delivery you need to have rsync program. In case you're using 
    129 rsync over ssh, program has also to be available. 
     129rsync over ssh, I<ssh> program has also to be available. 
    130130 
    131131In case your rsync/ssh programs are in custom directories simply set I<$PATH> 
  • trunk/omnipitr/doc/omnipitr-master-backup.pod

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