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.
REQUIREDOPTIONS
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 accessible 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.
Singletonconstructors
For singleton classes the method which returns the singleton instance should be declared with
"_singleton". This way the server takes care that references get never destroyed on server side.
Simplemethods
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.
Objectreturners
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.
SSLOPTIONS
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 issuing 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!
ssl_opts
This optional parameter takes a hash reference of options passed to IO::Socket::SSL->new(...) to have
more control over the server SSL listener.
AUTHENTICATIONOPTIONS
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.
LOGGINGOPTIONS
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.
MAINLOOPOPTIONS
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.
MESSAGEFORMATOPTIONS
Event::RPC supports different CPAN modules for data serialisation, named "message formats" here:
SERL -- Sereal::Encoder, Sereal::Decoder
CBOR -- CBOR::XS
JSON -- JSON::XS
STOR -- Storable
Server and client negotiate automatically which format is best to use but you can manipulate this
behaviour with the following options:
message_formats
This takes an array of format identifiers from the list above. Event::RPC::Server will only use /
accept these formats.
insecure_msg_fmt_ok
The Storable module is known to be insecure. But for backward compatibility reasons
Event::RPC::Server accepts clients which can't offer anything but Storable. You can prevent that by
setting this option explicitly to 0. It's enabled by default.
MISCELLANEOUSOPTIONShost
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 efficiently 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.
Install Now
PNG Icons
