Contents

• OmniPITR - omnipitr-synch
  • USAGE
  • DESCRIPTION
  • OUTPUT
  • EXAMPLES
    • Simplistic run, get data dir from Pg itself:
    • Automatic run, with tablespaces mapped to different delivery and logging
    • Automatic run, with 2 destinations and compression:
  • IMPORTANT NOTICES
  • COPYRIGHT

OmniPITR - omnipitr-synch

USAGE

/some/path/omnipitr/bin/omnipitr-synch [options]

Options:

--data-dir (-D)

Where PostgreSQL datadir is located (path). If skipped, it will be taken from PostgreSQL settings.

--database (-d)

Which database to connect to to issue required SQL queries. Defaults to postgres.

--host (-h)

Which host to connect to when connecting to database to run pg_backup_* functions. Shouldn't really be changed in 99% of cases. Defaults to empty string - i.e. use UNIX sockets.

--port (-p)

Which port to connect to when connecting to database. Defaults to 5432.

--username (-U)

What username to use when connecting to database. Defaults to postgres.

--output (-o)

Where to copy DATADIR - syntax should be one of:

• host:/absolute/path/to/new/place

• user@host:/absolute/path/to/new/place

If you need to use non-standard port number, you'll have to use ~/.ssh/config file to define it for given host - this is due to problem with passing ssh port number for rsync-over-ssh.

You can have multiple --output options to send data to multiple new machines with single cost of preparing data on source.

Please check OUTPUT section for more details.

--compress (-c)

Whether to use compression - value of parameter is name of compression program (with path if necessary).

It is also used (as a flag) when using --rsync option.

--rsync (-r)

If used, omnipitr-synch will use rsync instead of tar to transfer data (it will still be rsync over ssh). The benefit of using rsync is that it can send just the differences so it might be faster.

The drawback is that (depending on situation) it can be more taxing for source server hardware (IO/CPU).

Rsync will be used with data compression (-z) if --compress was given.

--map (-m)

When transmitting tablespaces, you might want to change output path for tablespace files - this is used then.

Please check OUTPUT section for more details.

--log (-l)

