conntrack-sync: improve overall documentation

1 files changed, 121 insertions, 59 deletions

diff --git a/docs/configuration/service/conntrack-sync.rst b/docs/configuration/service/conntrack-sync.rst
index 1d240f48..843f0d81 100644
--- a/docs/configuration/service/conntrack-sync.rst
+++ b/docs/configuration/service/conntrack-sync.rst
@@ -1,7 +1,8 @@
-.. include:: /_include/need_improvement.txt
+.. _conntrack-sync:
 
-Conntrack
----------
+##############
+Conntrack Sync
+##############
 
 One of the important features built on top of the Netfilter framework is
 connection tracking. Connection tracking allows the kernel to keep track of all
@@ -30,83 +31,150 @@ It is possible to use either Multicast or Unicast to sync conntrack traffic.
 Most examples below show Multicast, but unicast can be specified by using the
 "peer" keywork after the specificed interface, as in the following example:
 
-set service conntrack-sync interface eth0 peer 192.168.0.250
+:cfgcmd:`set service conntrack-sync interface eth0 peer 192.168.0.250`
 
+*************
 Configuration
-^^^^^^^^^^^^^
+*************
 
-.. code-block:: none
+  .. cfgcmd:: set service conntrack-sync accept-protocol
 
-  # Protocols only for which local conntrack entries will be synced (tcp, udp, icmp, sctp)
-  set service conntrack-sync accept-protocol
+    Accept only certain protocols: You may want to replicate the state of flows
+    depending on their layer 4 protocol.
 
-  # Queue size for listening to local conntrack events (in MB)
-  set service conntrack-sync event-listen-queue-size <int>
+    Protocols are: tcp, sctp, dccp, udp, icmp and ipv6-icmp.
 
-  # Protocol for which expect entries need to be synchronized. (all, ftp, h323, nfs, sip, sqlnet)
-  set service conntrack-sync expect-sync
+  .. cfgcmd:: set service conntrack-sync event-listen-queue-size <size>
 
-  # Failover mechanism to use for conntrack-sync [REQUIRED]
-  set service conntrack-sync failover-mechanism
+    The daemon doubles the size of the netlink event socket buffer size if it
+    detects netlink event message dropping. This clause sets the maximum buffer
+    size growth that can be reached.
 
-  set service conntrack-sync cluster group <string>
-  set service conntrack-sync vrrp sync-group <1-255>
+    Queue size for listening to local conntrack events in MB.
 
-  # IP addresses for which local conntrack entries will not be synced
-  set service conntrack-sync ignore-address <x.x.x.x>
+  .. cfgcmd:: set service conntrack-sync expect-sync <all|ftp|h323|nfs|sip|sqlnet>
 
-  # Interface to use for syncing conntrack entries [REQUIRED]
-  set service conntrack-sync interface <ifname>
+    Protocol for which expect entries need to be synchronized.
 
-  # Multicast group to use for syncing conntrack entries
-  set service conntrack-sync mcast-group <x.x.x.x>
+  .. cfgcmd:: set service conntrack-sync failover-mechanism vrrp sync-group <group>
 
-  # Peer to send Unicast UDP conntrack sync entires to, if not using Multicast above
-  set service conntrack-sync interface <ifname> peer <remote IP of peer>
+    Failover mechanism to use for conntrack-sync.
 
-  # Queue size for syncing conntrack entries (in MB)
-  set service conntrack-sync sync-queue-size <size>
+    Only VRRP is supported. Required option.
 
-Example
-^^^^^^^
-The next example is a simple configuration of conntrack-sync.
+  .. cfgcmd:: set service conntrack-sync ignore-address <x.x.x.x>
 
+    IP addresses or networks for which local conntrack entries will not be synced
 
-.. figure:: /_static/images/service_conntrack_sync-schema.png
-   :scale: 60 %
-   :alt: Conntrack Sync Example
+  .. cfgcmd:: set service conntrack-sync interface <name>
 
-   Conntrack Sync Example
+    Interface to use for syncing conntrack entries.
 
-First of all, make sure conntrack is enabled by running
+  .. cfgcmd:: set service conntrack-sync mcast-group <x.x.x.x>
 
-.. code-block:: none
+    Multicast group to use for syncing conntrack entries.
 
-  show conntrack table ipv4
+    Defaults to 225.0.0.50.
 
-If the table is empty and you have a warning message, it means conntrack is not
-enabled. To enable conntrack, just create a NAT or a firewall rule.
+  .. cfgcmd:: set service conntrack-sync interface <name> peer <address>
 
-.. code-block:: none
+    Peer to send unicast UDP conntrack sync entires to, if not using Multicast
+    configuration from above above.
 
-  set firewall state-policy established action accept
+  .. cfgcmd:: set service conntrack-sync sync-queue-size <size>
 
-You now should have a conntrack table
+    Queue size for syncing conntrack entries in MB.
 
