Merge pull request #2421 in SNORT/snort3 from ~OSHUMEIK/snort3:doc_dump_config to...

Squashed commit of the following:

commit 5c61850d9548f38433bad7adf1b1e2b8da730762
Author: Oleksii Shumeiko <oshumeik@cisco.com>
Date:   Fri Aug 21 16:12:24 2020 +0300

    doc: update the config dump in JSON format (main policy)

commit 8584173190dc92a07e381dcf84083c1ca46e030c
Author: Serhii Vlasiuk <svlasiuk@cisco.com>
Date:   Tue Aug 11 17:27:11 2020 +0300

    doc: update the config dump in JSON format (all policies)

diff --git a/doc/user/CMakeLists.txt b/doc/user/CMakeLists.txt
index f9ffde53e274620b7851a887c5b177d650096137..426827e13fe6f5caff8d421ae6fb3709d5382f90 100644 (file)
--- a/doc/user/CMakeLists.txt
+++ b/doc/user/CMakeLists.txt
@@ -11,7 +11,7 @@ set (
     byte_test.txt
     concepts.txt
     connectors.txt
-    consolidated_config.txt
+    dump_config.txt
     daq.txt
     dcerpc.txt
     errors.txt

diff --git a/doc/user/consolidated_config.txt b/doc/user/consolidated_config.txt
deleted file mode 100644 (file)
index 12d4ef9..0000000
--- a/doc/user/consolidated_config.txt
+++ /dev/null
@@ -1,55 +0,0 @@
-Using Consolidated Config output enables troubleshooting of configuration issues.
-The output contains applied configurations ( defaults and configured ) and is 
-printed for the main config and all included policies.
-So far, Snort supports output in text format.
-
-==== Text Format
-
-The --dump-config-text option verifies the configuration and dumps it to stdout in text format.
-
-Example:
-
-    consolidated config for snort.lua
-    binder[0].when.ips_policy_id=0
-    binder[0].when.role='any'
-    binder[0].when.nets='10.1.2.0/24'
-    binder[0].use.action='inspect'
-    binder[1].when.ips_policy_id=0
-    binder[1].when.role='any'
-    binder[1].when.nets='192.168.2.0/24'
-    binder[1].use.action='inspect'
-    host_cache.memcap=8.38861e+06
-    network.checksum_drop='none'
-    network.checksum_eval='all'
-    network.max_ip_layers=0
-    process.daemon=false
-    process.dirty_pig=false
-    process.utc=false
-    stream_tcp.flush_factor=0
-    stream_tcp.max_window=0
-    stream_tcp.overlap_limit=0
-    stream_tcp.max_pdu=16384
-    stream.footprint=0
-    stream.ip_frags_only=false
-    trace.modules.appid.all=1
-    trace.modules.detection.opt_tree=2
-    trace.modules.detection.fp_search=4
-    trace.modules.detection.rule_eval=1
-    trace.modules.wizard.all=1
-    trace.constraints.match=true
-    trace.constraints.dst_ip='10.1.1.2'
-    trace.constraints.dst_port=200
-    trace.constraints.src_port=100
-    trace.constraints.ip_proto=17
-    trace.output='stdout'
-    wizard.spells[0].proto='tcp'
-    wizard.spells[0].client_first=true
-    wizard.spells[0].service='http'
-    wizard.spells[0].to_client[0].spell='HTTP/'
-    wizard.spells[0].to_server[0].spell='GET'
-    wizard.spells[1].proto='tcp'
-    wizard.spells[1].client_first=true
-    wizard.spells[1].service='sip'
-    wizard.spells[1].to_server[0].spell='INVITE'
-
-For lists, the index next to the option name designates an element parsing order.
\ No newline at end of file

diff --git a/doc/user/dump_config.txt b/doc/user/dump_config.txt
new file mode 100644 (file)
index 0000000..c63d418
--- /dev/null
+++ b/doc/user/dump_config.txt
@@ -0,0 +1,295 @@
+Config dump mode generates a consolidated dump of the config passed to Snort.
+This output consists of the configured values as well as the module defaults
+for the values that aren't configured.
+
+In the dump mode Snort validates the config (similar to option -T)
+and suppresses unrelated messages going to stdout
+(but not stderr one like ParseWarnings).
+
+The dump mode is activated by the following options:
+--dump-config-text, --dump-config=all, --dump-config=top.
+They are described in detail below.
+
+The simple configuration is used in examples.
+The output contains applied configurations (defaults and configured).
+To simplify the output we show a brief list of default options.
+
+snort.lua
+
+    stream =
+    {
+        max_flows = 2
+    }
+
+    stream_tcp =
+    {
+        show_rebuilt_packets = true
+    }
+
+    binder =
+    {
+        { when = { nets = '10.1.2.0/24' }, use = { inspection_policy = 'http.lua' } },
+        { when = { nets = '192.168.2.0/24' }, use = { inspection_policy = 'sip.lua' } },
+    }
+
+http.lua
+
+    wizard =
+    {
+        spells =
+        {
+            { service = 'http', proto = 'tcp', client_first = true, to_server = { 'GET' }, to_client = { 'HTTP/' } },
+        }
+    }
+
+sip.lua
+
+    wizard =
+    {
+        spells =
+        {
+            { service = 'sip', to_server = { 'INVITE' } },
+        }
+    }
+
+==== Text Format
+
+The --dump-config-text option verifies the configuration and dumps it to stdout in text format.
+The output contains a config of the main policy and all other included sub-policies.
+
+Example:
+    snort -c snort.lua --dump-config-text
+
+    consolidated config for snort.lua
+    alerts.order="pass reset block drop alert log"
+    alerts.rate_filter_memcap=1048576
+    binder[0].when.ips_policy_id=0
+    binder[0].when.role="any"
+    binder[0].when.nets="10.1.2.0/24"
+    binder[0].use.action="inspect"
+    binder[0].use.inspection_policy="http.lua"
+    binder[1].when.ips_policy_id=0
+    binder[1].when.role="any"
+    binder[1].when.nets="192.168.2.0/24"
+    binder[1].use.action="inspect"
+    binder[1].use.inspection_policy="sip.lua"
+    output.obfuscate=false
+    output.wide_hex_dump=true
+    packets.address_space_agnostic=false
+    packets.limit=0
+    search_engine.split_any_any=true
+    search_engine.queue_limit=128
+    stream.file_cache.idle_timeout=180
+    stream.file_cache.cap_weight=32
+    stream.max_flows=2
+    stream_tcp.small_segments.maximum_size=0
+    stream_tcp.session_timeout=30
+    stream_tcp.track_only=false
+    stream_tcp.show_rebuilt_packets=true
+    consolidated config for http.lua
+    wizard.spells[0].proto="tcp"
+    wizard.spells[0].client_first=true
+    wizard.spells[0].service="http"
+    wizard.spells[0].to_client[0].spell="HTTP/"
+    wizard.spells[0].to_server[0].spell="GET"
+    consolidated config for sip.lua
+    wizard.spells[0].proto="tcp"
+    wizard.spells[0].client_first=true
+    wizard.spells[0].service="sip"
+    wizard.spells[0].to_server[0].spell="INVITE"
+
+For lists, the index next to the option name designates an element parsing order.
+
+==== JSON Format
+
+The --dump-config=all command-line option verifies the configuration and dumps it to
+stdout in JSON format. The output contains a config of the main policy and all other
+included sub-policies. Snort dumps output in a one-line format.
+
+There is 3rd party tool 'jq' for converting to a pretty printed format.
+
+Example:
+    snort -c snort.lua --dump-config=all | jq '.'
+
+    [
+        {
+            "filename": "snort.lua",
+            "config": {
+            "alerts": {
+                "order": "pass reset block drop alert log",
+                "rate_filter_memcap": 1048576
+            },
+            "binder": [
+                {
+                "when": {
+                    "ips_policy_id": 0,
+                    "role": "any",
+                    "nets": "10.1.2.0/24"
+                },
+                "use": {
+                    "action": "inspect",
+                    "inspection_policy": "http.lua"
+                }
+                },
+                {
+                "when": {
+                    "ips_policy_id": 0,
+                    "role": "any",
+                    "nets": "192.168.2.0/24"
+                },
+                "use": {
+                    "action": "inspect",
+                    "inspection_policy": "sip.lua"
+                }
+                }
+            ],
+            "output": {
+                "obfuscate": false,
+                "wide_hex_dump": true
+            },
+            "packets": {
+                "address_space_agnostic": false,
+                "limit": 0
+            },
+            "process": {
+                "daemon": false,
+                "dirty_pig": false,
+                "utc": false
+            },
+            "search_engine": {
+                "split_any_any": true,
+                "queue_limit": 128
+            },
+            "stream": {
+                "file_cache": {
+                "idle_timeout": 180,
+                "cap_weight": 32
+                },
+                "max_flows": 2
+            },
+            "stream_tcp": {
+                "small_segments": {
+                    "maximum_size": 0
+                },
+                "session_timeout": 30,
+                "track_only": false,
+                "show_rebuilt_packets": true
+            }
+            }
+        },
+        {
+            "filename": "http.lua",
+            "config": {
+            "wizard": {
+                "spells": [
+                {
+                    "proto": "tcp",
+                    "client_first": true,
+                    "service": "http",
+                    "to_client": [
+                    {
+                        "spell": "HTTP/"
+                    }
+                    ],
+                    "to_server": [
+                    {
+                        "spell": "GET"
+                    }
+                    ]
+                }
+                ]
+            }
+            }
+        },
+        {
+            "filename": "sip.lua",
+            "config": {
+            "wizard": {
+                "spells": [
+                {
+                    "proto": "tcp",
+                    "client_first": true,
+                    "service": "sip",
+                    "to_server": [
+                    {
+                        "spell": "INVITE"
+                    }
+                    ]
+                }
+                ]
+            }
+            }
+        }
+    ]
+
+The --dump-config=top command-line option is similar to --dump-config=all,
+except it produces dump for the main policy only.
+It verifies the configuration and dumps the main policy configuration to
+stdout in JSON format.
+
+Example:
+    snort -c snort.lua --dump-config=top | jq '.'
+
+    {
+        "alerts": {
+            "order": "pass reset block drop alert log",
+            "rate_filter_memcap": 1048576,
+        },
+        "binder": [
+            {
+                "when": {
+                    "ips_policy_id": 0,
+                    "role": "any",
+                    "nets": "10.1.2.0/24"
+                },
+                "use": {
+                    "action": "inspect",
+                    "inspection_policy": "http.lua"
+                }
+            },
+            {
+                "when": {
+                    "ips_policy_id": 0,
+                    "role": "any",
+                    "nets": "192.168.2.0/24"
+                },
+                "use": {
+                    "action": "inspect",
+                    "inspection_policy": "sip.lua"
+                }
+            }
+        ],
+        "output": {
+            "obfuscate": false,
+            "wide_hex_dump": true
+        },
+        "packets": {
+            "address_space_agnostic": false,
+            "limit": 0,
+        },
+        "process": {
+            "daemon": false,
+            "dirty_pig": false,
+            "utc": false
+        },
+        "search_engine": {
+            "split_any_any": true,
+            "queue_limit": 128
+        },
+        "stream": {
+            "file_cache": {
+                "idle_timeout": 180,
+                "cap_weight": 32
+            }
+            "max_flows": 2
+        },
+        "stream_tcp": {
+            "small_segments": {
+                "count": 0,
+                "maximum_size": 0
+            },
+            "session_timeout": 30,
+            "track_only": false,
+            "show_rebuilt_packets": true
+        },
+    }

diff --git a/doc/user/features.txt b/doc/user/features.txt
index 453d03102e747b1880e49519669de36e5941bb3c..cd2d735a4a36baabe3fa8b8da4172793e4a2bd2a 100644 (file)
--- a/doc/user/features.txt
+++ b/doc/user/features.txt
@@ -34,7 +34,7 @@ include::byte_options.txt[]
 
 === Consolidated Config
 
-include::consolidated_config.txt[]
+include::dump_config.txt[]
 
 === DCE Inspectors