[conntrack-tools PATCH 1/4] src/main: refresh help message

[conntrack-tools PATCH 1/4] src/main: refresh help message

[Arturo Borrero Gonzalez]

It seems there are two kind of options:
 * general commands (-d, -v, -h, -C)
 * client commands (which requires another conntrackd instance)

Refresh the help message to better reflect this.

Signed-off-by: Arturo Borrero Gonzalez <arturo.borrero.glez@gmail.com>
---
 src/main.c |   20 ++++++++------------
 1 file changed, 8 insertions(+), 12 deletions(-)

diff --git a/src/main.c b/src/main.c
index d12fe18..2be9b2f 100644
--- a/src/main.c
+++ b/src/main.c
@@ -36,9 +36,12 @@
 struct ct_general_state st;
 struct ct_state state;
 
-static const char usage_daemon_commands[] =
-	"Daemon mode commands:\n"
-	"  -d [options]\t\tRun in daemon mode\n";
+static const char usage_general_commands[] =
+	"General commands:\n"
+	"  -d, run in daemon mode\n"
+	"  -C [configfile], configuration file path\n"
+	"  -v, display conntrackd version\n"
+	"  -h, display this help information\n";
 
 static const char usage_client_commands[] =
 	"Client mode commands:\n"
@@ -54,22 +57,15 @@ static const char usage_client_commands[] =
 	"  -n, request resync with other node (only FT-FW and NOTRACK modes)\n"
 	"  -B, force a bulk send to other replica firewalls\n"
 	"  -x, dump cache in XML format (requires -i or -e)\n"
-	"  -t, reset the kernel timeout (see PurgeTimeout clause)\n"
-	"  -v, display conntrackd version\n"
-	"  -h, display this help information\n";
-
-static const char usage_options[] =
-	"Options:\n"
-	"  -C [configfile], configuration file path\n";
+	"  -t, reset the kernel timeout (see PurgeTimeout clause)\n";
 
 static void
 show_usage(char *progname)
 {
 	fprintf(stdout, "Connection tracking userspace daemon v%s\n", VERSION);
 	fprintf(stdout, "Usage: %s [commands] [options]\n\n", progname);
-	fprintf(stdout, "%s\n", usage_daemon_commands);
+	fprintf(stdout, "%s\n", usage_general_commands);
 	fprintf(stdout, "%s\n", usage_client_commands);
-	fprintf(stdout, "%s\n", usage_options);
 }
 
 static void

[conntrack-tools PATCH 2/4] conntrackd.8: refresh file

[Arturo Borrero Gonzalez]

Refresh conntrackd.8 manpage to match the help message in the binary.

Changes are related to the syntax and options of conntrackd,
the syntax of the manpage itself and clarification of some aspects.

Also, break lines at 80 characters.

Signed-off-by: Arturo Borrero Gonzalez <arturo.borrero.glez@gmail.com>
---
 conntrackd.8 |  158 ++++++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 104 insertions(+), 54 deletions(-)

diff --git a/conntrackd.8 b/conntrackd.8
index 3bb4335..bd195ec 100644
--- a/conntrackd.8
+++ b/conntrackd.8
@@ -1,86 +1,111 @@
-.TH CONNTRACKD 8 "Nov 19, 2015" "" ""
+.TH CONNTRACKD 8 "Aug 30, 2016" "" ""
 
 .\" Man page written by Pablo Neira Ayuso <pablo@netfilter.org> (Dec 2007)
 
 .SH NAME
 conntrackd \- netfilter connection tracking user-space daemon
+
 .SH SYNOPSIS
 .BR "conntrackd [options]"
+
 .SH DESCRIPTION
-.B conntrackd
-is the user-space daemon for the netfilter connection tracking system. This daemon synchronizes connection tracking states between several replica firewalls. Thus,
-.B conntrackd 
-can be used to deploy highly available stateful firewalls. The daemon supports Primary-Backup and Multiprimary setups. The daemon can also be used as statistics collector.
+\fBconntrackd\fP is the user-space daemon for the netfilter connection
+tracking system. This daemon synchronizes connection tracking states between
+several replica firewalls. Thus, \fBconntrackd\fP can be used to deploy highly
+available stateful firewalls.
+
+The daemon supports Primary-Backup and Multiprimary setups and can also be used
+as statistics collector.
+
 .SH OPTIONS