-.. code-block:: none
+*********
+Operation
+*********
+
+.. opcmd:: show conntrack table ipv4
+
+  Make sure conntrack is enabled by running and show connection tracking table.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show conntrack table ipv4
+    TCP state codes: SS - SYN SENT, SR - SYN RECEIVED, ES - ESTABLISHED,
+                     FW - FIN WAIT, CW - CLOSE WAIT, LA - LAST ACK,
+                     TW - TIME WAIT, CL - CLOSE, LI - LISTEN
+
+    CONN ID    Source                 Destination            Protocol         TIMEOUT
+    1015736576 10.35.100.87:58172     172.31.20.12:22        tcp [6] ES       430279
+    1006235648 10.35.101.221:57483    172.31.120.21:22       tcp [6] ES       413310
+    1006237088 10.100.68.100          172.31.120.21          icmp [1]         29
+    1015734848 10.35.100.87:56282     172.31.20.12:22        tcp [6] ES       300
+    1015734272 172.31.20.12:60286     239.10.10.14:694       udp [17]         29
+    1006239392 10.35.101.221          172.31.120.21          icmp [1]         29
+
+  .. note:: If the table is empty and you have a warning message, it means
+  conntrack is not enabled. To enable conntrack, just create a NAT or a firewall
+  rule. :cfgcmd:`set firewall state-policy established action accept`
+
+.. opcmd:: show conntrack-sync external-cache
+
+  Show connection syncing external cache entries
+
+.. opcmd:: show conntrack-sync internal-cache
+
+  Show connection syncing internal cache entries
+
+.. opcmd:: show conntrack-sync statistics
+
+  Retrieve current statistics of connection tracking subsystem.
+
+  .. code-block:: none
 
-  $ show conntrack table ipv4
-  TCP state codes: SS - SYN SENT, SR - SYN RECEIVED, ES - ESTABLISHED,
-                   FW - FIN WAIT, CW - CLOSE WAIT, LA - LAST ACK,
-                   TW - TIME WAIT, CL - CLOSE, LI - LISTEN
+    vyos@vyos:~$ show conntrack-sync statistics
+    Main Table Statistics:
 
-  CONN ID    Source                 Destination            Protocol         TIMEOUT
-  1015736576 10.35.100.87:58172     172.31.20.12:22        tcp [6] ES       430279
-  1006235648 10.35.101.221:57483    172.31.120.21:22       tcp [6] ES       413310
-  1006237088 10.100.68.100          172.31.120.21          icmp [1]         29
-  1015734848 10.35.100.87:56282     172.31.20.12:22        tcp [6] ES       300
-  1015734272 172.31.20.12:60286     239.10.10.14:694       udp [17]         29
-  1006239392 10.35.101.221          172.31.120.21          icmp [1]         29
+    cache internal:
+    current active connections:            19606
+    connections created:                 6298470    failed:            0
+    connections updated:                 3786793    failed:            0
+    connections destroyed:               6278864    failed:            0
+
+    cache external:
+    current active connections:            15771
+    connections created:                 1660193    failed:            0
+    connections updated:                   77204    failed:            0
+    connections destroyed:               1644422    failed:            0
+
+    traffic processed:
+                       0 Bytes                         0 Pckts
+
+    multicast traffic (active device=eth0.5):
+               976826240 Bytes sent            212898000 Bytes recv
+                 8302333 Pckts sent              2009929 Pckts recv
+                       0 Error send                    0 Error recv
+
+    message tracking:
+                       0 Malformed msgs                  263 Lost msgs
+
+
+.. opcmd:: show conntrack-sync status
+
+  Retrieve current status of connection tracking subsystem.
+
+  .. code-block:: none
+
+    vyos@vyos:~$ show conntrack-sync status
+    sync-interface        : eth0.5
+    failover-mechanism    : vrrp [sync-group GEFOEKOM]
+    last state transition : no transition yet!
+    ExpectationSync       : disabled
+
+
+*******
+Example
+*******
+
+The next example is a simple configuration of conntrack-sync.
+
+.. figure:: /_static/images/service_conntrack_sync-schema.png
+   :scale: 60 %
+   :alt: Conntrack Sync Example
 
 Now configure conntrack-sync service on ``router1`` **and** ``router2``
 
@@ -117,12 +185,9 @@ Now configure conntrack-sync service on ``router1`` **and** ``router2``
   set service conntrack-sync accept-protocol 'tcp'
   set service conntrack-sync accept-protocol 'udp'
   set service conntrack-sync accept-protocol 'icmp'
-  set service conntrack-sync event-listen-queue-size '8'
   set service conntrack-sync failover-mechanism vrrp sync-group 'syncgrp'
   set service conntrack-sync interface 'eth0'
   set service conntrack-sync mcast-group '225.0.0.50'
-  set service conntrack-sync sync-queue-size '8'
-
 
 On the active router, you should have information in the internal-cache of
 conntrack-sync. The same current active connections number should be shown in
@@ -159,11 +224,8 @@ On active router run:
   message tracking:
                      0 Malformed msgs                    0 Lost msgs
 
-
-
 On standby router run:
 
-
 .. code-block:: none