Commit 622190ae authored by Tomas Krizek's avatar Tomas Krizek

README: clarify answers db documentation

parent 5aff589a
......@@ -166,43 +166,56 @@ to the servers. Each query has a unique integer identifier, ``<QID>``.
Database ``answers``
~~~~~~~~~~~~~~~~~~~~
``answers`` database stores the binary reponses from the queried servers.
``answers`` database stores the binary responses from the queried servers.
If there are multiple servers, their reponses are stored within a single
``<QID>`` key. Multiple responses (in their binary form ``time | length | wire``
as described below) are simply concatenated within the value. Please
If there are multiple servers, their responses are stored within a single
``<QID>`` key. Multiple responses are stored within the value by simply
concatenating them in the binary format of ``response`` described below. Please
note the order of responses is significant and must correspond with the server
definition in the ``meta`` database.
+-----------+-----------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
| Key | Key Type | Value Description | Value Type |
+===========+=================+===============================+=====================================================================================================================================+
| ``<QID>`` | 4B unsigned int | DNS reponse(s) from server(s) | One or more of |
| | | | ``time | length | wire`` |
| | | | - ``time``: 4B unsigned int; time to receive the answer in microseconds; ``4294967295`` (max value) means *timeout* |
| | | | - ``length``: 2B unsigned short; the length (in bytes) of the DNS message that follows (``length`` is present in case of *timeout*) |
| | | | - ``wire``: ``length``-byte DNS wire format with the response from server |
+-----------+-----------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+
+-----------+-----------------+--------------------------------+---------------------------------------+
| Key | Key Type | Value Description | Value Type |
+===========+=================+================================+=======================================+
| ``<QID>`` | 4B unsigned int | DNS response(s) from server(s) | One or more ``response`` (see below) |
+-----------+-----------------+--------------------------------+---------------------------------------+
``response`` represents a single DNS response from a server and has the
following binary format::
0 1 2 3 4 5 6 ...
+----+----+----+----+----+----+----\\----+
| time | length | wire |
+----+----+----+----+----+----+----\\----+
+------------+--------------------------+---------------------------------------------------------------------------------------------------------------------------+
| Label | Type | Description |
+============+==========================+===========================================================================================================================+
| ``time`` | 4B unsigned int | time to receive the answer in microseconds; ``4294967295`` (``FF FF FF FF``) means *timeout* |
+------------+--------------------------+---------------------------------------------------------------------------------------------------------------------------+
| ``length`` | 2B unsigned int | byte-length of the DNS ``wire`` format message that may follow; (``length`` is always present, even in case of *timeout*) |
+------------+--------------------------+---------------------------------------------------------------------------------------------------------------------------+
| ``wire`` | ``length`` B binary blob | DNS wire format of the message received from server (``wire`` is present only if ``length`` isn't zero) |
+------------+--------------------------+---------------------------------------------------------------------------------------------------------------------------+
Database ``meta``
~~~~~~~~~~~~~~~~~
``meta`` database stores additional information used for further processing of the data.
+----------------+----------+-------------------------------------------------------------------+-----------------+
| Key | Key Type | Value Description | Value Type |
+================+==========+===================================================================+=================+
| ``version`` | ASCII | respdiff binary format version (current: ``2018-05-21``) | ASCII |
+----------------+----------+-------------------------------------------------------------------+-----------------+
| ``servers`` | ASCII | number of servers reponses are collected from | 4B unsigned int |
+----------------+----------+-------------------------------------------------------------------+-----------------+
| ``name0`` | ASCII | name identifier of the first server (same as in ``respdiff.cfg``) | ASCII |
+----------------+----------+-------------------------------------------------------------------+-----------------+
| ``name1`` | ASCII | name identifier of the second server | ASCII |
+----------------+----------+-------------------------------------------------------------------+-----------------+
| ``name<N>`` | ASCII | name identifier of the ``N+1``-th server | ASCII |
+----------------+----------+-------------------------------------------------------------------+-----------------+
| ``start_time`` | ASCII | (*optional*) unix timestamp of the start of data collection | 4B unsigned int |
+----------------+----------+-------------------------------------------------------------------+-----------------+
| ``end_time`` | ASCII | (*optional*) unix timestamp of the end of data collection | 4B unsigned int |
+----------------+----------+-------------------------------------------------------------------+-----------------+
+----------------+----------+-------------------------------------------------------------------+------------------+
| Key | Key Type | Value Description | Value Type |
+================+==========+===================================================================+==================+
| ``version`` | ASCII | respdiff binary format version (current: ``2018-05-21``) | ASCII |
+----------------+----------+-------------------------------------------------------------------+------------------+
| ``servers`` | ASCII | number of servers responses are collected from | 4B unsigned int |
+----------------+----------+-------------------------------------------------------------------+------------------+
| ``name0`` | ASCII | name identifier of the first server (same as in ``respdiff.cfg``) | ASCII |
+----------------+----------+-------------------------------------------------------------------+------------------+
| ``name1`` | ASCII | name identifier of the second server | ASCII |
+----------------+----------+-------------------------------------------------------------------+------------------+
| ``name<N>`` | ASCII | name identifier of the ``N+1``-th server | ASCII |
+----------------+----------+-------------------------------------------------------------------+------------------+
| ``start_time`` | ASCII | (*optional*) unix timestamp of the start of data collection | 4B unsigned int |
+----------------+----------+-------------------------------------------------------------------+------------------+
| ``end_time`` | ASCII | (*optional*) unix timestamp of the end of data collection | 4B unsigned int |
+----------------+----------+-------------------------------------------------------------------+------------------+
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment