IPC::PerlSSH - a class for executing remote perl code over an SSH link
IPC::PerlSSH
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.
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, ">", shift; print FILE shift; close FILE;", "foo.txt", "Hello, world!" ); # We can pre-compile stored procedures $ips->store( "get_file", "local $/; open FILE, "<", shift; $_ = <FILE>; close FILE; return $_;" ); foreach my $file ( @files ) { my $content = $ips->call( "get_file", $file ); ... }
This function returns a new instance of a IPC::PerlSSH object. The connection can be specified in one of three ways, given in the @args list:
@args
Connecting to a named host.
Host => $hostname
Optionally passing in the path to the perl binary in the remote host
Perl => $perl
Running a specified command, connecting to its standard input and output.
Command => $command
Or
Command => [ $command, @args ]
Using a given pair of functions as read and write operators.
Readfunc => \&read, Writefunc => \&write
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.
In this case, the write functions are called as
read( my $buffer, undef ); # read a line, like <$handle> read( my $buffer, $len ); # read a fixed-length buffer write( $buffer );
In each case, the returned value should be the number of bytes read or written.
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. Only string scalar values are supported in either the arguments or the return values; no deeply-nested structures can be passed.
eval
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.
If the remote code threw an exception, then this function propagates it as a plain string.
This method sends code to the remote host to store in a named procedure which can be executed later. The code should be passed in a string, along with a name which can later be called by the call method.
call
While the code is not executed, it will still be compiled into a CODE reference in the remote host. Any compile errors that occur will be throw as exceptions by this method.
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.
store
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.
bind
If an exception occurs during execution, it is propagated and thrown by this method.
Paul Evans <leonerd@leonerd.org.uk>
To install IPC::PerlSSH, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IPC::PerlSSH
CPAN shell
perl -MCPAN -e shell install IPC::PerlSSH
For more information on module installation, please visit the detailed CPAN module installation guide.