Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

IPC::Session
Drive ssh or other interactive shell, local or remote

IPC::Session - Drive ssh or other interactive shell, local or remote


NAME

IPC::Session - Drive ssh or other interactive shell, local or remote (like 'expect')


SYNOPSIS


 use IPC::Session;

 # open ssh session to fred

 # -- set timeout of 30 seconds for all send() calls

 my $session = new IPC::Session("ssh fred",30);

 

 $session->send("hostname");  # run `hostname` command on fred

 print $session->stdout();  # prints "fred"

 $session->send("date");  # run `date` within same ssh

 print $session->stdout();  # prints date

 

 # use like 'expect':

 $session->send("uname -s");

 for ($session->stdout)

 {

        /IRIX/ && do { $netstat = "/usr/etc/netstat" };

        /ConvexOS/ && do { $netstat = "/usr/ucb/netstat" };

        /Linux/ && do { $netstat = "/bin/netstat" };

 }

 

 # errno returned in scalar context:

 $errno = $session->send("$netstat -rn");

 # try this:

 $session->send("grep '^$user:' /etc/passwd") 

         && warn "$user not there";

 

 # hash returned in array context:

 %netstat = $session->send("$netstat -in");

 print "$netstat{'stdout'}\n";  # prints interface table

 print "$netstat{'stderr'}\n";  # prints nothing (hopefully)

 print "$netstat{'errno'}\n";   # prints 0


DESCRIPTION

This module encapsulates the open3() function call (see the IPC::Open3 manpage) and its associated filehandles. This makes it easy to maintain multiple interactive command sessions, such as multiple persistent 'ssh' and/or 'rsh' sessions, within the same perl script.

The remote shell session is kept open for the life of the object; this avoids the overhead of repeatedly opening remote shells via multiple ssh or rsh calls. This persistence is particularly useful if you are using ssh for your remote shell invocation; it helps you overcome the high ssh startup time.

For applications requiring remote command invocation, this module provides functionality that is similar to 'expect' or Expect.pm, but in a lightweight more Perlish package, with discrete STDOUT, STDERR, and return code processing.

By the way, there's nothing inherently ssh-ish about IPC::Session -- it doesn't even know anything about ssh, as a matter of fact. It will work with any interactive shell that supports 'echo'. For instance, 'make test' just drives a local /bin/sh session.


METHODS

my $session = new IPC::Session(``ssh fred'',30);

The constructor accepts the command string to be used to open the remote shell session, such as ssh or rsh; it also accepts an optional timeout value, in seconds. It returns a reference to the unique session object.

If the timeout is not specified then it defaults to 60 seconds. The timeout value can also be changed later; see timeout().

$commandhandle = $session->send(``hostname'');

The send() method accepts a command string to be executed on the remote host. The command will be executed in the context of the default shell of the remote user (unless you start a different shell by sending the appropriate command...). All shell escapes, command line terminators, pipes, redirectors, etc. are legal and should work, though you of course will have to escape special characters that have meaning to Perl.

In a scalar context, this method returns the return code produced by the command string.

In an array context, this method returns a hash containing the return code as well as the full text of the command string's output from the STDOUT and STDERR file handles. The hash keys are 'stdout', 'stderr', and 'errno'.

print $session->stdout();

Returns the full STDOUT text generated from the last send() command string.

Also available via array context return codes -- see send().

print $session->stderr();

Returns the full STDERR text generated from the last send() command string.

Also available via array context return codes -- see send().

print $session->errno();

Returns the return code generated from the last send() command string.

Also available via array context return codes -- see send().

$session->timeout(90);

Allows you to change the timeout for subsequent send() calls.

The timeout value is in seconds. Fractional seconds are allowed. The timeout applies to all send() calls.

Returns the current timeout if called with no args.


BUGS/RESTRICTIONS

  • The remote shell command you specify in new() is assumed to not prompt for any passwords or present any challenge codes; i.e.; you must use .rhosts, authorized_keys, ssh-agent, or the equivalent, and must be prepared to answer any passphrase prompt if using ssh. You can either run ssh-add ahead of time and provide the passphrase, have your script do that itself, or simply set the passphrase to null (if your security model allows it).

  • There must be a working /bin/sh on the target machine.


AUTHOR


 Steve Traugott <stevegt@TerraLuna.Org>


SEE ALSO

the IPC::Open3 manpage, rsh(1), ssh(1), Expect, expect(1)

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy