Quick-start guide to get up and running within minutes

SwiperProxy has few dependencies and can be installed in practically all major distributions.


Dependencies

  • Python, 2.7 or higher
  • Python IPY, 0.75 or higher
  • streamhtmlparser, 0.1 or higher

Installing

Select your distribution:


Debian 7 Wheezy, Debian 8 Jessie

Install the dependencies available from the stable repository:
$ apt-get install build-essential cython python python-dev python-ipy

Download and extract SwiperProxy:
$ mkdir /opt/SwiperProxy
$ wget https://github.com/SwiperProxy/swiperproxy/archive/v1.1.tar.gz \
-O /usr/local/src/swiperproxy-v1.1.tar.gz
$ tar -zxvf swiperproxy-v1.1.tar.gz
$ mv swiperproxy-v1.1 /opt/SwiperProxy/swiperproxy

Compile streamhtmlparser and the wrapper:
$ cd /opt/SwiperProxy/swiperproxy/include/streamhtmlparser
$ ./configure
$ make
$ make install
$ cd src/py-streamhtmlparser
$ make
$ make install

Copy the Python packages to a location where Debian will recognize them:
$ cp /usr/local/lib/python2.7/dist-packages/* /usr/lib/python2.7/dist-packages
$ ldconfig -v

Create the runtime environment and add an unprivileged user:
$ mkdir /var/log/swiperproxy
$ addgroup --system swiperproxy
$ adduser --system swiperproxy --ingroup=swiperproxy --home=/opt/SwiperProxy/swiperproxy
$ chown swiperproxy:swiperproxy /var/log/swiperproxy
$ chown -R swiperproxy:swiperproxy /opt/SwiperProxy/swiperproxy


CentOS/RHEL 7

Install the dependencies available from the repository:
$ yum install Cython python-devel python-IPy wget

Install tools required to compile libraries:
$ yum groupinstall 'Development Tools'

Download and extract SwiperProxy:
$ mkdir /opt/SwiperProxy
$ wget https://github.com/SwiperProxy/swiperproxy/archive/v1.1.tar.gz \
-O /usr/local/src/swiperproxy-v1.1.tar.gz
$ tar -zxvf swiperproxy-v1.1.tar.gz
$ mv swiperproxy-v1.1 /opt/SwiperProxy/swiperproxy

Compile streamhtmlparser and the wrapper:
$ cd /opt/SwiperProxy/swiperproxy/include/streamhtmlparser
$ ./configure
$ make
$ make install
$ cd src/py-streamhtmlparser
$ make
$ make install

Copy the shared libraries to a location where the distribution will recognize them:
$ cp /usr/local/lib/* /usr/lib
$ ldconfig -v

Create the runtime environment and add an unprivileged user:
$ mkdir /var/log/swiperproxy
$ groupadd -r swiperproxy
$ useradd -d /opt/Swiperproxy/swiperproxy -g swiperproxy -M -r swiperproxy
$ chown swiperproxy:swiperproxy /var/log/swiperproxy
$ chown -R swiperproxy:swiperproxy /opt/SwiperProxy/swiperproxy


Configuring

All configuration is done in the proxy.conf configuration file. A default configuration file detailing each configuration option is supplied.

The most important settings are:

  • http_listen_port, https_listen_port: The HTTP and HTTPS ports the proxy will listen on. You can configure the listen ports to be 80 and 443 and let users access the proxy directly by using libcap. You can also place a reverse proxy in-front of SwiperProxy. In that case, the listen ports should be different.
  • http_port, https_port: These are the ports the proxy is reachable on from the outside. They may be different from the listen addresses, for example in case of a reverse proxy.
  • https_certificate: A Base64-encoded DER file that contains the SwiperProxy x.509 certificate, if necessary an intermediate CA certificate and the private key.
  • hostname: The hostname SwiperProxy is reachable on.
  • block_robots: If you want to ensure that web spiders/crawlers do not try to crawl the entire internet through your proxy, you can set this setting to yes.
  • [rewrites]:: Under this section, you can add custom rewrites for specific hostnames. The syntax is hostname=newhostname. For instances, if you want to ensure that http://www.example.org/ does not pass through the proxy, you could create the following rewrite: www.example.org=www.example.org. You can also rewrite a specific hostname to pass through a different proxy: www.example.org=proxy2.example.com/www.example.org.

As a final configuration step, you will need to edit the index.html file found in the html directory. Change the example hostname found in that file to your selected hostname. Of course you can also apply custom styling, change the logo, etc.

You may want to optionally add a wildcard DNS-record to your proxy, e.g. IN A *.proxy.example.org. This allows people to also browse to, for example, http://example.org.proxy.yourdomain.tld which will be rewritten to http://proxy.yourdomain.tld/example.org. This works, even when forcing HTTPS, though will likely always throw a certificate warning.


Running SwiperProxy

$ sudo -u swiperproxy python Proxy.py -c proxy.conf or run as a daemon.