Skip to content

Commit

Permalink
updated README
Browse files Browse the repository at this point in the history
  • Loading branch information
Cielquan committed Nov 17, 2019
1 parent 0c80156 commit 490a72a
Showing 1 changed file with 45 additions and 105 deletions.
150 changes: 45 additions & 105 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.


Expand Down Expand Up @@ -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 <PASSWORD>

_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.
Expand Down

0 comments on commit 490a72a

Please sign in to comment.