Improve documentation

README.md

@@ -1 +1,73 @@
-# Firewall des Rézo Metz-Rennes Fédérés
+# Firewall de Rézo Metz-Rennes Fédérés
+
+Repository en charge du firewall. Les repositories suivants sont complémentaires :
+* [ansible](https://git.rezo-rm.fr/rezo/ansible), notamment le rôle [gateway](https://git.rezo-rm.fr/rezo/ansible/src/branch/config-infra-test/roles/gateway) (pour l'instant sur une branche non merged)
+* [updateBogons](https://git.rezo-rm.fr/rezo/updateBogons), qui permet de mettre à jour les adresses IP invalides
+
+Ce repository comporte deux parties. Premièrement la partie filtrage, le coeur du firewall. Deuxièmement la partie logging des connexions NAT via ulogd.
+
+## Firewall
+
+Le firewall est réalisé avec [nftables](https://wiki.nftables.org/wiki-nftables/index.php/What_is_nftables%3F). Le [wiki officiel](https://wiki.nftables.org/wiki-nftables/index.php/Main_Page) est une excellente source d'information pour comprendre comment fonctionne nftables.
+
+Le principal intérêt de nftables par rapport à iptables est son support de fonctionnalitées avancées par défaut (set, map ...) et sa syntaxe plus lisible.
+
+### Architecture du firewall
+
+Le fichier principal est [nftables.conf](nftables.conf).
+
+Deux tables sont définis dans le firewall : **table inet firewall** et **table netdev ddos_mitigation**.
+
+#### Table inet firewall
+
+C'est la table principale du firewall.
+
+**chain forward** :
+
+La chaîne *forward* est le point d'entrée principal dans les règles de firewall. Le rôle de cette chaîne est de filtrer le trafic sur tout le réseau. La logique de cette chaîne est la suivante :
+* On commence par filtrer les connexions déjà acceptées ou invalides
+* S'il s'agit d'une nouvelle connexion, on regarde l'interface d'entrée du paquet. Chaque interface étant relié à un réseau distinct, regarder l'interface d'entrée permet de savoir dans quel réseau se situe le paquet.
+* On continue ensuite en regardant l'interface de sortie du paquet. De la même façon que précedemment, l'interface de sortie correspond au réseau de sortie. On applique la décision finale dans la chaîne to_*
+
+Les chaînes principales sont ensuites les chaînes *destination_nat* et *source_nat*.
+
+**chain destination_nat, chain source_nat** :
+
+La page wiki [Netfilter hooks](https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks) permet d'avoir un bon aperçu des différents hooks (filtrage appliqués durant le parcours d'un paquet dans la pile réseau). Il est important de garder ce schéma à l'esprit lorsqu'on touche au NAT.
+
+* destination NAT : permet de réécrire l'adresse de destination d'un paquet. Cette étape intervient donc avant la décision de routage, et se place dans le hook *prerooting*. Typiquement on utilise le destination NAT pour faire du port-forwarding.
+* source NAT : permet de réécrire l'adresse source d'un paquet. Cette étape intervient donc après la décision de routage et après les règles forwards, et se place dans le hook *postrouting*. Typiquement on utilise le source NAT pour faire correspondre les adresses privées des adhérents à l'adresse publique de la passerelle.
+
+**Autres chaînes** :
+
+On retrouve les traditionnels chaînes *input* et *output*, ainsi que la chaîne *prefilter* qui permet de faire le filtrage des connexions sur le vlan Deco (pré-rezotage).
+
+#### Table netdev ddos_mitigation
+
+Cette table est définie dans le fichier [config/ddos_mitigation.nft](config/ddos_mitigation.nft) et permet de filtrer en amont les paquets invalides qui pourraient arriver sur le firewall via les interfaces publiques. Les paquets invalides sont :
+* Les paquets ayant une adresse privée
+* Les paquets ayant une fausse adresse IP (voir [Bogon filtering](https://en.wikipedia.org/wiki/Bogon_filtering) sur wikipedia).
+
+Pour le filtrage des bogons le repository [updateBogons](https://git.rezo-rm.fr/rezo/updateBogons) permet de mettre à jour régulièrement la liste des adresses IP invalides.
+
+Il est aussi possible d'ajouter des IP de façon dynamique dans les sets *banned_ipv4* et *banned_ipv6* afin de filtrer temporairement des IP (intéressant en complément de l'utilisation de fail2ban sur les serveurs par exemple).
+
+Cette table repose sur l'utilisation d'une interface pour le wan et d'une autre pour le lan pour bien fonctionner.
+
+## Logs
+
+Voir :
+* [Logging traffic](https://wiki.nftables.org/wiki-nftables/index.php/Logging_traffic) du wiki officiel
+* [Accounting with ulogd 2 and conntrack on a GBit NAT](https://mohskitchen.wordpress.com/2012/08/27/accounting-with-ulogd-2-and-conntrack-on-a-gbit-nat/)
+* [Logging connection tracking event with ulogd](https://home.regit.org/2014/02/logging-connection-tracking-event-with-ulogd/)
+
+
+Il est légalement nécessaire de logger les connexions faites par le NAT. En pratique il faut pouvoir logger pour chaque connexion les adresses IP (source, destination), l'heure et peut être aussi les identifiants (ports) de protocole de couche 4.
+
+Afin de capter les logs quand on est dans un LXC il est nécessaire de passer par des logs en userspace. En effet, dans un LXC le firewall n'a pas les droits pour écrire dans les logs kernels. C'est une considération à prendre en compte lors du développement mais qui nous amène à utiliser en pratique à *ulogd2*, qui est un excellent choix pour la collecte des logs.
+
+Les logs sont récupérés directement par l'interface *conntrack* de *ulogd2*. En pratique cela veut dire que les règles de log dans le firewall ne sont pas nécessaire à l'obtention des logs par *ulogd2*.
+
+Ce projet définit le fichier de configuration de *ulogd2*, [ulogd.conf](ulogd.conf) ainsi que le schéma de base de donnée *PostgreSQL* [pgsql-schema.sql](pgsql-schema.sql).
+
+Le schéma *PostgreSQL* définit notamment une vue appelée *view_log* qui permet de visualiser les logs facilement sans faire de requêtes compliquées.

nftables.conf

@@ -97,6 +97,7 @@ table inet firewall {
 		    $if_nerim:         jump from_nerim
 		}
 
+		# This counter should be zero if we correctlty filtered the connections
 		counter log group 1 prefix "Uncaught traffic:"
 	}