E2Guardian and the content filtering proxy that runs three ways

One filter, three deployment shapes

E2Guardian is described as a content filtering proxy that can work in explicit and transparent proxy mode or as an ICAP server mode, and the topic list spells the same thing out with proxy, transparent-proxy, transparent-https-proxy, icap-server, squid, http1-1, https, openssl and ssl among the tags.

The three modes matter more than they might appear, because they change what you have to build around the filter.

In explicit proxy mode, E2Guardian is the proxy. Clients are configured to talk to it, it makes the request on their behalf, and it decides whether to pass the response through or to replace it with a block page. That is the simplest arrangement and the least useful for a network you do not control, because every client has to be pointed at it.

In transparent proxy mode, the filter is invisible. Traffic is redirected to it at the network layer, so no client is configured, and the filter sees the original request. That is the mode for a school or a company network, and it requires you to run the interception yourself.

In ICAP server mode, E2Guardian is not the proxy at all. It implements the ICAP protocol, and another proxy does the connecting while delegating the filtering decision to it. The README points at a container image for Squid on Docker Hub with the note that there is no support here, and the topics include squid. So the intended architecture for a large deployment is Squid in front, E2Guardian behind it as the filter, and the two coordinated rather than merged.

That is the design decision worth understanding before you install anything. The same filtering engine can be a whole network appliance or a component in a larger one, and the choice is about what you already run rather than about what the software does.

The Dansguardian lineage and the list-driven configuration

E2Guardian descends from Dansguardian, and the topics list carries both names, which is the clearest signal about where the design comes from. The dansguardian topic alongside the e2guardian name signals this shared ancestry, and the README points to the comments in the configuration and list files themselves as the place where the filtering options are documented.

The distinction matters in practice. A URL list can say no to a path matching a pattern, and a phrase list can say no to a page containing a phrase, which is how the filter handles content that arrives on URLs you did not think to block. The README refers to the comments in the configuration and list files themselves as a source of information, which tells you the policy surface is files with inline documentation rather than a database or a web console.

That is a feature for the audience this software serves. A school or a library that wants to allow a site for a specific department edits a list file. The trade is that list files grow, and a large deployment ends up with a configuration management problem rather than a software problem, which is a familiar shape for this class of tool.

The notes/ directory in the distribution is where the operational detail lives, and the README points at it explicitly along with the comments in the configuration files. There is a doc/ directory for documentation and a contrib/ directory, which is the conventional place for the scripts and configuration fragments that get copied onto a deployment.

The topic list also names scalable, which points at the fact that this kind of filter sits in the request path and therefore has to keep up with the traffic it inspects. A filter that inspects response bodies is doing considerably more work per request than one that only matches URLs, and that difference is the main reason the content filtering side of this software is the expensive half.

Building it from the repository, and the packaging options

The repository is an autotools project with a CMakeLists.txt also present at the root. There is a configure.ac, an autogen.sh, a Makefile.am, m4/ for the autoconf macros, and gitlabci/ plus a .gitlab-ci.yml for the pipeline. The src/ directory holds the C++ sources, data/ holds the shipped data files, configs/ holds the configuration templates, and ChangeLog, ChangeLog3.x, ChangeLog4.x, DGChangeLog and NEWS record the history across those versions, which is a useful signal of how long this codebase has been in use.

For most deployments you would not build it. The README points at the INSTALL file for installation instructions, and at packages for Debian and Ubuntu at e2guardian.numsys.eu, plus official images on Docker Hub under fredbcode/e2guardian. The Docker route is the one that suits a quick evaluation, since the native packages assume a particular distribution layout.

The build itself is not where the difficulty lies. The difficulty is in the configuration, and the README is unusually clear about that. It instructs you to read notes/NEWIN_v5 before installing, and to read notes/Upgrading_to_V5.4 if you are coming from an earlier version, and it warns that some configuration files in this version are not fully backward compatible with v5.4 configuration files.

That warning is the most useful line in the readme for an evaluator. It tells you that a v5.4 deployment cannot simply be pointed at a v5.5 binary, which is exactly the kind of thing that turns a weekend evaluation into a weekend project.

