rename `examples' directory to `doc'

14 files changed, 722 insertions, 0 deletions

diff --git a/doc/sync/alarm/README b/doc/sync/alarm/README
new file mode 100644
index 0000000..dfd8474
--- /dev/null
+++ b/doc/sync/alarm/README
@@ -0,0 +1 @@
+This directory contains the files for the ALARM based protocol
diff --git a/doc/sync/alarm/node1/conntrackd.conf b/doc/sync/alarm/node1/conntrackd.conf
new file mode 100644
index 0000000..3004d07
--- /dev/null
+++ b/doc/sync/alarm/node1/conntrackd.conf
@@ -0,0 +1,140 @@
+#
+# Synchronizer settings
+#
+Sync {
+	Mode ALARM {
+		#
+		# If a conntrack entry is not modified in <= 15 seconds, then
+		# a message is broadcasted. This mechanism is used to
+		# resynchronize nodes that just joined the multicast group
+		#
+		RefreshTime 15
+	
+		#
+		# If we don't receive a notification about the state of 
+		# an entry in the external cache after N seconds, then
+		# remove it.
+		#
+		CacheTimeout 180
+
+		#
+		# Entries committed to the connection tracking table 
+		# starts with a limited timeout of N seconds until the
+		# takeover process is completed.
+		#
+		CommitTimeout 180
+	}
+
+	#
+	# Multicast IP and interface where messages are
+	# broadcasted (dedicated link). IMPORTANT: Make sure
+	# that iptables accepts traffic for destination
+	# 225.0.0.50, eg:
+	#
+	#	iptables -I INPUT -d 225.0.0.50 -j ACCEPT
+	#	iptables -I OUTPUT -d 225.0.0.50 -j ACCEPT
+	#
+	Multicast {
+		IPv4_address 225.0.0.50
+		IPv4_interface 192.168.100.100 # IP of dedicated link
+		Interface eth2
+		Group 3780
+	}
+
+	# Enable/Disable message checksumming
+	Checksum on
+
+	# Uncomment this if you want to replicate just certain TCP states.
+	# This option introduces a tradeoff in the replication: it reduces
+	# CPU consumption and lost messages rate at the cost of having 
+	# backup replicas that don't contain the current state that the active 
+	# replica holds. TCP states are: SYN_SENT, SYN_RECV, ESTABLISHED,
+	# FIN_WAIT, CLOSE_WAIT, LAST_ACK, TIME_WAIT, CLOSE, LISTEN.
+	# 
+	# Replicate ESTABLISHED TIME_WAIT for TCP
+
+	# If you have a multiprimary setup (active-active) without connection
+	# persistency, ie. you can't know which firewall handles a packet
+	# that is part of a connection, then you need direct commit of
+	# conntrack entries to the kernel conntrack table. OSPF setups must
+	# set on this option. Default is Off.
+	#
+	# CacheWriteThrough On
+}
+
+#
+# General settings
+#
+General {
+	#
+	# Number of buckets in the caches: hash table
+	#
+	HashSize 8192
+
+	#
+	# Maximum number of conntracks: 
+	# it must be >= $ cat /proc/sys/net/ipv4/netfilter/ip_conntrack_max
+	#
+	HashLimit 65535
+
+	#
+	# Logfile: on, off, or a filename
+	# Default: on (/var/log/conntrackd.log)
+	#
+	#LogFile off
+
+	#
+	# 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 /tmp/sync.sock
+		Backlog 20
+	}
+
+	#
+	# Netlink socket buffer size
+	#
+	SocketBufferSize 262142
+
+	#
+	# Increase the socket buffer up to maximum if required
+	#
+	SocketBufferSizeMaxGrown 655355
+}
+
+#
+# Ignore traffic for a certain set of IP's: Usually
+# all the IP assigned to the firewall since local
+# traffic must be ignored, just forwarded connections
+# are worth to replicate
+#
+IgnoreTrafficFor {
+	IPv4_address 127.0.0.1 # loopback
+	IPv4_address 192.168.0.1
+	IPv4_address 192.168.1.1
+	IPv4_address 192.168.100.100 # dedicated link ip
+	IPv4_address 192.168.0.100 # virtual IP 1
+	IPv4_address 192.168.1.100 # virtual IP 2
+}
+
+#
+# Do not replicate certain protocol traffic 
+#
+IgnoreProtocol {
+	UDP
+	ICMP
+	IGMP
+	VRRP
+	# numeric numbers also valid
+}
diff --git a/doc/sync/alarm/node1/keepalived.conf b/doc/sync/alarm/node1/keepalived.conf
new file mode 100644
index 0000000..f937467
--- /dev/null
+++ b/doc/sync/alarm/node1/keepalived.conf
@@ -0,0 +1,39 @@
+vrrp_sync_group G1 {   # must be before vrrp_instance declaration
+  group {
+    VI_1
+    VI_2
+  }
+  notify_master /etc/conntrackd/script_master.sh
+  notify_backup /etc/conntrackd/script_backup.sh
+#  notify_fault /etc/conntrackd/script_fault.sh
+}
+
+vrrp_instance VI_1 {
+    interface eth1
+    state SLAVE
+    virtual_router_id 61
+    priority 80
+    advert_int 3
+    authentication {
+      auth_type PASS
+      auth_pass papas_con_tomate
+    }
+    virtual_ipaddress {
+        192.168.0.100   # default CIDR mask is /32
+    }
+}
+
+vrrp_instance VI_2 {
+    interface eth0
+    state SLAVE
+    virtual_router_id 62
+    priority 80
+    advert_int 3
+    authentication {
+      auth_type PASS
+      auth_pass papas_con_tomate
+    }
+    virtual_ipaddress {
+        192.168.1.100
+    }
+}
diff --git a/doc/sync/alarm/node2/conntrackd.conf b/doc/sync/alarm/node2/conntrackd.conf
new file mode 100644
index 0000000..fb12130
--- /dev/null
+++ b/doc/sync/alarm/node2/conntrackd.conf
@@ -0,0 +1,140 @@
+#
+# Synchronizer settings
+#
+Sync {
+	Mode ALARM {
+		#
+		# If a conntrack entry is not modified in <= 15 seconds, then
+		# a message is broadcasted. This mechanism is used to
+		# resynchronize nodes that just joined the multicast group
+		#
+		RefreshTime 15
+	
+		#
+		# If we don't receive a notification about the state of 
+		# an entry in the external cache after N seconds, then
+		# remove it.
+		#
+		CacheTimeout 180
+
+		#
+		# Entries committed to the connection tracking table 
+		# starts with a limited timeout of N seconds until the
+		# takeover process is completed.
+		#
+		CommitTimeout 180
+	}
+
+	#
+	# Multicast IP and interface where messages are
+	# broadcasted (dedicated link). IMPORTANT: Make sure
+	# that iptables accepts traffic for destination
+	# 225.0.0.50, eg:
+	#
+	#	iptables -I INPUT -d 225.0.0.50 -j ACCEPT
+	#	iptables -I OUTPUT -d 225.0.0.50 -j ACCEPT
+	#
+	Multicast {
+		IPv4_address 225.0.0.50
+		IPv4_interface 192.168.100.200 # IP of dedicated link
+		Interface eth2
+		Group 3780
+	}
+
+	# Enable/Disable message checksumming
+	Checksum on
+
+	# Uncomment this if you want to replicate just certain TCP states.
+	# This option introduces a tradeoff in the replication: it reduces
+	# CPU consumption and lost messages rate at the cost of having 
+	# backup replicas that don't contain the current state that the active 
+	# replica holds. TCP states are: SYN_SENT, SYN_RECV, ESTABLISHED,
+	# FIN_WAIT, CLOSE_WAIT, LAST_ACK, TIME_WAIT, CLOSE, LISTEN.
+	# 
+	# Replicate ESTABLISHED TIME_WAIT for TCP
+
+	# If you have a multiprimary setup (active-active) without connection
+	# persistency, ie. you can't know which firewall handles a packet
+	# that is part of a connection, then you need direct commit of
+	# conntrack entries to the kernel conntrack table. OSPF setups must
+	# set on this option. Default is Off.
+	#
+	# CacheWriteThrough On
+}
+
+#
+# General settings
+#
+General {
+	#
+	# Number of buckets in the caches: hash table
+	#
+	HashSize 8192
+
+	#
+	# Maximum number of conntracks: 
+	# it must be >= $ cat /proc/sys/net/ipv4/netfilter/ip_conntrack_max
+	#
+	HashLimit 65535
+
+	#
+	# Logfile: on, off, or a filename
+	# Default: on (/var/log/conntrackd.log)
+	#
+	#LogFile off
+
+	#
+	# 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 /tmp/sync.sock
+		Backlog 20
+	}
+
+	#
+	# Netlink socket buffer size
+	#
+	SocketBufferSize 262142
+
+	#
+	# Increase the socket buffer up to maximum if required
+	#
+	SocketBufferSizeMaxGrown 655355
+}
+
+#
+# Ignore traffic for a certain set of IP's: Usually
+# all the IP assigned to the firewall since local
+# traffic must be ignored, just forwarded connections
+# are worth to replicate
+#
+IgnoreTrafficFor {
+	IPv4_address 127.0.0.1 # loopback
+	IPv4_address 192.168.0.2
+	IPv4_address 192.168.1.2
+	IPv4_address 192.168.100.200 # dedicated link ip
+	IPv4_address 192.168.0.200 # virtual IP 1
+	IPv4_address 192.168.1.200 # virtual IP 2
+}
+
+#
+# Do not replicate certain protocol traffic 
+#
+IgnoreProtocol {
+	UDP
+	ICMP
+	IGMP
+	VRRP
+	# numeric numbers also valid
+}
diff --git a/doc/sync/alarm/node2/keepalived.conf b/doc/sync/alarm/node2/keepalived.conf
new file mode 100644
index 0000000..f937467
--- /dev/null
+++ b/doc/sync/alarm/node2/keepalived.conf
@@ -0,0 +1,39 @@
+vrrp_sync_group G1 {   # must be before vrrp_instance declaration
+  group {
+    VI_1
+    VI_2
+  }
+  notify_master /etc/conntrackd/script_master.sh
+  notify_backup /etc/conntrackd/script_backup.sh
+#  notify_fault /etc/conntrackd/script_fault.sh
+}
+
+vrrp_instance VI_1 {
+    interface eth1
+    state SLAVE
+    virtual_router_id 61
+    priority 80
+    advert_int 3
+    authentication {
+      auth_type PASS
+      auth_pass papas_con_tomate
+    }
+    virtual_ipaddress {
+        192.168.0.100   # default CIDR mask is /32
+    }
+}
+
+vrrp_instance VI_2 {
+    interface eth0
+    state SLAVE
+    virtual_router_id 62
+    priority 80
+    advert_int 3
+    authentication {
+      auth_type PASS
+      auth_pass papas_con_tomate
+    }
+    virtual_ipaddress {
+        192.168.1.100
+    }
+}
diff --git a/doc/sync/alarm/script_backup.sh b/doc/sync/alarm/script_backup.sh
new file mode 100644
index 0000000..8ea2ad8
--- /dev/null
+++ b/doc/sync/alarm/script_backup.sh
@@ -0,0 +1,3 @@
+#!/bin/sh
+
+/usr/sbin/conntrackd -B
diff --git a/doc/sync/alarm/script_master.sh b/doc/sync/alarm/script_master.sh
new file mode 100644
index 0000000..70c26c9
--- /dev/null
+++ b/doc/sync/alarm/script_master.sh
@@ -0,0 +1,4 @@
+#!/bin/sh
+
+/usr/sbin/conntrackd -c
+/usr/sbin/conntrackd -R
diff --git a/doc/sync/ftfw/README b/doc/sync/ftfw/README
new file mode 100644
index 0000000..a09db10
--- /dev/null
+++ b/doc/sync/ftfw/README
@@ -0,0 +1 @@
+This directory contains the files for the FT-FW based protocol
diff --git a/doc/sync/ftfw/node1/conntrackd.conf b/doc/sync/ftfw/node1/conntrackd.conf
new file mode 100644
index 0000000..fadeb9d
--- /dev/null
+++ b/doc/sync/ftfw/node1/conntrackd.conf
@@ -0,0 +1,135 @@
+#
+# Synchronizer settings
+#
+Sync {
+	Mode FTFW {
+		#
+		# Size of the buffer that hold destroy messages for 
+		# possible resends (in bytes)
+		#
+		ResendBufferSize 262144
+
+		#
+		# Entries committed to the connection tracking table 
+		# starts with a limited timeout of N seconds until the
+		# takeover process is completed.
+		#
+		CommitTimeout 180
+
+		# Set Acknowledgement window size
+		ACKWindowSize 20
+	}
+
+	#
+	# Multicast IP and interface where messages are
+	# broadcasted (dedicated link). IMPORTANT: Make sure
+	# that iptables accepts traffic for destination
+	# 225.0.0.50, eg:
+	#
+	#	iptables -I INPUT -d 225.0.0.50 -j ACCEPT
+	#	iptables -I OUTPUT -d 225.0.0.50 -j ACCEPT
+	#
+	Multicast {
+		IPv4_address 225.0.0.50
+		IPv4_interface 192.168.100.100 # IP of dedicated link
+		Interface eth2
+		Group 3780
+	}
+
+	# Enable/Disable message checksumming
+	Checksum on
+
+	# Uncomment this if you want to replicate just certain TCP states.
+	# This option introduces a tradeoff in the replication: it reduces
+	# CPU consumption and lost messages rate at the cost of having 
+	# backup replicas that don't contain the current state that the active 
+	# replica holds. TCP states are: SYN_SENT, SYN_RECV, ESTABLISHED,
+	# FIN_WAIT, CLOSE_WAIT, LAST_ACK, TIME_WAIT, CLOSE, LISTEN.
+	# 
+	# Replicate ESTABLISHED TIME_WAIT for TCP
+
+	# If you have a multiprimary setup (active-active) without connection
+	# persistency, ie. you can't know which firewall handles a packet
+	# that is part of a connection, then you need direct commit of
+	# conntrack entries to the kernel conntrack table. OSPF setups must
+	# set on this option. Default is Off.
+	#
+	# CacheWriteThrough On
+}
+
+#
+# General settings
+#
+General {
+	#
+	# Number of buckets in the caches: hash table
+	#
+	HashSize 8192
+
+	#
+	# Maximum number of conntracks: 
+	# it must be >= $ cat /proc/sys/net/ipv4/netfilter/ip_conntrack_max
+	#
+	HashLimit 65535
+
+	#
+	# Logfile: on, off, or a filename
+	# Default: on (/var/log/conntrackd.log)
+	#
+	#LogFile off
+
+	#
+	# 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 /tmp/sync.sock
+		Backlog 20
+	}
+
+	#
+	# Netlink socket buffer size
+	#
+	SocketBufferSize 262142
+
+	#
+	# Increase the socket buffer up to maximum if required
+	#
+	SocketBufferSizeMaxGrown 655355
+}
+
+#
+# Ignore traffic for a certain set of IP's: Usually
+# all the IP assigned to the firewall since local
+# traffic must be ignored, just forwarded connections
+# are worth to replicate
+#
+IgnoreTrafficFor {
+	IPv4_address 127.0.0.1 # loopback
+	IPv4_address 192.168.0.1
+	IPv4_address 192.168.1.1
+	IPv4_address 192.168.100.100 # dedicated link ip
+	IPv4_address 192.168.0.100 # virtual IP 1
+	IPv4_address 192.168.1.100 # virtual IP 2
+}
+
+#
+# Do not replicate certain protocol traffic 
+#
+IgnoreProtocol {
+	UDP
+	ICMP
+	IGMP
+	VRRP
+	# numeric numbers also valid
+}
diff --git a/doc/sync/ftfw/node1/keepalived.conf b/doc/sync/ftfw/node1/keepalived.conf
new file mode 100644
index 0000000..f937467
--- /dev/null
+++ b/doc/sync/ftfw/node1/keepalived.conf
@@ -0,0 +1,39 @@
+vrrp_sync_group G1 {   # must be before vrrp_instance declaration
+  group {
+    VI_1
+    VI_2
+  }
+  notify_master /etc/conntrackd/script_master.sh
+  notify_backup /etc/conntrackd/script_backup.sh
+#  notify_fault /etc/conntrackd/script_fault.sh
+}
+
+vrrp_instance VI_1 {
+    interface eth1
+    state SLAVE
+    virtual_router_id 61
+    priority 80
+    advert_int 3
+    authentication {
+      auth_type PASS
+      auth_pass papas_con_tomate
+    }
+    virtual_ipaddress {
+        192.168.0.100   # default CIDR mask is /32
+    }
+}
+
+vrrp_instance VI_2 {
+    interface eth0
+    state SLAVE
+    virtual_router_id 62
+    priority 80
+    advert_int 3
+    authentication {
+      auth_type PASS
+      auth_pass papas_con_tomate
+    }
+    virtual_ipaddress {
+        192.168.1.100
+    }
+}
diff --git a/doc/sync/ftfw/node2/conntrackd.conf b/doc/sync/ftfw/node2/conntrackd.conf
new file mode 100644
index 0000000..59ffc4f
--- /dev/null
+++ b/doc/sync/ftfw/node2/conntrackd.conf
@@ -0,0 +1,134 @@
+#
+# Synchronizer settings
+#
+Sync {
+	Mode FTFW {
+                #
+		# Size of the buffer that hold destroy messages for 
+		# possible resends (in bytes)
+		#
+		ResendBufferSize 262144
+
+		# Entries committed to the connection tracking table 
+		# starts with a limited timeout of N seconds until the
+		# takeover process is completed.
+		#
+		CommitTimeout 180
+
+		# Set Acknowledgement window size
+		ACKWindowSize 20
+	}
+
+	#
+	# Multicast IP and interface where messages are
+	# broadcasted (dedicated link). IMPORTANT: Make sure
+	# that iptables accepts traffic for destination
+	# 225.0.0.50, eg:
+	#
+	#	iptables -I INPUT -d 225.0.0.50 -j ACCEPT
+	#	iptables -I OUTPUT -d 225.0.0.50 -j ACCEPT
+	#
+	Multicast {
+		IPv4_address 225.0.0.50
+		IPv4_interface 192.168.100.200 # IP of dedicated link
+		Interface eth2
+		Group 3780
+	}
+
+	# Enable/Disable message checksumming
+	Checksum on
+
+	# Uncomment this if you want to replicate just certain TCP states.
+	# This option introduces a tradeoff in the replication: it reduces
+	# CPU consumption and lost messages rate at the cost of having 
+	# backup replicas that don't contain the current state that the active 
+	# replica holds. TCP states are: SYN_SENT, SYN_RECV, ESTABLISHED,
+	# FIN_WAIT, CLOSE_WAIT, LAST_ACK, TIME_WAIT, CLOSE, LISTEN.
+	# 
+	# Replicate ESTABLISHED TIME_WAIT for TCP
+
+	# If you have a multiprimary setup (active-active) without connection
+	# persistency, ie. you can't know which firewall handles a packet
+	# that is part of a connection, then you need direct commit of
+	# conntrack entries to the kernel conntrack table. OSPF setups must
+	# set on this option. Default is Off.
+	#
+	# CacheWriteThrough On
+}
+
+#
+# General settings
+#
+General {
+	#
+	# Number of buckets in the caches: hash table
+	#
+	HashSize 8192
+
+	#
+	# Maximum number of conntracks: 
+	# it must be >= $ cat /proc/sys/net/ipv4/netfilter/ip_conntrack_max
+	#
+	HashLimit 65535
+
+	#
+	# Logfile: on, off, or a filename
+	# Default: on (/var/log/conntrackd.log)
+	#
+	#LogFile off
+
+	#
+	# 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 /tmp/sync.sock
+		Backlog 20
+	}
+
+	#
+	# Netlink socket buffer size
+	#
+	SocketBufferSize 262142
+
+	#
+	# Increase the socket buffer up to maximum if required
+	#
+	SocketBufferSizeMaxGrown 655355
+}
+
+#
+# Ignore traffic for a certain set of IP's: Usually
+# all the IP assigned to the firewall since local
+# traffic must be ignored, just forwarded connections
+# are worth to replicate
+#
+IgnoreTrafficFor {
+	IPv4_address 127.0.0.1 # loopback
+	IPv4_address 192.168.0.2
+	IPv4_address 192.168.1.2
+	IPv4_address 192.168.100.200 # dedicated link ip
+	IPv4_address 192.168.0.200 # virtual IP 1
+	IPv4_address 192.168.1.200 # virtual IP 2
+}
+
+#
+# Do not replicate certain protocol traffic 
+#
+IgnoreProtocol {
+	UDP
+	ICMP
+	IGMP
+	VRRP
+	# numeric numbers also valid
+}
diff --git a/doc/sync/ftfw/node2/keepalived.conf b/doc/sync/ftfw/node2/keepalived.conf
new file mode 100644
index 0000000..f937467
--- /dev/null
+++ b/doc/sync/ftfw/node2/keepalived.conf
@@ -0,0 +1,39 @@
+vrrp_sync_group G1 {   # must be before vrrp_instance declaration
+  group {
+    VI_1
+    VI_2
+  }
+  notify_master /etc/conntrackd/script_master.sh
+  notify_backup /etc/conntrackd/script_backup.sh
+#  notify_fault /etc/conntrackd/script_fault.sh
+}
+
+vrrp_instance VI_1 {
+    interface eth1
+    state SLAVE
+    virtual_router_id 61
+    priority 80
+    advert_int 3
+    authentication {
+      auth_type PASS
+      auth_pass papas_con_tomate
+    }
+    virtual_ipaddress {
+        192.168.0.100   # default CIDR mask is /32
+    }
+}
+
+vrrp_instance VI_2 {
+    interface eth0
+    state SLAVE
+    virtual_router_id 62
+    priority 80
+    advert_int 3
+    authentication {
+      auth_type PASS
+      auth_pass papas_con_tomate
+    }
+    virtual_ipaddress {
+        192.168.1.100
+    }
+}
diff --git a/doc/sync/ftfw/script_backup.sh b/doc/sync/ftfw/script_backup.sh
new file mode 100644
index 0000000..813e375
--- /dev/null
+++ b/doc/sync/ftfw/script_backup.sh
@@ -0,0 +1,3 @@
+#!/bin/sh
+
+/usr/sbin/conntrackd -n # request a resync from other nodes via multicast
diff --git a/doc/sync/ftfw/script_master.sh b/doc/sync/ftfw/script_master.sh
new file mode 100644
index 0000000..ff1dbc0
--- /dev/null
+++ b/doc/sync/ftfw/script_master.sh
@@ -0,0 +1,5 @@
+#!/bin/sh
+
+/usr/sbin/conntrackd -c # commit the cache
+/usr/sbin/conntrackd -f # flush the caches
+/usr/sbin/conntrackd -R # resync with kernel conntrack table