Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::SSH::Perl::SubsysUser:Contributed PerNet::SSH::Perl::Subsystem::Server(3)

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:

       o   Initialization

	   If you want your subclass to	do anything, you'll want to override
	   the init 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 register_handler method (see below).

       o   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.

       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:

       o   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 log method
	   (below) will	be written.

	   This	is an optional argument; if not	specified, no log file will be
	   used, and calls to log will be silently ignored.

   $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.

perl v5.32.0			  2017-03-Net::SSH::Perl::Subsystem::Server(3)

NAME | SYNOPSIS | DESCRIPTION | USAGE | NOTES | AUTHOR & COPYRIGHTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::SSH::Perl::Subsystem::Server&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help