view release on metacpan or  search on metacpan

lib/Net/OpenSSH/More.pm  view on Meta::CPAN

    my $result = { error => "Unable to deserialize output from remote_eval: $output" };
    if ( $output =~ /\d+START_STORABLE(.*)STOP_STORABLE\d+/ ) {
        $result = Storable::thaw( pack( "H*", $1 ) );
    }

    die $result->{error} if ( $result->{error} );

    return wantarray ? @{ $result->{data} } : $result->{data}[0];
}


sub cmd_stream {
    my ( $self, @cmd ) = @_;
    my $line_reader = sub {
        my ( $self, $out, $stash_param ) = @_;
        $out =~ s/[\r\n]{1,2}$//;
        $self->diag($out);
        $self->{$stash_param} .= "$out\n";

        return;
    };
    return $send->( $self, $line_reader, @cmd );
}


1;

__END__

=pod

=encoding UTF-8

=head1 NAME

Net::OpenSSH::More - Net::OpenSSH submodule with many useful features

=head1 VERSION

version 1.00

=head1 SYNOPSIS

    use Net::OpenSSH::More;
    my $ssh = Net::OpenSSH::More->new(
		'host'     => 'some.host.test',
		'port'     => 69420,
        'user'     => 'azurediamond',
        'password' => 'hunter2',
    );
    ...

=head1 DESCRIPTION

Submodule of Net::OpenSSH that contains many methods that were
otherwise left "as an exercise to the reader" in the parent module.
Highlights:
* Persistent terminal via expect for very fast execution, less forking.
* Usage of File::Temp and auto-cleanup to prevent lingering ctl_path cruft.
* Ability to manipulate incoming text while streaming the output of commands.
* Run perl subroutine refs you write locally but execute remotely.
* Many shortcut methods for common system administration tasks
* Registration method for commands to run upon DESTROY/before disconnect.
* Automatic reconnection ability upon connection loss

=head1 NAME

Net::OpenSSH::More

=head1 METHODS

=head2 new

Instantiate the object, establish the connection. Note here that I'm not allowing
a connection string like the parent module, and instead exploding these out into
opts to pass to the constructor. This is because we want to index certain things
under the hood by user, etc. and I *do not* want to use a regexp to pick out
your username, host, port, etc. when this problem is solved much more easily
by forcing that separation on the caller's end.

ACCEPTS:
* %opts - <HASH> A hash of key value pairs corresponding to the what you would normally pass in to Net::OpenSSH,
  along with the following keys:
  * use_persistent_shell - Whether or not to setup Expect to watch a persistent TTY. Less stable, but faster.
  * expect_timeout - When the above is active, how long should we wait before your program prints something
    before bailing out?
  * no_agent - Pass in a truthy value to disable the SSH agent. By default the agent is enabled.
  * die_on_drop - If, for some reason, the connection drops, just die instead of attempting reconnection.
  * output_prefix - If given, is what we will tack onto the beginning of any output via diag method.
    useful for streaming output to say, a TAP consumer (test) via passing in '# ' as prefix.
  * debug - Pass in a truthy value to enable certain diag statements I've added in the module and pass -v to ssh.
  * home - STRING corresponding to an absolute path to something that "looks like" a homedir. Defaults to the user's homedir.
    useful in cases where you say, want to load SSH keys from a different path without changing assumptions about where
    keys exist in a homedir on your average OpenSSH using system.
  * no_cache - Pass in a truthy value to disable caching the connection and object, indexed by host string.
    useful if for some reason you need many separate connections to test something. Make sure your MAX_SESSIONS is set sanely
    in sshd_config if you use this extensively.
  * retry_interval - In the case that sshd is not up on the remote host, how long to wait while before reattempting connection.
    defaults to 6s. We retry $RETRY_MAX times, so this means waiting a little over a minute for SSH to come up by default.
	If your situation requires longer intervals, pass in something longer.
  * retry_max - Number of times to retry when a connection fails. Defaults to 10.

RETURNS a Net::OpenSSH::More object.

=head3 A note on Authentication order

We attempt to authenticate using the following details, and in this order:
1) Use supplied key_path.
2) Use supplied password.
3) Use existing SSH agent (SSH_AUTH_SOCK environment variable)
4) Use keys that may exist in $HOME/.ssh - id_rsa, id_dsa and id_ecdsa (in that order).

If all methods therein fail, we will die, as nothing will likely work at that point.
It is important to be aware of this if your remove host has something like fail2ban or cPHulkd
enabled which monitors and blocks access based on failed login attempts. If this is you,
ensure that you have not configured things in a way as to accidentally lock yourself out
of the remote host just because you fatfingered a connection detail in the constructor.

=head2 use_persistent_shell

Pass "defined but falsy/truthy" to this to enable using the persistent shell or deactivate its' use.
Returns either the value you just set or the value it last had (if arg is not defined).

=head2 copy

Copies $SOURCE file on the remote machine to $DEST on the remote machine.
If you want to sync/copy files from remote to local or vice/versa, use
the sftp accessor (Net::SFTP::Foreign) instead.

Dies in this module, as this varies on different platforms (GNU/LINUX, Windows, etc.)

=head2 B<backup_files (FILES)>

Backs up files which you wish to later restore to their original state. If the file does
not currently exist then the method will still store a reference for later file deletion.
This may seem strange at first, but think of it in the context of preserving 'state' before
a test or scripted action is run. If no file existed prior to action, the way to restore
that state would be to delete the added file(s).

NOTE: Since copying files on the remote system to another location on the remote system
is in fact not something implemented by Net::SFTP::Foreign, this is necessarily going
to be a "non-portable" method -- use the Linux.pm subclass of this if you want to be able
to actually backup files without dying, or subclass your own for Windows, however they
choose to implement `copy` with their newfangled(?) SSH daemon.

C<FILES> - LIST - File(s) to backup.

C<STASH> - BOOL - mv files on backup instead of cp.  This will make sure FILES arg path no
                  longer exists at all so a fresh FILE can be written during run.