-The options recognized by
-.B conntrackd
-can be divided into several different groups.
-.SS MODES
-These options specify the particular operation mode in which conntrackd runs. Only one of them can be specified at any given time.
-.TP
-.BI "-d "
-Run conntrackd in daemon mode.
+The options recognized by \fBconntrackd\fP can be divided into two different
+groups.
+
+.SS GEMERAL OPTIONS
+General options for the \fBconntrackd\fP daemon.
+
+.TP
+.BI "-d"
+Run \fBconntrackd\fP in daemon mode (fork to background).
+
+.TP
+.BI "-C <path>"
+Load config file specified in \fIpath\fP. See \fBconntrackd.conf(5)\fP for
+details.
+
+.TP
+.BI "-v"
+Display version information.
+
+.TP
+.BI "-h"
+Display help information.
+
 .SS CLIENT COMMANDS
-.B conntrackd 
-can be used in client mode to request several information and operations to a running daemon
+\fBconntrackd\fP can be used in client mode to request several information and
+operations to a running instance of the daemon.
+
 .TP
-.BI "-i " "[ct|expect]"
+.BI "-i [ct|expect]"
 Dump the internal cache, i.e. show local states
+
 .TP
-.BI "-e " "[ct|expect]"
+.BI "-e [ct|expect]"
 Dump the external cache, i.e. show foreign states
+
 .TP
-.BI "-x "
+.BI "-x"
 Display output in XML format. This option is only valid in combination
-with "\-i" and "\-e" parameters.
+with \fB\-i\fP and \fB\-e\fP parameters.
+
 .TP
-.BI "-f " "[internal|external]"
+.BI "-f [internal|external]"
 Flush the internal and/or external cache
+
 .TP
 .BI "-F [ct|expect]"
 Flush the kernel conntrack table (if you use a Linux kernel >= 2.6.29, this
 option will not flush your internal and external cache).
 .TP
-.BI "-c "
+.BI "-c"
 Commit external cache to conntrack table.
 .TP
-.BI "-B "
+.BI "-B"
 Force a bulk send to other replica firewalls. With this command, you will
 ask conntrackd to send the state-entries that it owns to others.
 .TP
-.BI "-n "
+.BI "-n"
 Request resync with other node (only FT-FW and NOTRACK modes).
 .TP
-.BI "-k "
+.BI "-k"
 Kill the daemon
 .TP
-.BI "-s " "[network|cache|runtime|link|rsqueue|process|queue|ct|expect]"
+.BI "-s [network|cache|runtime|link|rsqueue|process|queue|ct|expect]"
 Dump statistics. If no parameter is passed, it displays the general statistics.
+.br
 If "network" is passed as parameter it displays the networking statistics.
+.br
 If "cache" is passed as parameter, it shows the extended cache statistics.
+.br
 If "runtime" is passed as parameter, it shows the run-time statistics.
+.br
 If "process" is passed as parameter, it shows existing child processes (if any).
+.br
 If "queue" is passed as parameter, it shows queue statistics.
+.br
 If "ct" is passed, it displays the general statistics.
+.br
 If "expect" is passed as parameter, it shows expectation statistics.
 .TP
-.BI "-R " "[ct|expect]"
+.BI "-R [ct|expect]"
 Force a resync against the kernel connection tracking table
 .TP
-.BI "-t "
+.BI "-t"
 Reset the in-kernel timers (See PurgeTimeout clause)
-.TP
-.BI "-v "
-Display version information.
-.TP
-.BI "-h "
-Display help information.
-.TP
-.BI "-C config file"
-Configuration file path. See \fBconntrackd.conf(5)\fP for details.
-.TP
+
 .SH DIAGNOSTICS
 The exit code is 0 for correct function. Errors cause an exit code of 1.
+
 .SH EXAMPLES
 The following example are illustrative, for a real use in a firewall fail-over,
 check the primary-backup.sh script that comes with the sources.
@@ -89,33 +114,58 @@ check the primary-backup.sh script that comes with the sources.
 Runs conntrackd in daemon and synchronization mode
 .TP
 .B conntrackd \-i
-Dumps the states held in the internal cache, i.e. those handled by this firewall
+Dumps the states held in the internal cache, i.e. those handled by this
+firewall
 .TP
 .B conntrackd \-e
-Dumps the states held in the external cache, i.e. those handled by other replica firewalls
+Dumps the states held in the external cache, i.e. those handled by other
+replica firewalls
 .TP
 .B conntrackd \-c
-Commits the external cache into the kernel connection tracking system. This is used to inject the state so that the connections can be recovered during the failover.
+Commits the external cache into the kernel connection tracking system.
+This is used to inject the state so that the connections can be recovered
+during the failover.
+
 .SH DEPENDENCIES
