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

FreeBSD Manual Pages

  
 
  

home | help
Event::RPC::Server(3) User Contributed Perl DocumentationEvent::RPC::Server(3)

NAME
       Event::RPC::Server - Simple API for event driven	RPC servers

SYNOPSIS
	 use Event::RPC::Server;
	 use My::TestModule;

	 my $server = Event::RPC::Server->new (
	     #-- Required arguments
	     port		=> 8888,
	     classes		=> {
	       "My::TestModule"	=> {
		 new	  => "_constructor",
		 get_data => 1,
		 set_data => 1,
		 clone	  => "_object",
	       },
	     },

	     #-- Optional arguments
	     name		 => "Test server",
	     logger		 => Event::RPC::Logger->new(),
	     start_log_listener	 => 1,

	     ssl		 => 1
	     ssl_key_file	 => "server.key",
	     ssl_cert_file	 => "server.crt",
	     ssl_passwd_cb	 => sub	{ "topsecret" },

	     auth_required	 => 1,
	     auth_passwd_href	 => { $user => Event::RPC->crypt($user,$pass) },
	     auth_module	 => Your::Own::Auth::Module->new(...),

	     loop		 => Event::RPC::Loop::Event->new(),

	     host		 => "localhost",
	     load_modules	 => 1,
	     auto_reload_modules => 1,
	     connection_hook	 => sub	{ ... },
	 );

	 $server->start;

	 # and later from inside your server implementation
	 Event::RPC::Server->instance->stop;

DESCRIPTION
       Use this	module to add a	simple to use RPC mechanism to your event
       driven server application.

       Just create an instance of the Event::RPC::Server class with a bunch of
       required	settings. Then enter the main event loop through it, or	take
       control over the	main loop on your own if you like (refer to the
       MAINLOOP	chapter	for details).

       General information about the architecture of Event::RPC	driven
       applications is collected in the	Event::RPC manpage.

