summaryrefslogtreecommitdiffstats
path: root/INSTALL
blob: cfb642e11000e703186459ea12617280d0e50363 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
Copyright (C) 2005-2007 Pablo Neira Ayuso <pablo netfilter org>

0.Introduction
==============

 The conntrack-tools package contains two programs:

  - conntrack:	the command line interface to interact with the connection 
		tracking system.

  - conntrackd: the connection tracking userspace daemon that can be used to
  		deploy highly available GNU/Linux firewalls and collect 
		statistics of the firewall use.

1. Requirements
===============

 You have to install the following software in order to get the conntrack-tools
 working, make sure that you have installed them correctly before going forward:

 o linux kernel version >= 2.6.18 (http://www.kernel.org) that, at least,
   has support for:

     - connection tracking system
	   CONFIG_NF_CONNTRACK=m
	   CONFIG_NF_CONNTRACK_IPV4=m

     - nfnetlink
           CONFIG_NETFILTER_NETLINK=m

     - ctnetlink (nf_conntrack_netlink)
           CONFIG_NF_CT_NETLINK=m

     - connection tracking event notification API
           CONFIG_NF_CONNTRACK_EVENTS=y

     	(To check that the event API is enabled in the kernel, make sure
	 you have loaded nf_netlink_conntrack module, run conntrack -E and 
	 generate traffic, you should see network events)

 o libnfnetlink: the netfilter netlink library available at:

     <http://www.netfilter.org/projects/libnfnetlink/files/>

 o libnetfilter_conntrack: the netfilter conntrack library available at:

     <http://www.netfilter.org/projects/libnetfilter_conntrack/files/>

2.Basic Installation
====================

 To compile and install conntrack-tools just follow the classical steps:

	$ ./configure
	$ make
	# make install

 Up to this point, the command line interface `conntrack' is ready for use,
 see man conntrack(8). However, the userspace daemon so-called `conntrackd' 
 requires some magic spells to get it working.

 *Fedora users*: If you are trying to install the libraries in /usr/local/,
 do not forget to do the following things:

	* PKG_CONFIG_PATH=/usr/local/lib/pkgconfig; export PKG_CONFIG_PATH
 	* Add `/usr/local/lib' to your /etc/ld.so.conf file and run `ldconfig'
 
 Check `ldd' for trouble-shooting, read <http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html#AEN70> for more information on how libraries work.

3.Setting up conntrackd
=======================

 conntrackd currently have two working modes: statistics and synchronization
 modes, both details here below.

3.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:


 o Keepalived version 1.x (http://www.keepalived.org)
     check if your distribution comes with a recent version

3.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/_type_/node1/keepalived.conf
    For node 2: conntrackd-x.x.x/examples/sync/_type_/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 alarm mode and the FTFW mode. The alarm mode consumes
    more resources than the FTFW mode but resolves synchronization issues 
    better. On the other the FTFW mode reduces resource consumption. I'll
    provide more information on both approaches soon.

    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 FTFW 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

3.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:

3.2.1. Requirements

 No extra requirements to set up the statistics mode apart from those detailed
 in section 1.

3.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

3.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