From 490a72a0dfd25ec88fe76535edf6ea7724fed556 Mon Sep 17 00:00:00 2001 From: Cielquan <> Date: Sun, 17 Nov 2019 22:33:16 +0100 Subject: [PATCH] updated README --- README.md | 150 ++++++++++++++++-------------------------------------- 1 file changed, 45 insertions(+), 105 deletions(-) diff --git a/README.md b/README.md index df15af9..7a13e51 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,6 @@ to create a DNS server under your own authority but with the abillity to use DoH ## Disclaimer -Currently still work in progress. Use at own risk. This project is made for linux. I run it on my raspberry pi 3b+ with raspbian buster lite. @@ -38,145 +37,86 @@ Query forwarding: Your machine needs to match the following conditions: * Have a static IP * Have `git`, `docker` and `docker-compose` installed -* Have valid SSL certificate (`*.crt`) and matching key (`*.key`) +* Have valid SSL certificate (`cert.crt`) and matching key (`key.key`) * Have a `dhparam.pem` file -### Setup +### Quick setup Here I show my way of setting the server (RasPi) up via SSH. Your mileage may vary. -Given paths are relative to this repositories root. +Given paths are relative to this repositories root. #### 1. Get this repo and make configs -Firstly clone this repo to your SSH machine - -##### 1.1 SSL certificate files -* copy your SSL `*.crt` file to 'certificates/certs/' -* copy your SSL `*.key` file to 'certificates/private/' -* copy your `dhparam.pem` file to 'certificates/' - -##### 1.2 pihole config files -You may also add the following files to 'pihole-docker/configs/pihole/': -* `adlists.list` - list of all blocklists -* `blacklist.txt` - blacklisted URLs except URLs from blocklists -* `lan.list` - list of addresses for local network _(added by `setup.sh` script)_ -* `whitelist.txt` - list of all whitelisted URLs - -##### 1.3 setup.conf file -You can add a 'setup.conf' file at '/' with the following parameters. Every variable not set in this file will be gathered -from the system. See [Variable Notes](https://github.com/Cielquan/DoTH-DNS#variable-notes) below for more information. -* `FRESH` -* `ARCHITECTURE` -* `COMPILE` -* `INTERFACE` -* `HOST_IP` -* `HOST_NAME` -* `TIMEZONE` -* `DOMAIN` - -##### 1.4 server.conf file -You can add a 'server.conf' file in 'pihole-docker/configs/' directory with parameters listed -[here](https://github.com/pi-hole/docker-pi-hole#environment-variables). -However this is not recommended because the `setup.sh` script will create it for you (rather set given variables in 'setup.conf'). -`ServerIP` and `TZ` are mandatory. -`DNS1` and `DNS2` are set in default.conf, but are overwritten by server.conf if set. - -##### 1.5 .env file -You can add a '.env' file to '/' with variables used by 'docker-compose.yaml' file (listed below) . -However this is not recommended because the `setup.sh` script will create it for you (rather set given variables in 'setup.conf'). -* `HOSTNAME` -* `TZ` - -#### 2. Send files to server -Now your setup is done and you can move the files to your server. +First clone this repo to your local machine. - $ scp -r ~/DoTH-DNS/ pi@192.168.0.1:~ +#### 2. Add custom files + +##### 2.1. SSL certificate files +Copy your `cert.crt`, `key.key` and `dhparam.pem` files to 'certificates/'. -Copies the repo from your home directory to the directory of the server. You need to alter the user, IP and paths to your parameters. +##### 2.2. .httpasswd file +To secure your traefik dashboard add a `.htpasswd` file to 'traefik-docker/shared/' containing a user-password-string following htpasswd standard. This is optional. -#### 3. run the scripts -Now cd into the repo on the server via SSH and first start the setup script. You can also start the script without sudo, but for the compiling part (when compiling) -root privileges are needed. The script supports flags see -[Variable Notes](https://github.com/Cielquan/DoTH-DNS#variable-notes) below for more information. +#### 3. Send files to server +When your setup is done and you can send the files to your server. - $ ./setup.sh + $ scp -r ~/DoTH-DNS/ pi@192.168.0.1:~ -After the script finished successfully you can start the `run.sh` script to actually start the docker containers. -You may need to start the script with sudo, because the docker daemon needs root privileges. The script supports flags run `$ ./run.sh -h` to see the help page. +Copies the repo from your home directory to the directory of the server. You need to alter the user, IP and paths to your parameters! - $ ./run.sh +#### 4. Run the `start_doth_dns.bash` script +Now cd into the repo on the server via SSH and start the `start_doth_dns.bash` script. Depending on the settings on your server you may need to start the script with `sudo` +because for docker root privileges are needed. The script supports flags. Information regarding available flag you can find below. -Instead of the `run.sh` script you can also run `docker-compose up -d`. -The script does the same, but it also outputs information about the status of the single containers till they are done booting and setting up. + $ ./start_doth_dns.bash -#### 4. Secure your pihole dashboard -If you have not set the '`WEBPASSWORD` variable in `server.conf` file (not recommended) you should now set a secure password for your pihole dashboard or deactivate it. +#### 5. Secure your pihole dashboard +If you have not set the `WEBPASSWORD` environment variable on your server you should now set a secure password for your pihole dashboard or deactivate it. - $ docker exec pihole -a -p + $ docker exec pihole -a -p -_The `run.sh` script also reminds you if a random password was generated from pihole._ +_The script also reminds you if a random password was generated from pihole._ -#### 5. Use the new DNS server +#### 6. Use the new DNS server Now you can setup your other devices to use the server. You may also install your CA certificate on your other devices. -### Variable Notes -Here are some explanations for above mentioned variables. The variables can also be set as flags when calling `setup.sh`. -Run `$ ./setup.sh -h` to see the help page. Flags overwrite variables from 'setup.conf'. -`FRESH` (flag: `-f`): -If set to 'y' then all configuration files are overwritten with new ones. +### Config flag notes +Here is an overview of the available flags for setup when calling the script. Run `-h` flag for help on commandline. + +* `-f`): If set then old configuration settings saved in `.env` file will not be loaded and a new `root.hints` file will be downloaded. + +* `-a`): Set Architecture of the processor ('arm' or 'x86') used by the server. Needed for determining the right docker images. If not set script will determine it. + +* `-c`): Set to force `goofball222/dns-over-https` docker image to be compiled. If not set then the `ARCHITECTURE` determines if the image will be compiled +('arm' -> yes; 'x86' -> no). Will only be compiled if non existing. -`ARCHITECTURE` (flag: `-a`): -If not set, gathered and printed by `setup.sh` script. -Architecture of the processor ('arm' or 'x86') used by the server. -Needed for determining the right docker images. +* `-I`): Set the network interface used from the server. Needed for determining the right IP address. If not set script will determine it. -`COMPILE` (flag: `-c`): -Determines if the 'goofball222/dns-over-https' image will rather be compiled than downloaded. -The image on docker hub is not compatible with ARM processors. -Can be set to 'n' to completely disable the compile part or set to 'y' for always compiling the image. -If not set then the `ARCHITECTURE` determines if the image will be compiled ('arm' -> yes; 'x86' -> no). +* `-i`): Set the IP address used by the server. If not set script will determine it with determined oder given (via `-I` flag) `INTERFACE`. -`INTERFACE` (flag: `-I`): -If not set, gathered and printed by `setup.sh` script. -The network interface used for the server. +* `-n`): Set hostname of the host machine. If not set script will determine it. -`HOST_IP` (flag: `-i`): -If not set, gathered and printed by `setup.sh` script. -IP used with the `INTERFACE`. +* `-t`): Set timezone the server is in. Used for e.g. daily resets. Format is like 'Europe/London'. If not set script will determine it. -`HOST_NAME` (flag: `-n`): -If not set, gathered and printed by `setup.sh` script. -Name of the host machine `$ hostname`. +* `-d`): Set domain the server is reachable under. If not set created by script: '`HOST_NAME`.dns'. -`TIMEZONE` (flag: `-t`): -If not set, gathered and printed by `setup.sh` script. -Timezone the server is in. Used for e.g. daily resets. -Format is like 'Europe/London'. +* `-N`): Set to deactivate traefik dashboard authorization when `.htpasswd` file is given. -`DOMAIN` (flag: `-d`): -If not set created by `setup.sh` script: '`HOST_NAME`.dns'. -### Update -If you want to update container with a newer image run following commands on your server while inside the repository directory _(via SSH)_. +### Run flag notes +Here is an overview of the available flags for running when calling the script. Run `-h` flag for help on commandline. -_But be wary of the need to compile the `goofball222/dns-over-https` image yourself for 'ARM' processors!_ +* `-R`): Set to recreate all containers. Containers will load new config files if given. -Single container: +* `-U`): Set to recreate and update all containers. - $ docker stop CONTAINER && docker rm CONTAINER - $ docker-compose pull CONTAINER - $ ./run.sh +* `-p`): Set with either `traefik` or `nginx` to use either reverse proxy. Default: `traefik` -All containers: - - $ docker-compose down - $ docker-compose pull - $ ./run.sh +* `-P`): Set to start without a reverse proxy. Overwrites `-p` flag. ### Reverse proxy You have three options for the reverse proxy. None, the old one `ngnix` and the new one `traefik`. -Traefik 2.0 is used which is currently in beta. -If you want to use none you have to set the flag `-P` when running the `run.sh` script. For setting `nginx` or `traefik` +If you want to use none you have to set the flag `-P` when running the script. For setting `nginx` or `traefik` you have to set the flag `-p` followed by `ngnix` or `traefik` (case insensitive). The latter is the default. Currently traefik does not work solo. I am working on getting the DoT part to work.