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

FreeBSD Manual Pages

  
 
  

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

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

SYNOPSIS
	   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
	   $proxy->register();

	   # and you can setup multiple	proxies

	   # and now proxy connections indefinitely
	   Net::Proxy->mainloop();

DESCRIPTION
       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
       fence.

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

METHODS
       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
       new

	   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.

       mainloop

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

       add_listeners

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

       Add the given sockets to	the list of listening sockets.

       watch_reader_sockets

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

       Add the given sockets to	the readers watch list.

       watch_writer_sockets

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

       Add the given sockets to	the writers watch list.

       remove_writer_sockets

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

       Remove the given	sockets	from the writers watch list.

       close_sockets

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

       Close the given sockets and cleanup the related internal	structures.

       set_verbosity

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

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

       error

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

       Log $message to STDERR, always.

       notice

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

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

       info

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

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

       debug

	   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 "##".)

       get_max_buffer_size

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

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

       set_max_buffer_size

	   Net::Proxy->set_max_buffer_size($buffsize);

       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.

       get_peer

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

       Get the socket peer.

       set_peer

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

       Set the socket peer.

       get_connector

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

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

       set_connector

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

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

       get_state

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

       Get the socket state.

       set_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
       connection.

       get_nick

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

       Get the socket nickname.

       set_nick

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

       get_buffer

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

       Get the content of the writing buffer for the socket.

       set_buffer

	   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()".

       get_callback

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

       Get the callback	currently associated with the socket.

       set_callback

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

       Set the callback	currently associated with the socket.

       add_to_buffer

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

       Add data	to the writing buffer of the socket.

   Instance methods
       register

	   $proxy->register();

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

       unregister

	   $proxy->unregister();

       Unregister the Net::Proxy object.

       in_connector

	   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.

       out_connector

	   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:

       stat_inc_opened

	   $proxy->stat_inc_opened();

       Increment the "opened" connection counter for this proxy.

       stat_inc_closed

	   $proxy->stat_inc_closed();

       Increment the "closed" connection counter for this proxy.

       stat_opened

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

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

       stat_closed

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

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

       stat_total_opened

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

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

       stat_total_closed

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

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

CONNECTORS
       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
	   connectors.

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

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

AUTHOR
       Philippe	'BooK' Bruhat, "<book@cpan.org>".

BUGS
       Please report any bugs or feature requests to
       "bug-net-proxy@rt.cpan.org", or through the web interface at
       <http://rt.cpan.org/>. I	will be	notified, and then you'll
       automatically be	notified of progress on	your bug as I make changes.

TODO
       Here's my own wishlist:

       o   Write a connector fully compatible with GNU httptunnel
	   (<http://www.nocrew.org/software/httptunnel.html>).

	   This	one will probably be named
	   "Net::Proxy::Connector::httptunnel".

       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,
	   2001.

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

       o   Implement DNS tunnel	connectors.

	   See <http://savannah.nongnu.org/projects/nstx/>, OzymanDNS,
	   <http://www.doxpara.com/slides/BH_EU_05-Kaminsky.pdf>.
	   <http://thomer.com/howtos/nstx.html>	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.

	   See
	   <http://www.linuxexposed.com/Articles/Hacking/Case-of-a-wireless-hack.html>,
	   <http://sourceforge.net/projects/itun>,
	   <http://www.cs.uit.no/~daniels/PingTunnel/>,
	   <http://thomer.com/icmptx/> 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
	   <http://fare.tunes.org/files/fwprc/>.

	   Look	also here: <http://gray-world.net/tools/>

       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.

SUPPORT
       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
	   <http://github.com/book/Net-Proxy/>

       AnnoCPAN: Annotated CPAN	documentation
	   <http://annocpan.org/dist/Net-Proxy>

       CPAN Ratings
	   <http://cpanratings.perl.org/d/Net-Proxy>

       RT: CPAN's request tracker
	   <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-Proxy>

       Search CPAN
	   <http://search.cpan.org/dist/Net-Proxy>

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

LICENSE
       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)

NAME | SYNOPSIS | DESCRIPTION | METHODS | CONNECTORS | AUTHOR | BUGS | TODO | SUPPORT | COPYRIGHT | LICENSE

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

home | help