Greg Sabino Mullane > Net-SSH-Perl-1.34 > Net::SSH::Perl::Subsystem::Server

Download:
Net-SSH-Perl-1.34.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

New  23
Open  21
Stalled  1
View/Report Bugs
Source   Latest Release: Net-SSH-Perl-1.38

NAME ^

Net::SSH::Perl::Subsystem::Server - Server infrastructure for SSH subsystems

SYNOPSIS ^

    use Net::SSH::Perl::Subsystem::Server;
    use base qw( Net::SSH::Perl::Subsystem::Server );

    use constant MSG_FOO => 1;

    sub init {
        my $ss = shift;
        $ss->SUPER::init(@_);

        $ss->register_handler(MSG_FOO, \&handle_foo);
    }

    sub handle_foo {
        my $ss = shift;
        my($msg) = @_;
        print "Got MSG_FOO message!\n";
    }

DESCRIPTION ^

Net::SSH::Perl::Subsystem::Server is a generic subclass that can be used to build servers for SSH-2 subsystems. A subsystem is a network protocol that runs on top of a secure, encrypted SSH connection between two machines: it allows the user and developer to build a secure network protocol without worrying about the details of that security, because it inherits the secure tunnel from SSH.

Subsystem::Server provides basic functionality needed by all subsystem servers. A subsystem daemon is started up by the sshd when a request comes in for that subsystem; sshd and the subsystem daemon then talk to each other through pipes, and data that the daemon wishes to send to the subsystem client is sent over the network through the SSH secure tunnel. Subsystem::Server handles the talking to the sshd, and lets the application developer focus on designing the network protocol and handling requests from the subsystem client.

USAGE ^

Net::SSH::Perl::Subsystem::Server is meant to be used as a base class for subsystem servers. With that in mind, general usage should follow the example above in the SYNOPSIS:

These are the public methods in which your subclass will be most interested:

$ss->init(%args)

Initializes the subsystem server object. This is where you'll want to set up your message handlers (using register_handler) and perhaps perform any other protocol-specific initialization.

Make sure that your init method returns the $ss object on success; failure to return init should be an indication of failure to calling code.

%args can contain whatever you like it to contain. The base class Net::SSH::Perl::Subsystem::Server takes these parameters in %args:

$ss->register_handler($type, $code)

Configures the subsystem server $ss such that any message sent from the client whose type is $type will automatically invoke the subroutine reference $code. This is how you build protocol-specific functionality into your subsystem: you associate message types with methods.

The subroutine reference $code will be invoked and given two arguments: $ss, the instance of the subsystem server that is blessed into your subclass, and $msg, a buffer in the class Net::SSH::Perl::Buffer (although you can choose a different buffer class--see buffer_class, below).

$ss->send_msg($msg)

Sends the message $msg to the client. Or, in more technical terms, adds the message $msg to the server's output queue, to be written back to the client the next time through the select loop.

$msg should be a buffer in the class Net::SSH::Perl::Buffer (although you can choose a different buffer class--see buffer_class, below).

$ss->serve

Enters the select loop, waiting for requests from the client. Users of your class should call this method when they're ready to start serving clients.

$ss->log($message)

Writes the log message $message to the log file, if one was specified as the Log argument to init (or, rather, to the constructor).

If a log file was not specified, returns silently.

$ss->buffer_class

By default, messages are represented by Net::SSH::Perl::Buffer objects. You can alter this by overriding the buffer_class method; it should return the name of an alternate class. Be aware that this alternate class must conform to the interface used by Net::SSH::Perl::Buffer, so you may be best off subclassing that class and adding in your own functionality.

NOTES ^

It should be noted that the external interface (API) to this module is alpha, and could change.

AUTHOR & COPYRIGHTS ^

Please see the Net::SSH::Perl manpage for author, copyright, and license information.

syntax highlighting: