view release on metacpan or  search on metacpan

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

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.01

=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:

=over 4

=item

Persistent terminal via expect for very fast execution, less forking.

=item

Usage of File::Temp and auto-cleanup to prevent lingering ctl_path cruft.

=item

Ability to manipulate incoming text while streaming the output of commands.

=item

Run perl subroutine refs you write locally but execute remotely.

=item

Many shortcut methods for common system administration tasks

=item

Registration method for commands to run upon DESTROY/before disconnect.

=item

Automatic reconnection ability upon connection loss

=back

=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:

=over 4

=item

%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:

=over 4

=item

use_persistent_shell - Whether or not to setup Expect to watch a persistent TTY. Less stable, but faster.

=item

expect_timeout - When the above is active, how long should we wait before your program prints something
before bailing out?

=item

no_agent - Pass in a truthy value to disable the SSH agent. By default the agent is enabled.

=item

die_on_drop - If, for some reason, the connection drops, just die instead of attempting reconnection.

=item

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.

=item

debug - Pass in a truthy value to enable certain diag statements I've added in the module and pass -v to ssh.

=item

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.

=item

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.

=item

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.
your situation requires longer intervals, pass in something longer.

=item

retry_max - Number of times to retry when a connection fails. Defaults to 10.

=back

=back

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_ed25519, id_ecdsa, id_rsa and id_dsa (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.)