NAME

Net::SSH::Expect - SSH wrapper to execute remote commands

SYNOPSIS

use Net::SSH::Expect;

# configures the ssh connection and authentication
my $ssh = Net::SSH::Expect->new (host => "myserver.com", password=> 'pass87word', user => 'bnegrao');

# establishes the ssh connection, 
# authenticating with that user and password
$ssh->connect();

# runs arbitrary commands
my $ls = $ssh->exec("ls -l /");
print($ls);

my $who = $ssh->exec("who");
print ($who);

# closes the ssh connection
$ssh->close();

DESCRIPTION

This module is a wrapper to the ssh executable that is available in your system's $PATH. Use this module to execute commands on the remote SSH server. It authenticates with the user and password you passed in the constructor's attributes user and password.

Once an ssh connection was started using the connect() method it will remain open until you call the close() method. This allows you execute how many commands you want with the exec() method using only one connection. This is a better approach over other ssh wrapper implementations, i.e: Net::SCP, Net::SSH and Net::SCP::Expect, that start a new ssh connection each time a remote command is issued or a file is transfered.

It uses Expect.pm module to interact with the SSH server. A get_expect() method is provided so you can obtain the internal Expect object connected to the SSH server. Use this only if you have some special need that you can't do with the exec() method.

This module was inspired by Net::SCP::Expect http://search.cpan.org/~djberg/Net-SCP-Expect-0.12/Expect.pm was designed to be its counterpart. Their API's are very similar, and sometimes identical. I'll refer to the documentation of Net::SCP::Expect anytime their functionality is the same.

EXPORT

None by default.

CONSTRUCTOR ATTRIBUTES

The constructor accepts all the following attributes that can be set in the form of attribute => 'value' pairs.

user

the username to login.

password

the password used to login.

host

the address(dns name/ip) to the ssh server

terminator

the line terminator in use on the SSH server, this will added at the end of each command passed to the exec() method. The default is \r.

verbose

Prints on the STDOUT all the conversation between this client and the SSH server. It also passes the option '-v' (verbose) to the wrapped ssh command, what will cause some ssh debugging messages to be displayed too. Useful for debugging.

timeout

The maximum time in seconds to wait for a command to return to the PROMPT. The default is 10 seconds. Remember to increase this attribute with the timeout() method before you run a command that takes a long time to return.

error_handler

TODO

cipher

TODO

port

alternate ssh port. default is 22.

protocol

TODO

identity_file

TODO

log_file

Path to a file to save all the ssh conversation. Default is no log file.

METHODS

connect() - establishes an ssh connection with the ssh server

params:

none

returns:

undef

dies:

IllegalState: if any of 'host' or 'user' or 'password' fields are unset.

RemotePromptUnavailable: if the prompt on the remote machine can't be obtained after establishing the ssh connection

SSHProccessError: if can't spawn the ssh process

SSHConnectionError: if the connection failed for some reason, like invalid 'host' address or network problems.

exec($remote_cmd [, $block]) - executes a command in the remote machine

params:

$remote_cmd: a string with the command line to be run in the remote server.

$block: 0 or 1. Blocks until remote_cmd returns. Default is 0.

0: does not block until prompt goes back, waiting util timeout seconds;

1: blocks waiting the prompt to return after running the $remote_cmd.

returns:

undef: if after running 'cmd_string' and waiting for 'timeout' seconds the prompt still didn't return. This can happen if 'cmd_string' takes a long time to conclude.

empty string: if the command sent doesn't have output.

string: a string containing all the output of the command ran. it can be a non readable character if this was the output. This can be memory intensive depending on the size of the output.

dies:

IllegalState: if this there is no valid ssh connection established

IllegalArgument: if no argument (no command string) is passed to this method.

RemotePromptUnavailable: if the prompt is not available for execution of $remote_cmd

close() - terminates the ssh connection

returns:

undef

get_expect() - returns a connected Expect object

params:

none

returns:

an Expect object connected to the SSH server. It will die if you try to run it without being connected.

dies:

IllegalState: if this there is no valid ssh connection established

Net::SCP::Expect, Net::SCP, Net::SSH::Perl, Expect

If you have a mailing list set up for your module, mention it here.

If you have a web site set up for your module, mention it here.

AUTHOR

Bruno Negrao Guimaraes Zica. <bnegrao@cpan.org>.

THANKS

Daniel Berger, author of Net::SCP::Expect

COPYRIGHT AND LICENSE

Copyright (C) 2007 by Bruno Negrao Guimaraes Zica

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.3 or, at your option, any later version of Perl 5 you may have available.