/ 
Net-EPP-Proxy-0.04
River stage zero No dependents
/ Net::EPP::Proxy

NAME

Net::EPP::Proxy - a proxy server for the EPP protocol.

SYNOPSIS

Construct your server process like so:

#!/usr/bin/perl
use Net::EPP::Proxy;
use Net::EPP::Frame::ObjectSpec;
use strict;

my $proxy = Net::EPP::Proxy->new;

$proxy->init(
	# EPP-specific params:
	remote_host	=> 'epp.nic.tld',
	remote_port	=> 700,
	ssl		=> 1,
	clid		=> $CLID,
	pw		=> $PW,

	# Net::Server params:
	host		=> 'localhost',
	port		=> 7000,
	log_level	=> 0,
	max_servers	=> 10,
	min_servers	=> 5,
);

Then, in your client processes:

my $client = Net::EPP::Client->new(
	host	=> 'localhost',
	port	=> 7000,
	ssl	=> undef,
);

print $client->connect;

DESCRIPTION

EPP is the Extensible Provisioning Protocol. EPP (defined in RFC 4930) is an application layer client-server protocol for the provisioning and management of objects stored in a shared central repository. Specified in XML, the protocol defines generic object management operations and an extensible framework that maps protocol operations to objects. As of writing, its only well-developed application is the provisioning of Internet domain names, hosts, and related contact details.

RFC 4934 defines a TCP based transport model for EPP, and this module implements a proxy server for this model. You can use it to construct a daemon that maintains a single connection to the EPP server that can be used by many local clients, thereby reducing the overhead for each transaction.

Net::EPP::Proxy is based on the Net::Server framework and Net::EPP::Client, which it uses to communicate with the server.

When a Net::EPP::Proxy server is started, it creates a connection to a single remote EPP server using the supplied credentials. Each proxy can connect to a single remote server - if you want to proxy for multiple servers you should create a proxy server for each, perhaps listening on a different TCP port.

+---+				+---+
| C |<-----------//------------>|   |	In this model, each client must
+---+				|   |   establish a session with the
				| S |   server, increasing the time and
+---+				| E |	bandwidth overheard associated
| C |<-----------//------------>| R |   with sending transactions to
+---+				| V |   the server, especially if the
				| E |   client is a CGI or PHP script
+---+				| R |	that must create a new
| C |<-----------//------------>|   |	connection each time.
+---+				+---+

Figure 1 - multiple clients connecting to a remote server


+---+		+---+		+---+
| C |<--------->|   |		|   |	In this model, the proxy server
+---+		|   |		|   |	maintains a single connection
		| P |		| S |	to the server on behalf of a
+---+		| R |		| E |	number of clients, reducing
| C |<--------->| O |<----//--->| R |	the time and bandwidth overhead
+---+		| X |		| V |	associated with sending
		| Y |		| E |	transactions to the server.
+---+		|   |		| R |
| C |<--------->|   |		|   |
+---+		+---+		+---+

Figure 2 - multiple clients connecting to a proxy

When a local client connects to the proxy, it is immediately sent the EPP <greeting> frame the proxy server received from the remote server. The client can then send EPP frames to the proxy, which passes these frames on to the server within the context of its own connection, and returns the remote servers' response to the client. A single connection to the remote server can thereby be shared among a large number of local clients without the need to connect and authenticate each client.

The proxy "speaks" the same protocol as an EPP server (XML payloads prefixed by 4 bytes containing the payload's length, sent over TCP), so any client capable of using the EPP protocol can use the proxy (eg, the Net::EPP::Client module, the Net_EPP_Client PHP class, etc).

USAGE

To start an EPP proxy server instance, use the following syntax:

my $proxy = Net::EPP::Proxy->new;

$proxy->init(%PARAMS);

The %PARAMS hash contain any of the configuration variables allowed by Net::Server, plus the following:

remote_host

The hostname of the remote EPP server to connect to.

remote_port

The TCP port number of the remote EPP server to connect to (usually 700).

ssL

Whether to use SSL to connect to the remote server (usually true).

clid

The client ID to use to authenticate.

pw

The password to use to authenticate.

req_timeout

The amount of time in seconds to wait for a response from the remote server. If there is a network outage or some other undefined error, the server will send an error frame to the local client and then shut down, so you may want to have your invocation script try to re-establish the connection.

Object Services

Versions of Net::EPP::Proxy prior to 0.03 required that you manually specify any service URIs required. As of Version 0.03, the services are automatically populated from the <svcMenu> element in the <greeting> received from the remote server.

If the proxy is unable to authenticate with the remote EPP server then the init() method will carp() and then return undef.

LOGGING, CONFIGURATION AND PERFORMANCE TUNING

See the documentation for Net::Server for information about configuring the server to do logging, and tweaking performance values.

Note that there is a fundamental limitation on performance due to the proxy server blocking while waiting for the remote server to respond. If you find that this becomes problematic, consider running multiple proxy server instances and distributing client connections between them.

AUTHOR

CentralNic Ltd (http://www.centralnic.com/).

COPYRIGHT

This module is (c) 2010 CentralNic Ltd. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 343:

You forgot a '=back' before '=head2'

Around line 350:

=back without =over