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

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 = "" # 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 =,

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

proxyName = ""
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 startup script, and make the script executable.

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

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

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/ , or the web based file editor.


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

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

case $1 in

Start the Polipo Proxy Service

Everything is finally in place to start the Polipo service.

/usr/local/etc/rc.d/ 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.

This article is accurate and true to the best of the author’s knowledge. Content is for informational or entertainment purposes only and does not substitute for personal counsel or professional advice in business, financial, legal, or technical matters.

© 2013 Sam Kear


    0 of 8192 characters used
    Post Comment
    • profile image


      3 years ago

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

    • profile image


      5 years ago

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

    • skear profile imageAUTHOR

      Sam Kear 

      5 years ago from Kansas City


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

    • profile image


      5 years ago

      [-d /var/run/polipo ]

      should be

      [ -d /var/run/polipo ]

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


    This website uses cookies

    As a user in the EEA, your approval is needed on a few things. To provide a better website experience, uses cookies (and other similar technologies) and may collect, process, and share personal data. Please choose which areas of our service you consent to our doing so.

    For more information on managing or withdrawing consents and how we handle data, visit our Privacy Policy at:

    Show Details
    HubPages Device IDThis is used to identify particular browsers or devices when the access the service, and is used for security reasons.
    LoginThis is necessary to sign in to the HubPages Service.
    Google RecaptchaThis is used to prevent bots and spam. (Privacy Policy)
    AkismetThis is used to detect comment spam. (Privacy Policy)
    HubPages Google AnalyticsThis is used to provide data on traffic to our website, all personally identifyable data is anonymized. (Privacy Policy)
    HubPages Traffic PixelThis is used to collect data on traffic to articles and other pages on our site. Unless you are signed in to a HubPages account, all personally identifiable information is anonymized.
    Amazon Web ServicesThis is a cloud services platform that we used to host our service. (Privacy Policy)
    CloudflareThis is a cloud CDN service that we use to efficiently deliver files required for our service to operate such as javascript, cascading style sheets, images, and videos. (Privacy Policy)
    Google Hosted LibrariesJavascript software libraries such as jQuery are loaded at endpoints on the or domains, for performance and efficiency reasons. (Privacy Policy)
    Google Custom SearchThis is feature allows you to search the site. (Privacy Policy)
    Google MapsSome articles have Google Maps embedded in them. (Privacy Policy)
    Google ChartsThis is used to display charts and graphs on articles and the author center. (Privacy Policy)
    Google AdSense Host APIThis service allows you to sign up for or associate a Google AdSense account with HubPages, so that you can earn money from ads on your articles. No data is shared unless you engage with this feature. (Privacy Policy)
    Google YouTubeSome articles have YouTube videos embedded in them. (Privacy Policy)
    VimeoSome articles have Vimeo videos embedded in them. (Privacy Policy)
    PaypalThis is used for a registered author who enrolls in the HubPages Earnings program and requests to be paid via PayPal. No data is shared with Paypal unless you engage with this feature. (Privacy Policy)
    Facebook LoginYou can use this to streamline signing up for, or signing in to your Hubpages account. No data is shared with Facebook unless you engage with this feature. (Privacy Policy)
    MavenThis supports the Maven widget and search functionality. (Privacy Policy)
    Google AdSenseThis is an ad network. (Privacy Policy)
    Google DoubleClickGoogle provides ad serving technology and runs an ad network. (Privacy Policy)
    Index ExchangeThis is an ad network. (Privacy Policy)
    SovrnThis is an ad network. (Privacy Policy)
    Facebook AdsThis is an ad network. (Privacy Policy)
    Amazon Unified Ad MarketplaceThis is an ad network. (Privacy Policy)
    AppNexusThis is an ad network. (Privacy Policy)
    OpenxThis is an ad network. (Privacy Policy)
    Rubicon ProjectThis is an ad network. (Privacy Policy)
    TripleLiftThis is an ad network. (Privacy Policy)
    Say MediaWe partner with Say Media to deliver ad campaigns on our sites. (Privacy Policy)
    Remarketing PixelsWe may use remarketing pixels from advertising networks such as Google AdWords, Bing Ads, and Facebook in order to advertise the HubPages Service to people that have visited our sites.
    Conversion Tracking PixelsWe may use conversion tracking pixels from advertising networks such as Google AdWords, Bing Ads, and Facebook in order to identify when an advertisement has successfully resulted in the desired action, such as signing up for the HubPages Service or publishing an article on the HubPages Service.
    Author Google AnalyticsThis is used to provide traffic data and reports to the authors of articles on the HubPages Service. (Privacy Policy)
    ComscoreComScore is a media measurement and analytics company providing marketing data and analytics to enterprises, media and advertising agencies, and publishers. Non-consent will result in ComScore only processing obfuscated personal data. (Privacy Policy)
    Amazon Tracking PixelSome articles display amazon products as part of the Amazon Affiliate program, this pixel provides traffic statistics for those products (Privacy Policy)
    ClickscoThis is a data management platform studying reader behavior (Privacy Policy)