diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/helper/conntrackd.conf | 116 | ||||
| -rw-r--r-- | doc/manual/conntrack-tools.tmpl | 166 | ||||
| -rw-r--r-- | doc/sync/alarm/conntrackd.conf | 3 | ||||
| -rw-r--r-- | doc/sync/ftfw/conntrackd.conf | 3 | ||||
| -rw-r--r-- | doc/sync/notrack/conntrackd.conf | 3 |
5 files changed, 282 insertions, 9 deletions
diff --git a/doc/helper/conntrackd.conf b/doc/helper/conntrackd.conf new file mode 100644 index 0000000..56f5162 --- /dev/null +++ b/doc/helper/conntrackd.conf @@ -0,0 +1,116 @@ +# +# Helper settings +# + +Helper { + # Before this, you have to make sure you have registered the `ftp' + # user-space helper stub via: + # + # nfct helper add ftp inet tcp + # + Type ftp inet tcp { + # + # Set NFQUEUE number you want to use to receive traffic from + # the kernel. + # + QueueNum 0 + + # + # Maximum number of packets waiting in the queue to receive + # a verdict from user-space. Default is 1024. + # + # Rise value if you hit the following error message: + # "nf_queue: full at X entries, dropping packets(s)" + # + QueueLen 10240 + + # + # Set the Expectation policy for this helper. + # + Policy ftp { + # + # Maximum number of simultaneous expectations + # + ExpectMax 1 + # + # Maximum living time for one expectation (in seconds). + # + ExpectTimeout 300 + } + } + Type rpc inet tcp { + QueueNum 1 + QueueLen 10240 + Policy rpc { + ExpectMax 1 + ExpectTimeout 300 + } + } + Type rpc inet udp { + QueueNum 2 + QueueLen 10240 + Policy rpc { + ExpectMax 1 + ExpectTimeout 300 + } + } + Type tns inet tcp { + QueueNum 3 + QueueLen 10240 + Policy tns { + ExpectMax 1 + ExpectTimeout 300 + } + } +} + +# +# General settings +# +General { + # + # Set the nice value of the daemon, this value goes from -20 + # (most favorable scheduling) to 19 (least favorable). Using a + # very low value reduces the chances to lose state-change events. + # Default is 0 but this example file sets it to most favourable + # scheduling as this is generally a good idea. See man nice(1) for + # more information. + # + Nice -20 + + # + # Select a different scheduler for the daemon, you can select between + # RR and FIFO and the process priority (minimum is 0, maximum is 99). + # See man sched_setscheduler(2) for more information. Using a RT + # scheduler reduces the chances to overrun the Netlink buffer. + # + # Scheduler { + # Type FIFO + # Priority 99 + # } + + # + # Logfile: on (/var/log/conntrackd.log), off, or a filename + # Default: off + # + LogFile on + + # + # Syslog: on, off or a facility name (daemon (default) or local0..7) + # Default: off + # + #Syslog on + + # + # Lockfile + # + LockFile /var/lock/conntrack.lock + + # + # Unix socket configuration + # + UNIX { + Path /var/run/conntrackd.ctl + Backlog 20 + } +} diff --git a/doc/manual/conntrack-tools.tmpl b/doc/manual/conntrack-tools.tmpl index dbf836d..f21a4ff 100644 --- a/doc/manual/conntrack-tools.tmpl +++ b/doc/manual/conntrack-tools.tmpl @@ -19,7 +19,7 @@ </authorgroup> <copyright> - <year>2008-2011</year> + <year>2008-2012</year> <holder>Pablo Neira Ayuso</holder> </copyright> @@ -37,7 +37,7 @@ <releaseinfo> This document details how to install and configure the <ulink url="http://conntrack-tools.netfilter.org">conntrack-tools</ulink> - >= 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.</releaseinfo> </bookinfo> @@ -660,6 +660,13 @@ Sync { <sect3 id="sync-expect"><title>Synchronization of expectations</title> + <note><title>Check your Linux kernel version first</title> + <para> + The synchronization of expectations require a Linux kernel >= 3.5 + to work appropriately. + </para> + </note> + <para>The connection tracking system provides helpers that allows you to filter multi-flow application protocols like FTP, H.323 and SIP among many others. These protocols usually split the control and data traffic in @@ -689,7 +696,9 @@ Sync { ExpectationSync { ftp sip - h323 + ras # for H.323 + q.931 # for H.323 + h.245 # for H.323 } } }</programlisting> @@ -818,7 +827,154 @@ Sync { </sect2> -<sect2 id="sync-trouble"><title>Troubleshooting</title> +</sect1> + +<sect1 id="helpers"><title>User-space helpers</title> + + <note><title>Check your Linux kernel version first</title> + <para> + The user-space helper infrastructure requires a Linux kernel >= 3.6 + to work appropriately. + </para> + </note> + +<para>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.</para> + +<para>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.</para> + +<para>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:</para> + +<itemizedlist> + +<listitem><para>Rapid connection tracking helper development, as developing code +in user-space is usually faster.</para></listitem> + +<listitem><para>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.</para></listitem> + +<listitem><para>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.</para></listitem> + +<listitem><para>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.</para></listitem> + +</itemizedlist> + +<para>Currently, the infrastructure supports the following user-space helpers: +</para> + +<itemizedlist> +<listitem><para>Oracle*TNS, to support its special <emphasis>Redirect</emphasis> message.</para></listitem> +<listitem><para>NFSv3, mind that version 4 does not require this helper.</para></listitem> +<listitem><para>FTP (this helper is also available in kernel-space).</para></listitem> +</itemizedlist> + +<para>The following steps describe how to enable the RPC portmapper helper for NFSv3 (this is similar for other helpers):</para> + +<orderedlist> +<listitem><para>Register user-space helper: + +<programlisting> +nfct helper add rpc inet udp +nfct helper add rpc inet tcp +</programlisting> + +This registers the portmapper helper for both UDP and TCP (NFSv3 traffic goes both over TCP and UDP). +</para></listitem> + +<listitem><para>Add iptables rule using the CT target: + +<programlisting> +# 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 +</programlisting> + +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.</para></listitem> + +<listitem><para>Add configuration to conntrackd.conf: + +<programlisting> +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 + } + } +} +</programlisting> + +This configures conntrackd to use NFQUEUE queue numbers 1 and 2 to send traffic +for inspection to user-space</para> + + <note><title>If you have some custom libnetfilter_queue application</title> + <para> + Make sure your queue numbers do not collide with those used in your + conntrackd.conf file. + </para> + </note> + +</listitem> + +</orderedlist> + +<para>Now you can test this (assuming you have some working NFSv3 setup) with: + +<programlisting> +mount -t nfs -onfsvers=3 mynfs.server.info:/srv/cvs /mnt/ +</programlisting> + +</para> + +<para>You should see new expectations being added via: + +<programlisting> +# 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 +</programlisting> +</para> + +</sect1> + +<sect1 id="sync-trouble"><title>Troubleshooting</title> <para>Problems with <emphasis>conntrackd</emphasis>? The following list of questions should help for troubleshooting:</para> @@ -1024,8 +1180,6 @@ not enough space errors: 0 </qandaset> -</sect2> - </sect1> </chapter> diff --git a/doc/sync/alarm/conntrackd.conf b/doc/sync/alarm/conntrackd.conf index b9520fb..0223745 100644 --- a/doc/sync/alarm/conntrackd.conf +++ b/doc/sync/alarm/conntrackd.conf @@ -194,7 +194,8 @@ Sync { # Set this option on if you want to enable the synchronization # of expectations. You have to specify the list of helpers that - # you want to enable. Default is off. + # you want to enable. Default is off. This feature requires + # a Linux kernel >= 3.5. # # ExpectationSync { # ftp diff --git a/doc/sync/ftfw/conntrackd.conf b/doc/sync/ftfw/conntrackd.conf index 53a7d0f..65e7b77 100644 --- a/doc/sync/ftfw/conntrackd.conf +++ b/doc/sync/ftfw/conntrackd.conf @@ -217,7 +217,8 @@ Sync { # Set this option on if you want to enable the synchronization # of expectations. You have to specify the list of helpers that - # you want to enable. Default is off. + # you want to enable. Default is off. This feature requires + # a Linux kernel >= 3.5. # # ExpectationSync { # ftp diff --git a/doc/sync/notrack/conntrackd.conf b/doc/sync/notrack/conntrackd.conf index 11f022e..3d036fb 100644 --- a/doc/sync/notrack/conntrackd.conf +++ b/doc/sync/notrack/conntrackd.conf @@ -256,7 +256,8 @@ Sync { # Set this option on if you want to enable the synchronization # of expectations. You have to specify the list of helpers that - # you want to enable. Default is off. + # you want to enable. Default is off. This feature requires + # a Linux kernel >= 3.5. # # ExpectationSync { # ftp |