Skip to content

Commit

Permalink
updated docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@Cielquan
Cielquan committed Feb 16, 2020
1 parent 160826f commit 43a47cd
Show file tree
Hide file tree
Showing 7 changed files with 169 additions and 172 deletions.
88 changes: 5 additions & 83 deletions docs/source/api.rst
View file
Original file line number Diff line number Diff line change
@@ -1,93 +1,15 @@
.. This file 'index.rst' created 2020-01-25 is part of the project/program 'DoTH-DNS'.
.. Copyright (c) 2019-2020 Christian Riedel, see LICENSE for more details
.. highlight:: console

.. _api:

API
===

The ``start_doth_dns.bash`` script has the following options and flag you can set when calling.

You can also call the script with the ``-h`` flag for the help page::

$ ./start_doth_dns.bash -h

Options
-------

* ``-f``:

If set then old configuration settings saved in ``.env`` file will not be loaded
and a new ``root.hints`` file will be downloaded.

* ``-F``:

Set to let the script fallback to next source for configuration variables.
Order: `flag -> environment -> .env file -> self gather`

* ``-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.

* ``-I``:

Set the network interface used from the server. Needed for determining the right
IP address. If not set script will determine it.

* ``-i``:

Set the IP address used by the server. If not set script will determine it with
determined oder given ``INTERFACE`` (via e.g. ``-I`` option).

* ``-n``:

Set hostname of the host machine. If not set script will determine it.

* ``-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.

* ``-d``:

Set domain the server is reachable under. If not set created by script: '``HOST_NAME``.dns'.

* ``-N``:

Set to deactivate ``traefik`` dashboard authorization when ``.htpasswd`` file is given.

* ``-h``:

Show help page and exit.


Flags
-----

* ``-R``:

Set to recreate all containers. Containers will load new config files if given.

* ``-U``:

Set to recreate and update all containers.

* ``-P``:

Set to start without reverse proxy ``traefik``.

* ``-D``:

Set to shut DoTH-DNS down. It will remove all DoTH-DNS containers and networks.
This part of the documentation covers the CLI interface and
is autogenerated by sphinx-click extension.


.. highlight:: default
.. click:: dothdns.cli:main
:prog: dothdns
:show-nested:
2 changes: 1 addition & 1 deletion docs/source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@
extensions = [
"sphinx_rtd_theme",
"sphinx.ext.intersphinx",
"sphinx.ext.autodoc",
"sphinx_click.ext",
]

intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)}
Expand Down
23 changes: 12 additions & 11 deletions docs/source/external_help.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,16 @@ Get Help

Here are some external links for further help:

* Pi-hole `documentation <https://docs.pi-hole.net/>`__
* Pi-hole image `documentation <https://github.com/pi-hole/docker-pi-hole/blob/master/README.md>`__
* Unbound `documentation <https://www.nlnetlabs.nl/documentation/unbound/>`__
* Unbound image `documentation <https://github.com/MatthewVance/unbound-docker-rpi/blob/master/README.md>`__
* traefik `documentation <https://docs.traefik.io/v2.0/>`__
* dns-over-https `documentation <https://github.com/m13253/dns-over-https/blob/master/Readme.md>`__
* dns-over-https image `documentation <https://github.com/goofball222/dns-over-https/blob/master/README.md>`__
* Docker `documentation <https://docs.docker.com/>`__
* Docker-compose `documentation <https://docs.docker.com/compose/>`__
* Pi-hole `documentation <https://docs.pi-hole.net>`__
* Pi-hole image `documentation <https://github.com/pi-hole/docker-pi-hole>`__
* Unbound `documentation <https://www.nlnetlabs.nl/documentation/unbound>`__
* Unbound image `documentation <https://github.com/MatthewVance/unbound-docker-rpi>`__
* traefik `documentation <https://docs.traefik.io/v2.1>`__
* dns-over-https `documentation <https://github.com/m13253/dns-over-https>`__
* dns-over-https image `documentation <https://github.com/goofball222/dns-over-https>`__
* Docker `documentation <https://docs.docker.com>`__
* Similar project - `link <https://github.com/chriscrowe/docker-pihole-unbound>`__
* Pi-hole blog post about slow loading sides and blocking QUIC protocol - `link <https://pi-hole.net/2018/02/02/why-some-pages-load-slow-when-using-pi-hole-and-how-to-fix-it/>`__
* Pi-hole guide about pi-hole+unbound - `link <https://docs.pi-hole.net/guides/unbound/>`__
* Pi-hole blog post about slow loading sides and blocking QUIC protocol - `link <https://pi-hole.net/2018/02/02/why-some-pages-load-slow-when-using-pi-hole-and-how-to-fix-it>`__
* Pi-hole guide about pi-hole+unbound - `link <https://docs.pi-hole.net/guides/unbound>`__
* Blog post realizing a similar construct - `link <https://www.aaflalo.me/2018/10/tutorial-setup-dns-over-https-server>`__
* Another blog post realizing a similar construct - `link <https://www.bentasker.co.uk/documentation/linux/407-building-and-running-your-own-dns-over-https-server>`__
50 changes: 32 additions & 18 deletions docs/source/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,33 +10,34 @@ Welcome to DoTH-DNS's documentation!

