NAME

POE::Component::Generic::Net::SSH2 - A POE component that provides non-blocking access to Net::SSH2

SYNOPSIS

    use POE::Component::Generic::Net::SSH2;

    my $ssh = POE::Component::Generic::Net::SSH2->spawn( 
                    alias   => 'my-ssh',
                    verbose => 1,
                    debug   => 0 );

    my $channel;

    POE::Session->create( 
        inline_states => {
            _start => sub {
                $poe_kernel->delay( 'connect', $N );
            },

            connect => sub {
                $ssh->connect( {event=>'connected'}, $HOST, $PORT );
            },
            connected => sub {
                $ssh->auth_password( {event=>'login'}, $USER, $PASSWORD );
            },
            error => sub {
                my( $resp, $code, $name, $error ) = @_[ARG0, $#_];
                die "Error $name ($code) $error";
            },

            login => sub {
                my( $resp, $OK ) = @_[ARG0..$#_];
                unless( $OK ) {
                    $ssh->error( {event=>'error', wantarray=>1} );
                    return;
                }

                $poe_kernel->yield( 'cmd_do' );
            },

            ################
            cmd_do => sub {
                $ssh->cmd( { event=>'cmd_output', wantarray=>1 }, "ls -l" );
                return;
            },
            cmd_output => sub {
                my( $resp, $stdout, $stderr ) = @_[ARG0..$#_];
                warn "Contents of home directory on $HOST:\n$stdout\n";


                $poe_kernel->yield( 'exec_do' );
            },

            exec_do => sub {
                 
                $ssh->exec( { event=>'exec_running', wantarray=>0 }, 
                                "cat - >$FILE", 
                                StdoutEvent => 'exec_stdout', 
                                StderrEvent => 'exec_stderr', 
                                ClosedEvent => 'exec_closed', 
                                ErrorEvent  => 'exec_error' 
                          );
            },
            exec_running => sub {
                my( $resp, $ch ) = @_[ARG0..$#_];
                # keep channel alive
                $channel = $ch;
                $channel->write( {}, "$$-CONTENTS OF THE FILE\n" );
                $channel->send_eof( {event=>'done'} );
            },

            done => sub {
                undef( $channel );
                $ssh->shutdown;
            }

            exec_error => sub {
                my( $code, $name, $string ) = @_[ARG0..$#_];
                die "ERROR: $name $string";
            },        
            exec_stderr => sub {
                my( $text, $bytes ) = @_[ARG0..$#_];
                die "STDERR: $text";
                return;
            },
            exec_stdout => sub {
                my( $text, $bytes ) = @_[ARG0..$#_];
                warn "STDOUT: $text";
                return;
            },
            exec_closed => sub {
                undef( $channel );
                $ssh->shutdown;
            },
        }
    );

DESCRIPTION

POE::Component::Generic::Net::SSH2 is a component for handling SSH2 connections from POE. It uses POE::Component::Generic to wrap Net::SSH2 into a non-blocking framework.

This component demonstrates many tricks that you might find useful when you build your own components based on POE::Component::Generic.

It is still ALPHA quality. Missing are scp, sftp support and better error handling.

Patches welcome.

METHODS

spawn

Net::SSH2 METHODS

POE::Component::Generic::Net::SSH2 supports most Net::SSH2 method calls using POE::Component::Generic's interface. The following additional methods are added for better POE support.

cmd

    $ssh->cmd( $data_hash, $command, $input );

Ultra-simple command execution. Runs $command in a new channel on the remote host. $input is then feed to it (NOT YET!). All output is accumulated until the command exits, then is sent to the response event as ARG1 (STDOUT) and ARG2 (STDERR).

exec

    $ssh->exec( $data_hash, $command, %events );

Runs $command in a new channel on the remote host. The response event will receive an SSH channel that it may use to write to or read from.

%events is a hash that may contain the following keys:

StdoutEvent

StderrEvent

Called when $command writes to STDOUT or STDERR, respectively, with 2 arguments: ARG0 is the data, ARG1 is the number of bytes.

ErrorEvent

Called when there is an SSH error. The documentation for libssh2 is piss-poor, so I'm not really sure what these could be, nor how to detect them all. Arguments are the same as Net::SSH2/error: ARG0 is error number, ARG1 is error name and ARG2 is the error string.

ClosedEvent

Called when the we encounter an SSH eof on the channel, which normaly corresponds to when $command exits.

No arguments.

Net::SSH2::Channel METHODS

A channel is a conduit by which SSH communicates to a sub-process on the remote side. Each command, shell or sub-system uses its own channel. A channel may only run one command, shell or sub-system.

Channels are created with the channel factory method:

    $ssh->channel( {event=>'got_channel'} );

    # Your got_channel event
    sub got_channel {
        my( $heap, $resp, $channel ) = @_[HEAP, ARG0, ARG1];
        die $resp->{error} if $resp->{error};

        $heap->{channel} = $channel;
    }

You may call most Net::SSH2::Channel methods on a channel using the normal POE::Component::Generic calling conventions.

    $heap->{channel}->write( {}, $string );

Channels are closed when you drop all references to the object.

    delete $heap->{channel};

There are some extensions to the channel interface:

cmd

    $heap->{channel}->cmd( {event=>'cmd_response'}, $command, $input );

Runs $command on the channel. Response event receives 2 arguments: ARG1 is the commands output to STDOUT, ARG2 is the commands output to STDERR.

If you do not set wantarray to 1, you will only receive STDOUT.

handler_stdout

handler_stderr

Registers a postback that is posted when the data is present on STDOUT (called 'in' in libssh2) or STDERR (called 'ext' in libssh2) respectively.

These could be used when you call "exec" in Net::SSH2::Channel on a channel.

handler_closed

Registers a postback that is posted when the channel closes, which normaly happens when the command has finished.

These could be used when you call "exec" in Net::SSH2::Channel on a channel.

AUTHOR

Philip Gwyn <gwyn-at-cpan.org>

SEE ALSO

POE, Net::SSH2, POE::Component::Generic.

RATING

Please rate this module. http://cpanratings.perl.org/rate/?distribution=POE-Component-Generic

BUGS

Probably. Report them here: http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE%3A%3AComponent%3A%3AGeneric

COPYRIGHT AND LICENSE

Copyright 2006, 2011 by Philip Gwyn.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm POE::Component::Generic

perl -MCPAN -e shell
install POE::Component::Generic