docs: update for bittorrent-dht app-layer

diff --git a/doc/userguide/output/eve/eve-json-format.rst b/doc/userguide/output/eve/eve-json-format.rst
index 926a7c468aaa05afd05bf8a8d4efec4d0779594d..2eed612dde649bab872e7e511b817e9580f16628 100644 (file)
--- a/doc/userguide/output/eve/eve-json-format.rst
+++ b/doc/userguide/output/eve/eve-json-format.rst
@@ -981,6 +981,181 @@ DCERPC BIND/BINDACK::
       "call_id": 2
     }
 
+Event type: BITTORRENT-DHT
+--------------------------
+
+Common fields:
+~~~~~~~~~~~~~~
+
+* "transaction_id" (string): the unique id of the transaction, generated by node making the request (a.k.a the querying node). Same transaction_id is echoed back by responding nodes. Usually a short string of binary numbers.
+* "client_version" (string): string which identifies the type and version of the bittorrent-dht client. Some implementations may be missing this field.
+
+Extra fields:
+~~~~~~~~~~~~~
+Packets should also contain one of either the fields:
+
+| error
+
+* "error": details of an error which occurred while processing the request
+   * "error.num" (num): the error code
+   * "error.msg" (string): the error message
+
+| request_type and request
+
+* "request_type" (string): the type of the request (a.k.a. the query). Included if this packet was a request
+* "request": a request (a.k.a. a query) sent by the bittorrent-dht client
+   * "request.id" (string): the node ID of the node which sent the request (20-byte string in network byte order)
+   * "request.target" (string): the target node ID. Used by the find_node request_type
+   * "request.info_hash" (string): info hash of target torrent (20-byte string). Used by the get_peers and announce_peer request_types
+   * "request.token" (string): token key received from previous get_peers request. Used by the announce_peer request type
+   * "request.implied_port" (num): 0 or 1, if 1 ignore provided port and use source port of UDP packet. Used by the announce_peer request_type
+   * "request.port" (num): port on which peer will download torrent. Used by the announce_peer request_type
+
+| response
+
+* "response": a response to the client's request
+   * "response.id" (string): the node ID of the node which sent the response (20-byte string in network byte order)
+   * "response.nodes" (string): find_node/get_peers - compact node info for target node or K(8) closest good nodes in routing table
+   * "response.values" (array): list of compact peer info strings. Used by the get_peers request_type
+   * "response.token" (string): token key required for sender's future announce_peer query
+
+Examples:
+~~~~~~~~~
+
+Ping and response::
+
+  "bittorrent-dht": {
+    "transaction_id": "aa",
+    "request_type": "ping",
+    "request": {
+      "id": "abcdefghij0123456789"
+    }
+  }
+  "bittorrent-dht": {
+    "transaction_id": "aa",
+    "response": {
+      "id": "mnopqrstuvwxyz123456"
+    }
+  }
+
+Find_node and response::
+
+  "bittorrent-dht": {
+    "transaction_id": "aa",
+    "client_version": "UT01",
+    "request_type": "find_node",
+    "request": {
+      "id": "abcdefghij0123456789",
+      "target": "mnopqrstuvwxyz123456"
+    }
+  }
+  "bittorrent-dht": {
+    "transaction_id": "aa",
+    "client_version": "UT01",
+    "response": {
+      "id": "0123456789abcdefghij",
+      "nodes": "def456..."
+    }
+  }
+
+Get_peers and response with values param::
+
+  "bittorrent-dht": {
+    "transaction_id": "aa",
+    "request_type": "get_peers",
+    "request": {
+      "id": "abcdefghij0123456789",
+      "info_hash": "mnopqrstuvwxyz123456"
+    }
+  }
+  "bittorrent-dht": {
+    "transaction_id": "aa",
+    "client_version": "UT12",
+    "response": {
+      "id": "abcdefghij0123456789",
+      "values": [
+        "axje.u",
+        "idhtnm"
+      ],
+      "token": "aoeusnth"
+    }
+  }
+
+Get_peers and response with nodes param::
+
+  "bittorrent-dht": {
+    "transaction_id": "aa",
+    "request_type": "get_peers",
+    "request": {
+      "id": "abcdefghij0123456789",
+      "info_hash": "mnopqrstuvwxyz123456"
+    }
+  }
+  "bittorrent-dht": {
+    "transaction_id": "aa",
+    "response": {
+      "id": "abcdefghij0123456789",
+      "nodes": "def456...",
+      "token": "aoeusnth"
+    }
+  }
+
+Announce_peer and response::
+
+  "bittorrent-dht": {
+    "transaction_id": "aa",
+    "request_type": "announce_peer",
+    "request": {
+      "id": "abcdefghij0123456789",
+      "info_hash": "mnopqrstuvwxyz123456",
+      "token": "aoeusnth",
+      "port": 6881
+    }
+  }
+  "bittorrent-dht": {
+    "transaction_id": "aa",
+    "response": {
+      "id": "mnopqrstuvwxyz123456"
+    }
+  }
+
+Announce_peer with implied_port param and response::
+
+  "bittorrent-dht": {
+    "transaction_id": "aa",
+    "request_type": "announce_peer",
+    "request": {
+      "id": "abcdefghij0123456789",
+      "info_hash": "mnopqrstuvwxyz123456",
+      "token": "aoeusnth",
+      "implied_port": 1,
+      "port": 6881
+    }
+  }
+  "bittorrent-dht": {
+    "transaction_id": "aa",
+    "response": {
+      "id": "mnopqrstuvwxyz123456"
+    }
+  }
+
+Sample error responses::
+
+  "bittorrent-dht": {
+    "transaction_id": "aa",
+    "error": {
+      "num": 201,
+      "msg": "A Generic Error Ocurred"
+    }
+  }
+  "bittorrent-dht": {
+    "transaction_id": "aa",
+    "error": {
+      "num": 203,
+      "msg": "Malformed Packet"
+    }
+  }
+
 NTLMSSP fields
 ~~~~~~~~~~~~~~
 

diff --git a/doc/userguide/partials/eve-log.yaml b/doc/userguide/partials/eve-log.yaml
index e664f92b37d2b8ce94d2d132374f85d63981fe5a..dca74196ed1b993c54ad4b9f9c0005e2bd58b58c 100644 (file)
--- a/doc/userguide/partials/eve-log.yaml
+++ b/doc/userguide/partials/eve-log.yaml
@@ -162,6 +162,8 @@ outputs:
         - nfs
         # IKE logging. Requires Rust.
         - ike
+        # BitTorrent DHT logging. Requires Rust.
+        - bittorrent-dht
         - ssh
         - stats:
             totals: yes       # stats for all threads merged together

diff --git a/doc/userguide/rules/intro.rst b/doc/userguide/rules/intro.rst
index 80e6919bfbd2e536d58e899de6db02b206f36bb6..6b0ac46961d12899c2e26416fa4986190c06e7aa 100644 (file)
--- a/doc/userguide/rules/intro.rst
+++ b/doc/userguide/rules/intro.rst
@@ -100,6 +100,7 @@ you can pick from. These are:
 * nfs
 * ike
 * krb5
+* bittorrent-dht
 * ntp
 * dhcp
 * rfb