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);

# enables collection of the exit codes of the commands ran
$ssh->collect_exit_code(1);

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

# shows the exit code of the last command ran
if ($ssh->last_exit_code() == 0) {
	print ("Last command ran OK!\n");
} else {
	print ("Last command failed and exited " . $ssh->last_exit_code());
}

# 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

collect_exit_code

boolean 0 or 1: disable/enable collection of the exit code of the last command run by exec(). With this feature enabled exec() will run a "echo $?" on the SSH server to collect the exit code of the last command ran. The exit code of the last command run can be get with the last_exit_code() method. This feature is disabled by default.

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_ssh

This will pass 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.

CONSTRUCTOR OPTIONS THAT CONFIGURE THE INTERNAL EXPECT OBJECT

The following constructor attributes can be used to configure special features of the internal Expect object used to communicate with the ssh server. These options will be passed to the Expect object inside the connect method before it spawns the ssh process.

log_file

Used as argument to the internal Expect->log_file() method. Default is no logfile.

log_stdout

Used as argument to the internal Expect->log_sdtout() method. Default is 0, to disable log to stdout.

exp_internal

Argument to be passed to the internal Expect->exp_internal() method. Default is 0, to disable the internal exposure.

debug

Argument to be passed to the internal Expect->debug() method. Default is 0, to disable debug.

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

collect_exit_code( [0 or 1] ) get/set the collect_exit_code attribute.

params:

boolean 0 or 1: disable/enable collection of the exit code of the last command run by exec(). Default is 0 to disable this. The exit code of the last command run can be get with the last_exit_code() method.

none: changes nothing and returns the current setting.

returns:

boolean 0 or 1 : the current value of this setting. If you just set a new value, it'll return the new value.

last_exit_code - returns the exit code of the last command executed by exec().

returns:

integer: the exit code returned by the last command executed.

dies:

IllegalState: if collect_exit_code is not set to 1 or if collect_exit_code is enabled but this method was called before calling exec();

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. Special thanks to the people helping me to improve this module by reporting their tests and the bugs they find.

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.

cpanm Net::SSH::Expect

perl -MCPAN -e shell
install Net::SSH::Expect