DxOdyssey Tunnels Quick Start Guide
Introduction
This quick start guide describes how to use DxOdyssey tunnels to connect to an application. Using this guide, the user will install and configure DxOdyssey on two VMs, then create a tunnel that can be used to access the application.
Prerequisites
-
Any application that listens on a TCP port. The IP address of the VM the application is running on will be required in later steps.
tipExample applications include SQL Server (port 1433), HTTP (80), HTTPS (443), Remote Desktop (3389), and many others. The example commands in this guide will use port 1433, but you can simply swap out that port number with the one your application uses.
-
Two DxOdyssey VMs (gateways) running on Linux. More information about installing DxOdyssey on Linux and creating a gateway group (a cluster of gateways) can be found in this guide. Please note the additional requirements for each VM below:
- The first gateway should be located within the same network as your application. This gateway must be able to directly access your application via an IP address, hostname, or FQDN.
- The second gateway should be joined into a gateway group with the first gateway. However, this gateway is not required to be on the same network as the application. You will be connecting to your application using the tunnel origin located on this gateway, more of which will be explained later in this guide.
Understanding DxOdyssey Tunnels
After you've joined your two VMs into a gateway group according to the prerequisites, setting up a tunnel is a one-step process. However, it is important to understand how DxOdyssey tunnels work before creating one.
DxOdyssey tunnels use a proprietary 'TCP over UDP' implementation for security, reliability, and performance. You can use DxOdyssey containers to connect to applications almost anywhere as long as the NAT type on your router is compatible with UDP hole-punching (most routers are).
There is a deeper technical dive into the details of Network Address Translation (NAT) available in our Understanding Different NAT Types Knowledge Base article.
Below is some helpful terminology to understand about tunnels:
-
Target: This is the application your tunnel is targeting. In the tunnel configuration, this consists of 1) the application's listening port and 2) the IP address, hostname, or FQDN of the server the application is running on.
-
Destination: This is the destination gateway for your tunnel, and the end of the tunnel itself. Your destination gateway will receive your tunnel traffic and send that information to your target application.
tipIt is possible for your destination gateway and target application to be on the same machine. To accomplish this, your application needs to be installed on the same device as DxOdyssey, and you need to use
127.0.0.1
orlocalhost
as the target IP/hostname. -
Origin: This is gateway where your tunnel traffic will originate from. Your tunnel origin gateway will package up incoming communication and send it to the destination gateway.
It is important to note that once communication is established between and origin and a target, tunnel traffic moves both ways. However, tunnel connections can only be initiated from an origin.
DxOdyssey gateways do not need to be within the same network to communicate with each other. Instead, DxOdyssey takes advantage of DH2i's match-making service so your gateways can discover and connect to each other over the internet. After your gateway group members have established connections, private communication between your gateways does not pass through the DH2i match-maker, but instead through secure tunnels internal to DxOdyssey. In other words, the match-maker is only there to help gateways find each other; it does not carry inter-gateway communication.
Create the Tunnel
Now we can create the tunnel using DxCLI. The syntax for creating a basic tunnel is given below:
dxcli add-tunnel <tunnel_name> <enabled> <destination_gateway_name> <target_address>:<target_port> <origin_gateway>,<origin_address>:<origin_port>
More information about this command, additional parameters, and examples can be found in the DxCLI guide.
I have a SQL Server instance I want to connect to from a remote location. To accomplish this using tunnels, I've installed DxOdyssey on one machine on-site (on the same network as the SQL instance), and one machine off-site. My add-tunnel
command would look something like this:
dxcli add-tunnel "TUNNEL1" "true" "DXO-DEST1" "MSSQL1:1433" "DXO-ORIGIN1,0.0.0.0:1433"
In the example above, my tunnel has the following parameters:
-
tunnel_name
: This is the name you want to assign the tunnel. -
enabled
: Whether or not the tunnel is enabled after creation. This is set to true unless you want to enable your tunnel at a later time. -
destination_gateway_name
: The name of the destination gateway. Remember, the destination gateway is the gateway that directs tunnel traffic to the target application. -
target_address
: The IP address or hostname of the target application (located in the same network as the destination). -
target_port
: The target application's port. -
origin_gateway
: The name of the origin gateway. -
origin_address
: This parameter specifies what address or addresses are allowed to connect to the origin. In the example above,0.0.0.0
means that any machine with network access to the origin is allowed to connect to the tunnel.infoTunnel access can be restricted by using a different IP address in the
origin_address
field. If only the origin gateway itself should have access to the tunnel, you could use local loopback (127.0.0.1) to facilitate this. Alternatively, if only a certain machine on the local network should have access, you could use that machine's IP address as the origin address. -
origin_port
: This is the port that applications will use to connect to the tunnel origin. In the example above, I've used the same default SQL Server port of 1433. However, you are free to change this to a non-default port. If you choose a port that is different from the default port of your application (like 31433), you'll need to specify the port in your connection string for connecting applications.
Connect Using the Tunnel
Now that the tunnel has been created, you can connect to your target application from the tunnel origin. To connect, you'll need 1) the IP address or hostname of the origin gateway and 2) the origin gateway's origin_port
. Note again that your tunnel origin is going to route incoming traffic to the tunnel destination, and the tunnel destination will send that traffic to the target application.
To connect to the target application from the off-site location in the example above, my sqlcmd
connection string would look something like this:
sqlcmd -S DXO-ORIGIN1 -U SA -P SqlPassW0rd
Alternatively, using the non-default SQL Server port, the connection string would look like this:
sqlcmd -S DXO-ORIGIN1,31433 -U SA -P SqlPassW0rd
Like in the other examples above, an IP address can be used instead of the hostname.