The copyright notice is also worth reading before you plan a deployment. It is held by Frederic Bourgeois, Philip Pearce and others, the code is GPL version 2, and there is a special exception permitting the code to be linked with the OpenSSL project library, or modified versions of it under the same licence, with the linked executables distributed, subject to the GPL applying to everything other than OpenSSL. The exception can be extended if you modify the file, and can be deleted if you would rather not carry it. The reason it exists is visible in the topic list, where openssl and ssl both appear, since TLS interception is the feature that makes the transparent modes work on HTTPS traffic.

The frozen branch, and what that means for an adopter

The readme states the version situation directly. It is the stable v5.5 version at v5.5.8r, and development of v5.5 is now frozen, with only bug fixes to be applied in the v5.5 branch.

There is an inconsistency in the repository worth flagging. The readme says the stable version is v5.5.8r, while the release list shows v5.5.9r as a stable release dated 2025-08-22, with v5.5.8r before it. The default branch is named v5.5, and the last push was on 2026-10-22, so work is continuing on the branch. Which of the two is current is something to check against the releases rather than take from the readme.

The freeze is the important fact for a decision. It is not a criticism; a mature filtering product freezing a branch to take bug fixes is a reasonable way to keep a stable deployment stable. It does mean that new features arrive on a different branch, and that a long-lived deployment will eventually face a version transition of the kind the readme already warns about for v5.4 to v5.5.

The contributing guidance is brief and points to where changes belong. Bugfixes primarily occur in the version branch, and there is a GitHub organisation for the project, an issues tracker for bugs and feature requests, a community forum on Google Groups, and a wiki described as holding helpful information. There is also a Codacy badge for code quality, and the project has a.gitlab-ci.yml, so the continuous integration runs on GitLab rather than GitHub Actions.

The practical reading for a team evaluating this is that you are adopting a mature, slowly moving project with a real community and real packaging, and you should plan on a version upgrade at some point rather than assuming the branch you install today is the branch you will still be running in three years.

Where E2Guardian is the wrong choice

Three boundaries are worth stating plainly.

The first is the operational weight of the network role. The transparent modes need packet interception, TLS interception with a certificate your clients trust, and the DNS and firewall rules to make it work. The ICAP mode assumes a proxy already exists and trusts it to do the connecting. Either way you are running a component in the path of every request, and the failure mode when it stalls is that nothing loads.

The second is the configuration surface. The filtering policy lives in list files with their own comment conventions, and the readme points at the notes directory rather than at a simpler mental model. A school with a dozen departments and a different policy for each will end up managing configuration rather than configuring a product, and that is real work that does not show up in the feature list.

The third is that content filtering is a blunt instrument. Phrase and URL matching will produce false positives on legitimate material and false negatives on material the lists do not cover, and no list engine fixes that. If the goal is preventing access to a category of site, a DNS-level or IP-level blocklist is simpler and has no interception cost, and if the goal is compliance logging rather than blocking, the interception is unnecessary work.

The alternative worth comparing against is a different class of tool for a different goal. A DNS resolver with per-category blocking handles the coarse cases with no TLS interception and no list maintenance, at the cost of working only at the hostname level. A dedicated TLS inspection appliance from a vendor handles the fine cases with support and updates, at a cost in money. E2Guardian sits in the middle: the full filtering capability of the Dansguardian family, in open source, with the operational burden of running a proxy in the path of your traffic, which is why the ICAP mode and the Squid image matter for anyone with an existing proxy.

Editorial conclusion

E2Guardian is a good fit for a school, library or company that needs URL and phrase filtering on HTTPS traffic and already runs a proxy stack, because the ICAP mode lets it sit behind Squid rather than replacing it, and the list-driven configuration means policy is data rather than code. It is a poor fit for a small home network with no proxy infrastructure, since the transparent and ICAP modes assume a network you control, and a poor fit if you need a supported upstream, since the v5.5 branch is frozen to bug fixes only. Before deploying, read the INSTALL file in the repository and the notes/NEWIN_v5 document, because the v5.5 configuration is not fully backward compatible with v5.4 configuration files.

Frequently asked questions

Official sources

1. e2guardian/e2guardian on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases