.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.37
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::SSH::Perl::Subsystem::Server 3"
.TH Net::SSH::Perl::Subsystem::Server 3 "2008-10-21" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Net::SSH::Perl::Subsystem::Server \- Server infrastructure for SSH subsystems
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Net::SSH::Perl::Subsystem::Server;
\&    use base qw( Net::SSH::Perl::Subsystem::Server );
.Ve
.PP
.Vb 1
\&    use constant MSG_FOO => 1;
.Ve
.PP
.Vb 3
\&    sub init {
\&        my $ss = shift;
\&        $ss->SUPER::init(@_);
.Ve
.PP
.Vb 2
\&        $ss->register_handler(MSG_FOO, \e&handle_foo);
\&    }
.Ve
.PP
.Vb 5
\&    sub handle_foo {
\&        my $ss = shift;
\&        my($msg) = @_;
\&        print "Got MSG_FOO message!\en";
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fINet::SSH::Perl::Subsystem::Server\fR is a generic subclass that can
be used to build servers for \s-1SSH\-2\s0 subsystems. A subsystem is a
network protocol that runs on top of a secure, encrypted \s-1SSH\s0
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 \s-1SSH\s0.
.PP
\&\fISubsystem::Server\fR 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 \s-1SSH\s0 secure tunnel. \fISubsystem::Server\fR
handles the talking to the sshd, and lets the application
developer focus on designing the network protocol and handling
requests from the subsystem client.
.SH "USAGE"
.IX Header "USAGE"
\&\fINet::SSH::Perl::Subsystem::Server\fR 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 \fI\s-1SYNOPSIS\s0\fR:
.IP "* Initialization" 4
.IX Item "Initialization"
If you want your subclass to do anything, you'll want to override
the \fIinit\fR method so that you can set up handlers for specific
types of messages from the subsystem client. For each message
type, you need to associate the type with a subroutine reference
that will be invoked when a message of that type is received
by the core server. You do this by calling the \fIregister_handler\fR
method (see below).
.IP "* Message Handling" 4
.IX Item "Message Handling"
When the core server receives new messages from the client, it
grabs the first byte from the incoming stream; the first byte is
a packed 8\-bit integer representing the type of the message. This
identifier is used to look up the message handler to handle this
particular type of message.
.PP
These are the public methods in which your subclass will be most
interested:
.Sh "$ss\->init(%args)"
.IX Subsection "$ss->init(%args)"
Initializes the subsystem server object. This is where you'll
want to set up your message handlers (using \fIregister_handler\fR)
and perhaps perform any other protocol-specific initialization.
.PP
Make sure that your \fIinit\fR method returns the \fI$ss\fR object
on success; failure to return \fIinit\fR should be an indication
of failure to calling code.
.PP
\&\fI%args\fR can contain whatever you like it to contain. The base
class \fINet::SSH::Perl::Subsystem::Server\fR takes these
parameters in \fI%args\fR:
.IP "* Log" 4
.IX Item "Log"
The location of a file on disk where you can write messages
to be logged. This is the file to which messages sent to
the \fIlog\fR method (below) will be written.
.Sp
This is an optional argument; if not specified, no log file
will be used, and calls to \fIlog\fR will be silently ignored.
.ie n .Sh "$ss\->register_handler($type, $code)"
.el .Sh "$ss\->register_handler($type, \f(CW$code\fP)"
.IX Subsection "$ss->register_handler($type, $code)"
Configures the subsystem server \fI$ss\fR such that any message
sent from the client whose type is \fI$type\fR will automatically
invoke the subroutine reference \fI$code\fR. This is how you build
protocol-specific functionality into your subsystem: you
associate message types with methods.
.PP
The subroutine reference \fI$code\fR will be invoked and given
two arguments: \fI$ss\fR, the instance of the subsystem server
that is blessed into your subclass, and \fI$msg\fR, a buffer in
the class \fINet::SSH::Perl::Buffer\fR (although you can choose
a different buffer class\*(--see \fIbuffer_class\fR, below).
.Sh "$ss\->send_msg($msg)"
.IX Subsection "$ss->send_msg($msg)"
Sends the message \fI$msg\fR to the client. Or, in more technical
terms, adds the message \fI$msg\fR to the server's output queue, to
be written back to the client the next time through the select
loop.
.PP
\&\fI$msg\fR should be a buffer in the class \fINet::SSH::Perl::Buffer\fR
(although you can choose a different buffer class\*(--see
\&\fIbuffer_class\fR, below).
.Sh "$ss\->serve"
.IX Subsection "$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.
.Sh "$ss\->log($message)"
.IX Subsection "$ss->log($message)"
Writes the log message \fI$message\fR to the log file, if one was
specified as the \fILog\fR argument to \fIinit\fR (or, rather, to the
constructor).
.PP
If a log file was not specified, returns silently.
.Sh "$ss\->buffer_class"
.IX Subsection "$ss->buffer_class"
By default, messages are represented by \fINet::SSH::Perl::Buffer\fR
objects. You can alter this by overriding the \fIbuffer_class\fR
method; it should return the name of an alternate class. Be aware
that this alternate class \fImust\fR conform to the interface used
by \fINet::SSH::Perl::Buffer\fR, so you may be best off subclassing
that class and adding in your own functionality.
.SH "NOTES"
.IX Header "NOTES"
It should be noted that the external interface (\s-1API\s0) to this
module is alpha, and could change.
.SH "AUTHOR & COPYRIGHTS"
.IX Header "AUTHOR & COPYRIGHTS"
Please see the Net::SSH::Perl manpage for author, copyright,
and license information.