`'pipe'` documentation

Installation

Once downloaded (and — if needed — uncompressed), the plugin library needs to be copied to the Sybase server's bin-directory — right next to and with the same permissions as the libcompress.so (or libcompress.dll). That's all!

Synopsis

	isql> {DUMP|LOAD} DATABASE DBNAME {TO|FROM} 'pipe::[option]:argument'
		[STRIPE ON .......]

While we strive for 100% accuracy and correctness, bugs happen — in both the software itself and the documentation. You are expected to learn the use of our software in a test environment using discardable databases before moving on to production use. We can accept no responsibility for any destruction or data loss.

Description

The plugin allows to manipulate the backup data stream in a number of ways, depending on the options. By default (no options specified) the argument is treated as a command line. The command is then executed and the data is written to its stdin (in case of DUMP) or read from its stdout (in case of LOAD).

Supported options include:

> and <

Argument is simply a filename. Dumping with this > is equivalent to dumping with the Sybase-provided compress plugin and then uncompressing the result. Note, that this is not the same as dumping without any plugins (Sybase uses a different format in that case).

'pipe' makes no distinction between > and < options currently, but the users are expected to use > for DUMP and < for LOAD.

Rhostname

This Unix-only option treats argument as a command to be executed on hostname. 'pipe' will call rcmd(3) thus bypassing the minor overhead of rsh or ssh. For example, assuming you hold your backups on a computer named "pandora" in the directory /backups. The following command will create a dump compatible with the standard 'compress' plugin, but with the CPU-intesive compression running on pandora instead of your Sybase server:

	isql> DUMP DATABASE FOO TO 'pipe::Rpandora:gzip -9 > /backups/FOO.cmp'

On most Operating Systems rcmd() can only be invoked by the super user, which means, your entire backup server needs to run with elevated privileges — unless the DBA has root access anyway, this is not advisable.

You'll be fine with using rsh or ssh instead of this option:

	isql> DUMP DATABASE FOO TO 'pipe:::rsh pandora gzip -9 \> /backups/FOO.cmp'

Phost

Dump directly to a Port on the remote host (can be either name or an IP-address). The argument must be an integer port number. 'pipe' will try to establish a client-side connection. This option is heavily used by the sybdump utility as well as in manual database transfers between servers:

	isql> DUMP DATABASE FOO TO 'pipe::Ppandora:10123'

Obviously, something has to wait for the connection in the above example on pandora's port 10123, or the command will fail.

Shost

Await on the Server socket for a connection. The host (either name or an IP-address) specifies the interface to listen on. The argument may specify the range of the port numbers to try binding to. If not specified, 'pipe' will try from 1 to 65535.

This option can be used for transfering a database from one server to another directly (see examples on the top page). It can also be used to avoid the NFS issues by using something like nc to stream your backup directly to your Sybase server.

Here we tell the Sybase server to bind to a port:

	isql> LOAD DATABASE FOO FROM 'pipe::Smyhost1025'
	....
	AWAITING ON ip.add.re.ss:1137

And now we can stream our dump directly to the server:

	% gzcat /backups/FOO.cmp | nc -p 1137 ip.add.re.ss

Authentication and authorization

Whenever more than one computer is involved, the two auth usually come into play. Unfortunately, the plugin is non-interactive and can not prompt you for passwords. Please, refer to your Operating System manuals for information on how to enable password-less logins for whatever method you try to use to access a remote system (rcmd, rsh, ssh).

Make sure, the same account, which is running the backup server, can login to the remote system without being prompted for password.

Examples

Create a 'compress'-compatible dump and load it

While discussing the R-option we've already seen two ways of producing a 'compress'-compatible dump.

Here is how to load it (under the same assumptions):

	isql> LOAD DATABASE FOO FROM 'compress::/net/pandora/backups/FOO.cmp'

Count the bytes in the dump

This artificial example writes the size of the dump into a temporary file. It is intended to remind, that, literary, any command can be used:

	isql> DUMP DATABASE FOO TO 'pipe:::wc -b \> /tmp/FOO-size.txt'

'pipe' documentation