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

Please see docs in Net::SCP::Expect to know how this option works.

cipher

Please see docs in Net::SCP::Expect to know how this option works.

port

alternate ssh port. default is 22.

protocol

Please see docs in Net::SCP::Expect to know how this option works.

identity_file

Please see docs in Net::SCP::Expect to know how this option works.

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

This method will use the values set in user and password to authenticate to the SSH server identified by host.

If it connects and authenticates successfully its first step will be trying to set the prompt in the remote machine to 'SSH_PROMPT>> ' by sending a command that changes the value of the $PS1 environment variable, what should replace the unknown remote prompt to this well know string.

connect() only returns after it sets the remote prompt successfully, it will die otherwise.

Setting the remote prompt to this constant, well-known string is important to the functioning of exec(). That method will know that the command it ran finished the execution when it sees the prompt string, 'SSH_PROMPT>> ', appearing again.

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

This method will try to execute the $remote_cmd on the SSH server and return the command's output. exec() knows that $remote_cmd finished its execution on the remote machine when the remote prompt string is received after the command was sent.

See connect() to read info on what the remote prompt string looks like.

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

SEE ALSO

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

REPORT YOUR TESTS TO ME, PLEASE

Please email me if you had problems of successes using my module. This way I can, one day, flag this module as "mature" in the modules database.

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.