Merge pull request #237 from cytopia/documentation-dns

Release v0.13.1 (Communicate with external hosts)

.devilbox/www/config.php

@@ -13,8 +13,8 @@
 putenv('RES_OPTIONS=retrans:1 retry:1 timeout:1 attempts:1');
 
 
-$DEVILBOX_VERSION = 'v0.13';
-$DEVILBOX_DATE = '2018-04-14';
+$DEVILBOX_VERSION = 'v0.13.1';
+$DEVILBOX_DATE = '2018-04-28';
 $DEVILBOX_API_PAGE = 'devilbox-api/status.json';
 
 //

docker-compose.yml

@@ -34,29 +34,57 @@ services:
   # Bind (DNS Server)
   # ------------------------------------------------------------
   bind:
-    image: cytopia/bind:0.11
+    image: cytopia/bind:0.15
     restart: always
     ports:
       # [local-machine:]local-port:docker-port
-      - "${LOCAL_LISTEN_ADDR}${HOST_PORT_BIND:-1053}:53"
+      - "${LOCAL_LISTEN_ADDR}${HOST_PORT_BIND:-1053}:53/tcp"
       - "${LOCAL_LISTEN_ADDR}${HOST_PORT_BIND:-1053}:53/udp"
 
     environment:
       ##
       ## Debug?
       ##
-      - DEBUG_COMPOSE_ENTRYPOINT
+      - DEBUG_ENTRYPOINT=${DEBUG_COMPOSE_ENTRYPOINT}
+
+      ##
+      ## Bind wildcard/host settings
+      ##
+      - WILDCARD_DNS=${TLD_SUFFIX:-loc}=172.16.238.11
+      - EXTRA_HOSTS=${EXTRA_HOSTS}
 
       ##
-      ## Bind settings
+      ## Forwarding
       ##
-      - WILDCARD_DOMAIN=${TLD_SUFFIX:-loc}
-      - WILDCARD_ADDRESS=172.16.238.11
       - DNS_FORWARDER=${BIND_DNS_RESOLVER:-8.8.8.8,8.8.4.4}
 
+      ##
+      ## Security
+      ##
+      - DNSSEC_VALIDATE=${BIND_DNSSEC_VALIDATE:-no}
+
+      ##
+      ## Time settings
+      ##
+      - TTL_TIME=${BIND_TTL_TIME}
+      - REFRESH_TIME=${BIND_REFRESH_TIME}
+      - RETRY_TIME=${BIND_RETRY_TIME}
+      - EXPIRY_TIME=${BIND_EXPIRY_TIME}
+      - MAX_CACHE_TIME=${BIND_MAX_CACHE_TIME}
+
+      ##
+      ## Query log
+      ##
+      - DOCKER_LOGS=${BIND_LOG_DNS_QUERIES}
+
     dns:
       - 127.0.0.1
 
+    # MacOS and Windows have this by default, this hack also allows it for Linux
+    extra_hosts:
+      docker.for.lin.host.internal: 172.16.238.1
+      docker.for.lin.localhost: 172.16.238.1
+
     networks:
       app_net:
         ipv4_address: 172.16.238.100
@@ -114,15 +142,18 @@ services:
       - MYSQL_BACKUP_PASS=${MYSQL_ROOT_PASSWORD}
       - MYSQL_BACKUP_HOST=mysql
 
+    dns:
+      - 172.16.238.100
+
+    # MacOS and Windows have this by default, this hack also allows it for Linux
+    extra_hosts:
+      docker.for.lin.host.internal: 172.16.238.1
+      docker.for.lin.localhost: 172.16.238.1
+
     networks:
       app_net:
         ipv4_address: 172.16.238.10
 
-    dns:
-      - 172.16.238.100
-      - 8.8.8.8
-      - 8.8.4.4
-
     volumes:
       # ---- Format: ----
       # HOST-DIRECTORY : DOCKER-DIRECTORY

docs/configuration-files/env-file.rst

@@ -245,6 +245,76 @@ this project visible to everyone in your corporate LAN.
     and
     `Docker Release notes <https://docs.docker.com/docker-for-mac/release-notes/#docker-community-edition-17120-ce-mac46-2018-01-09>`_
 
