docs: add a preliminary protocol description

docs/capture_analyse_packets.rst

@@ -0,0 +1,52 @@
+Capturing and analysing tunneldigger packets
+############################################
+
+Example pcap filter using tcpdump
+*********************************
+
+See :ref:`PDU types`
+
+capture control traffic
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code:: sh
+
+   # capture all tunneldigger control traffic
+   tcpdump -i eth0 -w /tmp/output.pcap 'udp port 8942 and udp[8] == 0x80'
+
+capture only USAGE packets
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code:: sh
+
+   # capture only USAGE packets
+   tcpdump -i eth0 -w /tmp/output.pcap 'udp port 8942 and udp[8] == 0x80 and udp[12] == 0x0a'
+
+capture control packets except KEEPALIVE, PMTUD, PMTUD_ACK, PMTUD_NTFY
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code:: sh
+
+   # capture control packets except KEEPALIVE, PMTUD, PMTUD_ACK, PMTUD_NTFY
+   tcpdump -i eth0 -w /tmp/output.pcap 'udp port 8942 and udp[8] == 0x80 and (udp[12] != 5 && udp[12] != 6 && udp[12] != 7 && udp[12] != 9)'
+
+
+Using wireshark
+***************
+
+There is a `custom dissector <https://github.com/wlanslovenija/tunneldigger/blob/master/docs/wireshark-tunneldigger.lua>`_ for tunneldigger written in lua. The dissector is registered as **TD**.
+
+To use the wireshark dissector call wireshark with:
+
+.. code:: sh
+
+   cd tunneldigger/docs/
+   wireshark -Xlua_script:wireshark-tunneldigger.lua
+
+Wireshark might decode the user data as a different protocol (e.g. Cisco HDLC). This can be changed by:
+
+* Click on "wrong" protocol in "Packet Details" pane (usually the pane in the middle).
+* Right mouse click, select **Decode As** (Ctrl-Shift-U).
+* A new window with decodes should open
+* A new row should be already created. The field should be called **L2TPv3 payload type**.
+* Select **Ethernet** in the **Current** column.

docs/conf.py

@@ -25,7 +25,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.intersphinx']
+extensions = ['sphinx.ext.intersphinx', 'sphinxcontrib.packetdiag']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/index.rst

@@ -24,6 +24,8 @@ Contents
 
    server
    client
+   protocol
+   capture_analyse_packets
 
 Source Code and Issue Tracker
 -----------------------------

docs/protocol.rst

@@ -0,0 +1,60 @@
+Tunneldigger protocol
+#####################
+
+The Tunneldigger protocol is based on L2TPv3.
+Tunneldigger implementing a custom control protocol,
+while user data is encapsulated as L2TPv3 specifies.
+This allows to use in kernel acceleration of the data path.
+
+The L2TPv3 is specified in `RFC3931 <https://tools.ietf.org/html/rfc3931>`_
+
+Control packets
+***************
+
+Tunneldigger is not following RFC3931 for control messages.
+Tunneldigger is only supporting the T bit in the first bit to
+mark a packet as control data. All other fields of RFC3931
+are ignore and have a different meaning..
+All fields are encoding with network byte order.
+
+.. packetdiag::
+
+    {
+        colwidth = 16
+        node_height = 48
+
+        0:      T
+        1-7:    0
+        8-23:   Magic 0x73A7
+        24-31:  Version
+        32-39:  Type
+        40-47:  Length
+        48-63:  Value
+    }
+
+
+* The T bit must be 1
+* Version must be 1
+* Type of the PDU
+* Length of the value
+
+.. _PDU types:
+
+PDU types
+^^^^^^^^^
+
+.. csv-table:: PDU types
+   :header: "Type", "Name", "Summary"
+
+   0x00, INVALID,
+   0x01, COOKIE,
+   0x02, PREPARE,
+   0x03, ERROR,
+   0x04, TUNNEL,
+   0x05, KEEPALIVE,
+   0x06, PMTUD,
+   0x07, PMTUD_ACK,
+   0x08, REL_ACK,
+   0x09, PMTU_NTFY,
+   0x0a, USAGE,
+   0x80, LIMIT,