Cop+ (Copplus)

"Gets the dirt others leave behind!"

Internal Details

You don't need to read any of this to use Cop+. This page is for linux admins or developers who want to know how Cop+ works, or who want to make modifications.

Dansguardian was compiled from source in an IPCop 1.4.21 development environment. The lfs file with switches used to compile dansguardian is here.

The copplusaddon-xxx.tgz tar file contains the /var/ipcop/copplus folder.
Inside that folder is an assortment of needed files and a tar archive containing most of what is needed. The installer program is a bash script called copplussetup, it can be run anytime, repeatedly. It in turn calls 1stboot.pl which is a perl script to finish some of the configuration tasks.

Summary of changes made to ipcop

• Add /etc/dansguardian folder and sub-folders
  /etc/dansguardian contains the main config files
  /etc/dansguardian/lists contains all the other config files DG uses
  Some of the config files "include" blacklists, which are all in /etc/dansguardian/lists/blacklists
• Add /home/httpd/cgi-bin/dansguardian folder containing perl cgi scripts which are the GUI for the content filter
• Add /home/httpd/html/dansguardian/ folder containing the dansguardian.pl "blocked page" cgi script -- NOT USED by Cop+ by default, and the languages folder, containing the "Blocked page" html template files in various languages, which ARE used by Cop+. The ukenglish templates have been modified by me, all others are as provided by dansguardian. If you change the language setting on the advanced-configuration page to match the name of one of these folder names, the templates in that folder will be used.
• Add /usr/local/bin/dgrestart binary. Source code is here.
• Insert "Content Filter" to the GUI menus by modifying /var/ipcop/header.pl
• Insert a check for Dansguardian's status by modifying the status.cgi page.
• Add some html help pages in /home/httpd/html/help/
• Add some images for the gui to /home/httpd/html/images/
• Add the dansguardian binary executable to /usr/sbin/dansguardian. Source code (500kbytes) is available from dansguardian.org or by emailing me at the address on the front page of this website.
• Add some extra dansguardian config files to /etc/dansguardian to support filter groups 2 and 3.Also create some empty blacklist files, so dansguardian will start. Cop+ does not include any blacklists, and dansguardian won't start if you "include" a blacklist file that isn't there!
• Add the blacklist autodownloader files: /usr/bin/blz.sh, /usr/local/bin/blacklistcheck, and /usr/local/bin/getblacklists
• Add a cron job to fcron to run blacklistcheck every 5 minutes, and getblacklists once a week. blacklistcheck launches blz.sh if it sees the file /var/ipcop/copplus/getblacklistsnow, which can be put there by the button on the contentfilter GUI page, or by the getblacklists script if the "autoblacklists" option is checked on the GUI page. blz.sh does the real work of downloading and installing the blacklists using wget.
• Add /usr/bin/wget binary. Source (1.4Mbytes) from here, or by emailng me. The lfs file I used is here.
• Add the /var/log/dansguardian folder for dg logs to live in.
• Change /etc/logrotate.conf so it rotates the dg logs weekly, keeping 12 weeks worth of logs.
• Modify /etc/rc.d/rc.local (which runs at boot time) to check if /var/ipcop/header.pl has the dansguardian additions. If not, run copplussetup. Also, startup dansguardian on every boot.
• Modify /etc/rc.d/rc.firewall.local to add iptables rules to block web browsing on ports 80 or 443 without going through dansguardian. If you don't want to force everybody on your network to go through dansguardian, the enforcement iptables rules won't be loaded if you delete the file /var/ipcop/copplus/enforcedg then reboot ipcop.
• Replace /usr/sbin/squid with a new version with extra compiled in options. The lfs file with compile options is here. Squid source code is here, or by emailing me.
• Replace the /usr/local/bin/restartsquid with restartsquid_copplus. Restartsquid loads iptables rules. Instead of transparent redirection to squid, iptables redirects to dansguardian on port 8080. Also put in iptables rule to block people talking directly to squid on port 800 (or whatever it's set to.) Source code is here.
• Add lines to /var/ipcop/proxy/acl to allow squid to use x-forwarded-for header to identify the IP number of the clients. Also do the same to /var/ipcop/proxy/advanced/acls/include.acl
  squid is turned on and transparent on Green, off on blue and the squid.conf file is rebuilt. Squid is restarted
• Modify /etc/snort/snort.conf to include 8080 as a valid HTTP port. (Dansguardian listens on port 8080)
• Add the dansguardian config files to the list of files to be backed up when you use the IPCop backup system. (in /var/ipcop/backup/include.user)
• The installer modifies a few of the settings in dansguardian.conf in order to make things work.
• The dansguardian logfile viewer is in home/httpd/cgi-bin/dansguardian/logs.cgi. It is a slightly modified version of Jimmy Myrick's DGLog 2.0 perl script. Thank you Jimmy!

Overview of how it works

In transparent mode, Dansguardian only gets involved with port 80 web traffic. If you turn off the transparent setting, you need to manually configure all your web browsers to use port 8080 on IPCop as their web Proxy. In this case, port 443 secure (https) web traffic is also policed. All other ports used by mail, ftp, bittorrent, skype etc. are not affected.

In transparent mode
Cop+ adds some rules in the /etc/rc.d/rc.firewall.local file which block any traffic going out to port 80 on the internet from your network. However, squid (the "web proxy" on IPCop) is still allowed to go out. So web browsing is broken, unless you go through squid.
The /usr/local/bin/restartsquid program starts up the squid web proxy whenever IPCop boots or when you hit the save button on the web Proxy GUI page. restartsquid normally loads an iptables rule to intercept anything headed out to port 80 on the internet and redirect it to squid on port 800 (or whatever port you set squid to.) The Cop+ modified restartsquid program instead loads a rule that intercepts port 80 traffic and directs it to dansguardian which is listening on port 8080.
Dansguardian is started at boot time by a line in /etc/rc.d/rc.local, which is the linux equivalent of autoexec.bat on a windows machine.
Dansguardian then is essentially doing a man-in-the-middle attack and pretending to be the web server (i.e. www.yahoo.com or others). Dansguardian either returns a web page that says "Blocked," or it asks squid to fetch the page originally requested and hands it over to your web browser.
If either Dansguardian or squid fail to start or hang up while running, web browsing will stop working on your network, but other things like email will continue to work.

In non-transparent mode
Mostly things work the same as above. Now both port 80 and port 443 are blocked from going out. There are no rules loaded to redirect requests headed to the internet to dansguardian. You must inform your web browsers to use a proxy server on IPCop's Green IP number, port 8080. If you don't you'll get "server not responding" or some such message when you try to web browse.
One advantage of non-transparent mode is you get a little control over https traffic. On port 443 (https) dansguardian is doing a pass-through of an encrypted tunnel, so it can't really see what the contents of the web pages are, but it can still block connections to web servers that are in the blacklists.
The main advantage of a non-transparent proxy is your proxy server can require a username and password before allowing people out.
The GUI Pages
The GUI is a series of perl cgi scripts which reside in /home/httpd/cgi-scripts/dansguardian/
They allow you to edit the multiple danguardian config files, which are all just text files, which reside in /etc/dansguardian and /etc/dansguardian/lists. There isn't really anything special about the dansguardian config on IPCop. If you want to you can go in and manually edit the config files with vi or WinSCP and create more groups or get really wild with the configuration. The magic that makes ip numbers appear in the squid logs is:
In dansguardian.conf:

forwardedfor = on

In /var/ipcop/proxy/acl (which is used to build squid.conf):

acl dansguardian src __GREEN_IP__ __BLUE_IP__
follow_x_forwarded_for allow dansguardian