NAME
IPC::PerlSSH - execute remote perl code over an SSH link
SYNOPSIS
use IPC::PerlSSH;
my $ips = IPC::PerlSSH->new( Host => "over.there" );
$ips->eval( "use POSIX qw( uname )" );
my @remote_uname = $ips->eval( "uname()" );
# We can pass arguments
$ips->eval( 'open FILE, ">", $_[0]; print FILE $_[1]; close FILE;',
"foo.txt", "Hello, world!" );
# We can pre-compile stored procedures
$ips->store( "get_file", 'local $/;
open FILE, "<", $_[0];
$_ = <FILE>;
close FILE;
return $_;' );
foreach my $file ( @files ) {
my $content = $ips->call( "get_file", $file );
...
}
# We can use existing libraries for remote stored procedures
$ips->use_library( "FS", qw( readfile ) );
foreach my $file ( @files ) {
my $content = $ips->call( "readfile", $file );
...
}
DESCRIPTION
This module provides an object class that provides a mechanism to
execute perl code in a remote instance of perl running on another host,
communicated via an SSH link or similar connection. Where it differs
from most other IPC modules is that no special software is required on
the remote end, other than the ability to run perl. In particular, it
is not required that the IPC::PerlSSH module is installed there. Nor
are any special administrative rights required; any account that has
shell access and can execute the perl binary on the remote host can use
this module.
Argument Passing
The arguments to, and return values from, remote code are always
transferred as lists of strings. This has the following effects on
various types of values:
* String values are passed as they stand.
* Booleans and integers will become stringified, but will work as
expected once they reach the other side of the connection.
* Floating-point numbers will get converted to a decimal notation,
which may lose precision.
* A single array of strings, or a single hash of string values, can
be passed by-value as a list, possibly after positional arguments:
$ips->store( 'foo', 'my ( $arg, @list ) = @_; ...' );
$ips->store( 'bar', 'my %opts = @_; ...' );
* No reference value, including IO handles, can be passed; instead it
will be stringified.
To pass or return a more complex structure, consider using a module
such as Storable, which can serialise the structure into a plain
string, to be deserialised on the remote end. Be aware however, that
Storable was only added to core in perl 5.7.3, so if the remote perl is
older, it may not be available.
To work with remote IO handles, see the IPC::PerlSSH::Library::IO
module.
CONSTRUCTORS
new (with Host)
$ips = IPC::PerlSSH->new( Host => $host, ... )
Returns a new instance of a IPC::PerlSSH object connected to the
specified host. The following arguments can be specified:
Host => STRING
Connect to a named host.
Port => INT
Optionally specify a non-default port.
Perl => STRING
Optionally pass in the path to the perl binary in the remote host.
User => STRING
Optionally pass in an alternative username
SshPath => STRING
Optionally specify a different path to the ssh binary
SshOptions => ARRAY
Optionally specify any other options to pass to the ssh binary, in an
ARRAY reference
new (with Command)
$ips = IPC::PerlSSH->new( Command => \@command, ... )
Returns a new instance of a IPC::PerlSSH object which uses the
STDIN/STDOUT streams of a command it executes, as the streams to
communicate with the remote perl.
Command => ARRAY
Specifies the command to execute
Command => STRING
Shorthand form for executing a single simple path
The Command key can be used to create an IPC::PerlSSH running perl
directly on the local machine, for example; so that the "remote" perl
is in fact running locally, but still in its own process.
my $ips = IPC::PerlSSH->new( Command => $^X );
new (with Readh + Writeh)
$ips = IPC::PerlSSH->new( Readh => $rd, Writeh => $wr )
Returns a new instance of a IPC::PerlSSH object using a given pair of
filehandles to read from and write to the remote perl process. It is
allowable for both filehandles to be the same - for example using a
socket.
new (with Readfunc + Writefunc)
$ips = IPC::PerlSSH->new( Readfunc => \&read, Writefunc => \&write )
Returns a new instance of a IPC::PerlSSH object using a given pair of
functions as read and write operators.
Usually this form won't be used in practice; it largely exists to
assist the test scripts. But since it works, it is included in the
interface in case the earlier alternatives are not suitable.
The functions are called as
$len = $Readfunc->( my $buffer, $maxlen );
$len = $Writewrite->( $buffer );
In each case, the returned value should be the number of bytes read or
written.
METHODS
eval
@result = $ips->eval( $code, @args )
This method evaluates code in the remote host, passing arguments and
returning the result.
The code should be passed in a string, and is evaluated using a string
eval in the remote host, in list context. If this method is called in
scalar context, then only the first element of the returned list is
returned.
If the remote code threw an exception, then this function propagates it
as a plain string. If the remote process exits before responding, this
will be propagated as an exception.
store
$ips->store( $name, $code )
$ips->store( %funcs )
This method sends code to the remote host to store in named
procedure(s) which can be executed later. The code should be passed in
strings.
While the code is not executed, it will still be compiled into CODE
references in the remote host. Any compile errors that occur will be
throw as exceptions by this method.
Multiple functions may be passed in a hash, to reduce the number of
network roundtrips, which may help latency.
bind
$ips->bind( $name, $code )
This method is identical to the store method, except that the remote
function will be available as a plain function within the local perl
program, as a function of the given name in the caller's package.
call
@result = $ips->call( $name, @args )
This method invokes a remote method that has earlier been defined using
the store or bind methods. The arguments are passed and the result is
returned in the same way as with the eval method.
If an exception occurs during execution, it is propagated and thrown by
this method. If the remote process exits before responding, this will
be propagated as an exception.
use_library
$ips->use_library( $library, @funcs )
This method loads a library of code from a module, and stores them to
the remote perl by calling store on each one. The $library name may be
a full class name, or a name within the IPC::PerlSSH::Library:: space.
If the @funcs list is non-empty, then only those named functions are
stored (analogous to the use perl statement). This may be useful in
large libraries that define many functions, only a few of which are
actually used.
For more information, see IPC::PerlSSH::Library.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>