Documentation: SSH and SSH tunnelling

docs/advanced/connect-to-host-os.rst

@@ -19,6 +19,12 @@ Prerequisites
 When you want to connect from inside a Docker container to a port on your host operating system,
 ensure the host service is listening on all interfaces for simplicity.
 
+The following sections will give you the IP address and/or the CNAME where the host os can be
+reached from within a container.
+
+
+.. _connect_to_host_os_docker_on_linux:
+
 Docker on Linux
 ===============
 
@@ -43,17 +49,17 @@ always point to the IP address of your host operating system. Depending on the D
 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``
 
@@ -68,14 +74,14 @@ CNAME will differ:
 .. important:: Ensure your firewall is not blocking Docker to host connections.
 
 Docker 18.03.0-ce+ and Docker compose 1.20.1+
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------------------------
 
 * CNAME: ``docker.for.win.host.internal``
 * CNAME: ``host.docker.internal``
 
 
 Docker 17.06.0-ce+ and Docker compose 1.14.0+
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------------------------
 
 CNAME: ``docker.for.win.host.localhost``
 
@@ -88,42 +94,73 @@ Docker Toolbox
 Docker Toolbox behaves the same way as Docker on Linux, with one major difference.
 The Devilbox IP address or the custom provided CNAMEs actually refer to the Docker Toolbox machine.
 
-In order to connect from inside the Docker container inside Docker Toolbox to your host OS,
+In order to connect from inside the Docker container (which is inside the Docker Toolbox machine)
-you need to create a remote port-forward from your host OS to the Docker Toolbox machine.
+to your host os, you need to create:
-In other words, you need to make the service from your host OS available inside the Docker Toolbox
-machine.
 
-Let's assume you have a service on your host, listening on ``127.0.0.1`` on port ``7771`` and
+1. either a **local** port-forward on the **Docker Toolbox** machine (``ssh -L``)
-want to forward that to port ``7772`` on the Docker Toolbox machine, so that the Docker container
+2. or a **remote** port-forward on your **host os** (``ssh -R``)
-can access port ``7772`` via the Devilbox bridge IP (``172.16.238.1``).
 
-You will have to paste the following into a terminal on your host:
+.. seealso:: |ext_lnk_ssh_tunnelling_for_fun_and_profit|
+
+
+For both examples we assume the following:
+
+* MySQL database exists on your host os and listens on ``127.0.0.1`` on port ``3306``
+* Docker Toolbox IP address is ``192.168.99.100``
+* Host IP address where SSH is listening on ``172.16.0.1``
+* Host SSH username is ``user``
+* Devilbox Docker container wants to access MySQL on host os
+
+
+Local port forward on Docker Toolbox
+------------------------------------
+
+.. important::
+   For that to work, your host operating system requires an SSH server to be up and running.
+
++----------------+----------------+--------------+--------------------+--------------+
+| Initiator      | From host      | From port    | To host            | To port      |
++================+================+==============+====================+==============+
+| Docker Toolbox | ``127.0.0.1``  | ``3306``     | ``192.168.99.100`` | ``3306``     |
++----------------+----------------+--------------+--------------------+--------------+
 
 .. code-block:: bash
 
-   # Change any of those three values
+   # From Docker Toolbox forward port 3306 (on host 172.16.0.1) to myself (192.168.99.100)
-   LOCAL_ADDR=127.0.0.1     # On what IP address does the service bind to locally (on your MacOS)
+   toolbox> ssh -L 3306:127.0.0.1:3306 user@172.16.0.1
-   LOCAL_PORT=7771          # On what port does the service listen locally (on your MacOS)
-   REMOTE_PORT=7772         # On what port it should listen in the Docker Toolbox machine
-
-   # Fixed Devilbox network IP
-   REMOTE_ADDR=172.16.238.1 # On what IP it should bind on the Docker Toolbox machine (Devilbox network IP)
-
-   # Docker Toolbox defines
-   USER=$(docker-machine inspect $docker_machine_name --format={{.Driver.SSHUser}})
-   HOST=$(docker-machine active)
-   PORT=$(docker-machine inspect $docker_machine_name --format={{.Driver.SSHPort}})
-   KEY=$(docker-machine inspect $docker_machine_name --format={{.Driver.SSHKeyPath}})
-
-   ssh -i ${KEY} -p ${PORT} \
-       -R ${REMOTE_ADDR}:${REMOVE_PORT}:${LOCAL_HOST}:${LOCAL_PORT} \
-       ${USER}@${HOST}
 
 .. seealso::
