Cell PhonesComputersConsumer ElectronicsGraphic Design & Video EditingHome Theater & AudioIndustrial TechnologyInternet

How to Set Up a Polipo Caching Web Proxy Server on pfSense

Updated on May 4, 2016
skear profile image

Sam works as a Network Analyst for an algorithmic trading firm. He obtained his Bachelors Degree in Information Technology from UMKC.

Benefits of Using the Polipo Proxy Service

Polipo has several great features that make it a good alternative to other more popular proxies such as Squid. The most attractive of these features is HTTP pipelining.

Pipelining allows the proxy to send multiple HTTP requests on a single connection without having to wait for replies to come back. The increased efficiency pipelining provides can provide a big improvement in web browsing speed.

Another great feature of Polipo is its ability to cache partial instances. If a connection becomes interrupted during a request the proxy will store the part of the request that was already completed as a partial object.

When a new request for the same object is received the proxy can request only the missing part of the request by using an HTTP range request

Polipo isn't currently available as a pfSense package but since a FreeBSD version already exists it can still be installed relatively easily.

The process involves editing a few config files but trust me it's well worth the effort!

Why do you use a proxy server on your network?

See results

Installing the Polipo Package

Since Polipo isn't an officially supported package it cannot be installed through the pfSense package manager. Instead Polipo must be installed through the command line shell using the pkg_add command.

pkg_add -r ftp://ftp-archive.freebsd.org/pub/FreeBSD-Archive/ports/i386/packages-8.1-release/Latest/polipo.tbz

The above command can also be executed through the execute command feature in the diagnostics menu or through an SSH terminal session.

Polipo is a very small package so it will not take very long to install..

Polipo can be installed through an SSH terminal or the web based command prompt.
Polipo can be installed through an SSH terminal or the web based command prompt.

Creating the Polipo Config File

The Polipo package installs a sample configuration file that can be edited to suit your network. Run the commands below to copy the sample configuration file to a new file called config.

cd /usr/local/etc/polipo/
cp config.sample config

Next edit the config file using either the vi editor or the web based file editor (Diagnostics \ Edit File)

vi config

Uncomment the following line in the basic configuration section of the config file. This instructs Polipo to listen on all interfaces on the system.

proxyAddress = "0.0.0.0" # IPv4 only

To secure the proxy uncomment the following line and change the network address to match the lan subnet of your local network.

Due to a bug in the FreeBSD Polipo package you must remove the double quotes from the command line. If you forget to remove the quotes you'll see the message "Couldn't parse network" when you attempt to start Polipo.

allowedClients = 127.0.0.1, 192.168.10.0/24

The web based file editor provides a quick and easy way to modify the configuration file.
The web based file editor provides a quick and easy way to modify the configuration file.

Optional Config File Tweaks

Parameters
Description
proxyName = "polipo.example.org"
This field can be used to change the name of the proxy displayed on error messages.
chunkHighMark = 50331648 objectHighMark = 16384
On boxes with plenty of memory these lines can be uncommented to improve performance.
diskCacheRoot = ""
Uncommenting this line disables the disk based cache and runs in memory only caching mode.
disableIndexing = false disableServersList = false
Uncomment these lines to enable the known servers and disk cache index pages on the web interface.
proxyPort = 3128
This variable can be used to modify the port Polipo runs on.
This table contains a few parameters you may want to modify in the Polipo configuration file.

Editing the rc.conf File

Before the Polipo server will start the rc.conf file must be modified to contain polipo_enable=yes. On pfSense this file is located in the /etc/defaults directory.

This entry can be added to any location of the rc.conf file. In the example below I added it to the end of the file using the web based file editor.

If you prefer to use SSH you can use the following command to automatically append the config flag to the bottom of the rc.conf file.

echo "polipo_enable=yes" >> /etc/defaults/rc.conf

The rc.conf file must be modified in order for the Polipo server to start.
The rc.conf file must be modified in order for the Polipo server to start.

Setting Up the Init Script

To ensure that the Polipo service starts successfully it is necessary to modify the startup script. Add the commands below to the beginning of the /usr/local/etc/rc.d/polipo file right after the comments section.

[ -d /var/run/polipo ] || mkdir /var/run/polipo

chown -R polipo /var/run/polipo/

