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

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>

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

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