From 494cb061c38d74ae93f2d020485d0fa4417aff9d Mon Sep 17 00:00:00 2001 From: cytopia Date: Sat, 28 Apr 2018 12:17:07 +0200 Subject: [PATCH] Documentation: Communicate with external hosts --- docs/configuration-files/env-file.rst | 181 ++++++++++++++++++ docs/configuration-global/auto-dns.rst | 42 ++-- docs/index.rst | 1 + .../communicating-with-external-hosts.rst | 152 +++++++++++++++ docs/tutorials/enable-xdebug.rst | 4 +- 5 files changed, 358 insertions(+), 22 deletions(-) create mode 100644 docs/tutorials/communicating-with-external-hosts.rst diff --git a/docs/configuration-files/env-file.rst b/docs/configuration-files/env-file.rst index 8824a3d8c..ce25d363c 100644 --- a/docs/configuration-files/env-file.rst +++ b/docs/configuration-files/env-file.rst @@ -245,6 +245,76 @@ this project visible to everyone in your corporate LAN. and `Docker Release notes `_ +.. _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 `_ 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 `_ + * `BIND SOA `_ + +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 `_ + +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 `_ + +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 `_ + +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 `_ + + + + + + .. |br| raw:: html
diff --git a/docs/configuration-global/auto-dns.rst b/docs/configuration-global/auto-dns.rst index 8ad6bc1c1..4b742e4fa 100644 --- a/docs/configuration-global/auto-dns.rst +++ b/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 diff --git a/docs/index.rst b/docs/index.rst index e30468e6d..2772475a4 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/tutorials/communicating-with-external-hosts.rst b/docs/tutorials/communicating-with-external-hosts.rst new file mode 100644 index 000000000..b305a507d --- /dev/null +++ b/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` diff --git a/docs/tutorials/enable-xdebug.rst b/docs/tutorials/enable-xdebug.rst index a5c1c2589..73a4306eb 100644 --- a/docs/tutorials/enable-xdebug.rst +++ b/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.