Net::SSH::Expect - SSH wrapper to execute remote commands
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();
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.
user
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.
connect()
close()
exec()
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.
get_expect()
Expect
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.
None by default.
The constructor accepts all the following attributes that can be set in the form of attribute => 'value' pairs.
the username to login.
the password used to login.
the address(dns name/ip) to the ssh server
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.
last_exit_code()
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.
\r
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.
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.
timeout()
Please see docs in Net::SCP::Expect to know how this option works.
alternate ssh port. default is 22.
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.
connect
Used as argument to the internal Expect->log_file() method. Default is no logfile.
Used as argument to the internal Expect->log_sdtout() method. Default is 0, to disable log to stdout.
Argument to be passed to the internal Expect->exp_internal() method. Default is 0, to disable the internal exposure.
Argument to be passed to the internal Expect->debug() method. Default is 0, to disable debug.
This method will use the values set in user and password to authenticate to the SSH server identified by host.
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.
none
undef
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.
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.
$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;
timeout
1: blocks waiting the prompt to return after running the $remote_cmd.
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.
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.
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.
boolean 0 or 1 : the current value of this setting. If you just set a new value, it'll return the new value.
integer: the exit code returned by the last command executed.
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();
collect_exit_code
an Expect object connected to the SSH server. It will die if you try to run it without being connected.
IllegalState: if this there is no valid ssh connection established
Net::SCP::Expect, Net::SCP, Net::SSH::Perl, Expect
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.
Bruno Negrao Guimaraes Zica. <bnegrao@cpan.org>.
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 (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.
3 POD Errors
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head2'
'=item' outside of any '=over'
You forgot a '=back' before '=head1'
To install Net::SSH::Expect, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::SSH::Expect
CPAN shell
perl -MCPAN -e shell install Net::SSH::Expect
For more information on module installation, please visit the detailed CPAN module installation guide.