first step forward to merge conntrackd and conntrack into the same building chain

1 files changed, 199 insertions, 0 deletions

diff --git a/INSTALL b/INSTALL
new file mode 100644
index 0000000..0de8dc0
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,199 @@
+Copyright (C) 2006-2007 Pablo Neira Ayuso <pablo netfilter org>
+
+1.Basic Installation
+====================
+
+ To compile and install 'conntrackd' just follow the classical steps:
+
+	$ ./configure
+	$ make
+	# make install
+	# mkdir /etc/conntrackd/
+
+2.1. Synchronization Mode
+=========================
+
+ Conntrackd can replicate the status of the connections that are currently
+ being processed by your stateful firewall based on Linux. This section
+ describes how to setup the daemon in synchronization mode:
+
+2.1.1. Requirements
+
+ You have to install the following software in order to get conntrackd working,
+ make sure that you have installed them correctly before going forward:
+
+ o linux kernel version >= 2.6.18 (http://www.kernel.org) with support for:
+     - connection tracking system (quite obvious ;)
+     - nfnetlink
+     - ctnetlink (ip_conntrack_netlink)
+     - connection tracking event notification API
+
+ o libnfnetlink: the netfilter netlink library
+
+     Since conntrackd version 0.9.2 you can used the official release availble at
+     http://www.netfilter.org/projects/libnfnetlink/files/
+
+     Up to conntrackd version 0.9.1 use the unofficial release available at the
+     download section
+
+ o libnetfilter_conntrack: the netfilter conntrack library
+
+     Since  conntrackd version 0.9.2 you can used the official release availble at
+     http://www.netfilter.org/projects/libnetfilter_conntrack/files/
+
+     Up to conntrackd version 0.9.1 use the unnoficial release available at the
+     download section
+
+ o Keepalived version 1.x (http://www.keepalived.org)
+     check if your distribution comes with a recent version
+
+2.1.2. Configuration
+
+ 1) Setting up keepalived
+
+    There is an example file available inside the conntrackd tarball:
+
+    For node 1: conntrackd-x.x.x/examples/sync/node1/keepalived.conf
+    For node 2: conntrackd-x.x.x/examples/sync/node2/keepalived.conf
+
+    These files 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.
+
+    If you are not familiar with keepalived, please read the official
+    docs available at http://www.keepalived.org
+
+    Please, make sure that keepalived is correctly working before passing
+    to step 2)
+
+ 2) Setting up conntrackd
+
+    To setup 'conntrackd' in synchronization mode, you have to put the
+    configuration file in the directory /etc/conntrackd.
+
+    On node 1:
+	# cp examples/sync/_type_/node1/conntrackd.conf /etc/conntrackd.conf
+
+    On node 2:
+        # cp examples/sync/_type_/node1/conntrackd.conf /etc/conntrackd.conf
+
+    Where _type_ is the synchronization type selected, currently there are
+    two: the persistent mode and the NACK mode. The persistent mode consumes
+    more resources than the NACK mode, however the NACK mode is still
+    experimental
+
+    Do not forget to edit the files in order to adapt them to the
+    setting that you are deploying.
+
+    Note: If you don't want to put the config file under /etc/conntrackd,
+    just tell conntrackd where to find it passing the option -C
+
+ 3) Running conntrackd
+
+    Conntrackd can run in console mode, in that case just type 'conntrackd',
+    otherwise, if you want to run it in daemon mode the type 'conntrackd -d'.
+
+ 4) Checking that conntrackd is working fine
+
+    Conntrackd comes with several facilities to check its status:
+
+    - Dump the cache of connections that are currently being processed by
+      this node (aka. internal cache):
+
+    # conntrackd -i
+
+    - Dump the cache of connections that has been transfered from
+      others active nodes in the network (aka. external cache)
+
+    # conntrackd -e
+
+    - Dump statistics collected by the replication daemon:
+
+    # conntrackd -s
+
+ 5) Setting up interaction with keepalived
+
+    If keepalived detects the failure of the active node, then it designates
+    a candidate node that will replace the failing active. On such event,
+    the external cache, eg. the cache that contains the connections processed
+    by other nodes, must be commited. To commit the external cache, just type:
+
+    # conntrackd -c
+
+    See that keepalived provides a shell script interface to interact with
+    other programs, so we can automate the process of commiting the external
+    cache by introducing the following line in the keepalived file:
+
+    notify_master /etc/conntrackd/script_master.sh
+
+    The script 'script_master.sh' just the following:
+
+    #!/bin/sh
+    /usr/sbin/conntrackd -c
+
+    Therefore, on failure event, the candidate node takes over the virtual
+    IPs and the connections that the failing active was processing. Observe
+    that this file differs for the NACK mode.
+
+ 6) Disable TCP window tracking
+
+ Until the appropiate patches don't go into kernel mainline, you will have
+ to disable TCP window tracking, consider this as a temporary solution:
+
+    # echo 1 > /proc/sys/net/ipv4/netfilter/ip_conntrack_tcp_be_liberal
+
+2.2. Statistics mode
+====================
+
+ Conntrackd can also run as statistics daemon, if you are not interested in
+ this mode, just skip it. It is not required in order to get the
+ synchronization mode working. This section details how to setup the daemon
+ in statistics mode:
+
+2.2.1. Requirements
+
+ You have to install the following software in order to get conntrackd working,
+ make sure that you have them installed correctly before going forward:
+
+ o linux kernel version >= 2.6.18 (http://www.kernel.org) with support for:
+      - connection tracking system
+      - nfnetlink
+      - ctnetlink (ip_conntrack_netlink)
+      - connection tracking event notification API
+
+ o libnfnetlink: the netfilter netlink library
+
+     Since conntrackd version 0.9.2 you can used the official release availble at
+     http://www.netfilter.org/projects/libnfnetlink/files/
+
+     Up to conntrackd version 0.9.1 use the unofficial release available at the
+     download section
+
+ o libnetfilter_conntrack: the netfilter conntrack library
+
+     Since  conntrackd version 0.9.2 you can used the official release availble at
+     http://www.netfilter.org/projects/libnetfilter_conntrack/files/
+
+     Up to conntrackd version 0.9.1 use the unnoficial release available at the
+     download section
+
+2.2.2. Configuration
+
+ Setting up conntrackd in statistics mode is rather easy. Just copy the
+ configuration file
+
+    # cp examples/stats/conntrackd.conf /etc/conntrackd.conf
+
+2.2.3. Running conntrackd in statistics mode
+
+ To run conntrackd in statistics mode:
+
+    # conntrackd -S
+
+ Alternatively, you can run conntrackd in daemon mode:
+
+    # conntrackd -S -d
+
+ In order to dump the statistics, just type:
+
+    # conntrackd -s