The first command creates the /var/run/polipo directory if it does not exist. The second command changes the owner of this directory to the Polipo user.

These extra commands are necessary due to the fact that pfSense deletes any extra directories in /var/run on system startup. Without these commands in the script Polipo will fail to run after a reboot.

The init script must be edited to allow Polipo to start automatically on boot.
The init script must be edited to allow Polipo to start automatically on boot.

Create the Startup Script

In order for pfSense to start Polipo automatically on boot a startup script must be created in /usr/local/etc/rc.d.

PfSense will automatically run any files in this directory ending in .sh during system startup.

The commands below will create create the polipo.sh startup script, and make the script executable.

touch /usr/local/etc/rc.d/polipo.sh

chmod +x /usr/local/etc/rc.d/polipo.sh

Once the script has been created copy and paste the contents below into the file and save it. As with the previous steps this can be done with the vi editor (vi /usr/local/etc/rc.d/polipo.sh) , or the web based file editor.

polipo.sh

#!/bin/sh

rc_start() {
/usr/local/etc/rc.d/polipo start
}

rc_stop() {
/usr/local/etc/rc.d/polipo stop
}

case $1 in
start)
rc_start
;;
stop)
rc_stop
;;
restart)
rc_stop
rc_start
;;
esac

Start the Polipo Proxy Service

Everything is finally in place to start the Polipo service.

/usr/local/etc/rc.d/polipo.sh start

To make sure that the service launched successfully check the Polipo log file.

tail /var/log/polipo

If everything is working properly you should see a message that states "Established listening socket on port 8123".

Starting the Polipo web proxy server using the SSH shell.
Starting the Polipo web proxy server using the SSH shell.

Testing the Proxy Server

Once Polipo is up and running it's time to test out the proxy server with a web browser. On computers running Windows 7 the proxy can be added through the internet options menu in the control panel.

From the internet properties menu click on the connections tap, then click on the LAN settings button.

Windows 7 Internet Properties Control Panel
Windows 7 Internet Properties Control Panel

Adding the Proxy Server IP

In the LAN settings control panel enable the checkbox 'Use a proxy server for your LAN'. Enter the LAN IP address of your pfSense server in the address box, then enter 8123 as the proxy port.

Port 8123 is the default port for polipo but it can be changed by adding the proxyPort variable to the config file.

Adding the proxy IP through the LAN settings control panel.
Adding the proxy IP through the LAN settings control panel.

Testing Internet Access

After adding the proxy IP and port save the settings then try to access a web page through a browser. If the page loads successfully then the Polipo proxy is functioning properly.

if web pages do not load then check to make sure that Polipo is running. The quickest way to check the status of the Polipo service is to run the command below.

/usr/local/etc/rc.d/polipo status

You should see a message indicating polipo is running as pid xxxxx.

Accessing the Polipo Web Interface

When the Polipo daemon is running the web interface for the server can be accessed on the lan interface on port 8123.

The web interface provides some useful status reports related to the current state of the proxy server.

The config page also allows you to view all of the currently configured settings.The config link also allows several parameters to be easily modified.

The Polipo web interface can be accessed by connecting to the LAN IP of the server on port 8123 using a browser.
The Polipo web interface can be accessed by connecting to the LAN IP of the server on port 8123 using a browser.

Additional Resources

The author of Polipo has created a lot of documentation for Polipo on his website. I would recommend reading through the FAQ section which contains several useful tips and tricks.

In the manual you'll find more in-depth details for almost any question you may have regarding Polipo.

© 2013 Sam Kear

Comments

    0 of 8192 characters used
    Post Comment

    • profile image

      JulioQc 2 years ago

      [-d /var/run/polipo ]

      should be

      [ -d /var/run/polipo ]

      Notice the space between the first bracket and the dash :)

    • skear profile image
      Author

      Sam Kear 2 years ago from Kansas City

      @JulioQc

      Thanks for bringing that to my attention, I have corrected it in the article.

    • profile image

      Jomar 23 months ago

      can you make a tutorial how to install it in windows? and can I use it on my laptop ? thanks

    • profile image

      Hero-man 2 months ago

      Bro , if i am installing Polipo Proxy Service , & in same time i want to use SquidGuard as web Filtering , is it possible

    Click to Rate This Article