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

FreeBSD Manual Pages


home | help
Net::Proxy(3)	      User Contributed Perl Documentation	 Net::Proxy(3)

       Net::Proxy - Framework for proxying network connections in many ways

	   use Net::Proxy;

	   # proxy connections from localhost:6789 to remotehost:9876
	   # using standard TCP	connections
	   my $proxy = Net::Proxy->new(
	       {   in  => { type => 'tcp', port	=> '6789' },
		   out => { type => 'tcp', host	=> 'remotehost', port => '9876'	},

	   # register the proxy	object

	   # and you can setup multiple	proxies

	   # and now proxy connections indefinitely

       A Net::Proxy object represents a	proxy that accepts connections and
       then relays the data transfered between the source and the destination.

       The goal	of this	module is to abstract the different methods used to
       connect from the	proxy to the destination.

       A proxy is a program that transfer data across a	network	boundary
       between a client	and a server. Net::Proxy introduces the	concept	of
       "connectors" (implemented as Net::Proxy::Connector subclasses), which
       abstract	the server part	(connected to the client) and the client part
       (connected to the server) of the	proxy.

       This architecture makes it easy to implement specific techniques	to
       cross a given network boundary, possibly	by using a proxy on one	side
       of the network fence, and a reverse-proxy on the	other side of the

       See "AVAILABLE CONNECTORS" for details about the	existing connectors.

       If you only intend to use Net::Proxy and	not write new connectors, you
       only need to know about "new()",	"register()" and "mainloop()".

   Class methods

	   my $proxy = Net::Proxy->new(	{ in =>	{ ... }, { out => { ...	} } );

       Return a	new Net::Proxy object, with two	connectors configured as
       described in the	hashref.

       The connector parameters	are described in the table below, as well as
       in each connector documentation.


	   Net::Proxy->mainloop( $max_connections )

       This method initialises all the registered "Net::Proxy" objects and
       then loops on all the sockets ready for reading,	passing	the data
       through the various "Net::Proxy::Connector" objets to handle the
       specifics of each connection.

       If $max_connections is given, the proxy will stop after having fully
       processed that many connections.	Otherwise, this	method does not


	   Net::Proxy->add_listeners( @sockets );

       Add the given sockets to	the list of listening sockets.


	   Net::Proxy->watch_reader_sockets( @sockets );

       Add the given sockets to	the readers watch list.


	   Net::Proxy->watch_writer_sockets( @sockets );

       Add the given sockets to	the writers watch list.


	   Net::Proxy->remove_writer_sockets( @sockets );

       Remove the given	sockets	from the writers watch list.


	   Net::Proxy->close_sockets( @sockets );

       Close the given sockets and cleanup the related internal	structures.


	   Net::Proxy->set_verbosity( $level );

       Set the logging level. 0	means not messages except warnings and errors.


	   Net::Proxy->error( $message );

       Log $message to STDERR, always.


	   Net::Proxy->notice( $message	);

       Log $message to STDERR if verbosity level is equal to 1 or more.


	   Net::Proxy->info( $message );

       Log $message to STDERR if verbosity level is equal to 2 or more.


	   Net::Proxy->debug( $message );

       Log $message to STDERR if verbosity level is equal to 3 or more.

       (Note: throughout the Net::Proxy	source code, calls to "debug()"	are
       commented with "##".)


	   my $buffsize	= Net::Proxy->get_max_buffer_size;

       Get the maximum allowed length of the internal write buffers used by
       each connector.



       Get or set the maximum allowed length of	the internal write buffers
       used by each connector.	A value	of 0 means that	the maximum length is
       not checked. The	default	value is 16384 bytes (16kB).

       Note that this is a global value, shared	by all proxies and connectors.

   Class methods related to sockets
       Some of the class methods are related to	the socket objects that	handle
       the actual connections.


	   my $peer = Net::Proxy->get_peer( $socket );

       Get the socket peer.


	   Net::Proxy->set_peer( $socket, $peer	);

       Set the socket peer.


	   my $connector = Net::Proxy->get_connector( $socket );

       Get the socket connector	(a Net::Proxy::Connector object).


	   Net::Proxy->set_connector( $socket, $connector );

       Set the socket connector	(a Net::Proxy::Connector object).


	   my $state = Net::Proxy->get_state( $socket );

       Get the socket state.


	   Net::Proxy->set_state( $socket, $state );

       Set the socket state. Some "Net::Proxy::Connector" subclasses may wish
       to use this to store some internal information about the	socket or the


	   my $nick = Net::Proxy->get_nick( $socket );

       Get the socket nickname.


	   Net::Proxy->set_nick( $socket, $nickname );

       Set the socket nickname.	Typically used by Net::Proxy::Connector	to
       give informative	names to socket	(used in the log messages).


	   my $buffer =	Net::Proxy->get_buffer(	$socket	);

       Get the content of the writing buffer for the socket.


	   Net::Proxy->set_buffer( $socket, $data );

       Set the content of the writing buffer for the socket.  Used by
       Net::Proxy::Connector in	"raw_read_from()" and "ranw_write_to()".


	   Net::Proxy->get_callback( $socket );

       Get the callback	currently associated with the socket.


	   Net::Proxy->set_callback( $socket, $coderef );

       Set the callback	currently associated with the socket.


	   Net::Proxy->add_to_buffer( $socket, $data );

       Add data	to the writing buffer of the socket.

   Instance methods


       Register	a Net::Proxy object so that it will be included	in the
       "mainloop()" processing.



       Unregister the Net::Proxy object.


	   my $connector = $proxy->in_connector();

       Return the Net::Proxy::Connector	objet that handles the incoming
       connection and handles the data coming from the "client"	side.


	   my $connector = $proxy->out_connector();

       Return the Net::Proxy::Connector	objet that creates the outgoing
       connection and handles the data coming from the "server"	side.

   Statistical methods
       The following methods manage some statistical information about the
       individual proxies:



       Increment the "opened" connection counter for this proxy.



       Increment the "closed" connection counter for this proxy.


	   my $opened =	$proxy->stat_opened();

       Return the count	of "opened" connections	for this proxy.


	   my $closed =	$proxy->stat_closed();

       Return the count	of "closed" connections	for this proxy.


	   my $opened =	$proxy->stat_total_opened();

       Return the total	count of "opened" connections across all proxy


	   my $closed =	$proxy->stat_total_closed();

       Return the total	count of "closed" connections across all proxy

       All connection types are	provided with the help of specialised classes.
       The logic for protocol "xxx" is provided	by the
       "Net::Proxy::Connector::xxx" class.

   Connector hooks
       There is	a single parameter that	all connectors accept: "hook".	Given
       a code reference, the code reference will be called when	data is
       received	on the corresponding socket.

       The code	reference should have the following signature:

	   sub callback	{
	       my ($dataref, $sock, $connector)	= @_;

       $dataref	is a reference to the chunk of data received, $sock is a
       reference to the	socket that received the data, and $connector is the
       "Net::Proxy::Connector" object that created the socket. This allows
       someone to eventually store data	in a stash stored in the connector, so
       as to share data	between	sockets.

   Available connectors
       tcp (Net::Proxy::Connector::tcp)
	   This	is the simplest	possible proxy connector. On the "in" side, it
	   sits	waiting	for incoming connections, and on the "out" side, it
	   connects to the configured host/port.

       connect (Net::Proxy::Connector::connect)
	   This	proxy connector	can connect to a TCP server though a web proxy
	   that	accepts	HTTP CONNECT requests.

       dual (Net::Proxy::Connector::dual)
	   This	proxy connector	is a Y-shaped connector: depending on the
	   client behaviour right after	the connection is established, it
	   connects it to one of two services, handled by two distinct

       dummy (Net::Proxy::Connector::dummy)
	   This	proxy connector	does nothing. You can use it as	a template for
	   writing new Net::Proxy::Connector classes.

       This table summarises all the available Net::Proxy::Connector classes
       and the parameters their	constructors recognise.

       "N/A" means that	the given Net::Proxy::Connector	cannot be used in that
       position	(either	"in" or	"out").

	    Connector  | in parameters	 | out parameters
	    tcp	       | host		 | host
		       | port		 | port
	    connect    | N/A		 | host
		       |		 | port
		       |		 | proxy_host
		       |		 | proxy_port
		       |		 | proxy_user
		       |		 | proxy_pass
		       |		 | proxy_agent
	    dual       | host		 | N/A
		       | port		 |
		       | timeout	 |
		       | server_first	 |
		       | client_first	 |
	    dummy      | N/A		 | N/A
	    ssl	       | host		 | host
		       | port		 | port
		       | start_cleartext | start_cleartext
	    connect_ssl| N/A		 | host
		       |		 | port
		       |		 | proxy_host
		       |		 | proxy_port
		       |		 | proxy_user
		       |		 | proxy_pass
		       |		 | proxy_agent

       Net::Proxy::Connector::dummy is used as the "out" parameter for a
       Net::Proxy::Connector::dual, since the later is linked to two different
       connector objects.

       Philippe	'BooK' Bruhat, "<>".

       Please report any bugs or feature requests to
       "", or through the web interface at
       <>. I	will be	notified, and then you'll
       automatically be	notified of progress on	your bug as I make changes.

       Here's my own wishlist:

       o   Write a connector fully compatible with GNU httptunnel

	   This	one will probably be named

       o   Enhance the httptunnel protocol to support multiple connections.

       o   Implement RFC 3093 -	Firewall Enhancement Protocol (FEP), as
	   "Net::Proxy::Connector::FEP". This RFC was published	on April 1,

	   This	is probably impossible with Net::Proxy,	since the FEP driver
	   is a	rather low-level driver	(at the	IP level of the	network

       o   Implement DNS tunnel	connectors.

	   See <>, OzymanDNS,
	   <>	for examples.

       o   Implement an	UDP connector. (Is it feasible?)

       o   Implement a connector that can be plugged to	the STDIN/STDOUT of an
	   external process, like the "ProxyCommand" option of OpenSSH.

       o   Implement "Net::Proxy::Connector::unix", for	UNIX sockets.

       o   Implement ICMP tunnel connectors.

	   <> for examples.

	   Since ICMP implies low-level	packet reading and writing, it may not
	   be possible for Net::Proxy to handle	it.

       o   Look	for inspiration	in the Firewall-Piercing HOWTO,	at

	   Look	also here: <>

       o   Implement a "Net::Proxy::Connector::starttls" connector that	can
	   upgrade upgrade a connection	to SSL transparently, even if the
	   client or server doesn't support STARTTLS.

	   Martin WerthmA<paragraph>ller provided a full implementation	of a
	   connector that can handle IMAP connections and upgrade them to TLS
	   if the client sends a "STARTTLS" command. My	implementation will
	   split this in two parts Net::Proxy::Connector::ssl and
	   "Net::Proxy::Connector::starttls", that inherits from the former.

       You can find documentation for this module with the perldoc command.

	   perldoc Net::Proxy

       You can also look for information at:

       The public source repository

       AnnoCPAN: Annotated CPAN	documentation

       CPAN Ratings

       RT: CPAN's request tracker

       Search CPAN

       Copyright 2006-2014 Philippe 'BooK' Bruhat, All Rights Reserved.

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

perl v5.32.0			  2014-11-02			 Net::Proxy(3)


Want to link to this manual page? Use this URL:

home | help