+   * :ref:`howto_find_docker_toolbox_ip_address`
    * :ref:`howto_ssh_into_docker_toolbox`
-   * :ref:`howto_ssh_port_forward_from_docker_toolbox_to_host`
+   * :ref:`howto_ssh_port_forward_on_docker_toolbox_from_host`
-   * :ref:`howto_ssh_port_forward_from_host_to_docker_toolbox`
+
-   * :ref:`howto_open_terminal_on_mac`
+Remote port-forward on host os
-   * :ref:`howto_open_terminal_on_win`
+------------------------------
-   * |ext_lnk_ssh_tunnelling_for_fun_and_profit|
+
-   * |ext_lnk_stackoverflow_ssh_into_docker_machine|
+.. important::
+   For that to work, your host operating system requires an SSH client (``ssh`` binary).
+
++----------------+----------------+--------------+--------------------+--------------+
+| Initiator      | From host      | From port    | To host            | To port      |
++================+================+==============+====================+==============+
+| Host os        | ``127.0.0.1``  | ``3306``     | ``192.168.99.100`` | ``3306``     |
++----------------+----------------+--------------+--------------------+--------------+
+
+.. code-block:: bash
+
+   # From host os forward port 3306 (from loopback 127.0.0.1) to Docker Toolbox (192.168.99.100)
+   host> ssh -R 3306:127.0.0.1:3306 docker@192.168.99.100
+
+.. seealso::
+   * :ref:`howto_find_docker_toolbox_ip_address`
+   * :ref:`howto_ssh_into_docker_toolbox`
+   * :ref:`howto_ssh_port_forward_on_host_to_docker_toolbox`
+
+Post steps
+----------
+
+With either of the above you have achieved the exact behaviour as
+:ref:`connect_to_host_os_docker_on_linux` for one single service/port (MySQL port 3306).
+
+You must now follow the steps for :ref:`connect_to_host_os_docker_on_linux` to actually connect
+to that service from within the Devilbox Docker container.

docs/howto/docker-toolbox/docker-toolbox-and-the-devilbox.rst

@@ -136,7 +136,7 @@ follows:
 .. seealso::
 
    * :ref:`howto_find_docker_toolbox_ip_address`
-   * :ref:`howto_ssh_port_forward_from_docker_toolbox_to_host`
+   * :ref:`howto_ssh_port_forward_on_docker_toolbox_from_host`
    * :ref:`setup_auto_dns`
 
 

docs/howto/docker-toolbox/ssh-into-docker-toolbox.rst

@@ -16,7 +16,12 @@ SSH into Docker Toolbox
 Requirements
 ============
 
-You shell must have an SSH client (the ``ssh`` command).
+You shell must have an SSH client (the ``ssh`` command or equivalent).
+
+.. seealso::
+   * :ref:`howto_open_terminal_on_mac`
+   * :ref:`howto_open_terminal_on_win`
+   * :ref:`howto_find_docker_toolbox_ip_address`
 
 
 Manual

docs/howto/docker-toolbox/ssh-port-forward-from-docker-toolbox-to-host.rst

@@ -1,11 +0,0 @@
-:orphan:
-
-.. _howto_ssh_port_forward_from_docker_toolbox_to_host:
-
-********************************************
-SSH port-forward from Docker Toolbox to host
-********************************************
-
-TODO
-
-https://stackoverflow.com/questions/30330442/how-to-ssh-into-docker-machine-virtualbox-instance#30331229

docs/howto/docker-toolbox/ssh-port-forward-from-host-to-docker-toolbox.rst

@@ -1,11 +0,0 @@
-:orphan:
-
-.. _howto_ssh_port_forward_from_host_to_docker_toolbox:
-
-********************************************
-SSH port-forward from host to Docker Toolbox
-********************************************
-
-TODO
-
-https://stackoverflow.com/questions/30330442/how-to-ssh-into-docker-machine-virtualbox-instance#30331229

docs/howto/docker-toolbox/ssh-port-forward-on-docker-toolbox-from-host.rst

