Updated README + linked documentation. Also added some comments to co…

…nfig fields.

Cargo.toml

@@ -3,7 +3,7 @@ name = "dns_dropper"
 version = "0.0.1"
 edition = "2021"
 authors = ["kalev gonvick <[email protected]>"]
-description = "DNS"
+description = "Customizable light-weight DNS proxy with domain filtering capabilities."
 license = "MIT"
 readme = "README.md"
 
@@ -19,7 +19,6 @@ keywords = [
     "udp"
 ]
 
-
 [profile.release]
 lto = true
 codegen-units = 1

README.md

@@ -1,16 +1,17 @@
 <img src="./docs/dns_dropper_banner01.png" alt="DNSDropper">
 
 ## What is it?
-DNSDropper is a tool for anyone looking for a light-weight dns proxy with filtering capabilities. Like blocking ads! It works by being a proxy in-between you and your normal DNS service, filtering any DNS requests for domains in your black list.
+_DNSDropper_ is a tool for anyone looking for a light-weight dns proxy with filtering capabilities (Like blocking ads!).  
+It works by being a proxy in-between you and your normal DNS service, filtering any DNS requests to domains specified in your black list.
 
 ## How to configure
-DNSDropper uses in a single configuration file that is divided up by major features: server, udp_proxy, and logging. You can find a breakdown of each feature below.
+_DNSDropper_ uses in a single configuration file that is divided up by major features: _server_, _udp_proxy_, and _logging_. You can find a breakdown of each feature below.
 
-| Section Name |            Description            |                    Breakdown Link                    |
-|:------------:|:---------------------------------:|:----------------------------------------------------:|
-|    server    | Configure the DNSDropper runtime. |  [server breakdown](docs/config.section.server.md)   |
-|  udp_proxy   |     Configure DNS filtering.      | [server breakdown](docs/config.section.udp_proxy.md) |
-|   logging    |     Configure logging output.     |  [server breakdown](docs/config.section.logging.md)  |
+|  Section Name | Description                       |                   Documentation Link                    |
+|--------------:|:----------------------------------|:-------------------------------------------------------:|
+|    **server** | Configure the DNSDropper runtime. |    [server breakdown](docs/config.section.server.md)    |
+| **udp_proxy** | Configure DNS filtering.          | [udp_proxy breakdown](docs/config.section.udp_proxy.md) |
+|   **logging** | Configure logging output.         |   [logging breakdown](docs/config.section.logging.md)   |
 
 You can also find examples of different configurations under the ```test/``` folder.
 
@@ -20,10 +21,3 @@ You can also find examples of different configurations under the ```test/``` fol
    2. ```config/server.yaml``` is the default if no arguments are provided.
 2. Configure your machines DNS to point to the locally running dns_dropper.
 3. All DNS requests should now be filtered to your specification!
-
-## How to develop
-// TODO
-
-## How to contribute
-// TODO
-

config/internal.yaml

@@ -1,4 +1,10 @@
 # Config constants internal systems
+
+# default config directory
 default_server_config_dir: "config/server.yaml"
+
+# max udp packet size
 max_udp_packet_size: 4096
+
+# worker name prefix displayed in logs
 worker_thread_name: "WT"

docs/config.section.logging.md

@@ -0,0 +1,11 @@
+# Logging Options
+
+## Overview
+This document covers all logging options available for the DnsDropper config file.
+
+## Options
+
+| Property |  Type   |                              Description                               | Example     |
+|:--------:|:-------:|:----------------------------------------------------------------------:|:------------|
+|  level   | String  | Select the level for runtime logging. (TRACE\DEBUG\INFO\WARNING\ERROR) | ```trace``` |
+| enabled  | Boolean |                   Enable/disable logging altogether.                   | ```true```  |

docs/config.section.server.md

@@ -0,0 +1,10 @@
+# Server Options
+
+## Overview
+This document covers all server options available for the DnsDropper config file.
+
+## Options
+
+|      Property       |  Type   |                         Description                          | Example |
+|:-------------------:|:-------:|:------------------------------------------------------------:|:--------|
+| worker_thread_count | Integer | Choose the number of (hardware) threads the server will use. | ```4``` |

docs/config.section.udp_proxy.md

@@ -0,0 +1,40 @@
+# Proxy Options
+
+## Overview
+This document covers all server options available for the DnsDropper config file.
+
+## Options
+
+|        Property        |     Type     | Description                                                                                                                                                                                                                                                                                           | Example                            |
+|:----------------------:|:------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------|
+|      **timeout**       |   Integer    | Choose the proxy timeout(ms).                                                                                                                                                                                                                                                                         | ```2000```                         |
+|        **bind**        |    String    | Choose the bind of the udp proxy. Most of the time it will either be 0.0.0.0:53 for external and 127.0.0.1:53 for loopback configurations. The port number *must* be included in the definition.                                                                                                      | ```127.0.0.1:53```                 |
+|     **dns_hosts**      | List(String) | Specify any number of DNS hosts you want to proxy DNS requests to.  The port number *must* be included in each definition.                                                                                                                                                                            | ```["8.8.8.8:53", "1.1.1.1:53"]``` |
+| **domain_block_lists** | List(String) | Specify any number of resources to grab block lists from. It can be any type of resource url (http, file, etc.). The content of these resources *must* be in the format ```<ip>\s<domain>\n```. Domains loaded from multiple resources that contain the same domains will be deduplicated on startup. | ```["8.8.8.8:53", "1.1.1.1:53"]``` |
+
+## Example Configurations
+
+### 
+```yaml
+...
+udp_proxy:
+
+  # Set a timeout of 2000ms
+  timeout: 2000
+
+  # Bind a loopback to the current machine on port 53.
+  bind: "127.0.0.1:53"
+
+  # Set the DNS destinations
+  dns_hosts:
+    - "8.8.8.8:53"
+    - "8.8.4.4:53"
+    - "1.0.0.1:53"
+    - "1.1.1.1:53"
+
+  # Add an external and local resource for our block list.
+  domain_block_lists:
+    - https://raw.githubusercontent.com/blocklistproject/Lists/master/ads.txt
+    - test/config/local_block_list.txt
+...
+```