NAME

App::HTTP_Proxy_IMP - HTTP proxy with the ability to inspect and modify content

SYNOPSIS

    # only use cmdline args
    App::HTTP_Proxy_IMP->new(@ARGV)->start;             
    # only use given args
    App::HTTP_Proxy_IMP->new(\%options)->start;         
    # combine cmdline args with given defaults
    App::HTTP_Proxy_IMP->new(\%options,@ARGV)->start;   

    # short for App::HTTP_Proxy_IMP->new(...)->start;
    App::HTTP_Proxy_IMP->start(...);

    # show cmdline usage
    App::HTTP_Proxy_IMP->usage();

DESCRIPTION

App::HTTP_Proxy_IMP implements an HTTP proxy, which can inspect and modify the HTTP header or content before forwarding. Inspection and modification is done with plugins implementing the Net::IMP interface.

The proxy is single-threaded and non-forking, but due to the event-driven model it can still process multiple connections in parallel. It is mainly intended to be used as a platform for easy prototyping of interesting ideas using IMP plugins, but should be also fast enough to be used to enhance, secure, restrict or protocol the browsing experience for small groups.

Public Methods

• new([\%OPTIONS],[@ARGV])

  Creates a new object. The first argument might be an hash reference with options. All other arguments will be used as ARGV for cmdline parsing and might result in overwriting the defaults from OPTIONS.

  The following options and its matching cmdline arguments are defined:

  filter ARRAY | -F|--filter mod

  List of IMP filters, which should be used for inspection and modification. These can be a fully qualified name, or a short name, which need to be combined with one of the given namespace prefixes to get the full name. It can also be already an IMP factory object.

  The cmdline option can be given multiple times. If '-' is given as name on the cmdline all previously defined filters are discarded.

  impns ARRAY | --imp-ns prefix

  Namespace prefixes to make adding filters from cmdline shorter. Defaults to App::HTTP_Proxy_IMP::IMP, Net::IMP.

  The cmdline option can be given multiple times. If '-' is given at cmdline all previously defined prefixes (including defaults) are discarded.

  addr [spec+]

  Array of listener/upstream specifications for proxy. Each specification can be

  ip:port - address where the proxy should listen

  ip:port=target_ip:port - listener address and upstream proxy address

  socket - precreated listener socket

  [ socket, target_ip:port ] - precreated listener socket and address of upstream proxy

  On the cmdline these are given as the remaining arguments, e.g. after all other options.

  mitm_ca proxy_ca.pem

  When this parameter is given it will intercept SSL connections by ending the connection from the server at the proxy and creating a new connection with a new certificate signed by the given ca.pem (e.g. man in the middle). Thus it will be able to analyse and manipulate encrypted connections.

  ca.pem needs to include the CA cert and key in PEM format. Also you better import the CA certificate into your browser, or you will get warnings on access to SSL sites, because of the correctly detected man in the middle attack.

  To generate the proxy certificate you might use openssl:

     openssl genrsa -out key.pem 1024
     openssl req -new -x509 -extensions v3_ca -key key.pem -out proxy_ca.pem 
     cat key.pem >> proxy_ca.pem
     # export to PKCS12 for import into browser
     openssl pkcs12 -export -in proxy_ca.pem -inkey proxy_ca.pem -out proxy_ca.p12

  It will try to create the directory proxy_ca.pem.cache and use it as a cache for generated cloned certificates. If this is not possible the cloned certificates will persist over restarts of the proxy.

  capath certs.pem | cert-dir

  The path (file with certificates or directory) with the CAs, which are used to verify SSL certificates when doing SSL interception. If not given it will check initially for various path, starting with using Mozilla::CA, trying /etc/ssl/certs and /etc/ssl/certs.pem before giving up and exiting.

  no_check_certificate

  If true disables checking of SSL certificates when doing SSL interception.

  childs N

  If N>0 it will fork N children to handle the requests. Whenever a child exits it will be restarted immediatly. This can be used to spread the load over multiple processors or to keep the proxy running, even if a child crashed.

  max_connect_per_child N | --maxconn N option

  If N>0 the child will fork itself after N connections to handle the unfinished connections. The parent will immediatly restart the child. If options childs is not greater than 0 this option will be ignored. This option is useful if the childs are leaking memory due to bad IMP plugins.

  The following options are only for the cmdline

  -d|--debug [RX]

  Enable debugging. If RX is given it will be used as a regular expression to restrict debugging to given packages.

  Outside the cmdline these settings can be done by setting $DEBUG and $DEBUG_RX exported by App::HTTP_Proxy_IMP::Debug.

  -T|--trace T

  Enable tracing for Net::Inspect modules. Outside the cmdline these settings can be done by setting %TRACE from the Net::Inspect::Debug package.

• start

  Start the proxy, e.g. start listeners and process incoming connections. No arguments are expected if called on an object, but one can use the form App::HTTP_Proxy_IMP->start(@args) as a shorter alternative to App::HTTP_Proxy_IMP->new(@args)->start.

  If no return value is expected from this method it will enter into an endless loop by calling loop. If a value is expected it will return 1, and the caller hast to call loop itself.

• loop

  Class method, which calls AnyEvent mainloop using AnyEvent->condvar->recv and handles all callback send by once.

• once

  Sometimes it is necessary to let the current event handler finish, before calling some specific action. The class method once schedules a subroutine to be called outside any other event handlers.

Reaction to Signals

The installs some signal handlers:

SIGUSR1

Dump current state to STDERR, e.g. active connections and their state.

SIGUSR2

Toggles debugging (e.g. enable|disable).

AUTHOR

Steffen Ullrich <sullr@cpan.org>

COPYRIGHT

Copyright 2012,2013 Steffen Ullrich.

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