@@ -0,0 +1,111 @@
+:orphan:
+
+.. include:: /_includes/all.rst
+
+.. _howto_ssh_port_forward_on_docker_toolbox_from_host:
+
+********************************************
+SSH port-forward on Docker Toolbox from host
+********************************************
+
+.. note:: This is a **Local SSH port-forward** (``ssh -L``)
+
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+Requirements
+============
+
+You **host operating system** must have an **SSH server** installed, up and running.
+
+.. seealso::
+   * :ref:`howto_open_terminal_on_mac`
+   * :ref:`howto_open_terminal_on_win`
+   * :ref:`howto_find_docker_toolbox_ip_address`
+   * :ref:`howto_ssh_into_docker_toolbox`
+   * |ext_lnk_ssh_tunnelling_for_fun_and_profit|
+
+
+Overview
+========
+
+This is a **local** SSH port-forward (``ssh -L``). In other words, the Docker Toolbox machine
+will make a port **locally available** from somewhere else. Therefore the process must be initiated
+on the Docker Toolbox machine.
+
+General command
+---------------
+
+The following represents the general structure of a local ssh port-forward:
+
+.. code-block:: bash
+
+   ssh -L <DockerToolbox_Port>:<HostOS_SRV_IP>:<HostOS_SRV_Port> <HostOS_SSH_USER>@<HostOS_SSH_IP>
+
++--------------------------+-----------------------------------------------------------------------------+
+| ``<DockerToolbox_Port>`` | The port on the Docker Toolbox machine the service should be made available |
++--------------------------+-----------------------------------------------------------------------------+
+| ``<HostOS_SRV_IP>``      | The IP address on the host os, where the service is currently listening     |
++--------------------------+-----------------------------------------------------------------------------+
+| ``<HostOS_SRV_PORT>``    | The port on the host os, where the service is bound to                      |
++--------------------------+-----------------------------------------------------------------------------+
+| ``<HostOS_SSH_USER>``    | The username of the host os SSH server for the connection                   |
++--------------------------+-----------------------------------------------------------------------------+
+| ``<HostOS_SSH_IP>``      | The IP address of the host at which the SSH server is reachable             |
++--------------------------+-----------------------------------------------------------------------------+
+
+Command example
+---------------
+
+Making ``127.0.0.1:10000`` from host os available on ``0.0.0.0:8080`` on Docker Toolbox machine:
+
+.. code-block:: bash
+
+   ssh -L 8080:127.0.0.1:10000 user@172.16.0.1
+
++--------------------------+-----------------------------------------------------------------------------+
+| ``8080``                 | Docker Toolbox should make the port available on itself on this port        |
++--------------------------+-----------------------------------------------------------------------------+
+| ``127.0.0.1``            | The service currently listens on that IP address on the host os             |
++--------------------------+-----------------------------------------------------------------------------+
+| ``10000``                | The service is currently bound to that port on the host os                  |
++--------------------------+-----------------------------------------------------------------------------+
+| ``user``                 | The username of the host os SSH server for the connection                   |
++--------------------------+-----------------------------------------------------------------------------+
+| ``172.16.0.1``           | The IP address of the host at which the SSH server is reachable             |
++--------------------------+-----------------------------------------------------------------------------+
+
+
+Examples
+========
+
+For this example we assume the following information:
+
+* Docker Toolbox IP address is ``192.168.99.100``
+* Host os IP address where SSH server is listening is ``172.16.0.1``
+* Host SSH username is ``user``
+
+Make host-based MySQL available on Docker Toolbox
+-------------------------------------------------
+
+1. Gather the IP address on your host os where the SSH server is listening
+2. SSH into the Docker Toolbox machine
+3. Forward: ``127.0.0.1:3306`` from host os to ``0.0.0.0:3306`` on Docker Toolbox
+
+   .. code-block:: bash
+
+    toolbox> ssh -L 3306:127.0.0.1:3306 user@172.16.0.1
+
+Make host-based PgSQL available on Docker Toolbox
+-------------------------------------------------
+
+1. Gather the IP address on your host os where the SSH server is listening
+2. SSH into the Docker Toolbox machine
+3. Forward: ``127.0.0.1:5432`` from host os to ``0.0.0.0:5432`` on Docker Toolbox
+
+   .. code-block:: bash
+
+    toolbox> ssh -L 5432:127.0.0.1:5432 user@172.16.0.1

docs/howto/docker-toolbox/ssh-port-forward-on-host-to-docker-toolbox.rst