-This daemon requires a Linux kernel version >= 2.6.18. TCP window tracking support requires >= 2.6.22, otherwise you have to disable it. Helpers are fully supported since >= 2.6.25, however, if you use any previous version, depending on the protocol helper and your setup (e.g. if you setup performs NAT sequence adjustments or not), your help connection may be successfully recovered.
-.TP
-There are several unsupported stateful iptables matches such as recent, connbytes and the quota matches which gather internal information to operate. Since that information does not belong to the domain of the connection tracking system, connections affected by those matches may not be fully recovered during the takeover.
-.TP
-The daemon requires a Linux kernel version >= 2.6.26 to support kernel-space event filtering. Otherwise, all the event filtering is done in userspace with the corresponding extra overhead. If you are not using the Filter clause in the configuration file, ignore this notice.
+This daemon requires a Linux kernel version >= 2.6.18. TCP window tracking
+support requires >= 2.6.22, otherwise you have to disable it.
+Helpers are fully supported since >= 2.6.25, however, if you use any previous
+version, depending on the protocol helper and your setup (e.g. if you setup
+performs NAT sequence adjustments or not), your help connection may be
+successfully recovered.
+
+There are several unsupported stateful iptables matches such as recent,
+connbytes and the quota matches which gather internal
+information to operate. Since that information does not belong to the
+domain of the connection tracking system, connections affected by
+those matches may not be fully recovered during the takeover.
+
+The daemon requires a Linux kernel version >= 2.6.26 to support kernel-space
+event filtering. Otherwise, all the event filtering is done in userspace with
+the corresponding extra overhead. If you are not using the Filter clause in
+the configuration file, ignore this notice.
+
 .SH INCOMPATIBILITIES
-During the 0.9.9 development, some important changes in the replication message format were introduced. Therefore, conntrackd >= 0.9.9 will not work appropriately with conntrackd <= 0.9.8. This should not be a problem if you use the same
-conntrackd version in all the firewall replica nodes.
+During the 0.9.9 development, some important changes in the replication message
+format were introduced. Therefore, \fBconntrackd\fP >= 0.9.9 will not work
+appropriately with \fBconntrackd\fP <= 0.9.8.
+
+This should not be a problem if you use the same conntrackd version in all
+the firewall replica nodes.
+
 .SH SEE ALSO
-.BR conntrack (8), iptables (8), conntrackd.conf (5)
+.BR conntrackd.conf(5)
+.BR conntrack(8)
+.BR iptables(8)
+.BR nft(8)
 .br
-See
-.BR "http://conntrack-tools.netfilter.org"
+.BR http://conntrack-tools.netfilter.org
+
 .SH BUGS
-Please, report them to netfilter-devel@vger.kernel.org or file a bug in
-Netfilter's bugzilla (https://bugzilla.netfilter.org).
+Please, report them to netfilter-devel@vger.kernel.org (subscription required)
+or file a bug in Netfilter's bugzilla (https://bugzilla.netfilter.org).
+
 .SH AUTHORS
 Pablo Neira Ayuso wrote and maintains the conntrackd tool
-.TP
-Please send bug reports to <netfilter-devel@lists.netfilter.org>. Subscription is required.
 .PP
 Man page written by Pablo Neira Ayuso <pablo@netfilter.org>.

Re: [conntrack-tools PATCH 2/4] conntrackd.8: refresh file

[Pablo Neira Ayuso]

On Tue, Aug 30, 2016 at 02:20:40PM +0200, Arturo Borrero Gonzalez wrote:
> Refresh conntrackd.8 manpage to match the help message in the binary.
> 
> Changes are related to the syntax and options of conntrackd,
> the syntax of the manpage itself and clarification of some aspects.
> 
> Also, break lines at 80 characters.

Also applied, thanks.

[conntrack-tools PATCH 3/4] conntrackd.8: add reference to systemd

[Arturo Borrero Gonzalez]

Add reference to systemd integration in the manpage.

Signed-off-by: Arturo Borrero Gonzalez <arturo.borrero.glez@gmail.com>
---
 conntrackd.8 |    7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/conntrackd.8 b/conntrackd.8
index bd195ec..6ccf261 100644
--- a/conntrackd.8
+++ b/conntrackd.8
@@ -145,6 +145,13 @@ event filtering. Otherwise, all the event filtering is done in userspace with
 the corresponding extra overhead. If you are not using the Filter clause in
 the configuration file, ignore this notice.
 
+.SH SYSTEMD INTEGRATION
+Starting with the 1.4.4 release, \fBconntrackd\fP includes integration with
+\fBsystemd(1)\fP to use an unit file of \fIType=notify\fP and watchdog support.
+
+The daemon should be configured at build time to include such support
+and \fBconntrackd.conf(5)\fP should contain \fBSystemd on\fP.
+
 .SH INCOMPATIBILITIES
 During the 0.9.9 development, some important changes in the replication message
 format were introduced. Therefore, \fBconntrackd\fP >= 0.9.9 will not work

Re: [conntrack-tools PATCH 3/4] conntrackd.8: add reference to systemd

