Documentation: Communicate with external hosts

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
+If the prerequisites are met, you can edit ``/etc/dhcp/dhclient.conf`` with root or sudo privileges
-and add the Devilbox DNS server line by adding a ``nameserver`` directive
+and add an instruction, which tells your local DHCP client that whenever any of your DNS servers
-which points to ``127.0.0.1``:
+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
+    :caption: /etc/dhcp/dhclient.conf
-    :name: /etc/resolv.conf
+    :name: /etc/dhcp/dhclient.conf
-    :emphasize-lines: 4
 
-    host> sudi vi /etc/resolv.conf
+    prepend domain-name-servers 127.0.0.1;
-    # 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
 
-.. important::
+When you do that for the first time, you need to restart the ``network-manager`` service.
-    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.
 
-.. important::
+.. code-block:: bash
-    The Devilbox ``nameserver`` entry should be the very first one.
+
+    # 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

docs/tutorials/communicating-with-external-hosts.rst

@@ -0,0 +1,152 @@
+.. _communicating_with_external_hosts:
+
+*********************************
+Communicating with external hosts
+*********************************
+
+This tutorial shows you how to connect the Devilbox to running Docker container outside the
+Devilbox network, i.e. Docker container you have started separately.
+
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+Prerequisites
+=============
+
+There are two things you need to make sure of are met beforehand:
+
+1. The external Docker container must expose its ports on all interfaces on your host operating system
+2. The IP by which the host is reachable from within the Devilbox container.
+
+Host IP: Docker on Linux
+------------------------
+
+If you run Docker on Linux the host IP is usually ``172.17.0.1``.
+
+
+Host IP: Docker for Mac
+-----------------------
+
+If you run Docker for Mac, an IP address is not necessary as it already provides a CNAME which will
+always point to the IP address of your host operating system. Depending on the Docker version this
+CNAME will differ:
+
+Docker 18.03.0-ce+ and Docker compose 1.20.1+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CNAME: ``host.docker.internal``
+
+Docker 17.12.0-ce+ and Docker compose 1.18.0+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CNAME: ``docker.for.mac.host.internal``
+
+Docker 17.06.0-ce+ and Docker compose 1.14.0+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CNAME: ``docker.for.mac.localhost``
+
+
+Host IP: Docker for Windows
+----------------------------
+
+If you run Docker for Windows, an IP address is not necessary as it already provides a CNAME which will
+always point to the IP address of your host operating system. Depending on the Docker version this
+CNAME will differ:
+
+Docker 18.03.0-ce+ and Docker compose 1.20.1+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CNAME: ``docker.for.win.host.internal``
+
+Docker 17.06.0-ce+ and Docker compose 1.14.0+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CNAME: ``docker.for.win.host.localhost``
+
+
+
+Make DNS available to the Devilbox
+==================================
+
+Inside each Devilbox Docker container you can already connect to all host ports (if they are bound
+to all interfaces) by the above specified IP addresses or CNAME's. You can however also create a
+custom DNS entry for convenience or if an external web server requires a special vhost name.
+
+Adding extra hosts
+------------------
+
+Extra hosts (hostname and IP address mappings or hostname and CNAME mappings) can be set in the
+``.env`` file.
+
+.. seealso:: :ref:`env_extra_hosts`
+
+
+Example
+-------
+
+Let's assume another Docker container is running on your host, which must be accessed by the exact
+name of ``mywebserver.loc`` in order to respond by that virtual host name.
+
+
+Mapping on Linux
+^^^^^^^^^^^^^^^^
+
+If you are running Linux as your host operating system you would use the IP address of the host
+computer which was identified as ``172.17.0.1``.
+
+.. code-block:: bash
+    :name: .env
+    :caption: .env
+
+    EXTRA_HOSTS=mywebserver.loc=172.17.0.1
+
+
+Mapping on MacOS
+^^^^^^^^^^^^^^^^
+
+If you are running MacOS as your host operating system you would use one of the identified CNAME's
+(depending on your Docker version).
+
+.. code-block:: bash
+    :name: .env
+    :caption: .env
+
+    EXTRA_HOSTS=mywebserver.loc=host.docker.internal
+
+The CNAME ``host.docker.internal`` will be resolved to an IP address during startup and ``mywebserver.loc``
+'s DNS record will point to that IP address.
+
+
+Mapping on Windows
+^^^^^^^^^^^^^^^^^^
+
+If you are running Windows as your host operating system you would use one of the identified CNAME's
+(depending on your Docker version).
+
+.. code-block:: bash
+    :name: .env
+    :caption: .env
+
+    EXTRA_HOSTS=mywebserver.loc=docker.for.win.host.internal
+
+The CNAME ``docker.for.win.host.internal`` will be resolved to an IP address during startup and ``mywebserver.loc``
+'s DNS record will point to that IP address.
+
+
+Auto DNS
+--------
+
+If you also turned on :ref:`global_configuration_auto_dns` these extra hosts will then also be available
+to your host operating system as well.
+
+
+Further reading
+===============
+
+.. seealso::
+    * :ref:`env_extra_hosts`
+    * :ref:`global_configuration_auto_dns`

docs/tutorials/enable-xdebug.rst

@@ -164,7 +164,7 @@ Docker 18.03.0-ce+ and Docker compose 1.20.1+
     :caption: xdebug.ini
     :emphasize-lines: 1
 
-    xdebug.remote_host=docker.for.mac.host.internal
+    xdebug.remote_host=docker.for.win.host.internal
     xdebug.remote_connect_back=0
 
 Docker 17.06.0-ce+ and Docker compose 1.14.0+
@@ -174,7 +174,7 @@ Docker 17.06.0-ce+ and Docker compose 1.14.0+
     :caption: xdebug.ini
     :emphasize-lines: 1
 
-    xdebug.remote_host=docker.for.mac.host.internal
+    xdebug.remote_host=docker.for.win.host.localhost
     xdebug.remote_connect_back=0
 
 If you have older versions, upgrade.