From 3e649ab5d7922a70263c2f25b366b7d4282e2dd3 Mon Sep 17 00:00:00 2001
From: Amir Zarrinkafsh <nightah@me.com>
Date: Fri, 15 Jan 2021 08:48:31 +1100
Subject: [PATCH] Add README.md for DNS generation scripts
Also fix up some typos in the main README.md.
---
README.md | 10 +++++-----
scripts/README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 54 insertions(+), 5 deletions(-)
create mode 100755 scripts/README.md
diff --git a/README.md b/README.md
index ffb506d..20ae7c9 100755
--- a/README.md
+++ b/README.md
@@ -11,13 +11,13 @@ You can use this list one of two ways:
- Overriding DNS for these hostnames to point to the IP of your cache server.
- Use them in Squid with WCCP to redirect content to the right cache server.
-There is a cache_domains.json file to define CDNs and additional meta deta with the following structure
+There is a cache_domains.json file to define CDNs and additional metadata with the following structure
- cache_domains: Array of cache_domain object
- name: shortname for the cache domain. Should match `^[0-9A-Za-z]$`
- description: a longer description to aid others in identifying what this domain does (not all users of this repo will want to enable all caches)
- notes: implementation specific notes which may be useful for other users
- - domain_files: array of files within the repo assosciated to the cdn. Most cdn's only need one file
+ - domain_files: array of files within the repo associated to the cdn. Most CDNs only need one file
- Example domain entry for steam
```json
{
@@ -35,7 +35,7 @@ There is a cache_domains.json file to define CDNs and additional meta deta with
There is a separate file for each cacheable service. Some notes on formatting:
- - Every line should be a seperate hostname for that service.
+ - Every line should be a separate hostname for that service.
- Only one entry is permitted per line.
- Wildcards are permitted as per below
- Lines starting with a # will be treated as a comment.
@@ -46,10 +46,10 @@ There is a separate file for each cacheable service. Some notes on formatting:
The wildcard format shall be defined as per the below
- - Wildcards should be represented with an asterix.
+ - Wildcards should be represented with an asterisk.
- If a wildcard is used, it should be the first character on the line.
- Wildcards are not treated as matching null, e.g. `*.example.com` will match `a.example.com` but will not match `example.com`
- - Only simple domain wildcards will be accepted eg `*.example.com` not `*ww.example.com`
+ - Only simple domain wildcards will be accepted e.g. `*.example.com` not `*ww.example.com`
##### Notes for Squid users
diff --git a/scripts/README.md b/scripts/README.md
new file mode 100755
index 0000000..32f3757
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,49 @@
+# DNS Generation Scripts
+
+## Introduction
+
+The respective shell scripts contained within this directory can be utilised to generate application specific compliant
+configuration which can be utilised with:
+
+* Dnsmasq
+* Unbound
+
+## Usage
+
+1. Copy `config.example.json` to `config.json`.
+2. Modify `config.json` to include your Cacheserver's IP(s) and the CDNs you plan to cache.
+ The following example assumes a single shared Cacheserver IP:
+```json
+{
+ "ips": {
+ "generic": ["10.10.10.200"]
+ },
+ "cache_domains": {
+ "blizzard": "generic",
+ "epicgames": "generic",
+ "nintendo": "generic",
+ "origin": "generic",
+ "riot": "generic",
+ "sony": "generic",
+ "steam": "generic",
+ "uplay": "generic",
+ "wsus": "generic"
+ }
+}
+```
+3. Run generation script relative to your DNS implementation: `bash create-dnsmasq.sh`.
+4. Copy files from `output/{dnsmasq,unbound}/*` to the respective locations for Dnsmasq/Unbound.
+5. Restart Dnsmasq or Unbound.
+
+### Notes for Dnsmasq users
+
+**This also applies to users utilising the script alongside Pi-hole.**
+
+If utilising the `create-dnsmasq.sh` the generation script will create a `lancache.conf` which also loads in the respective `*.hosts` files.
+
+The `lancache.conf` should be copied into the `/etc/dnsmasq.d/` location but also will need to be modified to point to the respective location of the `*.hosts` files.
+
+You can copy the `*.hosts` file to any location other than `/etc/dnsmasq.d/` as this location is utilised only for `*.conf` files.
+
+For example if utilising Pi-hole a user can copy the `*.hosts` files to `/etc/pihole/` and modify the `lancache.conf` with the following command, prior to copying it to `/etc/dnsmasq.d/`:
+`sed -i 's/dnsmasq.d/pihole/g' output/dnsmasq/lancache.conf`
\ No newline at end of file