+.. _env_extra_hosts:
+
+EXTRA_HOSTS
+-----------
+
+This variable allows you to add additional DNS entries from hosts outside the Devilbox network,
+such as hosts running on your host operating system, the LAN or from the internet.
+
++-----------------+------------------------------+---------------+
+| Name            | Allowed values               | Default value |
++=================+==============================+===============+
+| ``EXTRA_HOSTS`` | comma separated host mapping | empty         |
++-----------------+------------------------------+---------------+
+
+Adding hosts can be done in two ways:
+
+1. Add DNS entry for an IP address
+2. Add DNS entry for a hostname/CNAME which will be mapped to whatever IP address it will resolve
+
+
+The general structure to add extra hosts looks like this
+
+.. code-block:: bash
+
+    # Single host
+    EXTRA_HOSTS='hostname=1.1.1.1'
+    EXTRA_HOSTS='hostname=CNAME'
+
+    # Multiple hosts
+    EXTRA_HOSTS='hostname1=1.1.1.1,hostname2=2.2.2.2'
+    EXTRA_HOSTS='hostname1=CNAME1,hostname2=CNAME2'
+
+* The left side represents the name by which the host will be available by
+* The right side represents the IP address by which the new name will resolve to
+* If the right side is a CNAME itself, it will be first resolved to an IP address and then the left side will resolve to that IP address.
+
+A few examples for adding extra hosts:
+
+.. code-block:: bash
+
+    # 1. One entry:
+    # The following extra host 'loc' is added and will always point to 192.168.0.7.
+    # When reverse resolving '192.168.0.7' it will answer with 'tld'.
+    EXTRA_HOSTS='loc=192.168.0.7'
+
+    # 2. One entry:
+    # The following extra host 'my.host.loc' is added and will always point to 192.168.0.9.
+    # When reverse resolving '192.168.0.9' it will answer with 'my.host'.
+    EXTRA_HOSTS='my.host.loc=192.168.0.9'
+
+    # 3. Two entries:
+    # The following extra host 'tld' is added and will always point to 192.168.0.1.
+    # When reverse resolving '192.168.0.1' it will answer with 'tld'.
+    # A second extra host 'example.org' is added and always redirects to 192.168.0.2
+    # When reverse resolving '192.168.0.2' it will answer with 'example.org'.
+    EXTRA_HOSTS='tld=192.168.0.1,example.org=192.168.0.2'
+
+    # 4. Using CNAME's for resolving:
+    # The following extra host 'my.host' is added and will always point to whatever
+    # IP example.org resolves to.
+    # When reverse resolving '192.168.0.1' it will answer with 'my.host'.
+    EXTRA_HOSTS='my.host=example.org'
+
+.. seealso::
+
+    This resembles the feature of `Docker Compose: extra_hosts <https://docs.docker.com/compose/compose-file/#external_links>`_ to add external links.
+
+.. seealso:: :ref:`communicating_with_external_hosts`
+
+
 .. _env_new_uid:
 
 NEW_UID
@@ -1335,12 +1405,123 @@ Auto-DNS) in order to resolve custom project domains defined by ``TLD_SUFFIX``.
 To also be able to reach the internet from within the Container there must be some kind of
 upstream DNS server to ask for queries.
 
+Some examples:
+
+.. code-block:: bash
+
+    BIND_DNS_RESOLVER='8.8.8.8'
+    BIND_DNS_RESOLVER='8.8.8.8,192.168.0.10'
+
+
 .. note::
     If you don't trust the Google DNS server, then set it to something else.
     If you already have a DNS server inside your LAN and also want your custom DNS (if any)
     to be available inside the containers, set the value to its IP address.
 
 
