GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

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

    # and you can setup multiple proxies

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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, "<book@cpan.org>".

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.

Here's my own wishlist:
  • 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".

  • Enhance the httptunnel protocol to support multiple connections.
  • 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).

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

  • Implement an UDP connector. (Is it feasible?)
  • Implement a connector that can be plugged to the STDIN/STDOUT of an external process, like the "ProxyCommand" option of OpenSSH.
  • Implement "Net::Proxy::Connector::unix", for UNIX sockets.
  • 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.

  • Look for inspiration in the Firewall-Piercing HOWTO, at <http://fare.tunes.org/files/fwprc/>.

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

  • 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 Werthmö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
<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 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.
2014-11-02 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.