NAME

Apache::HTTunnel - Universal HTTP tunnel using Apache + mod_perl

SYNOPSIS

 # on the server: in /etc/httpd/conf.d/perl_httunnel.conf
   PerlSetVar              HTTunnelFifo          /var/lib/httunnel/httunnel.sock
   PerlPostConfigRequire   Apache/HTTunnel.pm
   <Location "/httunnel">
     SetHandler      perl-script
     PerlResponseHandler   Apache::HTTunnel
   </Location>

 # on the client: in /etc/httunnel.d/server_ssh.cfg
   [server ssh]
   local_port = 9876
   url = http://server/httunnel
   remote_host = localhost
   remote_port = 22

 # on the client
   % /usr/bin/httunnel -f /etc/httunnel.d/ssh.cfg &
   % ssh localhost -p 9876 

   # You will now have a ssh connection to server where the packets
   # are actually being transported over many HTTP requests.
      

DESCRIPTION

Apache::HTTunnel allows the creation of HTTP tunnels using Apache and mod_perl. The HTTunnel::Client class (or the httunnel daemon) can be used to configure the tunnels.

CONFIGURATION

The following configuration directives can be used inside httpd.conf (or some other file in the conf.d directory) to control the behaviour of Apache::HTTunnel.

Please note that HTTunnelFifo and HTTunnelConnectionTimeout must be used before the PerlPostConfigRequire directive since they are used at startup time. The other directives can be specified at the Location level.

HTTunnelFifo

Specifies the path to be used for the fifo that allows communication between the keeper process and the Apache workers.

Ex: HTTunnelFifo              /var/lib/httunnel/httunnel.sock

There is no default value. This directive is mandatory.

HTTunnelConnectionTimeout

Specifies the number of seconds after which inactive connections will be closed. The connection table is checked at least every 15 seconds.

Ex: HTTunnelConectionTimeout  900

The default value is 900, meaning connections idle for more than 15 minutes will be closed.

HTTunnelForceHost

Specifies the forced host. Clients using this URL will not be able to choose the remote host.

Ex: HTTunnelForceHost         somehost

The default value is undef, meaning clients can request connections to any host.

HTTunnelForcePort

Specifies the forced port number. Clients using this URL will not be able to choose the remote port number

Ex: HTTunnelForcePort         22

The default value is undef, meaning clients can request connections to any port number.

HTTunnelMaxConnectTimeout

When a client sends a connection request, it may specify a timeout value for the connection. In order to prevent blocking in the Apache child in cases when the connection blocks, this directive limits the connection timeout that may be specified by the client.

Ex: HTTunnelMaxConnectTimeout 10

The default value is 15 seconds. It is best to keep the value relatively low to prevent blocking in the Apache child.

HTTunnelMaxReadTimeout

HTTunnel::Client needs to poll to check if there is some data to be read from the remote socket. In order to not be troubled by proxies or other intermediaries that may terminate long lasting connections prematurely, Apache::HTTunnel will purposely time-out read requests that take longer than HTTunnelReadTimeout seconds. A special response is sent to the client telling it to retry the read request.

Ex: HTTunnelMaxReadTimeout    10

The default value is 15 seconds. It is best to keep the value relatively low to prevent blocking in the Apache child.

HTTunnelMaxReadLength

The maximum number of bytes that a client may request for a read.

Ex: HTTunnelMaxReadLength     16384

The default value is 131072 bytes.

SECURITY

Please keep in mind that HTTP is not, by default, encrypted. Further more, you will most certainly want to control which users are permitted to use the /httunnel URL since it can provide an entry point into your network.

For these reasons, the use of SSL and Basic Authentication is strongly recommended. See the Apache documentation (mod_ssl, mod_auth) for more information on how to configure these features.

BUGS

I'm sure there are some in there :)

SEE ALSO

File::FDkeeper, File::FDpasser, LWP

AUTHOR

Patrick LeBoutillier, <patl@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2005 by Patrick LeBoutillier

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