From affe4656f3aeeba4040f9d63efd7719ef0345ae9 Mon Sep 17 00:00:00 2001 From: Pablo Neira Ayuso Date: Mon, 8 Oct 2012 12:22:28 +0200 Subject: doc: detail user-space helper support This patch adds documentation on how to enable user-space helper support. Signed-off-by: Pablo Neira Ayuso --- doc/manual/conntrack-tools.tmpl | 155 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 150 insertions(+), 5 deletions(-) (limited to 'doc/manual/conntrack-tools.tmpl') diff --git a/doc/manual/conntrack-tools.tmpl b/doc/manual/conntrack-tools.tmpl index 63a53e4..f21a4ff 100644 --- a/doc/manual/conntrack-tools.tmpl +++ b/doc/manual/conntrack-tools.tmpl @@ -19,7 +19,7 @@ - 2008-2011 + 2008-2012 Pablo Neira Ayuso @@ -37,7 +37,7 @@ This document details how to install and configure the conntrack-tools - >= 1.0.0. This document will evolve in the future to cover new features + >= 1.4.0. This document will evolve in the future to cover new features and changes. @@ -827,7 +827,154 @@ Sync { -Troubleshooting + + +User-space helpers + + Check your Linux kernel version first + + The user-space helper infrastructure requires a Linux kernel >= 3.6 + to work appropriately. + + + +Connection tracking helpers allows you to filter multi-flow protocols +that usually separate control and data traffic into different flows. +These protocols usually violate network layering by including layer 3/4 +details, eg. IP address and TCP/UDP ports, in their application protocol +(which resides in layer 7). This is problematic for gateways since they +operate at packet-level, ie. layers 3/4, and therefore they miss this +important information to filter these protocols appropriately. + +Helpers inspect packet content (at layer 7) and create the so-called +expectations. These expectations are added to one internal table +that resides in the gateway. For each new packet arriving to the +gateway, the gateway first looks up for matching expectations. If +there is any, then this flow is accepted since it's been expected. +Note this lookup only occurs for the first packet that is part of one +newly established flow, not for all packets. + +Since 1.4.0, conntrackd provides the infrastructure to develop +helpers in user-space. The main features of the user-space infrastructure +for helpers are: + + + +Rapid connection tracking helper development, as developing code +in user-space is usually faster. + +Reliability: A buggy helper does not crash the kernel. If the helper +fails, ie. the conntrackd crashes, Moreover, we can monitor the helper process +and restart it in case of problems. + +Security: Avoid complex string matching and mangling in +kernel-space running in privileged mode. Going further, we can even think +about running user-space helper as a non-root process. + +It allows the development of very specific helpers for +proprietary protocols that are not standard. This is the case of the SQL*net +helper. Implementing this in kernel-space may be problematic, since +this may not be accepted for ainline inclusion in the Linux kernel. +As an alternative, we can still distribute this support as separate +patches. However, my personal experience is that, given that the +kernel API/ABI is not stable, changes in the interface lead to the +breakage of the patch. This highly increase the overhead in the +maintainance. + + + +Currently, the infrastructure supports the following user-space helpers: + + + +Oracle*TNS, to support its special Redirect message. +NFSv3, mind that version 4 does not require this helper. +FTP (this helper is also available in kernel-space). + + +The following steps describe how to enable the RPC portmapper helper for NFSv3 (this is similar for other helpers): + + +Register user-space helper: + + +nfct helper add rpc inet udp +nfct helper add rpc inet tcp + + +This registers the portmapper helper for both UDP and TCP (NFSv3 traffic goes both over TCP and UDP). + + +Add iptables rule using the CT target: + + +# iptables -I OUTPUT -t raw -p udp --dport 111 -j CT --helper rpc +# iptables -I OUTPUT -t raw -p tcp --dport 111 -j CT --helper rpc + + +With this, packets matching port TCP/UDP/111 are passed to user-space for +inspection. If there is no instance of conntrackd configured to support +user-space helpers, no inspection happens and packets are not sent to +user-space. + +Add configuration to conntrackd.conf: + + +Helper { + Type rpc inet udp { + QueueNum 1 + QueueLen 10240 + Policy rpc { + ExpectMax 1 + ExpectTimeout 300 + } + } + Type rpc inet tcp { + QueueNum 2 + QueueLen 10240 + Policy rpc { + ExpectMax 1 + ExpectTimeout 300 + } + } +} + + +This configures conntrackd to use NFQUEUE queue numbers 1 and 2 to send traffic +for inspection to user-space + + If you have some custom libnetfilter_queue application + + Make sure your queue numbers do not collide with those used in your + conntrackd.conf file. + + + + + + + +Now you can test this (assuming you have some working NFSv3 setup) with: + + +mount -t nfs -onfsvers=3 mynfs.server.info:/srv/cvs /mnt/ + + + + +You should see new expectations being added via: + + +# conntrack -E expect + [NEW] 300 proto=17 src=1.2.3.4 dst=1.2.3.4 sport=0 dport=54834 mask-src=255.255.255.255 mask-dst=255.255.255.255 sport=0 dport=65535 master-src=1.2.3.4 master-dst=1.2.3.4 sport=58190 dport=111 PERMANENT class=0 helper=rpc + [NEW] 300 proto=6 src=1.2.3.4 dst=1.2.3.4 sport=0 dport=2049 mask-src=255.255.255.255 mask-dst=255.255.255.255 sport=0 dport=65535 master-src=1.2.3.4 master-dst=1.2.3.4 sport=55450 dport=111 PERMANENT class=0 helper=rpc + [NEW] 300 proto=17 src=1.2.3.4 dst=1.2.3.4 sport=0 dport=58031 mask-src=255.255.255.255 mask-dst=255.255.255.255 sport=0 dport=65535 master-src=1.2.3.4 master-dst=1.2.3.4 sport=56309 dport=111 PERMANENT class=0 helper=rpc + + + + + +Troubleshooting Problems with conntrackd? The following list of questions should help for troubleshooting: @@ -1033,8 +1180,6 @@ not enough space errors: 0 - - -- cgit v1.2.3