CONFIGURATION OPTIONS
       All options described here may be passed	to the new() constructor of
       Event::RPC::Server. As well you may set or modify them using set_OPTION
       style mutators, but not after start() or	setup_listeners() was called!
       All options may be read using get_OPTION	style accessors.

   REQUIRED OPTIONS
       If you just pass	the required options listed beyond you have a RPC
       server which listens to a network port and allows everyone connecting
       to it to	access a well defined list of classes and methods resp.	using
       the correspondent server	objects.

       There is	no authentication or encryption	active in this minimal
       configuration, so aware that this may be	a big security risk!  Adding
       security	is easy, refer to the chapters about SSL and authentication.

       These are the required options:

       port
	   TCP port number of the RPC listener.

       classes
	   This	is a hash ref with the following structure:

	     classes =>	{
	       "Class1"	=> {
		 new		 => "_constructor",
		 simple_method	 => 1,
		 object_returner => "_object",
	       },
	       "Class2"	=> { ... },
	       ...
	     },

	   Each	class which should be accessable for clients needs to be
	   listed here at the first level, assigned a hash of methods allowed
	   to be called. Event::RPC disuinguishes three	types of methods by
	   classifying their return value:

	   Constructors
	       A constructor method creates a new object of the	corresponding
	       class and returns it. You need to assign	the string
	       "_constructor" to the method entry to mark a method as a
	       constructor.

	   Simple methods
	       What's simple about these methods is their return value:	it's a
	       scalar, array, hash or even any complex reference structure
	       (Ok, not	simple anymore ;), but in particular it	returns	NO
	       objects,	because	this needs to handled specially	(see below).

	       Declare simple methods by assigning 1 in	the method
	       declaration.

	   Object returners
	       Methods which return objects need to be declared	by assigning
	       "_object" to the	method name here. They're not bound to return
	       just one	scalar object reference	and may	return an array	or
	       list reference with a bunch of objects as well.

   SSL OPTIONS
       The client/server protocol of Event::RPC	is not encrypted by default,
       so everyone listening on	your network can read or even manipulate data.
       To prevent this efficiently you can enable SSL encryption.  Event::RPC
       uses the	IO::Socket::SSL	Perl module for	this.

       First you need to generate a server key and certificate for your	server
       using the openssl command which is part of the OpenSSL distribution,
       e.g. by issueing	these commands (please refer to	the manpage of openssl
       for details - this is a very rough example, which works in general, but
       probably	you want to tweak some parameters):

	 % openssl genrsa -des3	-out server.key	1024
	 % openssl req -new -key server.key -out server.csr
	 % openssl x509	-req -days 3600	-in server.csr \
		   -signkey server.key -out server.crt

       After executing these commands you have the following files

	 server.crt
	 server.key
	 server.csr

       Event::RPC needs	the first two of them to operate with SSL encryption.

       To enable SSL encryption	you need to pass the following options to the
       constructor:

       ssl The ssl option needs	to be set to 1.

       ssl_key_file
	   This	is the filename	of the server.key you generated	with the
	   openssl command.

       ssl_cert_file
	   This	is the filename	of the server.crt file you generated with the
	   openssl command.

       ssl_passwd_cb
	   Your	server key is encrypted	with a password	you entered during the
	   key creation	process	described above. This callback must return it.
	   Depending on	how critical your application is you probably must
	   request the password	from the user during server startup or place
	   it into a more or less secured file.	For testing purposes you can
	   specify a simple anonymous sub here,	which just returns the
	   password, e.g.

	     ssl_passwd_cb => sub { return "topsecret" }

	   But note: having the	password in plaintext in your program code is
	   insecure!

   AUTHENTICATION OPTIONS
       SSL encryption is fine, now it's	really hard for	an attacker to listen
       or modify your network communication. But without any further
       configuration any user on your network is able to connect to your
       server. To prevent this users resp. connections to your server needs to
       be authenticated	somehow.

       Since version 0.87 Event::RPC has an API	to delegate authentication
       tasks to	a module, which	can be implemented outside Event::RPC.	To be
       compatible with prior releases it ships the module
       Event::RPC::AuthPasswdHash which	implements the old behaviour
       transparently.

       This default implementation is a	simple user/password based model. For
       now this	controls just the right	to connect to your server, so knowing
       one valid user/password pair is enough to access	all exported methods
       of your server. Probably	a more differentiated model will be added
       later which allows granting access to a subset of exported methods only
       for each	user who is allowed to connect.

       The following options control the authentication:

       auth_required
	   Set this to 1 to enable authentication and nobody can connect your
	   server until	he passes a valid user/password	pair.

       auth_passwd_href
	   If you like to use the builtin Event::RPC::AuthPasswdHash module
	   simply set this attribute. If you decide to use auth_module
	   (explained beyound) it's not	necessary.

	   auth_passwd_href is a hash of valid user/password pairs. The
	   password stored here	needs to be encrypted using Perl's crypt()
	   function, using the username	as the salt.

	   Event::RPC has a convenience	function for generating	such a crypted
	   password, although it's currently just a 1:1	wrapper	around Perl's
	   builtin crypt() function, but probably this changes someday,	so
	   better use this method:

	     $crypted_pass = Event::RPC->crypt($user, $pass);

	   This	is a simple example of setting up a proper auth_passwd_href
	   with	two users:

	     auth_passwd_href => {
	       fred => Event::RPC->crypt("fred", $freds_password),
	       nick => Event::RPC->crypt("nick", $nicks_password),
	     },

       auth_module
	   If you like to implement a more complex authentication method
	   yourself you	may set	the auth_module	attribute to an	instance of
	   your	class.	For now	your implementation just needs to have this
	   method:

	     $auth_module->check_credentials($user, $pass)

	   Aware that $pass is encrypted as explained above, so	your original
	   password needs to by	crypted	using Event::RPC->crypt	as well, at
	   least for the comparison itself.

       Note: you can use the authentication module without SSL but aware that
       an attacker listening to	the network connection will be able to grab
       the encrypted password token and	authenticate himself with it to	the
       server (replay attack). Probably	a more sophisticated
       challenge/response mechanism will be added to Event::RPC	to prevent
       this. But you definitely	should use SSL encryption in a critical
       environment anyway, which renders grabbing the password from the	net
       impossible.

   LOGGING OPTIONS
       Event::RPC has some logging abilities, primarily	for debugging
       purposes.  It uses a logger for this, which is an object	implementing
       the Event::RPC::Logger interface. The documentation of
       Event::RPC::Logger describes this interface and Event::RPC's logging
       facilities in general.

       logger
	   To enable logging just pass such an Event::RPC::Logger object to
	   the constructor.

       start_log_listener
	   Additionally	Event::RPC can start a log listener on the server's
	   port	number incremented by 1. All clients connected to this port
	   (e.g. by using telnet) get the server's log output.

	   Note: currently the logging port supports neither SSL nor
	   authentication, so be careful enabling the log listener in critical
	   environments.

   MAINLOOP OPTIONS
       Event::RPC derived it's name from the fact that it follows the event
       driven paradigm.	There are several toolkits for Perl which allow	event
       driven software development. Event::RPC has an abstraction layer	for
       this and	thus should be able to work with any toolkit.

       loop
	   This	option takes an	object of the loop abstraction layer you want
	   to use. Currently the following modules are implemented:

	     Event::RPC::Loop::AnyEvent	 Use the AnyEvent module
	     Event::RPC::Loop::Event	 Use the Event module
	     Event::RPC::Loop::Glib	 Use the Glib module

	   If loop isn't set, Event::RPC::Server tries all supported modules
	   in a	row and	aborts the program, if no module was found.

	   More	modules	will be	added in the future. If	you want to implement
	   one just take a look	at the code in the modules above: it's really
	   easy	and I appreciate your patch. The interface is roughly
	   described in	the documentation of Event::RPC::Loop.

       If you use the Event::RPC->start() method as described in the SYNOPSIS
       Event::RPC will enter the correspondent main loop for you. If you want
       to have full control over the main loop,	use this method	to setup all
       necessary Event::RPC listeners:

	 $rpc_server->setup_listeners();

       and manage the main loop	stuff on your own.

   MISCELLANEOUS OPTIONS
       host
	   By default the network listeners are	bound to all interfaces	in the
	   system. Use the host	option to bind to a specific interface,	e.g.
	   "localhost" if you efficently want to prevent network clients from
	   accessing your server.

       load_modules
	   Control whether the class module files should be loaded
	   automatically when first accesed by a client. This options defaults
	   to true, for	backward compatibility reasons.

       auto_reload_modules
	   If this option is set Event::RPC::Server will check on each method
	   call	if the corresponding module changed on disk and	reloads	it
	   automatically. Of course this has an	effect on performance, but
	   it's	very useful during development.	You probably shouldn't enable
	   this	in production environments.

       connection_hook
	   This	callback is called on each connection /	disconnection with two
	   arguments: the Event::RPC::Connection object	and a string
	   containing either "connect" or "disconnect" depending what's
	   currently happening with this connection.