[Pablo Neira Ayuso]

On Tue, Aug 30, 2016 at 02:20:45PM +0200, Arturo Borrero Gonzalez wrote:
> Add reference to systemd integration in the manpage.

Applied, thanks Arturo.

[conntrack-tools PATCH 4/4] doc/manual/conntrack-tools: include some bits about init systems

[Arturo Borrero Gonzalez]

Update the conntrack-tools manual to include some bits regarding init systems
and the integration with systemd.

More on this topic here:
 http://ral-arturo.blogspot.com.es/2016/08/why-conntrackd-in-debian-is-better-with.html

Suggested-by: Pablo Neira Ayuso <pablo@netfilter.org>
Signed-off-by: Arturo Borrero Gonzalez <arturo.borrero.glez@gmail.com>
---
 doc/manual/conntrack-tools.tmpl |   51 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/doc/manual/conntrack-tools.tmpl b/doc/manual/conntrack-tools.tmpl
index 87a792e..5c12c4a 100644
--- a/doc/manual/conntrack-tools.tmpl
+++ b/doc/manual/conntrack-tools.tmpl
@@ -1185,4 +1185,55 @@ not enough space errors:                   0
 
 </chapter>
 
+  <chapter id="system-integration"><title>System integration</title>
+
+  <para>
+	You may want to integrate conntrackd into your system in order to build
+	a robust firewall cluster. You should take a look at how the linux
+	distro of your choose does this, as there are some interesting things
+	to take into account.
+  </para>
+
+  <para>
+	Depending on the architecture of the firewall cluster, you may want to
+	sync each node after a failback operation, so the new node
+	inmediately knows the connection of the other. This is specially
+	interesting in <emphasis>Active-Active</emphasis> mode.
+  </para>
+
+  <para>
+	This can be done using <emphasis>conntrackd -n</emphasis> just after
+	the new node has joined the conntrackd cluster, for example at boot
+	time. This operations requires the main conntrackd daemon to open the
+	UNIX socket to receive the order from the
+	<emphasis>conntrackd -n</emphasis> call.
+  </para>
+
+  <para>
+	Care must be taken that no race conditions happens (i.e, the UNIX
+	socket is actually opened before <emphasis>conntrackd -n</emphasis> is
+	launched). Otherwise, you may end with a new node (after failback)
+	which doesn't know any connection states from the other node.
+  </para>
+
+  <para>
+	Since <emphasis>conntrack-tools 1.4.4</emphasis>, the conntrackd
+	daemon includes integration with <emphasis>libsystemd</emphasis>. If
+	conntrackd is configured at build time with this support
+	(using <emphasis>--enable-systemd</emphasis>), the you can
+	use <emphasis>Systemd on</emphasis> in the
+	<emphasis>conntrackd.conf</emphasis> main configuration file.
+	To benefit from this integration, you should use a systemd service file
+	of <emphasis>Type=notify</emphasis>, which also includes support for
+	the systemd watchdog.
+  </para>
+
+  <para>
+	Using systemd and conntrackd with libsystemd support and a service file
+	of Type=notify means that conntrackd will notify of his readiness to
+	systemd, so you can launch <emphasis>conntrackd -n</emphasis> safely,
+	avoiding such race conditions.
+  </para>
+
+  </chapter>
 </book>

Re: [conntrack-tools PATCH 4/4] doc/manual/conntrack-tools: include some bits about init systems

[Rami Rosen]

Hi, Arturo,
Several light fixes/suggestions are following:


should be: of youe choice
> +       distro of your choose does this, as there are some interesting things
> +       to take into account.
> +  </para>


I would suggest: fallback (I think it is more techncally common, maybe
I am wrong)
> +       sync each node after a failback operation, so the new node

Should be: these  operations
> +       time. This operations requires the main conntrackd daemon to open the
> +       UNIX socket to receive the order from the

I would suggest: after fallback (Again, I think it is more techncally
common, maybe I am wrong)
> +       launched). Otherwise, you may end with a new node (after failback)

should be: then you can
> +       (using <emphasis>--enable-systemd</emphasis>), the you can
> +
> +  <para>
> +       Using systemd and conntrackd with libsystemd support and a service file
I would suggest: of its readiness
> +       of Type=notify means that conntrackd will notify of his readiness to

Keep on the good work!

Rami Rosen

Re: [conntrack-tools PATCH 1/4] src/main: refresh help message

[Pablo Neira Ayuso]

On Tue, Aug 30, 2016 at 02:20:35PM +0200, Arturo Borrero Gonzalez wrote:
> It seems there are two kind of options:
>  * general commands (-d, -v, -h, -C)
>  * client commands (which requires another conntrackd instance)
> 
> Refresh the help message to better reflect this.

Applied, thanks.