Copyright (c) 2005 Gregor Maier <gregor@majordomus.org>
All right reserved. See LICENSE file for details.


netfico is a complete Linux/netfilter firewall and gateway configuration tool.
It takes over the complete process of brining up the network interfaces,
configuring VLANs, setting routes and configure the netfilter rules. This
also means that there is just one central place, where IP addresses and
netmasks are configured, thus eliminating the redunancy between the system's
network configuration scripts and the firewall setup code. 


netfico uses stateful IPv6 filtering rules. You need at least 
iptables 1.3.5 and you'll also need to patch the Linux kernel to 
support statefull IPv6 filtering. The patch can be found at 
http://www.net.in.tum.de/~gregor/projects/

NOTE: This is a pretty early version. Expect more convenience and better
integrationd into System V Init (/etc/init.d) and stuff in the near future. 

FEATURES
- Combines network interface configuration and firewall rule setup
- Supports IPv4 and IPv6. Rules are only written once autmaticly
    applied to IPv4 and IPv6.
- Supports VLAN interfaces 
- Different interfaces for the same subnet for IPv4 and IPv6 possible 
    (e.g. when IPv6 is tunneled)
- Easy handling of multiple subnets with "virtual firewalls"
- Customizeable. Custom rules resp. rule templates can easily be added
    to netfico.


CONTROL FLOW 
- Set sysctl settings (/proc/sys) from sysctl.prestart.conf
- Initialise iptables. Flush all tables, set policies allow traffic
    inside the local machine.
- Setup Chains. Create the XAR, FROM_* and TO_* chains. Set the jumps 
    from FORWARD and XBAR to the appropriate FROM_* and TO_* chains.
- Config Rules. Setup the Firewalling Rules according to the
    settings in rules.d/.
- Append catch all LOG and DROP targets at the end of each chain
- Configure the network interfaces and the routing table (if enabled).
- Set sysctl settings (/proc/sys) from sysctl.poststart.conf


HOW TO SET RULES FOR THE LOCAL MACHINE

in this very early version, you must edit fw_functions.pl and edit the
xxx_allow_me() function to contain the rules for the local machine. This
will change in the future

HOW PACKETS TRAVERSE THE RULES

Please note, that the external link is also called a subnet in this
document. So when I talk about subnet it my the internet or an internal
subnet. 

A primary goal for netfico was, that it must be able to handle a larger
number of subnets. Since the number of cross-connects between subnets
is N(N-1) the number of cross-connects grows quadratically. 

My solution is to build "virtual" firewalls in front of each subnet and use
a central virtual router. This means that a packet is allowed, when the
firewall on both affected subnets allows the packet.  I.e. when the
intersection of both firewall rules allow the packet. The virtual firewall 
of each subnet is represented by the rules in the file rules.d/SUBNET. For 
each subnet two chains are generated, namely FROM_SUBNET and TO_SUBNET

When a packet travels from subnet X to subnet Y, it is first handed to 
the chain FROM_X. There it is either dropped or, if the packet should be
accepted, it is send to the XBAR (crossbar) chain. This XBAR chain is the
"virtual router". The XBAR chains checks the destination of the packet and
hands it to the appropriate TO_* chain, in this case the TO_Y chain. The
TO_Y chain now either accepts or drops the packet. 


CONFIGURATION OF THE NETWORK TOPOLOGY
is done in the config.pl file. There are a lot of comments there, that
you can use as documentation.


WHAT RULES CAN BE SPECIFIED IN rules.d

Several functions exist, that can be used in the rules.d/ files.  All these
rules are filtered using stateful rules. So if we talk about "allow tcp
from X to Y", this means that TCP _connections_ are allowed, when they
originate in subnet X.
The currentely defined rule templates are: 

allow_tcp_in FROM_SPECIFICATION  PORT  [CONSTRAINING_ADDR_RANGE]
allow_udp_in FROM_SPECIFICATION  PORT  [CONSTRAINING_ADDR_RANGE]
allow_icmp_related_in FROM_SPECIFICATION [CONSTRAINING_ADDR_RANGE]
allow_ping_in FROM_SPECIFICATION  PORT  [CONSTRAINING_ADDR_RANGE]
allow_ciscovpn_in FROM_SPECIFICATION  PORT  [CONSTRAINING_ADDR_RANGE]

allow_tcp_out TO_SPECIFICATION  PORT  [CONSTRAINING_ADDR_RANGE]
allow_udp_out TO_SPECIFICATION  PORT  [CONSTRAINING_ADDR_RANGE]
allow_icmp_related_in TO_SPECIFICATION [CONSTRAINING_ADDR_RANGE]
allow_ping_out TO_SPECIFICATION   [CONSTRAINING_ADDR_RANGE]
allow_ciscovpn_out TO_SPECIFICATION  [CONSTRAINING_ADDR_RANGE]

allow_forward_tcpudp PROTO SRC-ADDR-SPEC SRC-PORT DST-ADDR-SPEC DST-PORT DIRECTION    ....... see the comment below for this function!


The *_in  rules allow "connections" into the current subnet, coming from 
the subnet or the IP range specified by FROM_SPECIFICATION (see below). The
desitnation IP addresses are the complete subnet. This can be limited by the
CONSTRAINING_ADDR_RANGE parameter. 

The *_out rules allow "connections" from the current subnet to the subnet
specified by TO_SPECIFICATION. The source IP addresses are the complete
subnet.  This can be limited by the CONSTRAINING_ADDR_RANGE parameter. 

TO_SPECIFICATION and FROM_SPECIFICATION:
This can either be the name of a subnet (as defined as hash-keys in 
config.pl). Or an it can be of the form "ip:IP-HASH-KEY. Where IP-HASH-KEY
is a hash-key of the %IP hash in config.pl

PORT is the destination port of the udp/tcp service. Currently the sourceport
for allow_tcp_* and allow_udp_* is 0:65535.

CONSTRANING_ADDR_RANGE is optional and can be used to limit the allowed
destination- resp. sourceaddresses within the current subnet. E.g. if you want
to allow http traffic only to a specific IP-Address within your subnet. This
parameter is of the form "ip:IP-HASH-KEY" (see above). If this parameter
is present, it sort of overrides.


allow_forward_tcpudp PROTO SRC-ADDR-SPEC SRC-PORT DST-ADDR-SPEC DST-PORT DIRECTION    

can be used if the other functions for tcp/udp are not powerfull enough. All
the other tcp and udp functions are wrappers around this function. PROTO
is either "tcp" or  "udp", SRC-ADDR-SPEC is any address specification, SRC-PORT
is the sourceport range (iptables syntax). DST-* is the same but for the
destination. DIRECTION is "in" or "out" (e.g. DIRECTION specifies if the 
current subnet is the Source or the Destination of this connection). 
NOTE: no sanity checks are done on SRC-* and DST-* fields. 


FILES
config.pl     Contains the configuration of network interfaces and some
    global settings
fw_setup.pl   Contains general functions that configure and setup the
	iptables stuff. 
fw_functions.pl   Contains the functions, that actually set the firewall
	rules. These functions can be used from the files in rules.d/ 
network_setup.pl   Contains function to bring up and configure the network
	interfaces and the routing table of the machine. 
sysctl.conf   Contains the sysctl settings that are used. 
main.pl	Is the main entry point of netfico.


