Skip to content

Configuration

Philip Pearce edited this page Nov 28, 2018 · 4 revisions

Overview

E2Guardian is a modern fork of Dansguardian and as such it shares much of its configuration variables and settings. A lot of good documentation already exists for Dansguardian that we invite users to take a look at. It may be or particular use to take a look at the big picture installation guide.That said that can be a lot to digest so a quick intro is provided below.

Differences

Similarities apart, many options are migrated from the main config file, e2guardian.conf, the the per group config file, e2guardianfx.conf and of course references to dansguardian, including the name of the config files, have been replaced with e2guardian.

Filtering group

Before we get into the nitty gritty of the config files it's important to understand a basic principle of E2G: filtering groups.

A filtering group is a way to identify one or more users who will share some settings, for example what's banned and what's allowed. This is key because many of the times when something doesn't work it can be due to the user having ended up in the wrong group or settings being added in the wrong place.

There are various ways that can be used to identify a user, but the two most common ones are authentication or ips/dns. For more information on filtering groups see the related DG's doc.

Filtering lists

When you install E2G you will find a directory called lists containing various lists to help you define what's allowed and what's blocked. There are 4 basic types of lists:

  • ban lists, to completely ban something
  • exception list, to trust something so that it's always allowed
  • a grey list, something in between a ban and exception (white) list, which trusts a site but still subjects it to content checking
  • phrase lists, that help you allow or ban pages based on the content (words) appearing on the page

For ban, exception and grey lists, there are 4 ways you can express them:

  • a straight site ban, ie example.com , which would ban example.com and any subdomain
  • a regular expression, ie *.css, which would allow all the css files
  • a url, to allow or ban a page, while the rest of the domain can be allowed/banned.
  • a mime type, especially useful for files

There's a lot more possible, but should be sufficient to get a decent basic setup.

Words/Phrase list

This is possibly the most interesting part of E2G because for most people creating a list of what's allowed and what's banned is hard to impossible. Rather ideally the content filter would just recognize when a page is "bad" and block it. Of course this is easier said than done and as a word of warning be ready to have to make adjustments over time.

Put it simply, a words/phrase list is just that, a list of words or phrases with a "score" assigned, either positive or negative. So for example you could have a list such as:

+100 -100 +100

In the group configuration file there is a setting called "naughtiness" which defines a threshold used by the algorithm to decide if a page should be blocked or not and the way it work is by adding the scores and comparing the total to that value.

So for example if you were to visit a page containing the words "cussing", "leaning linux" and "badness" its total score would be +100-100+100=100. If your naughtiness level is 50, ie less than the total, the page will be blocked, otherwise it will be allowed.

The problem with phraselists is that of course you can find good words on bad sites and viceversa so it's not unusual to find things banned when they shouldn't or the opposite and that's where tuning comes in.

For more information about phraselists and its syntax please take a look at the DG's docs

Basic E2G configuration

The main configuration file for e2g is called e2guardian.conf. If you are running a simple filter with just one group on standard ports, there isn't actually anything to change in this file.

That said the settings worth mentioning are:

  • language , in case you want to change the language e2g works with
  • loglevel, which you may want to increase for debugging if you're having problems
  • filterip, if you are installing a server and want the service to be available on the network
  • filterports, if you want to run E2G on a non standard port other than 8080
  • proxyip, where to find the proxy, squid or other, that e2g can use to fetch the pages
  • filtergroups , how many groups you want
  • all your lists, such as bannedsiteslist, etc, you can add your own lists too
  • authplugin, if you want to run more than one group, this is needed to identify who ends up in which group

There are some other important options for SSL which are covered in the [SSL Filtering](../HTTPS Filtering) page and a few that are useful to tune performances, which are described in the [Performance Tuning](../Performance Tuning) page.

Basic filtering group configuration

This is where the filtering action happens. The primary tunables are again your lists definition. Make sure that these point to whatever ban/white/grey lists you want to load for this group.

The other key setting is the naughtiness level, which like we mentioned earlier is what controls if a page is blocked or not depending on its content and wordslists.

Everything else can stay default however if you wish to be able to override a ban, you want to set bypass to a number greater than 0 and customize your access denied page. For more information on bypass see this

Misc

There are a few variables that aren't about performance tuning, but can greatly influence the behavior of E2G and so we include those here:

maxheaderlines

When a request is made to a remote server a number of headers are returned along with the page's data. In some cases the number of headers returned can be really high or artificially high as a way to attack the client. As such E2G limits how many headers can be sent before it considers the server malicious and closes the connection.

By default that number is 40, however this can be too conservative for some complex sites backed up by chatty services. If this number is too low E2G will return a 502 Gateway Error, effectively making the site unreachable. If you are affected by this it's ok to raise that variable to maybe 100 and retry. There shouldn't be many cases where that number should exceed a hundred, although the acceptable values are all the way up to 2000.

You can’t perform that action at this time.