Merge remote-tracking branch 'source/master' into upstreamupstream

6 files changed, 311 insertions, 62 deletions

diff --git a/doc/debian.conntrackd.init.d b/doc/debian.conntrackd.init.d
deleted file mode 100644
index ba847dd..0000000
--- a/doc/debian.conntrackd.init.d
+++ /dev/null
@@ -1,48 +0,0 @@
-#!/bin/sh
-#
-# /etc/init.d/conntrackd
-#
-# Maximilian Wilhelm <max@rfc2324.org>
-#  -- Mon, 06 Nov 2006 18:39:07 +0100
-#
-
-export PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
-
-NAME="conntrackd"
-DAEMON=`command -v conntrackd`
-CONFIG="/etc/conntrack/conntrackd.conf"
-PIDFILE="/var/run/${NAME}.pid"
-
-
-# Gracefully exit if there is no daemon (debian way of life)
-if [ ! -x "${DAEMON}" ]; then
-	exit 0
-fi
-
-# Check for config file
-if [ ! -f /etc/conntrackd/conntrackd.conf ]; then
-	echo "Error: There is no config file for $NAME" >&2
-	exit 1;
-fi
-
-case "$1" in
-  start)
-        echo -n "Starting $NAME: "
-	start-stop-daemon --start --quiet --make-pidfile --pidfile "/var/run/${NAME}.pid" --background --exec "${DAEMON}"  && echo "done." || echo "FAILED!"
-	;;
-  stop)
-        echo -n "Stopping $NAME:"
-	start-stop-daemon --stop --quiet --oknodo --pidfile "/var/run/${NAME}.pid" && echo "done." || echo "FAILED!"
-	;;
-
-  restart)
-	$0 start
-	$0 stop
-	;;
-
-  *)
-	echo "Usage: /etc/init.d/conntrackd {start|stop|restart}"
-	exit 1
-esac
-
-exit 0
diff --git a/doc/helper/conntrackd.conf b/doc/helper/conntrackd.conf
new file mode 100644
index 0000000..5c07509
--- /dev/null
+++ b/doc/helper/conntrackd.conf
@@ -0,0 +1,132 @@
+#
+# Helper settings
+#
+
+Helper {
+	# Before this, you have to make sure you have registered the `ftp'
+	# user-space helper stub via:
+	#
+	# nfct add helper 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
+		}
+	}
+	Type dhcpv6 inet6 udp {
+		QueueNum 4
+		QueueLen 10240
+		Policy dhcpv6 {
+			ExpectMax 1
+			ExpectTimeout 300
+		}
+	}
+	Type ssdp inet udp {
+		QueueNum 5
+		QueueLen 10240
+		Policy ssdp {
+			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 4936a76..87a792e 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>
-  &gt;= 1.0.0. This document will evolve in the future to cover new features
+  &gt;= 1.4.0. This document will evolve in the future to cover new features
   and changes.</releaseinfo>
 
  </bookinfo>
@@ -641,10 +641,11 @@ Sync {
  broken.</para>
 
  <para>The following example shows how to only generate the
- <emphasis>assured</emphasis> event:</para>
+ <emphasis>assured</emphasis> and <emphasis>destroy</emphasis>
+ events:</para>
 
  <programlisting>
- # iptables -I PREROUTING -t raw -j CT --ctevents assured
+ # iptables -I PREROUTING -t raw -j CT --ctevents assured,destroy
  </programlisting>
 
  <note><title>Assured flows</title>
@@ -659,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 &gt;= 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
@@ -688,7 +696,9 @@ Sync {
                ExpectationSync {
                        ftp
                        sip
-                       h323
+                       ras    # for H.323
+                       q.931  # for H.323
+                       h.245  # for H.323
                }
        }
 }</programlisting>
@@ -817,7 +827,155 @@ 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 &gt;= 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>
+<listitem><para>SSDP.</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 add helper rpc inet udp
+nfct add helper 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>
@@ -1023,8 +1181,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 deed291..0223745 100644
--- a/doc/sync/alarm/conntrackd.conf
+++ b/doc/sync/alarm/conntrackd.conf
@@ -194,11 +194,14 @@ 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
-		#       h323
+		#       ras
+		#	q.931
+		#	h.245
 		#       sip
 		# }
 		#
diff --git a/doc/sync/ftfw/conntrackd.conf b/doc/sync/ftfw/conntrackd.conf
index 0304f0f..65e7b77 100644
--- a/doc/sync/ftfw/conntrackd.conf
+++ b/doc/sync/ftfw/conntrackd.conf
@@ -217,11 +217,14 @@ 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
-		#	h323
+		#	ras
+		#	q.931
+		#	h.245
 		#	sip
 		# }
 		#
diff --git a/doc/sync/notrack/conntrackd.conf b/doc/sync/notrack/conntrackd.conf
index 34e7b32..3d036fb 100644
--- a/doc/sync/notrack/conntrackd.conf
+++ b/doc/sync/notrack/conntrackd.conf
@@ -256,11 +256,14 @@ 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
-		#       h323
+		#       ras
+		#	q.931
+		#	h.245
 		#       sip
 		# }
 		#