1Net::SSH::Perl::SubsystUesme:r:SCeornvterri(b3u)ted PerlNeDto:c:uSmSeHn:t:aPteiroln::Subsystem::Server(3)
2
3
4

NAME

6       Net::SSH::Perl::Subsystem::Server - Server infrastructure for SSH
7       subsystems
8

SYNOPSIS

10           use Net::SSH::Perl::Subsystem::Server;
11           use base qw( Net::SSH::Perl::Subsystem::Server );
12
13           use constant MSG_FOO => 1;
14
15           sub init {
16               my $ss = shift;
17               $ss->SUPER::init(@_);
18
19               $ss->register_handler(MSG_FOO, \&handle_foo);
20           }
21
22           sub handle_foo {
23               my $ss = shift;
24               my($msg) = @_;
25               print "Got MSG_FOO message!\n";
26           }
27

DESCRIPTION

29       Net::SSH::Perl::Subsystem::Server is a generic subclass that can be
30       used to build servers for SSH-2 subsystems. A subsystem is a network
31       protocol that runs on top of a secure, encrypted SSH connection between
32       two machines: it allows the user and developer to build a secure
33       network protocol without worrying about the details of that security,
34       because it inherits the secure tunnel from SSH.
35
36       Subsystem::Server provides basic functionality needed by all subsystem
37       servers. A subsystem daemon is started up by the sshd when a request
38       comes in for that subsystem; sshd and the subsystem daemon then talk to
39       each other through pipes, and data that the daemon wishes to send to
40       the subsystem client is sent over the network through the SSH secure
41       tunnel. Subsystem::Server handles the talking to the sshd, and lets the
42       application developer focus on designing the network protocol and
43       handling requests from the subsystem client.
44

USAGE

46       Net::SSH::Perl::Subsystem::Server is meant to be used as a base class
47       for subsystem servers. With that in mind, general usage should follow
48       the example above in the SYNOPSIS:
49
50       •   Initialization
51
52           If you want your subclass to do anything, you'll want to override
53           the init method so that you can set up handlers for specific types
54           of messages from the subsystem client. For each message type, you
55           need to associate the type with a subroutine reference that will be
56           invoked when a message of that type is received by the core server.
57           You do this by calling the register_handler method (see below).
58
59       •   Message Handling
60
61           When the core server receives new messages from the client, it
62           grabs the first byte from the incoming stream; the first byte is a
63           packed 8-bit integer representing the type of the message. This
64           identifier is used to look up the message handler to handle this
65           particular type of message.
66
67       These are the public methods in which your subclass will be most
68       interested:
69
70   $ss->init(%args)
71       Initializes the subsystem server object. This is where you'll want to
72       set up your message handlers (using register_handler) and perhaps
73       perform any other protocol-specific initialization.
74
75       Make sure that your init method returns the $ss object on success;
76       failure to return init should be an indication of failure to calling
77       code.
78
79       %args can contain whatever you like it to contain. The base class
80       Net::SSH::Perl::Subsystem::Server takes these parameters in %args:
81
82       •   Log
83
84           The location of a file on disk where you can write messages to be
85           logged. This is the file to which messages sent to the log method
86           (below) will be written.
87
88           This is an optional argument; if not specified, no log file will be
89           used, and calls to log will be silently ignored.
90
91   $ss->register_handler($type, $code)
92       Configures the subsystem server $ss such that any message sent from the
93       client whose type is $type will automatically invoke the subroutine
94       reference $code. This is how you build protocol-specific functionality
95       into your subsystem: you associate message types with methods.
96
97       The subroutine reference $code will be invoked and given two arguments:
98       $ss, the instance of the subsystem server that is blessed into your
99       subclass, and $msg, a buffer in the class Net::SSH::Perl::Buffer
100       (although you can choose a different buffer class--see buffer_class,
101       below).
102
103   $ss->send_msg($msg)
104       Sends the message $msg to the client. Or, in more technical terms, adds
105       the message $msg to the server's output queue, to be written back to
106       the client the next time through the select loop.
107
108       $msg should be a buffer in the class Net::SSH::Perl::Buffer (although
109       you can choose a different buffer class--see buffer_class, below).
110
111   $ss->serve
112       Enters the select loop, waiting for requests from the client.  Users of
113       your class should call this method when they're ready to start serving
114       clients.
115
116   $ss->log($message)
117       Writes the log message $message to the log file, if one was specified
118       as the Log argument to init (or, rather, to the constructor).
119
120       If a log file was not specified, returns silently.
121
122   $ss->buffer_class
123       By default, messages are represented by Net::SSH::Perl::Buffer objects.
124       You can alter this by overriding the buffer_class method; it should
125       return the name of an alternate class. Be aware that this alternate
126       class must conform to the interface used by Net::SSH::Perl::Buffer, so
127       you may be best off subclassing that class and adding in your own
128       functionality.
129

NOTES

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

AUTHOR & COPYRIGHTS

135       Please see the Net::SSH::Perl manpage for author, copyright, and
136       license information.
137
138
139
140perl v5.34.0                      2021-07-2N2et::SSH::Perl::Subsystem::Server(3)
Impressum