conntrack-sync: improve overall documentation

(cherry picked from commit 1c2d4401144553acd1dafdceadd6beda10ae87f1)

1 files changed, 127 insertions, 70 deletions

diff --git a/docs/configuration/service/conntrack-sync.rst b/docs/configuration/service/conntrack-sync.rst
index 3c9f08e4..b38854d1 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
@@ -28,106 +29,165 @@ will be mandatorily defragmented.
 
 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:  
+"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, udp and icmp.
 
-  # Protocol for which expect entries need to be synchronized. (all, ftp, h323, nfs, sip, sqlnet)
-  set service conntrack-sync expect-sync
+    .. note:: When using multiple protocols they must be separated by comma.
 
-  # Failover mechanism to use for conntrack-sync [REQUIRED]
-  set service conntrack-sync failover-mechanism
+  .. cfgcmd:: set service conntrack-sync event-listen-queue-size <size>
 
-  set service conntrack-sync cluster group <string>
-  set service conntrack-sync vrrp sync-group <1-255>
+    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.
 
-  # IP addresses for which local conntrack entries will not be synced
-  set service conntrack-sync ignore-address ipv4 <x.x.x.x>
+    Queue size for listening to local conntrack events in MB.
 
-  # Interface to use for syncing conntrack entries [REQUIRED]
-  set service conntrack-sync interface <ifname>
- 
-  # Multicast group to use for syncing conntrack entries
-  set service conntrack-sync mcast-group <x.x.x.x>
-  
-  # 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>
+  .. cfgcmd:: set service conntrack-sync expect-sync <all|ftp|h323|nfs|sip|sqlnet>
 
-  # Queue size for syncing conntrack entries (in MB)
-  set service conntrack-sync sync-queue-size <size>
+    Protocol for which expect entries need to be synchronized.
 
-Example
-^^^^^^^
-The next example is a simple configuration of conntrack-sync.
+  .. cfgcmd:: set service conntrack-sync failover-mechanism vrrp sync-group <group>
 
+    Failover mechanism to use for conntrack-sync.
 
-.. figure:: /_static/images/service_conntrack_sync-schema.png
-   :scale: 60 %
-   :alt: Conntrack Sync Example
+    Only VRRP is supported. Required option.
 
-   Conntrack Sync Example
+  .. cfgcmd:: set service conntrack-sync ignore-address ipv4 <x.x.x.x>
 
-First of all, make sure conntrack is enabled by running
+    IP addresses or networks for which local conntrack entries will not be synced
 
-.. code-block:: none
+  .. cfgcmd:: set service conntrack-sync interface <name>
 
-  show conntrack table ipv4
+    Interface to use for syncing conntrack entries.
 
-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 mcast-group <x.x.x.x>
 
-.. code-block:: none
+    Multicast group to use for syncing conntrack entries.
 
-  set firewall state-policy established action accept
+    Defaults to 225.0.0.50.
 
-You now should have a conntrack table
+  .. 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.
 
-  $ 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
+  .. cfgcmd:: set service conntrack-sync sync-queue-size <size>
 
-  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
+    Queue size for syncing conntrack entries in MB.
 
-Now configure conntrack-sync service on ``router1`` **and** ``router2``
+*********
+Operation
+*********
 
-.. code-block:: none
+.. opcmd:: show conntrack table ipv4
 
-  set service conntrack-sync accept-protocol 'tcp,udp,icmp'
-  set service conntrack-sync event-listen-queue-size '8'
-  set service conntrack-sync failover-mechanism cluster group 'GROUP'
-  set service conntrack-sync interface 'eth0'
-  set service conntrack-sync mcast-group '225.0.0.50'
-  set service conntrack-sync sync-queue-size '8'
+  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
+
+    vyos@vyos:~$ show conntrack-sync statistics
+    Main Table Statistics:
+
+    cache internal:
+    current active connections:            19606
+    connections created:                 6298470    failed:            0
+    connections updated:                 3786793    failed:            0
+    connections destroyed:               6278864    failed:            0
 
-If you are using VRRP, you need to define a VRRP sync-group, and use
-``vrrp sync-group`` instead of ``cluster group``.
+    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``
 
 .. code-block:: none
 
   set high-availablilty vrrp group internal virtual-address ... etc ...
   set high-availability vrrp sync-group syncgrp member 'internal'
+  set service conntrack-sync accept-protocol 'tcp,udp,icmp'
   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'
 
 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
@@ -164,11 +224,8 @@ On active router run:
   message tracking:
                      0 Malformed msgs                    0 Lost msgs
 
-
-
 On standby router run:
 
-
 .. code-block:: none