diff options
Diffstat (limited to 'doc/manual')
| -rw-r--r-- | doc/manual/Makefile | 4 | ||||
| -rw-r--r-- | doc/manual/config.xsl | 10 | ||||
| -rw-r--r-- | doc/manual/conntrack-tools.html | 202 | ||||
| -rw-r--r-- | doc/manual/conntrack-tools.tmpl | 577 | ||||
| -rw-r--r-- | doc/manual/docbook.css | 43 |
5 files changed, 836 insertions, 0 deletions
diff --git a/doc/manual/Makefile b/doc/manual/Makefile new file mode 100644 index 0000000..bd179a6 --- /dev/null +++ b/doc/manual/Makefile @@ -0,0 +1,4 @@ +html-no-chunks: + xmlto xhtml-nochunks -m config.xsl conntrack-tools.tmpl +clean: + rm -f conntrack-tools.html diff --git a/doc/manual/config.xsl b/doc/manual/config.xsl new file mode 100644 index 0000000..04722a5 --- /dev/null +++ b/doc/manual/config.xsl @@ -0,0 +1,10 @@ +<?xml version='1.0'?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:fo="http://www.w3.org/1999/XSL/Format" + version="1.0"> + <xsl:param name="use.id.as.filename" select="'1'"/> + <xsl:param name="admon.graphics" select="'1'"/> + <xsl:param name="admon.graphics.path"></xsl:param> + <xsl:param name="chunk.section.depth" select="0"></xsl:param> + <xsl:param name="html.stylesheet" select="'docbook.css'"/> +</xsl:stylesheet> diff --git a/doc/manual/conntrack-tools.html b/doc/manual/conntrack-tools.html new file mode 100644 index 0000000..c2702b1 --- /dev/null +++ b/doc/manual/conntrack-tools.html @@ -0,0 +1,202 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The conntrack-tools user manual</title><link rel="stylesheet" href="docbook.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.72.0" /></head><body><div class="book" lang="en" xml:lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="conntrack-tools-how-to"></a>The conntrack-tools user manual</h1></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Pablo</span> <span class="surname">Neira Ayuso</span></h3><div class="affiliation"><div class="address"><p><br /> + <code class="email"><<a href="mailto:pablo@netfilter.org">pablo@netfilter.org</a>></code><br /> + </p></div></div></div></div></div><div><p class="releaseinfo"> + This document details how to install and configure the + <a href="http://conntrack-tools.netfilter.org" target="_top">conntrack-tools</a> + 0.9.8. This software is under development, for that reason, it is likely + that this document will evolve in the future to cover new features and + changes.</p></div><div><p class="copyright">Copyright © 2008 Pablo Neira Ayuso</p></div><div><div class="legalnotice"><a id="id2592572"></a><p> + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + </p></div></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#introduction">1. Introduction</a></span></dt><dt><span class="chapter"><a href="#what">2. What are the conntrack-tools?</a></span></dt><dt><span class="chapter"><a href="#requirements">3. Requirements</a></span></dt><dt><span class="chapter"><a href="#Installation">4. Installation</a></span></dt><dt><span class="chapter"><a href="#conntrack">5. Using conntrack: the command line interface</a></span></dt><dt><span class="chapter"><a href="#settingup">6. Setting up conntrackd: the daemon</a></span></dt><dd><dl><dt><span class="sect1"><a href="#sync">State table synchronization</a></span></dt><dd><dl><dt><span class="sect2"><a href="#sync-requirements">Requirements</a></span></dt><dt><span class="sect2"><a href="#sync-configure">Configuring the daemon</a></span></dt><dt><span class="sect2"><a href="#sync-pb">Active-Backup setup</a></span></dt><dt><span class="sect2"><a href="#sync-aa">Active-Active setup</a></span></dt><dt><span class="sect2"><a href="#sync-launch">Launching conntrackd</a></span></dt><dt><span class="sect2"><a href="#sync-trouble">Troubleshooting</a></span></dt></dl></dd></dl></dd></dl></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="introduction"></a>Chapter 1. Introduction</h2></div></div></div><p>This document should be a kick-off point to install and configure the + <a href="http://conntrack-tools.netfilter.org" target="_top">conntrack-tools</a>. + If you find any error or imprecision in this document, please send an email + to the author, it will be appreciated.</p><p>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 <span class="emphasis"><em>stateful</em></span> and <span class="emphasis"><em>stateless</em></span> firewalls. If this is not your case, I strongly suggest you to read the article <a href="http://people.netfilter.org/pablo/docs/login.pdf" target="_top">Netfilter's Connection Tracking System</a> published in <span class="emphasis"><em>:login; the USENIX magazine</em></span>. That document contains a general description that should help to clarify the concepts.</p><p>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 <span class="emphasis"><em>stateless</em></span>, it is very likely that the <span class="emphasis"><em>conntrack-tools</em></span> will not be of any help for you. You have been warned!</p></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="what"></a>Chapter 2. What are the conntrack-tools?</h2></div></div></div><p>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 <a href="http://people.netfilter.org/pablo/docs/login.pdf" target="_top">Connection Tracking System</a>, 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 <span class="emphasis"><em>state</em></span> or <span class="emphasis"><em>ctstate</em></span> iptables matches, you are indeed using it. + + </p><p>The <a href="http://conntrack-tools.netfilter.org" target="_top">conntrack-tools</a> package contains two programs:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="emphasis"><em>conntrack</em></span> is command line interface conntrack provides a more flexible interface to the connnection tracking system than /proc/net/ip_conntrack. With conntrack, you can show, delete and update the existing state entries; and you can also listen to flow events.</p></li><li><p><span class="emphasis"><em>conntrackd</em></span> is the user-space connection tracking daemon. This daemon can be used to deploy fault-tolerant GNU/Linux firewalls but you can also use it to collect flow-based statistics of the firewall use.</p></li></ul></div><p>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.</p></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="requirements"></a>Chapter 3. Requirements</h2></div></div></div><p>You have to install the following software in order to get the <span class="emphasis"><em>conntrack-tools</em></span> working. Make sure that you have installed them correctly before going ahead:</p><div class="itemizedlist"><ul type="disc"><li><p><a href="http://www.kernel.org" target="_top">Linux kernel</a> version >= 2.6.18 that, at least, has support for:</p><div class="itemizedlist"><ul type="circle"><li><p>Connection Tracking System.</p><div class="itemizedlist"><ul type="square"><li><p>CONFIG_NF_CONNTRACK=m</p></li><li><p>CONFIG_NF_CONNTRACK_IPV4=m</p></li><li><p>CONFIG_NF_CONNTRACK_IPV6=m (if your setup supports IPv6)</p></li></ul></div></li><li><p>nfnetlink: the generic messaging interface for Netfilter.</p><div class="itemizedlist"><ul type="square"><li><p>CONFIG_NETFILTER_NETLINK=m</p></li></ul></div></li><li><p>nf_conntrack_netlink: the messaging interface for the Connection Tracking System.</p><div class="itemizedlist"><ul type="square"><li><p>CONFIG_NF_CT_NETLINK=m</p></li></ul></div></li><li><p>connection tracking event notification API: the flow-based event notification interface.</p><div class="itemizedlist"><ul type="square"><li><p>CONFIG_NF_CONNTRACK_EVENTS=y</p></li></ul></div></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note: Verifying kernel support"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="note.png" /></td><th align="left">Verifying kernel support</th></tr><tr><td align="left" valign="top"><p> + Make sure you have loaded <span class="emphasis"><em>nf_conntrack</em></span>, <span class="emphasis"><em>nf_conntrack_ipv4</em></span> (if your setup also supports IPv6, <span class="emphasis"><em>nf_conntrack_ipv6</em></span>) and <span class="emphasis"><em>nf_conntrack_netlink</em></span>. + </p></td></tr></table></div></li><li><p>libnfnetlink: the netfilter netlink library use the official release available in <a href="http://www.netfilter.org" target="_top">netfilter.org</a></p></li><li><p>libnetfilter_conntrack: the netfilter netlink library use the official release available in <a href="http://www.netfilter.org" target="_top">netfilter.org</a></p></li></ul></div></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="Installation"></a>Chapter 4. Installation</h2></div></div></div><p>To compile and install the <span class="emphasis"><em>conntrack-tools</em></span> run the following commands:</p><pre class="programlisting"> + (non-root)$ tar xvjf conntrack-tools-x.x.x.tar.bz2 + (non-root)$ cd conntrack-tools-x.x.x + (non-root)$ ./configure --prefix=/usr + (non-root)$ make + (root) # make install</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note: Fedora Users"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="note.png" /></td><th align="left">Fedora Users</th></tr><tr><td align="left" valign="top"><p>If you are installing the libraries in /usr/local/, do not forget to do the following things:</p><div class="itemizedlist"><ul type="disc"><li><p>PKG_CONFIG_PATH=/usr/local/lib/pkgconfig; export PKG_CONFIG_PATH</p></li><li><p>Add `/usr/local/lib' to your /etc/ld.so.conf file and run `ldconfig'</p></li></ul></div><p>Check `ldd' for trouble-shooting, read <a href="http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html" target="_top">this</a> for more information on how libraries work.</p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note: Verifying kernel support"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="note.png" /></td><th align="left">Verifying kernel support</th></tr><tr><td align="left" valign="top"><p>To check that the modules are enabled in the kernel, run <span class="emphasis"><em>`conntrack -E'</em></span> and generate traffic, you should see flow events reporting new connections and updates. + </p></td></tr></table></div></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="conntrack"></a>Chapter 5. Using conntrack: the command line interface</h2></div></div></div><p>The <span class="emphasis"><em>/proc/net/ip_conntrack</em></span> interface is very limited as it only allows you to display the existing flows, their state and other information:</p><pre class="programlisting"> + # cat /proc/net/ip_conntrack + 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 secmark=0 use=1 + 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 secmark=0 use=1 + </pre><p>The command line tool <span class="emphasis"><em>conntrack</em></span> can be used to display the same information:</p><pre class="programlisting"> + # 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 secmark=0 use=1 + 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 secmark=0 use=1 +conntrack v0.9.7 (conntrack-tools): 2 flow entries has been shown. + </pre><p>You can natively filter the output without using <span class="emphasis"><em>grep</em></span>:</p><pre class="programlisting"> + # conntrack -L -p tcp --dport 34856 + 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 secmark=0 use=1 +conntrack v0.9.7 (conntrack-tools): 1 flow entries has been shown. + </pre><p>Update the mark based on a selection, this allows you to change the mark of an entry without using the CONNMARK target:</p><pre class="programlisting"> + # conntrack -U -p tcp --dport 3486 --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=1 secmark=0 use=1 +conntrack v0.9.7 (conntrack-tools): 1 flow entries has been updated. + </pre><p>Delete one entry, this can be used to block traffic (you have to set <span class="emphasis"><em>/proc/sys/net/ipv4/netfilter/ip_conntrack_tcp_be_liberal</em></span> to zero).</p><pre class="programlisting"> + # conntrack -D -p tcp --dport 3486 + 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=1 secmark=0 use=1 +conntrack v0.9.7 (conntrack-tools): 1 flow entries has been deleted. + </pre><p>Display the connection tracking events:</p><pre class="programlisting"> + # 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 + [UPDATE] udp 17 29 src=192.168.2.100 dst=192.168.2.1 sport=57767 dport=53 src=192.168.2.1 dst=192.168.2.100 sport=53 dport=57767 + [NEW] tcp 6 120 SYN_SENT src=192.168.2.100 dst=66.102.9.104 sport=33379 dport=80 [UNREPLIED] src=66.102.9.104 dst=192.168.2.100 sport=80 dport=33379 + [UPDATE] tcp 6 60 SYN_RECV 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 + [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] +</pre><p>You can also display the existing flows in XML format, filter the output based on the NAT handling applied, etc.</p></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="settingup"></a>Chapter 6. Setting up conntrackd: the daemon</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#sync">State table synchronization</a></span></dt><dd><dl><dt><span class="sect2"><a href="#sync-requirements">Requirements</a></span></dt><dt><span class="sect2"><a href="#sync-configure">Configuring the daemon</a></span></dt><dt><span class="sect2"><a href="#sync-pb">Active-Backup setup</a></span></dt><dt><span class="sect2"><a href="#sync-aa">Active-Active setup</a></span></dt><dt><span class="sect2"><a href="#sync-launch">Launching conntrackd</a></span></dt><dt><span class="sect2"><a href="#sync-trouble">Troubleshooting</a></span></dt></dl></dd></dl></div><p>The daemon <span class="emphasis"><em>conntrackd</em></span> supports two working modes:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="emphasis"><em>State table synchronization</em></span>: 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.</p></li><li><p><span class="emphasis"><em>Flow-based statistics collection</em></span>: the daemon can be used to collect flow-based statistics. This feature is similar to what <a href="http://www.netfilter.org/projects/ulogd2/" target="_top">ulogd-2.x</a> provides.</p></li></ul></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sync"></a>State table synchronization</h2></div></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sync-requirements"></a>Requirements</h3></div></div></div><p>In order to get <span class="emphasis"><em>conntrackd</em></span> working in synchronization mode, you have to fulfill the following requirements:</p><div class="orderedlist"><ol type="1"><li><p>A <span class="emphasis"><em>high availability manager</em></span> like <a href="http://www.keepalived.org" target="_top">keepalived</a> 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, <span class="emphasis"><em>conntrackd</em></span> will not work appropriately.</p><p>The state synchronization setup requires a working installation of <a href="http://www.keepalived.org" target="_top">keepalived</a>, preferibly a recent version. Check if your distribution comes with a recent packaged version. Otherwise, you may compile it from the sources. + </p><p> + There is a very simple example file in the <span class="emphasis"><em>conntrackd</em></span> + sources to setup a simple HA cluster with keepalived (see the file + keepalived.conf under the doc/sync/ directory). This file can be used to + set up a simple VRRP cluster composed of two machines that hold the virtual + IPs 192.168.0.100 on eth0 and 192.168.1.100 on eth1.</p><p>If you are not familiar with <span class="emphasis"><em>keepalived</em></span>, please + read the official documentation available at the keepalived website + (<a href="http://www.keepalived.org" target="_top">http://www.keepalived.org</a>).</p><p>If you use a different high availability manager, make sure it works correctly before going ahead.</p></li><li><p>A dedicated link. The dedicated link between the firewalls is used + to transmit and receive the state information. The use of a dedicated link + is mandatory for security reasons as someone may pick the state information + that is transfered between the firewalls.</p></li><li><p>A well-formed stateful rule-set. Otherwise you are likely to experience + problems during the fail-over. An example of a well-formed stateful iptables + rule-set is available in the <a href="http://conntrack-tools.netfilter.org/testcase.html" target="_top">conntrack-tools website</a>.</p></li><li><p>If your Linux kernel is < 2.6.22, you have to disable TCP window + tracking: + </p><pre class="programlisting"> + # echo 1 > /proc/sys/net/ipv4/netfilter/ip_conntrack_tcp_be_liberal + </pre><p> + </p></li></ol></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sync-configure"></a>Configuring the daemon</h3></div></div></div><p>The daemon <span class="emphasis"><em>conntrackd</em></span> in synchronization mode + supports up to three replication approaches:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="emphasis"><em>notrack</em></span>: this approach is the most simple as + it is based on a best effort replication protocol, ie. unreliable + protocol. This protocol sends and receives the state information + without performing any specific checking. + </p></li><li><p><span class="emphasis"><em>ft-fw</em></span>: this approach is based on a reliable + protocol that performs message tracking. Thus, the protocol can recover + from message loss, re-ordering and corruption.</p></li><li><p><span class="emphasis"><em>alarm</em></span>: this approach is spamming. It is based + on a alarm-based protocol that periodically re-sends the flow state to + the backup firewall replicas. This protocol consumes a lot of bandwidth + but it resolves synchronization problems fast.</p></li></ul></div><p>The three existing approaches are soft real-time asynchronous + replication protocols that are aimed to have negligible impact in terms + of latency and bandwidth throughput in the stateful firewall filtering.</p><p>To configure <span class="emphasis"><em>conntrackd</em></span> in any of the existing + synchronization modes, you have to copy the example configuration file to + the directory /etc/conntrackd/ on every firewall replica. Note that + <span class="emphasis"><em>_type_</em></span> is the synchronization type selected.</p><pre class="programlisting"> + (conntrack-tools-x.x.x)# cp doc/_type_/conntrackd.conf /etc/conntrackd/conntrackd.conf +</pre><p> + Do not forget to edit the files before going ahead. There are several + parameters that you have to tune to adapt the example configuration file + to your setup. +</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note: Configuration file location"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="note.png" /></td><th align="left">Configuration file location</th></tr><tr><td align="left" valign="top"><p>If you don't want to put the config file under /etc/conntrackd/, just tell conntrackd where to find it passing the option -C.</p></td></tr></table></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sync-pb"></a>Active-Backup setup</h3></div></div></div><p>In the Active-Backup setup, one of the stateful firewall replicas + filters traffic and the other acts as backup. If you use this approach, + you have to copy the script <span class="emphasis"><em>primary-backup.sh</em></span> to: + </p><pre class="programlisting"> + (conntrack-tools-x.x.x)# cp doc/sync/primary-backup.sh /etc/conntrackd/ +</pre><p>The HA manager invokes this script when a transition happens, ie. If + a stateful firewall replica:</p><div class="itemizedlist"><ul type="disc"><li><p>becomes active to recover the filtering.</p></li><li><p>becomes backup.</p></li><li><p>hits failure (this is available if the HA manager has a failure state, which is true for <a href="http://www.keepalived.org" target="_top">keepalived</a>.</p></li></ul></div><p>The script is simple, and it contains the different actions that + <span class="emphasis"><em>conntrackd</em></span> performs to recover the filtering or + purge obsolete entries from the state table, among others. The script is + commented, you can have a look at it if you need further information.</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sync-aa"></a>Active-Active setup</h3></div></div></div><p>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.</p><p>We can classify the type of Active-Active setups in several + families:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="emphasis"><em>Symmetric path routing</em></span>: The stateful firewall + replicas share the workload in terms of flows, ie. the packets that are + part of a flow are always filtered by the same firewall.</p></li><li><p><span class="emphasis"><em>Asymmetric multi-path routing</em></span>: The packets that + are part of a flow can be filtered by whatever stateful firewall in the + cluster. Thus, every flow-states have to be propagated to all the firewalls + in the cluster as we do not know which one would be the next to filter a + packet. This setup goes against the design of stateful firewalls as we + define the filtering policy based on flows, not in packets anymore. + </p></li></ul></div><p>As for 0.9.8, the design of <span class="emphasis"><em>conntrackd</em></span> 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. + </p><p>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.</p><p>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 <span class="emphasis"><em>conntrackd</em></span>. 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).</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sync-launch"></a>Launching conntrackd</h3></div></div></div><p> + Once you have configured <span class="emphasis"><em>conntrackd</em></span>, you can run in + <span class="emphasis"><em>console mode</em></span> which is an interactive mode, in that case + type 'conntrackd' as root.</p><pre class="programlisting">(root)# conntrackd</pre><p>If you want to run <span class="emphasis"><em>conntrackd</em></span> in <span class="emphasis"><em>daemon + mode</em></span>, then type:</p><pre class="programlisting">(root)# conntrackd -d</pre><p>You can verify that conntrackd is running by checking the log messages + via <span class="emphasis"><em>ps</em></span>. Moreover, if <span class="emphasis"><em>conntrackd</em></span> is + running fine, you can dump the current status of the daemon:</p><pre class="programlisting"> + # conntrackd -s + cache internal: + current active connections: 4 + connections created: 4 failed: 0 + connections updated: 0 failed: 0 + connections destroyed: 0 failed: 0 + + cache external: + current active connections: 0 + connections created: 0 failed: 0 + connections updated: 0 failed: 0 + connections destroyed: 0 failed: 0 + + traffic processed: + 0 Bytes 0 Pckts + + multicast traffic: + 352 Bytes sent 0 Bytes recv + 22 Pckts sent 0 Pckts recv + 0 Error send 0 Error recv + + multicast sequence tracking: + 0 Pckts mfrm 0 Pckts lost + </pre><p>This command displays the number of entries in the internal and + external cache:</p><div class="itemizedlist"><ul type="disc"><li><p>The internal cache contains the states that this firewall replica is filtering, ie. this is a cache of the kernel state table. + </p></li><li><p>The external cache contains the states that the other firewall replica is filtering. + </p></li></ul></div><p>You can dump the internal cache with the following command:</p><pre class="programlisting"> + # conntrackd -i + tcp 6 ESTABLISHED src=192.168.2.100 dst=139.174.175.20 sport=58491 dport=993 src=139.174.175.20 dst=192.168.2.100 sport=993 dport=58491 [ASSURED] mark=0 secmark=0 [active since 536s] + tcp 6 ESTABLISHED src=192.168.2.100 dst=123.59.27.117 sport=38211 dport=993 src=123.59.27.117 dst=192.168.2.100 sport=993 dport=38211 [ASSURED] mark=0 secmark=0 [active since 536s] + tcp 6 ESTABLISHED src=192.168.2.100 dst=123.59.27.117 sport=38209 dport=993 src=123.59.27.117 dst=192.168.2.100 sport=993 dport=38209 [ASSURED] mark=0 secmark=0 [active since 536s] + tcp 6 TIME_WAIT src=192.168.2.100 dst=74.125.45.166 sport=42593 dport=80 src=74.125.45.166 dst=192.168.2.100 sport=80 dport=42593 [ASSURED] [active since 165s] + tcp 6 ESTABLISHED src=192.168.2.100 dst=139.174.175.20 sport=37962 dport=993 src=139.174.175.20 dst=192.168.2.100 sport=993 dport=37962 [ASSURED] mark=0 secmark=0 [active since 536s] + </pre><p>You can dump the external cache with the following command:</p><pre class="programlisting"># conntrackd -e</pre><p>If the replication works fine, <span class="emphasis"><em>conntrackd -s</em></span> + displays the active's internal cache should display the same number of + entries than the backup's external cache and vice-versa.</p><p>To verify that the recovery works fine, if you trigger a fail-over, + the log files should display the following information:</p><pre class="programlisting"> + [Thu Sep 18 18:03:02 2008] (pid=9759) [notice] committing external cache + [Thu Sep 18 18:03:02 2008] (pid=9759) [notice] Committed 1545 new entries</pre><p>This means that the state entries have been injected into the kernel correctly.</p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="sync-trouble"></a>Troubleshooting</h3></div></div></div><p>Problems with <span class="emphasis"><em>conntrackd</em></span>? The following list + of questions should help for troubleshooting:</p><div class="qandaset"><dl><dt>1. <a href="#id2553370"> + I see packets lost in conntrackd -s + </a></dt><dt>2. <a href="#id2553403"> + The log messages report that the maximum netlink socket buffer has been reached. + </a></dt><dt>3. <a href="#id2553432"> + I see can't open multicast server in the log messages + </a></dt><dt>4. <a href="#id2602252"> + Can I use wackamole, heartattack or any other HA manager? + </a></dt></dl><table border="0" summary="Q and A Set"><col align="left" width="1%" /><tbody><tr class="question"><td align="left" valign="top"><a id="id2553370"></a><a id="id2553372"></a><b>1.</b></td><td align="left" valign="top"><p> + I see <span class="emphasis"><em>packets lost</em></span> in <span class="emphasis"><em>conntrackd -s</em></span> + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + You can rise the value of <span class="emphasis"><em>McastRcvSocketBuffer</em></span> and <span class="emphasis"><em>McastRcvSocketBuffer</em></span>, if the problem is due to buffer overruns in the multicast sender or the receiver, the problem should disapear. + </p></td></tr><tr class="question"><td align="left" valign="top"><a id="id2553403"></a><a id="id2553405"></a><b>2.</b></td><td align="left" valign="top"><p> + The log messages report that the <span class="emphasis"><em>maximum netlink socket buffer has been reached</em></span>. + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + You can increase the values of <span class="emphasis"><em>SocketBufferSize</em></span> and <span class="emphasis"><em>SocketBufferSizeMaxGrown</em></span>. + </p></td></tr><tr class="question"><td align="left" valign="top"><a id="id2553432"></a><a id="id2553435"></a><b>3.</b></td><td align="left" valign="top"><p> + I see <span class="emphasis"><em>can't open multicast server</em></span> in the log messages + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + Make sure that the <span class="emphasis"><em>IPv4_interface</em></span> clause has the IP of the dedicated link. + </p></td></tr><tr class="question"><td align="left" valign="top"><a id="id2602252"></a><a id="id2602254"></a><b>4.</b></td><td align="left" valign="top"><p> + Can I use <a href="http://www.backhand.org/wackamole/" target="_top">wackamole</a>, heartattack or any other HA manager? + </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p> + Absolutely, you can. But before reporting issues, make sure that your HA manager is not the source of the problems. + </p></td></tr></tbody></table></div></div></div></div></div></body></html> diff --git a/doc/manual/conntrack-tools.tmpl b/doc/manual/conntrack-tools.tmpl new file mode 100644 index 0000000..b897318 --- /dev/null +++ b/doc/manual/conntrack-tools.tmpl @@ -0,0 +1,577 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> + +<book id="conntrack-tools-how-to"> + <bookinfo> + <title>The conntrack-tools user manual</title> + + <authorgroup> + <author> + <firstname>Pablo</firstname> + <surname>Neira Ayuso</surname> + <affiliation> + <address> + <email>pablo@netfilter.org</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2008</year> + <holder>Pablo Neira Ayuso</holder> + </copyright> + + <legalnotice> + <para> + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + </para> + </legalnotice> + + <releaseinfo> + This document details how to install and configure the + <ulink url="http://conntrack-tools.netfilter.org">conntrack-tools</ulink> + 0.9.8. This software is under development, for that reason, it is likely + that this document will evolve in the future to cover new features and + changes.</releaseinfo> + + </bookinfo> + + <toc></toc> + + <chapter id="introduction"><title>Introduction</title> + + <para>This document should be a kick-off point to install and configure the + <ulink url="http://conntrack-tools.netfilter.org">conntrack-tools</ulink>. + If you find any error or imprecision in this document, please send an email + to the author, it will be appreciated.</para> + + <para>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 <emphasis>stateful</emphasis> and <emphasis>stateless</emphasis> firewalls. If this is not your case, I strongly suggest you to read the article <ulink url="http://people.netfilter.org/pablo/docs/login.pdf">Netfilter's Connection Tracking System</ulink> published in <emphasis>:login; the USENIX magazine</emphasis>. That document contains a general description that should help to clarify the concepts.</para> + +<para>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 <emphasis>stateless</emphasis>, it is very likely that the <emphasis>conntrack-tools</emphasis> will not be of any help for you. You have been warned!</para> + + </chapter> + <chapter id="what"><title>What are the conntrack-tools?</title> + + <para>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 <ulink url="http://people.netfilter.org/pablo/docs/login.pdf">Connection Tracking System</ulink>, 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 <emphasis>state</emphasis> or <emphasis>ctstate</emphasis> iptables matches, you are indeed using it. + + </para> + +<para>The <ulink url="http://conntrack-tools.netfilter.org">conntrack-tools</ulink> package contains two programs:</para> + + <itemizedlist> + <listitem> + <para><emphasis>conntrack</emphasis> is command line interface conntrack provides a more flexible interface to the connnection tracking system than /proc/net/ip_conntrack. With conntrack, you can show, delete and update the existing state entries; and you can also listen to flow events.</para> + </listitem> + <listitem> + <para><emphasis>conntrackd</emphasis> is the user-space connection tracking daemon. This daemon can be used to deploy fault-tolerant GNU/Linux firewalls but you can also use it to collect flow-based statistics of the firewall use.</para> + </listitem> + </itemizedlist> + + <para>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.</para> + + </chapter> + + <chapter id="requirements"><title>Requirements</title> + + <para>You have to install the following software in order to get the <emphasis>conntrack-tools</emphasis> working. Make sure that you have installed them correctly before going ahead:</para> + + <itemizedlist> + <listitem> + <para><ulink url="http://www.kernel.org">Linux kernel</ulink> version >= 2.6.18 that, at least, has support for:</para> + <itemizedlist> + <listitem> + <para>Connection Tracking System.</para> + <itemizedlist> + <listitem> + <para>CONFIG_NF_CONNTRACK=m</para> + </listitem> + <listitem> + <para>CONFIG_NF_CONNTRACK_IPV4=m</para> + </listitem> + <listitem> + <para>CONFIG_NF_CONNTRACK_IPV6=m (if your setup supports IPv6)</para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para>nfnetlink: the generic messaging interface for Netfilter.</para> + <itemizedlist> + <listitem> + <para>CONFIG_NETFILTER_NETLINK=m</para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para>nf_conntrack_netlink: the messaging interface for the Connection Tracking System.</para> + <itemizedlist> + <listitem> + <para>CONFIG_NF_CT_NETLINK=m</para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para>connection tracking event notification API: the flow-based event notification interface.</para> + <itemizedlist> + <listitem> + <para>CONFIG_NF_CONNTRACK_EVENTS=y</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + <note><title>Verifying kernel support</title> + <para> + Make sure you have loaded <emphasis>nf_conntrack</emphasis>, <emphasis>nf_conntrack_ipv4</emphasis> (if your setup also supports IPv6, <emphasis>nf_conntrack_ipv6</emphasis>) and <emphasis>nf_conntrack_netlink</emphasis>. + </para> + </note> + </listitem> + <listitem> + <para>libnfnetlink: the netfilter netlink library use the official release available in <ulink url="http://www.netfilter.org">netfilter.org</ulink></para> + </listitem> + <listitem> + <para>libnetfilter_conntrack: the netfilter netlink library use the official release available in <ulink url="http://www.netfilter.org">netfilter.org</ulink></para> + </listitem> + </itemizedlist> + </chapter> + + <chapter id="Installation"><title>Installation</title> + + <para>To compile and install the <emphasis>conntrack-tools</emphasis> run the following commands:</para> + <programlisting> + (non-root)$ tar xvjf conntrack-tools-x.x.x.tar.bz2 + (non-root)$ cd conntrack-tools-x.x.x + (non-root)$ ./configure --prefix=/usr + (non-root)$ make + (root) # make install</programlisting> + +<note><title>Fedora Users</title> + <para>If you are installing the libraries in /usr/local/, do not forget to do the following things:</para> + <itemizedlist> + <listitem><para>PKG_CONFIG_PATH=/usr/local/lib/pkgconfig; export PKG_CONFIG_PATH</para></listitem> + <listitem><para>Add `/usr/local/lib' to your /etc/ld.so.conf file and run `ldconfig'</para></listitem> + </itemizedlist> + <para>Check `ldd' for trouble-shooting, read <ulink url="http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html">this</ulink> for more information on how libraries work.</para> +</note> + +<note><title>Verifying kernel support</title> + <para>To check that the modules are enabled in the kernel, run <emphasis>`conntrack -E'</emphasis> and generate traffic, you should see flow events reporting new connections and updates. + </para> +</note> + + </chapter> + + <chapter id="conntrack"><title>Using conntrack: the command line interface</title> + + <para>The <emphasis>/proc/net/ip_conntrack</emphasis> interface is very limited as it only allows you to display the existing flows, their state and other information:</para> + + <programlisting> + # cat /proc/net/ip_conntrack + 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 secmark=0 use=1 + 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 secmark=0 use=1 + </programlisting> + +<para>The command line tool <emphasis>conntrack</emphasis> can be used to display the same information:</para> + <programlisting> + # 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 secmark=0 use=1 + 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 secmark=0 use=1 +conntrack v0.9.7 (conntrack-tools): 2 flow entries have been shown. + </programlisting> + +<para>You can natively filter the output without using <emphasis>grep</emphasis>:</para> +<programlisting> + # conntrack -L -p tcp --dport 34856 + 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 secmark=0 use=1 +conntrack v0.9.7 (conntrack-tools): 1 flow entries have been shown. + </programlisting> + +<para>Update the mark based on a selection, this allows you to change the mark of an entry without using the CONNMARK target:</para> +<programlisting> + # conntrack -U -p tcp --dport 3486 --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=1 secmark=0 use=1 +conntrack v0.9.7 (conntrack-tools): 1 flow entries has been updated. + </programlisting> + +<para>Delete one entry, this can be used to block traffic (you have to set <emphasis>/proc/sys/net/ipv4/netfilter/ip_conntrack_tcp_be_liberal</emphasis> to zero).</para> +<programlisting> + # conntrack -D -p tcp --dport 3486 + 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=1 secmark=0 use=1 +conntrack v0.9.7 (conntrack-tools): 1 flow entries has been deleted. + </programlisting> + +<para>Display the connection tracking events:</para> +<programlisting> + # 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 + [UPDATE] udp 17 29 src=192.168.2.100 dst=192.168.2.1 sport=57767 dport=53 src=192.168.2.1 dst=192.168.2.100 sport=53 dport=57767 + [NEW] tcp 6 120 SYN_SENT src=192.168.2.100 dst=66.102.9.104 sport=33379 dport=80 [UNREPLIED] src=66.102.9.104 dst=192.168.2.100 sport=80 dport=33379 + [UPDATE] tcp 6 60 SYN_RECV 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 + [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] +</programlisting> + +<para>You can also display the existing flows in XML format, filter the output based on the NAT handling applied, etc.</para> + +</chapter> + + <chapter id="settingup"><title>Setting up conntrackd: the daemon</title> + + <para>The daemon <emphasis>conntrackd</emphasis> supports two working modes:</para> + + <itemizedlist> + <listitem> + <para><emphasis>State table synchronization</emphasis>: 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.</para> + </listitem> + <listitem> + <para><emphasis>Flow-based statistics collection</emphasis>: the daemon can be used to collect flow-based statistics. This feature is similar to what <ulink url="http://www.netfilter.org/projects/ulogd/">ulogd-2.x</ulink> provides.</para> + </listitem> + </itemizedlist> + + <sect1 id="sync"><title>State table synchronization</title> + + <sect2 id="sync-requirements"><title>Requirements</title> + + <para>In order to get <emphasis>conntrackd</emphasis> working in synchronization mode, you have to fulfill the following requirements:</para> + + <orderedlist> + <listitem> + <para>A <emphasis>high availability manager</emphasis> like <ulink url="http://www.keepalived.org">keepalived</ulink> 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, <emphasis>conntrackd</emphasis> will not work appropriately.</para> + + <para>The state synchronization setup requires a working installation of <ulink url="http://www.keepalived.org">keepalived</ulink>, preferibly a recent version. Check if your distribution comes with a recent packaged version. Otherwise, you may compile it from the sources. + </para> + + <para> + There is a very simple example file in the <emphasis>conntrackd</emphasis> + sources to setup a simple HA cluster with keepalived (see the file + keepalived.conf under the doc/sync/ directory). This file can be used to + set up a simple VRRP cluster composed of two machines that hold the virtual + IPs 192.168.0.100 on eth0 and 192.168.1.100 on eth1.</para> + + <para>If you are not familiar with <emphasis>keepalived</emphasis>, please + read the official documentation available at the keepalived website + (<ulink url="http://www.keepalived.org">http://www.keepalived.org</ulink>).</para> + +<para>If you use a different high availability manager, make sure it works correctly before going ahead.</para> + + </listitem> + + <listitem> + <para>A dedicated link. The dedicated link between the firewalls is used + to transmit and receive the state information. The use of a dedicated link + is mandatory for security reasons as someone may pick the state information + that is transfered between the firewalls.</para> + </listitem> + + <listitem> + <para>A well-formed stateful rule-set. Otherwise you are likely to experience + problems during the fail-over. An example of a well-formed stateful iptables + rule-set is available in the <ulink url="http://conntrack-tools.netfilter.org/testcase.html">conntrack-tools website</ulink>.</para> + </listitem> + + <listitem> + <para>If your Linux kernel is < 2.6.22, you have to disable TCP window + tracking: + <programlisting> + # echo 1 > /proc/sys/net/ipv4/netfilter/ip_conntrack_tcp_be_liberal + </programlisting> + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="sync-configure"><title>Configuring the daemon</title> + + <para>The daemon <emphasis>conntrackd</emphasis> in synchronization mode + supports up to three replication approaches:</para> + + <itemizedlist> + <listitem> + <para><emphasis>notrack</emphasis>: this approach is the most simple as + it is based on a best effort replication protocol, ie. unreliable + protocol. This protocol sends and receives the state information + without performing any specific checking. + </para> + </listitem> + <listitem> + <para><emphasis>ft-fw</emphasis>: this approach is based on a reliable + protocol that performs message tracking. Thus, the protocol can recover + from message loss, re-ordering and corruption.</para> + </listitem> + <listitem> + <para><emphasis>alarm</emphasis>: this approach is spamming. It is based + on a alarm-based protocol that periodically re-sends the flow state to + the backup firewall replicas. This protocol consumes a lot of bandwidth + but it resolves synchronization problems fast.</para> + </listitem> + </itemizedlist> + + <para>The three existing approaches are soft real-time asynchronous + replication protocols that are aimed to have negligible impact in terms + of latency and bandwidth throughput in the stateful firewall filtering.</para> + + <para>To configure <emphasis>conntrackd</emphasis> in any of the existing + synchronization modes, you have to copy the example configuration file to + the directory /etc/conntrackd/ on every firewall replica. Note that + <emphasis>_type_</emphasis> is the synchronization type selected.</para> + +<programlisting> + (conntrack-tools-x.x.x)# cp doc/_type_/conntrackd.conf /etc/conntrackd/conntrackd.conf +</programlisting> + +<para> + Do not forget to edit the files before going ahead. There are several + parameters that you have to tune to adapt the example configuration file + to your setup. +</para> + +<note><title>Configuration file location</title> + <para>If you don't want to put the config file under /etc/conntrackd/, just tell conntrackd where to find it passing the option -C.</para> +</note> + +</sect2> + +<sect2 id="sync-pb"><title>Active-Backup setup</title> + + <para>In the Active-Backup setup, one of the stateful firewall replicas + filters traffic and the other acts as backup. If you use this approach, + you have to copy the script <emphasis>primary-backup.sh</emphasis> to: + </para> + +<programlisting> + (conntrack-tools-x.x.x)# cp doc/sync/primary-backup.sh /etc/conntrackd/ +</programlisting> + + <para>The HA manager invokes this script when a transition happens, ie. If + a stateful firewall replica:</para> + + <itemizedlist> + <listitem> + <para>becomes active to recover the filtering.</para> + </listitem> + <listitem> + <para>becomes backup.</para> + </listitem> + <listitem> + <para>hits failure (this is available if the HA manager has a failure state, which is true for <ulink url="http://www.keepalived.org">keepalived</ulink>.</para> + </listitem> + </itemizedlist> + + <para>The script is simple, and it contains the different actions that + <emphasis>conntrackd</emphasis> performs to recover the filtering or + purge obsolete entries from the state table, among others. The script is + commented, you can have a look at it if you need further information.</para> + +</sect2> + +<sect2 id="sync-aa"><title>Active-Active setup</title> + + <para>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.</para> + + <para>We can classify the type of Active-Active setups in several + families:</para> + + <itemizedlist> + <listitem> + <para><emphasis>Symmetric path routing</emphasis>: The stateful firewall + replicas share the workload in terms of flows, ie. the packets that are + part of a flow are always filtered by the same firewall.</para> + </listitem> + <listitem> + <para><emphasis>Asymmetric multi-path routing</emphasis>: The packets that + are part of a flow can be filtered by whatever stateful firewall in the + cluster. Thus, every flow-states have to be propagated to all the firewalls + in the cluster as we do not know which one would be the next to filter a + packet. This setup goes against the design of stateful firewalls as we + define the filtering policy based on flows, not in packets anymore. + </para> + </listitem> + </itemizedlist> + + <para>As for 0.9.8, the design of <emphasis>conntrackd</emphasis> 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. + </para> + + <para>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.</para> + + <para>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 <emphasis>conntrackd</emphasis>. 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).</para> + +</sect2> + +<sect2 id="sync-launch"><title>Launching conntrackd</title> + + <para> + Once you have configured <emphasis>conntrackd</emphasis>, you can run in + <emphasis>console mode</emphasis> which is an interactive mode, in that case + type 'conntrackd' as root.</para> + + <programlisting>(root)# conntrackd</programlisting> + + <para>If you want to run <emphasis>conntrackd</emphasis> in <emphasis>daemon + mode</emphasis>, then type:</para> + + <programlisting>(root)# conntrackd -d</programlisting> + + <para>You can verify that conntrackd is running by checking the log messages + via <emphasis>ps</emphasis>. Moreover, if <emphasis>conntrackd</emphasis> is + running fine, you can dump the current status of the daemon:</para> + + <programlisting> + # conntrackd -s + cache internal: + current active connections: 4 + connections created: 4 failed: 0 + connections updated: 0 failed: 0 + connections destroyed: 0 failed: 0 + + cache external: + current active connections: 0 + connections created: 0 failed: 0 + connections updated: 0 failed: 0 + connections destroyed: 0 failed: 0 + + traffic processed: + 0 Bytes 0 Pckts + + multicast traffic: + 352 Bytes sent 0 Bytes recv + 22 Pckts sent 0 Pckts recv + 0 Error send 0 Error recv + + multicast sequence tracking: + 0 Pckts mfrm 0 Pckts lost + </programlisting> + + <para>This command displays the number of entries in the internal and + external cache:</para> + + <itemizedlist> + <listitem> + <para>The internal cache contains the states that this firewall replica is filtering, ie. this is a cache of the kernel state table. + </para> + </listitem> + <listitem> + <para>The external cache contains the states that the other firewall replica is filtering. + </para> + </listitem> + </itemizedlist> + + <para>You can dump the internal cache with the following command:</para> + + <programlisting> + # conntrackd -i + tcp 6 ESTABLISHED src=192.168.2.100 dst=139.174.175.20 sport=58491 dport=993 src=139.174.175.20 dst=192.168.2.100 sport=993 dport=58491 [ASSURED] mark=0 secmark=0 [active since 536s] + tcp 6 ESTABLISHED src=192.168.2.100 dst=123.59.27.117 sport=38211 dport=993 src=123.59.27.117 dst=192.168.2.100 sport=993 dport=38211 [ASSURED] mark=0 secmark=0 [active since 536s] + tcp 6 ESTABLISHED src=192.168.2.100 dst=123.59.27.117 sport=38209 dport=993 src=123.59.27.117 dst=192.168.2.100 sport=993 dport=38209 [ASSURED] mark=0 secmark=0 [active since 536s] + tcp 6 TIME_WAIT src=192.168.2.100 dst=74.125.45.166 sport=42593 dport=80 src=74.125.45.166 dst=192.168.2.100 sport=80 dport=42593 [ASSURED] [active since 165s] + tcp 6 ESTABLISHED src=192.168.2.100 dst=139.174.175.20 sport=37962 dport=993 src=139.174.175.20 dst=192.168.2.100 sport=993 dport=37962 [ASSURED] mark=0 secmark=0 [active since 536s] + </programlisting> + + <para>You can dump the external cache with the following command:</para> + + <programlisting># conntrackd -e</programlisting> + + <para>If the replication works fine, <emphasis>conntrackd -s</emphasis> + displays the active's internal cache should display the same number of + entries than the backup's external cache and vice-versa.</para> + + <para>To verify that the recovery works fine, if you trigger a fail-over, + the log files should display the following information:</para> + + <programlisting> + [Thu Sep 18 18:03:02 2008] (pid=9759) [notice] committing external cache + [Thu Sep 18 18:03:02 2008] (pid=9759) [notice] Committed 1545 new entries</programlisting> + + <para>This means that the state entries have been injected into the kernel correctly.</para> + +</sect2> + +<sect2 id="sync-trouble"><title>Troubleshooting</title> + + <para>Problems with <emphasis>conntrackd</emphasis>? The following list + of questions should help for troubleshooting:</para> + + <qandaset> + + <qandaentry> + <question> + <para> + I see <emphasis>packets lost</emphasis> in <emphasis>conntrackd -s</emphasis> + </para> + </question> + <answer> + <para> + You can rise the value of <emphasis>McastRcvSocketBuffer</emphasis> and <emphasis>McastRcvSocketBuffer</emphasis>, if the problem is due to buffer overruns in the multicast sender or the receiver, the problem should disapear. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + The log messages report that the <emphasis>maximum netlink socket buffer has been reached</emphasis>. + </para> + </question> + <answer> + <para> + You can increase the values of <emphasis>SocketBufferSize</emphasis> and <emphasis>SocketBufferSizeMaxGrown</emphasis>. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + I see <emphasis>can't open multicast server</emphasis> in the log messages + </para> + </question> + <answer> + <para> + Make sure that the <emphasis>IPv4_interface</emphasis> clause has the IP of the dedicated link. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + Can I use <ulink url="http://www.backhand.org/wackamole/">wackamole</ulink>, heartattack or any other HA manager? + </para> + </question> + <answer> + <para> + Absolutely, you can. But before reporting issues, make sure that your HA manager is not the source of the problems. + </para> + </answer> + </qandaentry> + + </qandaset> + +</sect2> + +</sect1> + +</chapter> + +</book> diff --git a/doc/manual/docbook.css b/doc/manual/docbook.css new file mode 100644 index 0000000..81f4016 --- /dev/null +++ b/doc/manual/docbook.css @@ -0,0 +1,43 @@ +/* stolen from "Making your DocBook/XML HTML output not suck" */ + +body { + font-family: luxi sans,sans-serif; +} + +.screen { + font-family: monospace; + font-size: 1em; + display: block; + padding: 10px; + border: 1px solid #bbb; + background-color: #eee; + color: #000; + overflow: auto; + border-radius: 2.5px; + -moz-border-radius: 2.5px; + margin: 0.5em 2em; +} + +.programlisting { + font-family: monospace; + font-size: 1em; + display: block; + padding: 10px; + border: 1px solid #bbb; + background-color: #ddd; + color: #000; + overflow: auto; + border-radius: 2.5px; + -moz-border-radius: 2.5px; + margin: 0.5em 2em; +} + +a { + text-decoration: none; + border-bottom: 1px dotted #000; +} + +a:hover { + background-color: #777; + color: #fff; +} |