NAME Rexec.pm

Execute commands remotely and returning the output and status of the remotely executed command.

VERSION

Andrew DeFaria <Andrew@ClearSCM.com>

Revision:

Revision 1.21

Created:

Mon Oct 9 18:28:28 CDT 2006

Modified:

Modifed 2012/04/07 00:39:48

SYNOPSIS

  use Rexec;

  my $status;
  my $cmd;
  my @lines;

  my $remote = new Rexec (host => $host);

  if ($remote) {
    print "Connected using " . $remote->{protocol} . " protocol\n";

    $cmd = "ls /tmp";
    @lines = $remote->execute ($cmd);
    $status = $remote->status;
    print "$cmd status: $status\n";
    $remote->print_lines;

    print "$_\n" foreach ($remote->execute ("cat /etc/passwd"));
  } else {
    print "Unable to connect to $username\@$host\n";
  } # if

DESCRIPTION

This module provides an object oriented interface to executing remote commands on Linux/Unix system (or potentially well configured Windows machines with Cygwin installed). Upon object creation a connection is attempted to the specified host in a cascaded fashion. First ssh is attempted, then rsh/rlogin and finally telnet. This clearly favors secure methods over those less secure ones. If username or password is prompted for, and if they are supplied, then they are used, otherwise the attempted connection is considered failed.

Once connected the caller can use the exec method to execute commands on the remote host. Upon object destruction the connection is shutdown. Output from the remotely executed command is returned through the exec method and also avaiable view the lines method. Remote status is available via the status method. This means you can now more reliably obtain the status of the command executed remotely instead of just the status of the ssh/rsh command itself.

Note: Currently no attempt has been made to differentiate output written to stdout and stderr.

As Expect is used to drive the remote session particular attention should be defining a regex to locate the prompt. The standard prompt regex (if not specified by the caller at object creation) is

qr'[#>:$](\s*|\e.+)$'.

This covers most default and common prompts.

Handling Timeouts

The tricky thing when dealing with remote execution is attempting to determine if the remote machine has finished, stopped responding or otherwise crashed. It's more of an art than a science! The best one can do it send the command along and wait for a response. But how long to wait is the question. If your wait is too short then you run the risk of timing out before the remote command is finished. If you wait too long then you can be possibly waiting for something that will not be happening because the remote machine is either down or did not behave in a manner that you expected it to.

To a large extent this module attempts to mitigate these issues on the principal that remote command execution is pretty well known. You log in and get a prompt. Issue a command and get another prompt. If the prompts are well known and easily determinable things go smoothly. However what happens if you execute a command remotely that will take 30 minutes to finish?

This module has two timeout values. The first is login timeout. It's assumed that logins should happen fairly quickly. The default timeout for logins is 5 seconds.

Command timeouts are set by default to 30 seconds. Most commands will finish before then. If you expect a command to take much longer then you can set an alternate timeout period.

You can achieve longer timeouts in several ways. To give a longer login timeout specify your timeout to the new call. To give a longer exec timeout either pass a longer timeout to exec or set it view setTimeout. The current exec timeout is returned by getTimeout.

METHODS

The following routines are exported:

login

Performs a login on the remote host. Normally this is done during construction but this method allows you to login, say again, as maybe another user...

Parameters:

None

Returns:

Nothing

logoff

Performs a logout on the remote host. Normally handled in the destructor but you could call logout to logout if you wish.

Parameters:

None

Returns:

Nothing

new (<parms>)

This method instantiates a new Rexec object. Currently only hash style parameter passing is supported.

Parameters:

host => <host>:

Specifies the host to connect to. Default: localhost

username => <username>

Specifies the username to use if prompted. Default: No username specified.

password => <password>

Specifies the password to use if prompted. Default: No password specified. Note passwords must be in cleartext at this time. Specifying them makes you insecure!

prompt => <prompt regex>

Specifies a regex describing how to identify a prompt. Default: qr'[#>:$](\s*|\e.+)$'

protocol => <ssh|rsh|rlogin|telnet>

Specifies the protocol to use when connecting. Default: Try them all starting with ssh.

opts => <options>

Additional options for protocol (e.g. -X for ssh and X forwarding)

verbose => <0|1>

If true then status messages are echoed to stdout. Default: 0.

Returns:

Rexec object

exec ($cmd, $timeout)

This method executes a command on the remote host returning an array of lines that the command produced, if any. Status of the command is stored in the object and accessible via the status method.

Parameters:

$cmd:

Command to execute remotely

$timeout

Set timeout for this execution. If timeout is 0 then wait forever. If you wish to interrupt this then set up a signal handler.

Returns:

@lines

An array of lines from STDOUT of the command. If STDERR is also wanted then add STDERR redirection to $cmd. Exit status is not returned by retained in the object. Use status method to retrieve it.

abortCmd

Aborts the current command by sending a Control-C (assumed to be the interrupt character).

Parameters:

None

Returns:

$status

1 if abort was successful (we got a command prompt back) or 0 if it was not.

status

Returns the status of the last command executed remotely.

Parameters:

None

Returns:

$status

Last status from exec.

shellstyle

Returns the shellstyle

Parameters:

None

Returns:

"sh"|"csh"

sh: Bourne or csh: for csh style shells

lines

Returns the lines array from the last command called by exec.

Parameters:

None

Returns:

@lines

An array of lines from the last call to exec.

print_lines

Essentially prints the lines array to stdout

Parameters:

None

Returns:

Nothing

host

Returns the host from the object.

Parameters:

None

Returns:

$hostname

getTimeout

Returns the timeout from the object.

Parameters:

None

Returns:

$timeout

setTimeout ($timeout)

Sets the timeout value for subsequent execution.

Parameters:

$timeout

New timeout value to set

Returns:

$timeout

Old timeout value

DIAGNOSTICS

Errors

If verbose is turned on then connections or failure to connect will be echoed to stdout.

Error text

  <host> is not responding to <protocol>
  Connected to <host> using <protocol> protocol
  Unable to connect to <host> using <protocol> protocol

Warnings

Specifying cleartext passwords is not recommended for obvious security concerns.

CONFIGURATION AND ENVIRONMENT

Configuration files and environment variables.

None

DEPENDENCIES

Perl Modules

ClearSCM Perl Modules

Display

INCOMPATABILITIES

None yet...

BUGS AND LIMITATIONS

There are no known bugs in this module.

Please report problems to Andrew DeFaria <Andrew@ClearSCM.com>.

LICENSE AND COPYRIGHT

This Perl Module is freely available; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This Perl Module is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License (http://www.gnu.org/copyleft/gpl.html) for more details.

You should have received a copy of the GNU General Public License along with this Perl Module; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. reserved.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 10:

=over should be: '=over' or '=over positive_number'

You can't have =items (as at line 15) unless the first thing after the =over is an =item