README

Berlin is a collection of firewall configuration scripts.



##      OVERVIEW

Berlin is an attempt to make my personal firewall config scripts available to
the public. The project, which in its early days was known to few as "vuurmuur"
is named after another historic wall.

Key features:
 -  Easily deployable NAT firewall
 -  Multiple subnets
 -  Advertisement filtering


Berlin is available under the terms of the GNU General Public License version
3, or, at your discretion, any later version. See the file COPYING for details.


Requirements:
 -  python
 -  iptables

Optional:
 -  Apache 2 for ad filtering
 -  mod_proxy_http for more advanced ad filtering
 -  PHP5 for even more advanced ad filtering



##      INSTALLATION

To set up, verify every network interface is installed and working correctly.
After that, run  helper-scripts/deploy.sh  as root, and follow the on-screen
instructions.

bin/generate-config.py is a simple text-based UI designed to help you configure
your router. It is also possible (and sometimes necessary) to modify the con-
figuration files by hand.

After modifying the configuration files, run  rules.py  to generate the corres-
ponding iptables rules, or run  firewall  to immediately install the new rule-
set as well.

Below is a list of each configuration file, and its function.

    ./apache/
                Directory containing apache-specific configuration files
      default.html
      favicon.ico
                Default file to show instead of blocked content. The favicon
                is shown instead of any /favicon.ico request.
      filtered/*
                Pages that require more advanced filtering are stored here.
      greylist.conf
      whitelist.conf
                A grey- and whitelist respectively.
                Hosts on the whitelist will not get blocked; hosts on the grey-
                list are filtered according to the corresponding PHP file.
    
    /etc/berlin/
      networks/*
                All internal subnets are defined here
      ports/*
                Rules for forwarding ports. See dedicated section below.
      if-config
                Configuration concerning the installed NICs
      ad-hosts
      malware-hosts
                Hosts (IP addresses) containing lots of ads or malware respec-
                tively. Any HTTP connection to an address on this list will be
                rerouted to a local apache installation, which will, in most
                cases, block the content.
      smtp-hosts
                A list of SMTP servers to which it is ok to connect.
                Users on the network will not be able to establish an SMTP
                connection to any IP not on this list, effectively preventing
                them from participating in any spam bot network.



##      PORT FORWARDING

By default, berlin blocks all incoming traffic, but this may not always be
desirable. For instance, there may be a public HTTP server on the router, or
somewhere on the network. Or you may want the router to act as a SSH gateway to
the rest of the network.

In such cases, it's necessary to 'open ports' to the public.
If traffic should be accepted locally, this can be achieved using the text-
based UI provided. Press the [s] key, and enter the port number.

However, if traffic to an external port should be forwarded to a host on the
local net, or if berlin's configuration is modified from a script, it'll be
necessary to edit the appropriate files by hand.

To open a port, create a file in the  /etc/berlin/ports/  folder with the
port number as its name. After that:
 -  To accept all traffic on said port locally, just leave the file empty.
 -  To forward traffic to a specific host in the local network, enter its IP 
    address in the file.
 -  To forward traffic to a different port on a host, enter both an IP address
    and a port number in the form
                aaa.bbb.ccc.ddd:xxxx
    where xxxx is the destination port on the target machine.