METHODS
       The following methods are publically available:

       Event::RPC::Server->instance
	   This	returns	the latest created Event::RPC::Server instance
	   (usually you	have only one instance in one program).

       $rpc_server->start
	   Start the mainloop of your Event::RPC::Server.

       $rpc_server->stop
	   Stops the mainloop which usually means, that	the server exits, as
	   long	you don't do more sophisticated	mainloop stuff by your own.

       $rpc_server->setup_listeners
	   This	method initializes all networking listeners needed for
	   Event::RPC::Server to work, using the configured loop module.  Use
	   this	method if you don't use	the start() method but manage the
	   mainloop on your own.

       $rpc_server->log	( [$level,] $msg )
	   Convenience method for logging. It simply passes the	arguments to
	   the configured logger's log() method.

       $rpc_server->get_clients_connected
	   Returns the number of currently connected Event::RPC	clients.

       $rpc_server->get_log_clients_connected
	   Returns the number of currently connected logging clients.

       $rpc_server->get_active_connection
	   This	returns	the currently active Event::RPC::Connection object
	   representing	the connection resp. the client	which currently
	   requests method invocation. This is undef if	no client call is
	   active.

AUTHORS
	 JA<paragraph>rn Reder <joern at zyn dot de>

COPYRIGHT AND LICENSE
       Copyright (C) 2002-2006 by Joern	Reder, All Rights Reserved.

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 783:
	   You forgot a	'=back'	before '=head1'

       Around line 834:
	   Non-ASCII character seen before =encoding in	'JA<paragraph>rn'.
	   Assuming CP1252

perl v5.32.0			  2011-03-08		 Event::RPC::Server(3)

NAME | SYNOPSIS | DESCRIPTION | CONFIGURATION OPTIONS | METHODS | AUTHORS | COPYRIGHT AND LICENSE | POD ERRORS

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

home | help