Polipo Configuration Guide: Key Settings Explained

Polipo configuration lives in a plain text file made of simple name = value lines. Once you understand a handful of variables, you can control who connects, where the cache is stored, how much memory is used and whether traffic goes through another proxy. This guide walks through the settings people change most often.

Every example here uses option names documented in the project's manual. Values are examples, not recommendations for every network, so adapt them to your own setup and test after each change.

Where the Configuration File Lives

A system-wide configuration is commonly read from /etc/polipo/config, and a per-user file from ~/.polipo. You can also point the program at any file with the -c option, which is handy when testing a new configuration without touching the live one.

Variables can be set on the command line too, using the same name=value form. That is useful for quick experiments, for example starting a second instance on another port without editing any file.

polipo -c ~/polipo-test.conf
polipo proxyPort=8124

Seeing current values

The built-in local interface, reached at the proxy address under /polipo/, can display current variables. Running the binary with -v lists the variables it knows about, which is a reliable way to check spelling before editing.

Listening Address and Port

Two variables decide where the proxy accepts connections. proxyAddress sets the interface, and proxyPort sets the port, which defaults to 8123. Binding to 127.0.0.1 limits access to the same machine and is the safest starting point.

proxyAddress = "127.0.0.1"
proxyPort = 8123

To serve other machines on your home network, set the address to 0.0.0.0 or a specific LAN address and combine it with the access controls described next. Never open the proxy to the public internet without strict client limits.

Controlling Which Clients Connect

The allowedClients variable lists the addresses or networks permitted to use the proxy. Anything outside the list is refused, so it is the most important protection when the proxy listens beyond localhost.

proxyAddress = "0.0.0.0"
allowedClients = 127.0.0.1, 192.168.1.0/24

Disk Cache Settings

diskCacheRoot points to the directory used for on-disk caching. The directory must exist and be writable by the account running the proxy. Setting it to an empty string disables the disk cache entirely, which can be useful when you only want forwarding.

Housekeeping variables such as diskCacheTruncateSize and diskCacheUnlinkTime influence how cached files are trimmed and removed over time. The cache management guide explains how they interact with the expiry run.

Memory Limits

The proxy also keeps objects in memory. Variables like chunkHighMark and objectHighMark set upper limits on memory used for data chunks and for the number of objects. On small systems, lowering these values keeps memory use predictable.

Parent Proxies

To send traffic through another HTTP proxy, set parentProxy to its host and port. To use a SOCKS proxy instead, set socksParentProxy and choose the protocol with socksProxyType, such as socks5. A detailed walkthrough is in the SOCKS and Tor guide.

socksParentProxy = "localhost:9050"
socksProxyType = socks5

Privacy-Related Options

Some headers reveal information about the client. The censoredHeaders variable lists headers to remove from outgoing requests, and censorReferer controls how the Referer header is handled. Removing too much can break sites, so change these gradually.

• censoredHeaders: headers stripped from requests, for example from, accept-language.
• censorReferer: whether and when the Referer header is removed.
• forbiddenFile: a file of URL patterns the proxy refuses to fetch.

Locking Down the Local Interface

The built-in web interface is convenient, but on shared machines you may not want users changing settings through it. Variables such as disableLocalInterface and disableConfiguration restrict it. Setting them is a sensible step whenever more than one person can reach the proxy.

A Balanced Example Configuration

The example below suits a small home network: it listens on the LAN, restricts clients, caches to disk and disables remote configuration. Adjust the network range and paths before using it.

proxyAddress = "0.0.0.0"
proxyPort = 8123
allowedClients = 127.0.0.1, 192.168.1.0/24
diskCacheRoot = "/var/cache/polipo/"
disableConfiguration = true
censoredHeaders = from, accept-language

Ports for Tunnels and Requests

Two more variables control which destination ports clients may reach. allowedPorts limits ports for ordinary proxied requests, and tunnelAllowedPorts limits ports for CONNECT tunnels used by HTTPS. Keeping these lists narrow prevents the proxy from being used to reach unusual services.

Make sure port 443 stays in the tunnel list, otherwise secure websites will fail. If an internal service uses a non-standard port, add only that port rather than opening a broad range.

DNS Options

The proxy can resolve names itself. dnsNameServer sets the resolver it queries, and dnsQueryIPv6 controls whether IPv6 records are requested. On networks without working IPv6, adjusting the latter can remove long delays before connections are made.

Logging and Running in the Background

logFile sets where messages are written, while daemonise and pidFile let the program detach and record its process ID. These settings matter when you run it without a service manager.

Polipo Configuration FAQs

Conclusion

Polipo configuration is straightforward once you know the core variables: address and port for listening, allowedClients for access, diskCacheRoot for the cache, memory limits for small machines and parent proxy settings for chaining. Start with localhost only, then widen access carefully.

After each change, restart the proxy and test with a client. If a setting does not seem to apply, the troubleshooting guide lists the usual causes.