From c859f93e8fb2be79c251fdc25ebfc86847c23213 Mon Sep 17 00:00:00 2001 From: Pablo Neira Ayuso Date: Sun, 7 Jun 2020 23:19:29 +0200 Subject: doc: manual: general documentation revamp A quick revamp on the conntrack-tools manual which is aging a bit. Signed-off-by: Pablo Neira Ayuso --- doc/manual/conntrack-tools.tmpl | 172 +++++++++++++++++++++------------------- 1 file changed, 91 insertions(+), 81 deletions(-) (limited to 'doc/manual/conntrack-tools.tmpl') diff --git a/doc/manual/conntrack-tools.tmpl b/doc/manual/conntrack-tools.tmpl index 739b7f1..64ac5dd 100644 --- a/doc/manual/conntrack-tools.tmpl +++ b/doc/manual/conntrack-tools.tmpl @@ -19,7 +19,7 @@ - 2008-2012 + 2008-2020 Pablo Neira Ayuso @@ -35,10 +35,8 @@ - This document details how to install and configure the - conntrack-tools - >= 1.4.0. This document will evolve in the future to cover new features - and changes. + This document details how to install and to configure the conntrack-tools. + @@ -46,21 +44,13 @@ Introduction - This document should be a kick-off point to install and configure the - conntrack-tools. - If you find any error or imprecision in this document, please send an email - to the author, it will be appreciated. +This documentation provides a description on how to install and to configure the conntrack-tools. - In this document, the author assumes that the reader is familiar with firewalling concepts and iptables in general. If this is not your case, I suggest you to read the iptables documentation before going ahead. Moreover, the reader must also understand the difference between stateful and stateless firewalls. If this is not your case, I strongly suggest you to read the article Netfilter's Connection Tracking System published in :login; the USENIX magazine. That document contains a general description that should help to clarify the concepts. - -If you do not fulfill the previous requirements, this documentation is likely to be a source of frustration. Probably, you wonder why I'm insisting on these prerequisites too much, the fact is that if your iptables rule-set is stateless, it is very likely that the conntrack-tools will not be of any help for you. You have been warned! +This documentation assumes that the reader is familiar with basic firewalling and Netfilter concepts. You also must understand the difference between stateless and stateful firewalls. Otherwise, please read Netfilter's Connection Tracking System published in :login; the USENIX magazine for a quick reference. What are the conntrack-tools? - The conntrack-tools are a set of free software tools for GNU/Linux that allow system administrators interact, from user-space, with the in-kernel Connection Tracking System, which is the module that enables stateful packet inspection for iptables. Probably, you did not hear about this module so far. However, if any of the rules of your rule-set use the state or ctstate iptables matches, you are indeed using it. - - The conntrack-tools package contains two programs: @@ -72,17 +62,18 @@ - Although the name of both tools is very similar - and you can blame me for that, I'm not a marketing guy - they are used for very different tasks. +Mind the trailing d that refers to either the command line utility or the daemon. Requirements - You have to install the following software in order to get the conntrack-tools working. Make sure that you have installed them correctly before going ahead: +If you are using the Linux kernel that your distribution provides, then you most likely can skip this. + +If you compile your own Linux kernel, then please make sure the following options are enabled. + +You require a Linux kernel version >= 2.6.18. - - - Linux kernel version >= 2.6.18 that, at least, has support for: Connection Tracking System. @@ -123,19 +114,47 @@ - Verifying kernel support - - Make sure you have loaded nf_conntrack, nf_conntrack_ipv4 (if your setup also supports IPv6, nf_conntrack_ipv6) and nf_conntrack_netlink. - - - + +Validating Linux kernel support +You can validate that your Linux kernel support for the conntrack-tools through modinfo. + + + # modinfo nf_conntrack +filename: /lib/modules/5.2.0/kernel/net/netfilter/nf_conntrack.ko +license: GPL +alias: nf_conntrack-10 +alias: nf_conntrack-2 +alias: ip_conntrack +depends: nf_defrag_ipv6,libcrc32c,nf_defrag_ipv4 +retpoline: Y +intree: Y +name: nf_conntrack +vermagic: 5.7.0+ SMP preempt mod_unload modversions +parm: tstamp:Enable connection tracking flow timestamping. (bool) +parm: acct:Enable connection tracking flow accounting. (bool) +parm: nf_conntrack_helper:Enable automatic conntrack helper assignment (default 0) (bool) +parm: expect_hashsize:uint +parm: enable_hooks:Always enable conntrack hooks (bool) + + +Make sure nf_conntrack_netlink is also available. + + +You also need to install the following library dependencies: + + - libnfnetlink: the netfilter netlink library use the official release available in netfilter.org + libnfnetlink: the netfilter netlink library use the official release available in netfilter.org - libnetfilter_conntrack: the netfilter netlink library use the official release available in netfilter.org + libnetfilter_conntrack: the netfilter netlink library use the official release available in netfilter.org + +Installing library dependencies +Your distribution most likely also provides packages for this software, so you do not have to compile it yourself. + + Installation @@ -148,18 +167,8 @@ (non-root)$ make (root) # make install -Fedora Users - If you are installing the libraries in /usr/local/, do not forget to do the following things: - - PKG_CONFIG_PATH=/usr/local/lib/pkgconfig; export PKG_CONFIG_PATH - Add `/usr/local/lib' to your /etc/ld.so.conf file and run `ldconfig' - - Check `ldd' for trouble-shooting, read this for more information on how libraries work. - - -Verifying kernel support - To check that the modules are enabled in the kernel, run `conntrack -E' and generate traffic, you should see flow events reporting new connections and updates. - +Installing conntrack and conntrackd +Your distribution most likely also provides packages for this software, so you do not have to compile it yourself. @@ -174,7 +183,7 @@ tcp 6 431698 ESTABLISHED src=192.168.2.100 dst=123.59.27.117 sport=34849 dport=993 packets=244 bytes=18723 src=123.59.27.117 dst=192.168.2.100 sport=993 dport=34849 packets=203 bytes=144731 [ASSURED] mark=0 use=1 -The command line tool conntrack can be used to display the same information: +You can list the existing flows using the conntrack utility via -L command: # conntrack -L tcp 6 431982 ESTABLISHED src=192.168.2.100 dst=123.59.27.117 sport=34846 dport=993 packets=169 bytes=14322 src=123.59.27.117 dst=192.168.2.100 sport=993 dport=34846 packets=113 bytes=34787 [ASSURED] mark=0 use=1 @@ -182,25 +191,23 @@ conntrack v1.4.6 (conntrack-tools): 2 flow entries have been shown. -You can natively filter the output without using grep: + The conntrack syntax is similar to iptables. + +You can filter out the listing without using grep: # conntrack -L -p tcp --dport 993 tcp 6 431982 ESTABLISHED src=192.168.2.100 dst=123.59.27.117 sport=34846 dport=993 packets=169 bytes=14322 src=123.59.27.117 dst=192.168.2.100 sport=993 dport=34846 packets=113 bytes=34787 [ASSURED] mark=0 use=1 conntrack v1.4.6 (conntrack-tools): 1 flow entries have been shown. -Update the mark based on a selection, this allows you to change the mark of an entry without using the CONNMARK target: +You can update the ct mark, extending the previous example: # conntrack -U -p tcp --dport 993 --mark 10 tcp 6 431982 ESTABLISHED src=192.168.2.100 dst=123.59.27.117 sport=34846 dport=993 packets=169 bytes=14322 src=123.59.27.117 dst=192.168.2.100 sport=993 dport=34846 packets=113 bytes=34787 [ASSURED] mark=10 use=1 conntrack v1.4.6 (conntrack-tools): 1 flow entries have been updated. -Delete one entry, this can be used to block traffic if: - - You have a stateful rule-set that blocks traffic in INVALID state. - You set /proc/sys/net/netfilter/nf_conntrack_tcp_loose to zero. - +You can also delete entries # conntrack -D -p tcp --dport 993 @@ -208,7 +215,14 @@ conntrack v1.4.6 (conntrack-tools): 1 flow entries have been updated. conntrack v1.4.6 (conntrack-tools): 1 flow entries have been deleted. -Display the connection tracking events: + +This allows you to block TCP traffic if: + + You have a stateful rule-set that drops traffic in INVALID state. + You set /proc/sys/net/netfilter/nf_conntrack_tcp_loose to zero. + + +You can also listen to the connection tracking events: # conntrack -E [NEW] udp 17 30 src=192.168.2.100 dst=192.168.2.1 sport=57767 dport=53 [UNREPLIED] src=192.168.2.1 dst=192.168.2.100 sport=53 dport=57767 @@ -218,20 +232,23 @@ conntrack v1.4.6 (conntrack-tools): 1 flow entries have been deleted. [UPDATE] tcp 6 432000 ESTABLISHED src=192.168.2.100 dst=66.102.9.104 sport=33379 dport=80 src=66.102.9.104 dst=192.168.2.100 sport=80 dport=33379 [ASSURED] -You can also display the existing flows in XML format, filter the output based on the NAT handling applied, etc. +There are many options, including support for XML output, more advanced filters, and so on. Please check the manpage for more information. Setting up conntrackd: the daemon - The daemon conntrackd supports two working modes: + The conntrackd daemon supports three modes: - + + + State table synchronization, to synchronize the connection tracking state table between several firewalls in High Availability (HA) scenarios. + - State table synchronization: the daemon can be used to synchronize the connection tracking state table between several firewall replicas. This can be used to deploy fault-tolerant stateful firewalls. This is the main feature of the daemon. + Userspace connection tracking helpers, for layer 7 Application Layer Gateway (ALG) such as DHCPv6, MDNS, RPC, SLP and Oracle TNS. As an alternative to the in-kernel connection tracking helpers that are available in the Linux kernel. - Flow-based statistics collection: the daemon can be used to collect flow-based statistics. This feature is similar to what ulogd-2.x provides. + Flow-based statistics collection, to collect flow-based statistics as an alternative to ulogd2, although ulogd2 allows for more flexible statistics collection. @@ -239,15 +256,12 @@ conntrack v1.4.6 (conntrack-tools): 1 flow entries have been deleted. Requirements - In order to get conntrackd working in synchronization mode, you have to fulfill the following requirements: + If you would like to configure conntrackd to work in state synchronization mode, then you require: - A high availability manager like keepalived that manages the virtual IPs of the - firewall cluster, detects errors, and decide when to migrate the virtual IPs - from one firewall replica to another. Without it, conntrackd will not work appropriately. - The state synchronization setup requires a working installation of keepalived, preferibly a recent version. Check if your distribution comes with a recent packaged version. Otherwise, you may compile it from the sources. + A working installation of keepalived, preferibly a recent version. Check if your distribution comes with a recent packaged version. Otherwise, you may compile it from the sources. @@ -342,7 +356,7 @@ conntrack v1.4.6 (conntrack-tools): 1 flow entries have been deleted. -Active-Backup setup +Active-Backup setups Stateful firewall architectures A good reading to extend the information about firewall architectures is Demystifying cluster-based fault-tolerant firewalls published in IEEE Internet Computing magazine. @@ -380,19 +394,19 @@ conntrack v1.4.6 (conntrack-tools): 1 flow entries have been deleted. -Active-Active setup +Active-Active setups The Active-Active setup consists of having more than one stateful - firewall replicas actively filtering traffic. Thus, we reduce the resource - waste that implies to have a backup firewall which does nothing. + firewall actively filtering traffic. Thus, we reduce the resource + waste that implies to have a backup firewall which is spare. We can classify the type of Active-Active setups in several families: - Symmetric path routing: The stateful firewall - replicas share the workload in terms of flows, ie. the packets that are + Symmetric path routing: The stateful firewalls + share the workload in terms of flows, ie. the packets that are part of a flow are always filtered by the same firewall. @@ -406,24 +420,20 @@ conntrack v1.4.6 (conntrack-tools): 1 flow entries have been deleted. - As for 0.9.8, the design of conntrackd allows you - to deploy an symmetric Active-Active setup based on a static approach. - For example, assume that you have two virtual IPs, vIP1 and vIP2, and two - firewall replicas, FW1 and FW2. You can give the virtual vIP1 to the - firewall FW1 and the vIP2 to the FW2. + conntrackd allows you to deploy an symmetric +Active-Active setup based on a static approach. For example, assume that you +have two virtual IPs, vIP1 and vIP2, and two firewall replicas, FW1 and FW2. +You can give the virtual vIP1 to the firewall FW1 and the vIP2 to the FW2. - Unfortunately, you will have to wait for the support for the - Active-Active setup based on dynamic approach, ie. a workload sharing setup - without directors that allow the stateful firewall share the filtering. - - On the other hand, the asymmetric scenario may work if your setup - fulfills several strong assumptions. However, in the opinion of the author - of this work, the asymmetric setup goes against the design of stateful - firewalls and conntrackd. Therefore, you have two - choices here: you can deploy an Active-Backup setup or go back to your - old stateless rule-set (in that case, the conntrack-tools will not be - of any help anymore, of course). + The asymmetric path scenario is hard: races might occurs between state + synchronization and packet forwarding. If you would like to deploy an + Active-Active setup with an assymmetic multi-path routing configuration, + then, make sure the same firewall forwards packets + coming in the original and the reply directions. If you cannot guarantee + this and you still would like to deply an Active-Active setup, then you + might have to consider downgrading your firewall ruleset policy to stateless +filtering. -- cgit v1.2.3