Netgate is offering COVID-19 aid for pfSense software users, learn more.
A Brief Introduction to Web Proxies and Reporting: Squid, SquidGuard, and Lightsquid¶
This section is not meant to be a formal, detailed, and comprehensive how-to for using Squid and other related web proxy software, but a quick run-through to get it up and running and to cover the most commonly asked questions about their capabilities. This section covers Squid for caching web pages and related tasks, SquidGuard for filtering and controlling access to web content, and Lightsquid for reporting user activity based on the Squid access logs.
This discussion assumes the pfSense® firewall has a simple single LAN and single WAN configuration. If problems occur during this configuration, visit the pfSense Documentation Wiki and pfSense Forum for additional guidance and assistance.
For additional information, you may access the Hangouts Archive to view the March 2014 hangout on Squid, SquidGuard, and Lightsquid.
HTTPS traffic cannot be transparently intercepted in nearly all cases, this section only covers transparently capturing HTTP traffic. See Transparent Proxies and HTTP/HTTPS for details.
Squid Caching Web Proxy¶
Squid is the foundation of many other tasks that start with a proxy: It can act as a cache for improving web performance, it can hook into SquidGuard for content filtering, and its logs provide the basis for reporting on where users are going on the web.
Before anything else, the Squid package must be installed. Once installed, the package must be configured. The Squid configuration is broken up into several tabs. Before leaving a tab, click Save.
To start the configuration, navigate to Services > Squid Proxy Server.
Configure the Squid settings as follows, starting with the General tab:
- Enable Squid Proxy
- Keep Settings
- Proxy Interfaces
- Allow users on Interface
Checked, so that LAN users will be allowed to use the proxy.
- Transparent HTTP Proxy
Checked, so client HTTP traffic will be intercepted.
- Bypass proxy for Private Address Destination
Checked, so that local and VPN traffic will bypass the proxy.
- Bypass Proxy for these Source IPs
If certain local client IP addresses need to bypass the proxy, put them in this box. Multiple addresses, networks, or alias names may be entered separated by a semicolon.
- Bypass Proxy for these Destination IPs
If certain remote servers need to bypass the proxy, put them in this box. Multiple addresses, networks, or alias names may be entered separated by a semicolon.
- Enable Access Logging
If pfSense is running on a full install (NOT embedded/NanoBSD) and web access reporting is desired, check this box.
- Visible Hostname
Enter the hostname of the firewall as presented to clients in proxy error messages.
- Administrator E-mail
Enter a usable contact address. If a user encounters a proxy error, this will be shown to the user so they may contact the address for support.
Save settings, then change to the Local Cache tab and configure it as follows:
- Hard Disk Cache Size
Set this to a value that is reasonable for the available drive space and RAM. If running NanoBSD, enter
- Hard Disk Cache System
If running NanoBSD, set this to
Other parameters on this tab can be tweaked as needed to control the size of objects to be cached, how much memory can be used for caching, and other related settings. Save the settings before navigating away from the page.
If there are more local subnets behind a static route on the LAN, visit the Access Control tab and add them into the Allowed Subnets list.
After these configuration steps have been completed, the proxy will be up and running. If transparent mode is in use, loading a proxy test site such as http://www.lagado.com/proxy-test will now reveal that the request was routed through a proxy.
SquidGuard Web Access Control and Filtering¶
The SquidGuard package enables very powerful URL content filtering and access control. It can use blacklists or custom lists of web sites, and can selectively allow or deny access to those sites. SquidGuard can work on full installs and NanoBSD, but blacklists may only be used on full installations. SquidGuard is capable of much more than will be covered in this section. Visit the pfSense Documentation Wiki and pfSense Forum for more information and related tutorials.
To use SquidGuard:
Install and configure Squid as described in the previous section
Install the SquidGuard package
Navigate to Services > Proxy Filter to configure SquidGuard.
Navigate to Services > SquidGuard Proxy Filter, General Settings tab
Check Enable to enable SquidGuard
Check boxes to optionally enable other desired features, such as block event logging and GUI event logging
After saving the settings on any tab in SquidGuard, always return to the General Settings tab and click the Apply button. Until that action has been taken, the new SquidGuard settings will not be used.
Blacklists are predefined lists of sites in specific categories, such as Social sites, Adult sites, Music sites, and Sports sites. To use blacklists, check Blacklist and fill in a Blacklist URL. The two most common lists are the MESD list and the Shalla list.
Blacklists do not work properly on NanoBSD. Do not attempt to use them on that platform.
Before the blacklist may be used, it must be downloaded and unpacked. To do this, after saving the settings on this tab, visit the Blacklist tab and click Download.
If only blacklists are used, SquidGuard may fail. Define at least one Target Category as detailed in Target Categories.
Target Categories are custom lists of sites or other expressions that define a group of items that can be used to allow or deny access. They are maintained on the Target Categories tab.
When adding a new Target Category, a few options are required:
The Name for the category, as it will appear for selection on ACLs. The name must have between 2 and 15 alphanumeric characters, and the first character must be a letter.
- Domain List
This is the list of domain names to block, such as
microsoft.com, etc. Multiple domains may be entered, separated by a space.
- Redirect mode
This option controls what happens when a user is blocked by a site in this list. The default of none will not redirect the user. The most common setting is int error page.
If the user is redirected using int error page, enter the error message that will be presented to the user here. If an external redirect type is used, enter the full URL to the desired target site, including the proper protocol such as
Access Lists (ACLs)¶
There are two types of ACL entries in SquidGuard:
Common ACL, which is the default ACL applied to all users
Group ACL entries which are applied to specific IP addresses, groups of IP addresses, or Networks.
First, visit the Common ACL tab. Choose the default actions for all available categories from blacklists or those defined locally. To do this, click Target Rules List , and pick the desired actions from the drop-down at the end of the row for each category. The Default Access [all] choice controls what happens when no match has been found in any of the available categories.
After saving the settings, change to the Group ACL tab to create an entry for a specific user or group of users. Using a Group ACL, an exception to the Common ACL rules may be crafted, either to block access to a site others can reach, or to allow access to a site that others are blocked from viewing.
To create a Group ACL:
Change to the Group ACL tab
Click Add to start a new entry and configure it as follows:
The name of the ACL
- Client (source)
Enter the user’s IP address, subnet, etc. Multiple values can be entered, separated by spaces.
- Target Rules List
Defines the list of actions for this specific set of users
Return to the General Settings tab
Lightsquid Web Access Reporting¶
Lightsquid is used to create reports that detail the web history of computers that have accessed sites through the proxy. After the Lightsquid package has been installed, the report settings may be found under Status > Squid Proxy Reports.
This feature is not compatible with embedded/NanoBSD installs without manual modifications that are beyond what most users are capable of performing.
The look and feel of the reports may be customized by choosing the Language, Bar color, and Report Scheme.
The Refresh scheduler option controls how often the report will be automatically updated, e.g. every 30 minutes.
Click Save to store the settings and then click Refresh Full to build the initial report. Wait a few minutes, then click the Open Lightsquid button to view the report.
If there is no data in the report, check to make sure that Enable Logging is set in Squid, and that the user traffic is going through the proxy as expected.
Transparent Proxies and HTTP/HTTPS¶
When using a proxy, it is only possible to intercept HTTP traffic transparently. That is, only HTTP traffic may be grabbed automatically and forced through a proxy without intervention from the user or their knowledge. This is convenient, since it does not require configuring any settings on the user’s PC. The downside is that only HTTP traffic may be captured using this method; It is not possible to intercept HTTPS in the same way.
Attempting to transparently intercept HTTPS would break the chain of trust created by SSL, causing the user to be greeted with a scary certificate warning when they attempt to access a secure site. This warning would be valid in that case, because the proxy is essentially performing a man-in-the-middle attack in order to inspect the user’s traffic.
The Squid proxy package is capable of intercepting HTTPS, but it cannot be done completely without the knowledge of the user or alterations to their computer. At a minimum, intercepting HTTPS requires the installation of a trusted root CA that has been created for this purpose, so that the proxy can appear to use valid certificates.
The best method is to place the proxy settings into the user’s computer and/or browser software. This task can be done manually, via GPO on a Windows Domain, by DHCP, or automatically using WPAD. The details of those are beyond the scope of this book, but there is information on many of those tactics on the pfSense Documentation Wiki and pfSense Forum.