Skip to main content
Version: Archive

DxOdyssey Containers Quick Start Guide

Introduction​

This quick start guide describes how to use DxOdyssey containers to connect to a remote SQL instance via tunnels. Using this guide, the user will create and configure containers at two sites (physical locations) using Docker, join the containers together into a gateway group, and create a tunnel between the sites that can be used to access the SQL instance.

Prerequisites​

  • A virtual machine at Site A running Microsoft SQL Server and listening on port 1433. The IP address of the VM will also be required in later steps. For information about installing SQL Server, view Microsoft documentation. The VM may be Linux or Windows.
  • Linux Docker hosts at Site A and Site B. For information about installing Docker, please reference Docker documentation. The Docker host at Site B should not have direct network access to the SQL instance at Site A.
  • SSMS or sqlcmd installed on a VM at Site B. This VM can be the same VM running the container at Site B.

Create Container at Site A​

  1. Pull the latest DxOdyssey image using the command docker pull dh2i/dxo.

  2. Start a DxOdyssey container using the command docker run. Parameter explanations and a command example are given below.

    • DxOdyssey uses TCP port 7979 for gateway group administration with the DxOdyssey Client UI. To map this port, use the -p parameter. The port number to the right of the colon must be 7979, but the number to the left of the colon – the port mapped to the host – do not have to be identical.
    • The -d flag runs the container in "detached" (background) mode so that the host machine’s command line can still be used after launching the container.
    • The -h parameter assigns the internal container hostname, which is used by DxOdyssey. This must be a unique name for each container participating in the gateway group.
    • --name parameter specifies the name visible in Docker for the container when using a command like docker ps -a. The --namme parameter isn't required, but it helps with easier identification of the containers.
    • The -v parameter creates a named Docker volume for the /etc/dh2i folder. If the container is removed, this parameter will save the DxOdyssey gateway group configuration in a Docker volume which can be used by a new container.

    Example

    docker run -p 7979:7979 -d -h dxodocker1 --name dxo1 -v dxo1vol:/etc/dh2i dh2i/dxo

  3. Activate DxOdyssey using the command dxcli activate-server.

    info

    Use docker exec to run commands within containers. This can be done in one of two ways: from the current shell using docker exec dxo1 <commmand>, or in a new shell using docker exec -it dxo1 bash. The examples given in this guide use the first example.

    Example

    docker exec dxo1 dxcli activate-server AAAA-BBBB-CCCC-DDDD

  4. Set the DxOdyssey gateway group passkey using the command dxcli gateway-group-set-secret-ex.

    Example

    docker exec dxo1 dxcli gateway-group-set-secret-ex PassW0rd

  5. Set a One-Time PassKey (OTPK) for the gateway group using the command dxcli set-otpk. The output from this command will be used in the next section to join the second gateway to the first in a gateway group.

    Example

    docker exec dxo1 dxcli set-otpk

Create Container at Site B​

  1. Pull the latest DxOdyssey image using the command docker pull dh2i/dxo.

  2. Start a DxOdyssey container using the command docker run. Use the parameter examples given in step 2 of the previous section, making sure to use a container hostname that is unique.

    Additionally, you will need to map a tunnel origin to the host machine. Origins are port(s) on the DxOdyssey gateway which other machines can use to access the tunnel. Later on in this guide, you will use the tunnel origin to access the SQL instance. In the command example below, the origin is mapped to port 11433:

    docker run -p 7979:7979 -p 11433:11433 -d -h dxodocker2 --name dxo2 -v dxo2vol:/etc/dh2i dh2i/dxo

  3. Activate DxOdyssey using the command dxcli activate-server.

    Example

    docker exec dxo2 dxcli activate-server AAAA-BBBB-CCCC-DDDD

  4. Join the containers together into a gateway group using the commmand dxcli join-gateway-group-ex.

    Example

    docker exec dxo2 dxcli join-gateway-group-ex match.dh2i.com 331bc8bf-7096-99bc-05e5-0dd097393600 true

  5. Create a tunnel using the command dxcli add-tunnel.

    info

    The command example given below shows a tunnel with an origin at the Site B container (e.g., the container you just configured). This origin accepts connections from any IP address (0.0.0.0) that has access to the Docker host on port 11433. The destination gateway for the tunnel is the container at Site A. The destination IP and port is the SQL Server VM at Site A using the default SQL listening port of 1433. In this example, the <destination_IP> should be substituted with the IP address of the SQL Server VM.

    To make the origin accessible only to the Docker host, use loopback (127.0.0.1) as the origin address instead. This means that you will need to have sqlcmd installed on the Docker host to access the SQL instance.

    Example 1: Accept all connections

    dxcli add-tunnel SQL_TUNNEL true dxodocker1 <destination_IP>:1433 dxodocker2,0.0.0.0:11433

    Example 2: Only accept connections from the Docker host

    dxcli add-tunnel SQL_TUNNEL true dxodocker1 <destination_IP>:1433 dxodocker2,127.0.0.1:11433

Connect to the SQL Server Instance from Site B​

  1. Connect to the machine running SSMS or sqlcmd.

  2. Use one of following connection strings to access the tunnel, substituting in the Docker host’s IP address or hostname when applicable:

    <Docker Host IP>,11433
    <Docker Host Hostname>,11433
    127.0.0.1,11433

References​