README

OVERVIEW
========

This program is a nfq-based traffic filter. The filtering
occur on the basis of list entries which must be blocked or accepted.

CONFIG
======

The current config file format is considered as temporary. To see
how it must look in the future open file conf_future.

Each line of config file contain an entries list file declaration in
the next format:

list FILE_NAME ACTION_ON_MATCH MARK_ON_MATCH

FILE_NAME - is a file, which contain a list entries
ACTION_ON_MATCH - NFQUEUE verdict to set on a packet if it's matched some
                  entry in this list. One of: accept, repeat or drop.
MARK_ON_MATCH - mark set on a packet if it's matched some entry in this
                list. Any interger values from 0 to (2^32 - 1).

Mark on drop action is useless, but must be specified to satisfy the format.

Each line of an entries list file contain an entry declaration in
the CSV format(with ":" as field delimiter, "'" as quote char) with
next fields:

FILTER_NAME:FILTER_DATA

Now we have the next filters: f_ipsrv, f_domain, f_domaintree, f_uri.
f_ipsrv blocks packets based on ip address, proto number and protocol
port number. f_domain blocks packets based on domain name.
f_domaintree blocks packets based on domain name(blocks specified name
and all it subdomains). f_uri blocks packets based on uri.
Filters entry format:

f_ipsrv:

ip-srv:IP[:PROTO[:PROTO_DATA]]

  where PROTO_DATA:

  for PROTO=1 (icmp):
  
  TYPE[:CODE]
  
  for PROTO=6 (tcp):
  
  PORT
  
  for PROTO=17 (udp):
  
  PORT

f_domain:

domain:DOMAIN_NAME

f_domaintree:

domain-tree:DOMAIN_NAME

f_uri:

uri:URI

URI for http scheme must not contain any trailing slashes(because,
pkt_http removes it on packet parsing).

Example config can be seen in conf_example file.

FEATURES
========

- libnetfilter_queue based userspace filter;
- multithreading (one thread for each nfqueue);
- blocking occur on the basis of lists of entries to block/accept;
- list entries are arranged in avl-tree structures;
- support blocking by: ip address, ip protocol, icmp type, icmp code,
  tcp dest port, udp dest port, domain name, domain name and all it subdomains,
  uri;
- retrieve domain name from: http-request, dns-request, https-request;
- retrieve uri from: http-request;
- support a live config reloading(reloading config without stopping of
  a service);
- has a supervisor, which restarts the program when it crashed;
- has a mudular architecture.

ARCHITECTURE
============

trfl do a live config reloading on receiving SIGUSR1 signal.

trfl on startup run a supervisor which restart a program when it
crashed(unless a situation when it crashed on config error).

After this, supervisor run a main process, which spawn a thread for
each nfqueue.

Then the main thread wait for SIGUSR1 to reload the config. Others
threads do actual packet parsing and filtering.

During packet parsing, needed info for filters, like domain names and URIs,
are collected. After this, a packet with collected info is passed to filters
where it is compared to filters entries.

BUILDING
========

make clean && make DEBUG=1

USING
=====

Place something like this in iptables:

iptables -N trfl
iptables -A trfl -m statistic --mode nth --every 4 --packet 0 -j NFQUEUE --queue-num 0
iptables -A trfl -m statistic --mode nth --every 3 --packet 0 -j NFQUEUE --queue-num 1
iptables -A trfl -m statistic --mode nth --every 2 --packet 0 -j NFQUEUE --queue-num 2
iptables -A trfl -j NFQUEUE --queue-num 3

iptables -A FORWARD -p tcp -m tcp -m mark --mark 1 -j REJECT --reject-with tcp-reset
iptables -A FORWARD -m mark --mark 1 -j REJECT --reject-with icmp-port-unreachable
iptables -A FORWARD -i eth0 -j trfl

Use conf_example. Start trfl:

./trfl -q 0:3 -p /var/run/trfl.pid conf_example