Merge pull request #189 from Tantalor93/docs

Docs
Tantalor93 · Nov 18, 2023 · 2efc944 · 2efc944
2 parents 75b0a3b + c8d01c2
commit 2efc944
Show file tree

Hide file tree

Showing 19 changed files with 245 additions and 139 deletions.
diff --git a/cmd/benchmark.go b/cmd/benchmark.go
@@ -386,8 +386,8 @@ func (b *Benchmark) Run(ctx context.Context) ([]*ResultStats, error) {
 			}
 
 			for i = 0; i < b.Count || b.Duration != 0; i++ {
-				for _, qt := range qTypes {
-					for _, q := range questions {
+				for _, q := range questions {
+					for _, qt := range qTypes {
 						if ctx.Err() != nil {
 							return
 						}

diff --git a/docs/Gemfile b/docs/Gemfile
@@ -1,9 +1,9 @@
 source 'https://rubygems.org'
 
-gem "jekyll", "~> 4.3" # installed by `gem jekyll`
+gem "jekyll", "~> 4.3.2" # installed by `gem jekyll`
 # gem "webrick"        # required when using Ruby >= 3 and Jekyll <= 4.2.2
 
-gem "just-the-docs", "0.5.0" # pinned to the current release
+gem "just-the-docs", "0.7.0" # pinned to the current release
 # gem "just-the-docs"        # always download the latest release
 
 gem "jekyll-relative-links", "0.7.0"
diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock
@@ -1,20 +1,23 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.1)
+    addressable (2.8.5)
       public_suffix (>= 2.0.2, < 6.0)
     colorator (1.1.0)
-    concurrent-ruby (1.1.10)
+    concurrent-ruby (1.2.2)
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
     eventmachine (1.2.7)
-    ffi (1.15.5)
+    ffi (1.16.3)
     forwardable-extended (2.6.0)
+    google-protobuf (3.23.4-arm64-darwin)
+    google-protobuf (3.23.4-x86_64-darwin)
+    google-protobuf (3.23.4-x86_64-linux)
     http_parser.rb (0.8.0)
-    i18n (1.12.0)
+    i18n (1.14.1)
       concurrent-ruby (~> 1.0)
-    jekyll (4.3.0)
+    jekyll (4.3.2)
       addressable (~> 2.4)
       colorator (~> 1.0)
       em-websocket (~> 0.5)
@@ -30,43 +33,47 @@ GEM
       safe_yaml (~> 1.0)
       terminal-table (>= 1.8, < 4.0)
       webrick (~> 1.7)
+    jekyll-include-cache (0.2.1)
+      jekyll (>= 3.7, < 5.0)
     jekyll-relative-links (0.7.0)
       jekyll (>= 3.3, < 5.0)
-    jekyll-sass-converter (2.2.0)
-      sassc (> 2.0.1, < 3.0)
+    jekyll-sass-converter (3.0.0)
+      sass-embedded (~> 1.54)
     jekyll-seo-tag (2.8.0)
       jekyll (>= 3.8, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
-    just-the-docs (0.5.0)
+    just-the-docs (0.7.0)
       jekyll (>= 3.8.5)
+      jekyll-include-cache
       jekyll-seo-tag (>= 2.0)
       rake (>= 12.3.1)
     kramdown (2.4.0)
       rexml
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
-    liquid (4.0.3)
-    listen (3.7.1)
+    liquid (4.0.4)
+    listen (3.8.0)
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.4.0)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
-    public_suffix (5.0.0)
-    rake (13.0.6)
+    public_suffix (5.0.4)
+    rake (13.1.0)
     rb-fsevent (0.11.2)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
-    rexml (3.2.5)
+    rexml (3.2.6)
     rouge (3.30.0)
     safe_yaml (1.0.5)
-    sassc (2.4.0)
-      ffi (~> 1.9)
+    sass-embedded (1.58.3)
+      google-protobuf (~> 3.21)
+      rake (>= 10.0.0)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
-    unicode-display_width (2.3.0)
-    webrick (1.7.0)
+    unicode-display_width (2.5.0)
+    webrick (1.8.1)
 
 PLATFORMS
   arm64-darwin-21
@@ -76,9 +83,9 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
-  jekyll (~> 4.3)
+  jekyll (~> 4.3.2)
   jekyll-relative-links (= 0.7.0)
-  just-the-docs (= 0.5.0)
+  just-the-docs (= 0.7.0)
 
 BUNDLED WITH
    2.3.9
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -16,3 +16,11 @@ plugins:
 
 logo: "/assets/logo.png"
 favicon_ico: "/assets/favicon.ico"
+
+callouts:
+  note:
+    color: purple
+  warning:
+    color: red
+  important:
+    color: blue
diff --git a/docs/basics.md b/docs/basics.md
@@ -0,0 +1,28 @@
+---
+title: Basics
+layout: default
+parent: Examples
+---
+
+# Basics
+*dnspyre* is a tool for benchmarking DNS servers, it works by spawning configured number of concurrent worker thread, where each worker thread
+is sending DNS queries for a domains provided to the *dnspyre* tool. The *dnspyre* runs until on the conditions is met:
+* configured number of repetitions of domain queries is sent (`-n`, `--number` flag is specified)
+* the required duration of benchmark run elapses (`--duration` is specified)
+* benchmark is interrupted with the SIGINT signal
+
+## Run benchmark with the configured number of repetitions
+This example runs the benchmark in 10 parallel threads, where each thread will send 2 `example.com.` DNS queries
+of type `A` one after another to the `8.8.8.8` server
+
+```
+dnspyre -n 2 -c 10 --server 8.8.8.8 example.com
+```
+
+## Run benchmark over specified time
+This example runs the benchmark in 10 parallel threads for a duration of 30 seconds while sending `example.com` DNS queries of type `A`
+to the `8.8.8.8` server
+
+```
+dnspyre --duration 30s -c 10 --server 8.8.8.8 google.com
+```
diff --git a/docs/concurrency.md b/docs/concurrency.md
@@ -0,0 +1,15 @@
+---
+title: Concurrency
+layout: default
+parent: Examples
+---
+
+# Concurrency
+*dnspyre* by default benchmarks a DNS server using a single thread (worker). This can be adjusted using `-c` (`--concurrency`) flag.
+
+In this example, the benchmark runs in 10 parallel threads (option `-c`) , where each thread will send 2 (option `-n`) `example.com.` DNS queries 
+of type `A` one after another to the `8.8.8.8` server
+
+```
+dnspyre -n 2 -c 10 --server 8.8.8.8 example.com
+```
diff --git a/docs/doh.md b/docs/doh.md
@@ -8,6 +8,7 @@ parent: Examples
 {: .no_toc }
 
 *dnspyre* supports running benchmarks against [RFC-8484](https://www.rfc-editor.org/rfc/rfc8484) compatible DNS over HTTPS servers
+
 ```
 dnspyre --server 'https://1.1.1.1' google.com
 ```
@@ -19,17 +20,20 @@ See other examples of customization of DoH benchmarks
 
 ## DoH via GET/POST
 you can also specify whether the DoH is done via GET or POST using `--doh-method`
+
 ```
 dnspyre --server 'https://1.1.1.1' --doh-method get google.com
 ```
 
 benchmarking DoH server via DoH over POST method 
+
 ```
 dnspyre --server 'https://1.1.1.1' --doh-method post google.com
 ```
 
 ## DoH/1.1, DoH/2, DoH/3
 you can also specify whether the DoH is done over HTTP/1.1, HTTP/2, HTTP/3 using `--doh-protocol`, for example:
+
 ```
 dnspyre --server 'https://1.1.1.1' --doh-protocol 2 google.com
 ```

diff --git a/docs/domainsources.md b/docs/domainsources.md
@@ -0,0 +1,33 @@
+---
+title: Domain sources
+layout: default
+parent: Examples
+---
+
+# Domain sources
+*dnspyre* benchmarks DNS servers by querying the domains specified as arguments to the tool, the domains to the tool can be passed in a various ways:
+
+
+## Domains provided directly as arguments
+You can pass an arbitrary number of domains to be used for the DNS benchmark, by specifying more arguments. In this example, domains
+`redsift.io`, `example.com`, `google.com` are used to generate DNS queries
+
+```
+dnspyre -n 10 -c 10 --server 8.8.8.8 redsift.io example.com google.com
+```
+
+## Domains provided using file on local filesystem
+Instead of specifying domains as arguments to the *dnspyre* tool, you can just specify a file containing domains to be used by the tool.
+By referencing the file using `@<path-to-file>`. In this example, the domains are read from the `data/2-domains` file.
+
+```
+dnspyre -n 10 -c 10 --server 8.8.8.8 @data/2-domains
+```
+
+## Domains provided using file publicly available using HTTP(s)
+The file containing hostnames does not need to be available locally, it can be also downloaded from the remote location using HTTP(s).
+In this example, the domains are downloaded from the https://raw.githubusercontent.com/Tantalor93/dnspyre/master/data/2-domains
+
+```
+dnspyre -n 10 -c 10 --server 8.8.8.8 https://raw.githubusercontent.com/Tantalor93/dnspyre/master/data/2-domains
+```
diff --git a/docs/edns0.md b/docs/edns0.md
@@ -9,13 +9,15 @@ parent: Examples
 
 ## UDP message size
 advertisement for support of larger DNS response size (UDP message size) using `--edns0` flag
+
 ```
 dnspyre  --server '1.1.1.1' google.com --edns0=1024
 ```
 
 ## DNSSEC
 [DNSSEC](https://datatracker.ietf.org/doc/html/rfc9364) security extension using `--dnssec` flag, by using this flag the *dnspyre* will also
 count the **number of domains that were successfully validated by DNS resolver**
+
 ```
 dnspyre  --server '1.1.1.1' cloudflare.com --dnssec
 ```
@@ -25,6 +27,7 @@ sending various EDNS0 options using `--ednsopt` flag, you have to specify the de
 data format depends on the EDNS0 option
 
 for example to send [client subnet EDNS0 option](https://datatracker.ietf.org/doc/html/rfc7871) for subnet `81.0.198.170/24` you specify code `8` and data `000118005100c6` (`0001` = IPv4 Family, `18` = source mask `/24`, `00` = no additional scope, `5100C6AA` = `81.0.198.170` )
+
 ```
 dnspyre  --server '8.8.8.8' aws.amazon.com --ednsopt '8:000118005100c6'
 ```
diff --git a/docs/examples.md b/docs/examples.md
@@ -6,119 +6,3 @@ has_children: true
 ---
 
 # Examples
-{: .no_toc }
-This page shows examples of *dnspyre* usage and its various options
-
-* TOC
-{:toc}
-
-
-## Sending queries from multiple parallel threads
-This example will execute the benchmark in 10 parallel threads (option `-c`) , where each thread will
-send 2 (option `-n`) `example.com.` DNS queries of type `A` one after another to the `8.8.8.8` server
-```
-dnspyre -n 2 -c 10 --server 8.8.8.8 example.com
-```
-
-## Run benchmark over specified time
-This example will execute the benchmark in 10 parallel threads for a duration of 30 seconds while sending `example.com` DNS queries of type `A`
-to the `8.8.8.8` server
-```
-dnspyre --duration 30s -c 10 --server 8.8.8.8 google.com
-```
-
-## Sending AAAA DNS queries
-You can choose, which type of query to send to the DNS server using `-t` option, 
-```
-dnspyre -n 2 -c 10 --server 8.8.8.8 -t AAAA example.com
-```
-
-## Pass multiple hostnames
-You can pass arbitrary number of domains to be used for the DNS benchmark, by specifying more arguments, in this example domains
-`redsift.io`, `example.com`, `google.com` will be used to generate DNS queries
-```
-dnspyre -n 10 -c 10 --server 8.8.8.8 redsift.io example.com google.com
-```
-
-## Hostnames provided using file on local filesystem
-Instead of specifying hostnames as arguments to *dnspyre* tool, you can just specify file containing hostnames to be used by the tool,
-by referencing the file using `@<path-to-file>`
-```
-dnspyre -n 10 -c 10 --server 8.8.8.8 @data/2-domains
-```
-
-## Hostnames provided using file publicly available using HTTP(s) 
-The file containing hostnames does not need to be available locally, it can be also downloaded from the remote location using HTTP(s)
-```
-dnspyre -n 10 -c 10 --server 8.8.8.8 https://raw.githubusercontent.com/Tantalor93/dnspyre/master/data/2-domains
-```
-
-## Combining multiple query types in the benchmark
-Multiple DNS query types can be specified for *dnspyre* tool. 
-This can be achieved by repeating type `-t`, all queries will be made by each specified query type
-```
-dnspyre -n 10 -c 10 --server 8.8.8.8 -t A -t AAAA @data/2-domains
-```
-together with probability option this can be used for generating arbitrary random load
-```
-dnspyre -n 10 -c 10 --server 8.8.8.8 -t A -t AAAA @data/2-domains --probability 0.33
-```
-
-## IPv6 DNS server benchmarking
-DNS server address can be also provided as an IPv6 address, note the brackets format when specifying port
-```
-dnspyre -n 10 -c 10 --server '[2001:4860:4860::8888]:53' idnes.cz
-```
-
-or 
-
-```
-dnspyre -n 10 -c 10 --server '2001:4860:4860::8888' idnes.cz
-```
-
-## Using probability to randomize concurrent queries
-You can randomize queries fired by each concurrent thread by using probability lesser than 1, in this example
-roughly every third hostname from the datasource will be used by the each concurrent benchmark thread
-```
-dnspyre --duration 30s -c 10 --server 8.8.8.8  --probability 0.33  https://raw.githubusercontent.com/Tantalor93/dnspyre/master/data/1000-domains
-```
-
-## Output benchmark results as JSON
-By specifying `--json` flag, *dnspyre* can output benchmark results in a JSON format, which is better for further automatic processing
-```
-dnspyre --duration 5s --server 8.8.8.8 google.com  --json
-```
-
-example of chaining of *dnspyre* with [jq](https://stedolan.github.io/jq/) for getting pretty JSON
-```
-dnspyre --duration 5s --server 8.8.8.8 google.com --no-distribution --json | jq '.'
-```
-like this
-```
-{
-  "totalRequests": 276,
-  "totalSuccessCodes": 276,
-  "totalErrors": 0,
-  "TotalIDmismatch": 0,
-  "totalTruncatedResponses": 0,
-  "responseRcodes": {
-    "NOERROR": 276
-  },
-  "questionTypes": {
-    "A": 276
-  },
-  "queriesPerSecond": 55.18,
-  "benchmarkDurationSeconds": 5,
-  "latencyStats": {
-    "minMs": 12,
-    "meanMs": 18,
-    "stdMs": 13,
-    "maxMs": 176,
-    "p99Ms": 71,
-    "p95Ms": 33,
-    "p90Ms": 24,
-    "p75Ms": 15,
-    "p50Ms": 14
-  }
-}
-```
diff --git a/docs/graphs.md b/docs/graphs.md
@@ -9,6 +9,7 @@ parent: Examples
 Graphs are exported into the new subdirectory `graphs-<RFC3339 timestamp>` on provided path
 
 For example, this command
+
 ```
 dnspyre -d 30s -c 2 --server 8.8.8.8 --plot . https://raw.githubusercontent.com/Tantalor93/dnspyre/master/data/10000-domains
 ```