Name of logfile (actually template, as it supports %% strftime(3) markers. Unfortunately due to the %x usage by PostgreSQL, We cannot use %% macros directly. Instead - any occurence of ^ character in log dir will be first changed to %, and later on passed to strftime.

Please note that on some systems (Solaris for example) default shell treats ^ as special character, which requires you to quote the log filename (if it contains ^ character). So you'd better write it as:

--log '/var/log/omnipitr-^Y-^m-^d.log'

--pid-file

Name of file to use for pidfile. If it is specified, than only one copy of omnipitr-synch (with this pidfile) can run at the same time.

Trying to run second copy of omnipitr-synch will result in an error.

--verbose (-v)

Log verbosely what is happening.

--tee-path (-ep)

Full path to tee program - in case you can't set proper PATH environment variable.

--tar-path (-tp)

Full path to tar program - in case you can't set proper PATH environment variable.

--psql-path (-pp)

Full path to psql program - in case you can't set proper PATH environment variable.

--ssh-path (-sp)

Full path to ssh program - in case you can't set proper PATH environment variable.

--rsync-path (-rp)

Full path to rsync program - in case you can't set proper PATH environment variable.

--remote-tar-path (-rtp)

Full path to tar program on output side.

--remote-rsync-path (-rsp)

Full path to rsync program on output side.

--remote-compressor-path (-rcp)

Full path to compression program that will be used to decompress data on remote machine (if local data will be compressed). Defaults to whatever was passed to --compress.

--remote-rm-path (-rrp)

Full path to rm program on output server - it will be used to clear output directories before uncompressing new data.

--automatic (-a)

Run without confirmations. Without this option, omnipitr-synch will first gather data, apply output mappings, list all details, and then wait for use confirmation.

--temp-dir (-t)

Where to create temporary files (defaults to /tmp or $TMPDIR environment variable location)

--shell-path (-sh)

Full path to shell to be used when calling compression/archiving/checksumming.

It is important becaus the shell needs to support >( ... ) constructions.

One of the shells that do support it is bash, and this is the default value for --shell-path. You can substitute different shell if you're sure it supports mentioned construction.

--version (-V)

Prints version of omnipitr-synch, and exists.

--help (-?)

Prints this manual, and exists.

--config-file (--config / --cfg)

Loads options from config file.

Format of the file is very simple - each line is treated as argument with optional value.

Examples:

--verbose
--host 127.0.0.1
-h=127.0.0.1
--host=127.0.0.1

It is important that you don't need to quote the values - value will always be up to the end of line (trailing spaces will be removed). So if you'd want, for example, to have magic-option set to "/mnt/badly named directory", you'd need to quote it when setting from command line:

/some/omnipitr/program --magic-option="/mnt/badly named directory"

but not in config:

--magic-option=/mnt/badly named directory

Empty lines, and comment lines (starting with #) are ignored.

DESCRIPTION

This program is meant to be ran by hand to setup new slave system for replication.

It transfers PGDATA of PostgreSQL instance to new server, together with all necessary tablespaces, but skipping irrelevant files.

The transfer can be made when running source instance, thanks to calls to pg_start_backup() and pg_stop_backup() PostgreSQL functions.

Which options should be given depends only on installation, but generally you will need at least:

• --output

  to specify where to send the data dir.

  omnipitr-synch delivers files to destination using rsync program. Both direct-rsync and rsync-over-ssh are supported (it's better to use direct rsync - it uses less resources due to lack of encryption.

  To allow delivery you need to have ssh program.

• --log

  to make sure that information is logged someplace about progress. Unlike other omnipitr-* programs, when you'll don't provide -l, omnipitr-synch will output to STDOUT. This was done because unlike other omnipitr programs, this one is meant to be ran by hand, and not from cronjobs (although it's possible to do).

OUTPUT

If omnipitr-synch detects additional tablespaces, they will be also sent to destination (--output) server.

Full path to tablespaces will be te same as on source server, so for example, assuming you have tablespaces located in:

• /ts1

• /mnt/ssd/ts2

• /var/ts3

and PGDATA in /var/lib/pgsql/data, and you'll call omnipitr-synch with:

--output remote:/a/b/c

Then:

• content of /var/lib/pgsql/data (pgdata) will be delivered to remote:/a/b/c

• tablespace from /ts1 will be delivered to remote:/ts1

• tablespace from /mnt/ssd/ts2 will be delivered to remote:/mnt/ssd/ts2

• tablespace from /var/ts3 will be delivered to remote:/var/ts3

Since it might not always be desirable, omnipitr-synch supports the notion of maps. These are used to change tablespace output paths (not data dir, just tablespace paths).

--map option has following syntax:

--map from:to

for example:

--map /ts1:remote:/x/y/z

Above means that tablespace located in /ts1 directory locally will be delivered to directory /x/y/z on remote machine.

Map syntax assumes the given paths are prefixes. So, for example adding:

--map /:remote:/root/ --output remote:/a/b/c

would (in our example situation described above):

• deliver content of /var/lib/pgsql/data (pgdata) remote:/a/b/c

• deliver tablespace from /ts1 to remote:/root/ts1

• deliver tablespace from /mnt/ssd/ts2 to remote:/root/mnt/ssd/ts2

• deliver tablespace from /var/ts3 to remote:/root/var/ts3

If given tablespace is not matching any map rules, it will be delivered normally, like if no maps were provided.

Please note and understand that changing paths to PostgreSQL instance is not supported - the mapping process is only meant as a way to simplify transfer of data in specific cases where dba needs this modification to fit the data on disk.

Using it will not change PostgreSQL internal paths to use tablespaces in different locations.

EXAMPLES

Simplistic run, get data dir from Pg itself:

/.../omnipitr-synch -o remote:/pgdata

Automatic run, with tablespaces mapped to different delivery and logging

/.../omnipitr-synch -D /mnt/data/ -l "/var/log/omnipitr/synch-^Y-^m-^d.log" -a -o remote:/pgdata -m /:remote:/tablespaces/

Automatic run, with 2 destinations and compression:

/.../omnipitr-synch -a -o slave1:/pgdata -o slave2:/pgdata -c gzip

IMPORTANT NOTICES

• This program is dangerous - it will delete data on the destination server - you should be sure what you want to do not to delete important files.

COPYRIGHT

The OmniPITR project is Copyright (c) 2011-2012 OmniTI. All rights reserved.