Installing SwiperProxy

This documentation uses generic instructions. For operating system-specific instructions, take a look at the Quick-start Guide.

Installing dependencies

You will need the following dependencies for SwiperProxy itself.

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

streamhtmlparser and its python module are included with SwiperProxy and needs to be compiled. For this, you will need:

A recent C-compiler like gcc
The Cython extensions
The Python development environment

You may install these in whatever way you prefer. Using your distribution's package manager is highly recommended.

Getting SwiperProxy

You can download an archive to extract, or clone from git. See the Downloads page for more information.

Set up the runtime environment

SwiperProxy should run as an unprivileged user that needs at least read-access to the SwiperProxy directory and configuration files (including the x.509 certificate) and read+write access to the log directory.

If you want the Proxy.py process to listen on privileged ports (below 1024), pass CAP_NET_BIND_SERVICE to the python binary.

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.