NAME
    POE::Component::OpenSSH - Nonblocking SSH Component for POE using
    Net::OpenSSH

VERSION
    Version 0.03

SYNOPSIS
    Need nonblocking SSH? You like Net::OpenSSH? Try out this stuff right
    here.

        use POE::Component::OpenSSH;

        my $ssh = POE::Component::OpenSSH->new( args => [ $host, user => $user ] );
        $ssh->obj->system( { event => 'read_system_output' }, 'w' );

    Perhaps you want it with debugging and verbose of
    POE::Component::Generic

        my $ssh = POE::Component::OpenSSH->new(
            args    => [ 'root@host', passwd => $pass ],
            verbose => 1, # turns on POE::Component::Generic verbose
            debug   => 1, # turns on POE::Component::Generic debug
        );

    What about setting timeout for Net::OpenSSH?

        my $ssh = POE::Component::OpenSSH->new(
            args => [ 'root@host', passwd => $pass, timeout => 10 ],
        );

    Here is an example using MooseX::POE:

    (If you know <POE::Session>, you can use that too)

        package Runner;

        use MooseX::POE;

        has 'host' => ( is => 'ro', isa => 'Str', default => 'localhost' );
        has 'user' => ( is => 'ro', isa => 'Str', default => 'root'      );
        has 'pass' => ( is => 'ro', isa => 'Str', default => 'psss'      );
        has 'cmd'  => ( is => 'ro', isa => 'Str', default => 'w'         );

        sub START {
            my $self = $_[OBJECT];
            my $ssh  = POE::Component::OpenSSH->new(
                args => [
                    $self->host,
                    user   => $self->user,
                    passwd => $self->passwd,
                ],
            );

            # remember, $ssh is just POE::Component::OpenSSH
            # you want the Net::OpenSSH object (or psuedo-object)
            $ssh->obj->capture( { event => 'parse_cmd' }, $cmd );
        }

        event 'parse_cmd' => sub {
            my ( $self, $output ) @_[ OBJECT, ARG1 ];
            my $host = $self->host;
            print "[$host]: $output";
        };

        package main;

        use POE::Kernel;

        my @machines = ( qw( server1 server2 server3 ) );

        foreach my $machine (@machines) {
            Runner->new(
                host => $machine,
                pass => 'my_super_pass',
                cmd  => 'uname -a',
            );
        }

        POE::Kernel->run();

DESCRIPTION
    This module allows you to use SSH (via Net::OpenSSH) in a nonblocking
    manner.

    I kept having to write this small thing each time I needed nonblocking
    SSH in a project. I got tired of it so I wrote this instead.

    You might ask 'why put the args in an "args" attribute instead of
    straight away attributes?' Because Net::OpenSSH has a lot of options and
    they may collide with POE::Component::Generic's options and I don't feel
    like maintaining the mess.

    It's on Github so you can patch it up if you want (I accept patches...
    and foodstamps).

METHODS
  new
    Creates a new POE::Component::OpenSSH object. If you want to access the
    Net::OpenSSH check *obj* below.

    You should note this object is simply a component, you're still required
    to put it in a POE::Session. The examples use MooseX::POE which does the
    same thing.

  obj
    This method access the actual Net::OpenSSH object. It is wrapped with
    POE::Component::Generic, so the first argument is actually a hashref
    that POE::Component::Generic requires. Specifically, noting which event
    will handle the return of the Net::OpenSSH method.

    For example:

        $ssh->obj->capture( { event => 'handle_capture' }, 'echo yo yo' );

  args
    These are the arguments that will go to Net::OpenSSH creation. This is
    an arrayref.

    For example:

        # using user@host
        my $ssh = POE::Component::OpenSSH->new( args => [ 'root@remote_host' ] );

        # using separate arguments
        my $ssh = POE::Component::OpenSSH->new( args => [ 'remote_host, user => 'root' ] );

        # same thing, just with pass, and writing it nicer
        my $ssh = POE::Component::OpenSSH->new(
            args => [
                'remote_host',
                user   => 'root',
                passwd => $pass,
            ],
        );

AUTHOR
    Sawyer X, "<xsawyerx at cpan.org>"

BUGS
    Please report any bugs or feature requests to "bug-poe-component-openssh
    at rt.cpan.org", or through the web interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-OpenSSH>.
    I will be notified, and then you'll automatically be notified of
    progress on your bug as I make changes.

    Also available is the Github's issue tracker at
    <http://github.com/xsawyerx/poe-component-openssh/issues>.

SUPPORT
    You can find documentation for this module with the perldoc command.

        perldoc POE::Component::OpenSSH

    You can also look for information at:

    *   RT: CPAN's request tracker

        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-OpenSSH>

    *   Github issue tracker

        <http://github.com/xsawyerx/poe-component-openssh/issues>

    *   Github page

        <http://github.com/xsawyerx/poe-component-openssh/tree/master>

    *   AnnoCPAN: Annotated CPAN documentation

        <http://annocpan.org/dist/POE-Component-OpenSSH>

    *   CPAN Ratings

        <http://cpanratings.perl.org/d/POE-Component-OpenSSH>

    *   Search CPAN

        <http://search.cpan.org/dist/POE-Component-OpenSSH/>

SEE ALSO
    If you have no idea what I'm doing (but you generally know what POE is),
    check these stuff:

    POE::Component::Generic

    Net::OpenSSH

    If you don't know POE at all, check POE.

DEPENDENCIES
    Net::OpenSSH

    POE

    POE::Component::Generic

    Moose

ACKNOWLEDGEMENTS
    All the people involved in the aforementioned projects and the Perl
    community.

COPYRIGHT & LICENSE
    Copyright 2009 Sawyer X, all rights reserved.

    This program is free software; you can redistribute it and/or modify it
    under the terms of either: the GNU General Public License as published
    by the Free Software Foundation; or the Artistic License.

    See http://dev.perl.org/licenses/ for more information.