@@ -0,0 +1,107 @@
+:orphan:
+
+.. include:: /_includes/all.rst
+
+.. _howto_ssh_port_forward_on_host_to_docker_toolbox:
+
+******************************************
+SSH port-forward on host to Docker Toolbox
+******************************************
+
+.. note:: This is a **Remote SSH port-forward** (``ssh -R``)
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+Requirements
+============
+
+You shell must have an **SSH client** (the ``ssh`` command or equivalent).
+
+.. seealso::
+   * :ref:`howto_open_terminal_on_mac`
+   * :ref:`howto_open_terminal_on_win`
+   * :ref:`howto_find_docker_toolbox_ip_address`
+   * :ref:`howto_ssh_into_docker_toolbox`
+   * |ext_lnk_ssh_tunnelling_for_fun_and_profit|
+
+
+Overview
+========
+
+This is a **remote** SSH port-forward (``ssh -R``). In other words, the host os will make the port
+**remotely availabl** on the Docker Toolbox machine. Therefore the process must be initiated
+on the host os.
+
+General command
+---------------
+
+The following represents the general structure of a remote ssh port-forward:
+
+.. code-block:: bash
+
+   ssh -R <DockerToolbox_Port>:<HostOS_SRV_IP>:<HostOS_SRV_Port> <DockerToolbox_SSH_USER>@<DockerToolbox_SSH_IP>
+
++------------------------------+-----------------------------------------------------------------------------+
+| ``<DockerToolbox_Port>``     | The port on the Docker Toolbox machine the service should be made available |
++------------------------------+-----------------------------------------------------------------------------+
+| ``<HostOS_SRV_IP>``          | The IP address on the host os, where the service is currently listening     |
++------------------------------+-----------------------------------------------------------------------------+
+| ``<HostOS_SRV_PORT>``        | The port on the host os, where the service is bound to                      |
++------------------------------+-----------------------------------------------------------------------------+
+| ``<DockerToolbox_SSH_USER>`` | The username of the host os SSH server for the connection                   |
++------------------------------+-----------------------------------------------------------------------------+
+| ``<DockerToolbox_SSH_IP>``   | The IP address of the host at which the SSH server is reachable             |
++------------------------------+-----------------------------------------------------------------------------+
+
+Command example
+---------------
+
+Making ``127.0.0.1:10000`` from host os available on ``0.0.0.0:8080`` on Docker Toolbox machine:
+
+.. code-block:: bash
+
+   ssh -R 8080:127.0.0.1:10000 docker@192.168.99.100
+
++--------------------------+-----------------------------------------------------------------------------+
+| ``8080``                 | Docker Toolbox should make the port available on itself on this port        |
++--------------------------+-----------------------------------------------------------------------------+
+| ``127.0.0.1``            | The service currently listens on that IP address on the host os             |
++--------------------------+-----------------------------------------------------------------------------+
+| ``10000``                | The service is currently bound to that port on the host os                  |
++--------------------------+-----------------------------------------------------------------------------+
+| ``docker``               | The username of the Docker Toolbox SSH server for the connection            |
++--------------------------+-----------------------------------------------------------------------------+
+| ``192.168.99.100``       | The IP address of the Docker Toolbox at which the SSH server is reachable   |
++--------------------------+-----------------------------------------------------------------------------+
+
+
+Examples
+========
+
+For this example we assume the following information:
+
+* Docker Toolbox IP address is ``192.168.99.100``
+* Docker Toolbox SSH username is ``docker``
+
+Make host-based MySQL available on Docker Toolbox
+-------------------------------------------------
+
+1. Open a terminal on your host os
+2. Forward: ``127.0.0.1:3306`` from host os to ``0.0.0.0:3306`` on Docker Toolbox
+
+   .. code-block:: bash
+
+    toolbox> ssh -R 3306:127.0.0.1:3306 docker@192.168.99.100
+
+Make host-based PgSQL available on Docker Toolbox
+-------------------------------------------------
+
+1. Open a terminal on your host os
+2. Forward: ``127.0.0.1:5432`` from host os to ``0.0.0.0:5432`` on Docker Toolbox
+
+   .. code-block:: bash
+
+    toolbox> ssh -R 5432:127.0.0.1:5432 docker@192.168.99.100

docs/intermediate/setup-auto-dns.rst

@@ -129,7 +129,7 @@ Assuming the Docker Toolbox IP is ``192.168.99.100`` your forwards must be as fo
 +----------------+-----------+-----------+---------+
 
 .. seealso::
-   * :ref:`howto_ssh_port_forward_from_docker_toolbox_to_host`
+   * :ref:`howto_ssh_port_forward_on_docker_toolbox_from_host`
    * :ref:`howto_find_docker_toolbox_ip_address`