.. include:: badges.rst

Utilizes the power of `pi-hole <https://pi-hole.net>`_ and
`unbound <https://www.nlnetlabs.nl/projects/unbound/about>`_
to create a DNS server under your own authority but with the ability to use
DoH (`DNS over HTTPS <https://en.wikipedia.org/wiki/DNS_over_HTTPS>`_) and
DoT (`DNS over TLS <https://en.wikipedia.org/wiki/DNS_over_TLS>`_).
Utilizes the power of the DNS sinkhole `pi-hole`_ and `unbound`_
to create a DNS server under your own authority but with the ability to connect via
Do53 (default, unencrypted), DoH (`DNS over HTTPS`__) and DoT (`DNS over TLS`__).

__ https://en.wikipedia.org/wiki/DNS_over_HTTPS
__ https://en.wikipedia.org/wiki/DNS_over_TLS


Description
-----------
This project's goal is setup a DNS server inside docker with the option to connect via DoH or DoT.
Therefor pi-hole, unbound, traefik and a `DoH-server <https://github.com/m13253/dns-over-https>`__ are utilized.
This project's goal is setup a recursive DNS server inside docker with the option to also connect via DoH or DoT.
Therefor `pi-hole`_, `unbound`_, `traefik`__ and a `DoH-server`__ are utilized.

You may ask 'Why use DoH or DoT for an local DNS server?'. Good question! I set this up
because firefox needs you to use DoH if you want to use `ESNI
<https://en.wikipedia.org/wiki/Server_Name_Indication>`__. The DoT support was just some lines
because firefox needs you to use DoH if you want to use `ESNI`__. The DoT support was just some lines
of code more so I did it also.

The docker-compose file creates a bridge network and the following containers:
``pi-hole/pi-hole``, ``mvance/unbound``, ``traefik``, ``goofball222/dns-over-https``.
You could also run the stack in a cloud (not tested) and connect there via DoH/DoT.

Query forwarding:

* Normal DNS query: port 53 -> pihole -> unbound
* Do53 query: port 53 -> pihole -> unbound
* DoT query: port 853 -> traefik -> pihole -> unbound
* DoH query: port 443 -> traefik -> DoH-server -> pihole -> unbound
* pihole dashboard query: port 80/443 -> traefik -> pihole
* traefik dashboard query: port 80/443 -> traefik

__ https://docs.traefik.io/
__ https://github.com/m13253/dns-over-https
__ https://en.wikipedia.org/wiki/Server_Name_Indication


Project name origin
Expand All @@ -51,11 +52,24 @@ because it `does DNS` (see slogan at top).

Acknowledgements
----------------
Thanks to the creators of docker, pi-hole, unbound, traefik and 'dns-over-https' for their awesome software.
Also thanks you to the maintainers of the images.

Thanks to the creator of this `docker-pihole-unbound <https://github.com/chriscrowe/docker-pihole-unbound>`__
project which inspired me.
Thanks to the creators, maintainers and developers of the software used in this project.

Special thanks to:

- the `dns-over-https`__ project and its `docker version`__.
- the `docker-pihole-unbound`__ project for the inspiration.
- this `blog post`__ and this `blog post`__ being the first foundation of this project.

__ https://github.com/m13253/dns-over-https
__ https://github.com/goofball222/dns-over-https
__ https://github.com/chriscrowe/docker-pihole-unbound
__ https://www.aaflalo.me/2018/10/tutorial-setup-dns-over-https-server
__ https://www.bentasker.co.uk/documentation/linux/407-building-and-running-your-own-dns-over-https-server


.. _pi-hole: https://pi-hole.net
.. _unbound: https://www.nlnetlabs.nl/projects/unbound/about


.. toctree::
Expand Down
26 changes: 16 additions & 10 deletions docs/source/installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,24 +13,30 @@ Prerequisites
Your machine needs to match the following conditions:

* Have a static IP
* Have git, docker and docker-compose installed
* Have python >= 3.6 + pip and docker installed
* Have valid SSL certificate (cert.crt) and matching key (key.key)


Installation
------------
A true installation is not directly supported yet.

You just need to download the `Git repository`__.
Then put your SSL certificate files
Afterwards you can just call ``start_doth_dns.bash`` script::
Installation from source
------------------------
DoTH-DNS can be install directly from a clone of the `Git repository`__. You can either
clone the repo and install the local clone::

$ git clone https://github.com/Cielquan/DoTH-DNS.git
$ cd DoTH-DNS
$ chmod +x start_doth_dns.bash menu_start_doth_dns.bash
$ ./start_doth_dns.bash
$ pip install .

or install it directly via :command:`git`::

$ pip install git+https://github.com/Cielquan/DoTH-DNS.git

You can also grab the repo in either `tar.gz`__ or `zip`__ format.
After downloading and extracting you can install it with :command:`pip` like above.


.. highlight:: default


__ https://github.com/Cielquan/DoTH-DNS
__ https://github.com/Cielquan/DoTH-DNS/archive/master.tar.gz
__ https://github.com/Cielquan/DoTH-DNS/archive/master.zip
Loading

0 comments on commit 43a47cd

Please sign in to comment.