+BIND_DNSSEC_VALIDATE
+^^^^^^^^^^^^^^^^^^^^
+
+This variable controls the DNSSEC validation of the DNS server. By default it is turned off.
+
++--------------------------+--------------------------------------+---------------------+
+| Name                     | Allowed values                       | Default value       |
++==========================+======================================+=====================+
+| ``BIND_DNSSEC_VALIDATE`` | ``no``, ``auto``, ``yes``            | ``no``              |
++--------------------------+--------------------------------------+---------------------+
+
+* ``yes`` - DNSSEC validation is enabled, but a trust anchor must be manually configured. No validation will actually take place.
+* ``no`` - DNSSEC validation is disabled, and recursive server will behave in the "old fashioned" way of performing insecure DNS lookups, until you have manually configured at least one trusted key.
+* ``auto`` - DNSSEC validation is enabled, and a default trust anchor (included as part of BIND) for the DNS root zone is used.
+
+BIND_LOG_DNS
+^^^^^^^^^^^^
+
+This variable controls if DNS queries should be shown in Docker log output or not. By default no
+DNS queries are shown.
+
++--------------------------+------------------------+---------------------+
+| Name                     | Allowed values         | Default value       |
++==========================+========================+=====================+
+| ``BIND_LOG_DNS``         | ``1`` or ``0``         | ``0``               |
++--------------------------+------------------------+---------------------+
+
+If enabled all DNS queries are shown. This is useful for debugging.
+
+
+BIND_TTL_TIME
+^^^^^^^^^^^^^
+
+This variable controls the DNS TTL in seconds. If empty or removed it will fallback to a sane default.
+
++--------------------------+----------------------+---------------------+
+| Name                     | Allowed values       | Default value       |
++==========================+======================+=====================+
+| ``BIND_TTL_TIME``        | integer              | empty               |
++--------------------------+----------------------+---------------------+
+
+.. seealso::
+
+    * `BIND TTL <http://www.zytrax.com/books/dns/apa/ttl.html>`_
+    * `BIND SOA <http://www.zytrax.com/books/dns/ch8/soa.html>`_
+
+BIND_REFRESH_TIME
+^^^^^^^^^^^^^^^^^
+
+This variable controls the DNS Refresh time in seconds. If empty or removed it will fallback to a sane default.
+
++--------------------------+----------------------+---------------------+
+| Name                     | Allowed values       | Default value       |
++==========================+======================+=====================+
+| ``BIND_REFRESH_TIME``    | integer              | empty               |
++--------------------------+----------------------+---------------------+
+
+.. seealso:: `BIND SOA <http://www.zytrax.com/books/dns/ch8/soa.html>`_
+
+BIND_RETRY_TIME
+^^^^^^^^^^^^^^^
+
+This variable controls the DNS Retry time in seconds. If empty or removed it will fallback to a sane default.
+
++--------------------------+----------------------+---------------------+
+| Name                     | Allowed values       | Default value       |
++==========================+======================+=====================+
+| ``BIND_RETRY_TIME``      | integer              | empty               |
++--------------------------+----------------------+---------------------+
+
+.. seealso:: `BIND SOA <http://www.zytrax.com/books/dns/ch8/soa.html>`_
+
+BIND_EXPIRY_TIME
+^^^^^^^^^^^^^^^^
+
+This variable controls the DNS Expiry time in seconds. If empty or removed it will fallback to a sane default.
+
++--------------------------+----------------------+---------------------+
+| Name                     | Allowed values       | Default value       |
++==========================+======================+=====================+
+| ``BIND_EXPIRY_TIME``     | integer              | empty               |
++--------------------------+----------------------+---------------------+
+
+.. seealso:: `BIND SOA <http://www.zytrax.com/books/dns/ch8/soa.html>`_
+
+BIND_MAX_CACHE_TIME
+^^^^^^^^^^^^^^^^^^^
+
+This variable controls the DNS Max Cache time in seconds. If empty or removed it will fallback to a sane default.
+
++--------------------------+----------------------+---------------------+
+| Name                     | Allowed values       | Default value       |
++==========================+======================+=====================+
+| ``BIND_MAX_CACHE_TIME``  | integer              | empty               |
++--------------------------+----------------------+---------------------+
+
+.. seealso:: `BIND SOA <http://www.zytrax.com/books/dns/ch8/soa.html>`_
+
+
+
+
+
+
 .. |br| raw:: html
 
    <br />

docs/configuration-global/auto-dns.rst

@@ -78,32 +78,34 @@ The output should look like this (It is only important that there is no ``:53``.
 Linux
 -----
 
-If the prerequisites are met, you can edit ``/etc/resolv.conf`` with root or sudo privileges
-and add the Devilbox DNS server line by adding a ``nameserver`` directive
-which points to ``127.0.0.1``:
+If the prerequisites are met, you can edit ``/etc/dhcp/dhclient.conf`` with root or sudo privileges
+and add an instruction, which tells your local DHCP client that whenever any of your DNS servers
+are changed, you always want to have an additional entry, which is the one from the Devilbox.
+
+Add the following line to to the very beginning to ``/etc/dhcp/dhclient.conf``:
 
 .. code-block:: bash
-    :caption: /etc/resolv.conf
-    :name: /etc/resolv.conf
-    :emphasize-lines: 4
+    :caption: /etc/dhcp/dhclient.conf
+    :name: /etc/dhcp/dhclient.conf
 
-    host> sudi vi /etc/resolv.conf
-    # Dynamic resolv.conf(5) file for glibc resolver(3) generated by resolvconf(8)
-    #     DO NOT EDIT THIS FILE BY HAND -- YOUR CHANGES WILL BE OVERWRITTEN
-    nameserver 127.0.0.1
-    nameserver 192.168.0.10
-    search local
+    prepend domain-name-servers 127.0.0.1;
 
-.. important::
-    Keep all other ``nameserver`` entries intact. The Devilbox DNS nameserver will only work
-    once the Devilbox is running. If you remove all others and don't run the Devilbox,
-    you won't be able to resolve any DNS names anymore.
+When you do that for the first time, you need to restart the ``network-manager`` service.
 
-.. important::
-    The Devilbox ``nameserver`` entry should be the very first one.
+.. code-block:: bash
+
+    # Via service command
+    $ sudo service network-manager restart
+
+    # Or the systemd way
+    $ sudo systemctl restart network-manager
+
+This will make sure that whenever your /etc/resolv.conf is deployed, you will have ``127.0.0.1``
+as the first entry and also make use of any other DNS server which are deployed via the LAN's DHCP server.
+
+If the Devilbox DNS server is not running, it does not affect the name resolution, because you will
+still have other entries in ``/etc/resolv.conf``.
 
-If you now start the Devilbox you don't need to take care about manually adding DNS records
-anymore. Auto-DNS is now setup working.
 
 
 MacOS

docs/index.rst

@@ -65,6 +65,7 @@ host is ready to be served with your custom domain.
    :maxdepth: 2
    :caption: Tutorials
 
+   tutorials/communicating-with-external-hosts
    tutorials/add-your-own-docker-image
    tutorials/overwrite-existing-docker-image
    tutorials/adding-subdomains