Access by Proxy and VPN using DC/OS Tunnel

Updated: April 18, 2017

When developing services on DC/OS, you may find it helpful to access your cluster from your local machine via SOCKS proxy, HTTP proxy, or VPN. For instance, you can work from your own development environment and immediately test against your DC/OS cluster.

Warning: DC/OS Tunnel is appropriate for development, debugging, and testing only. Do not use DC/OS Tunnel in production.


DC/OS Tunnel can run a SOCKS proxy over SSH to the cluster. SOCKS proxies work for any protocol, but your client must be configured to use the proxy, which runs on port 1080 by default.


The HTTP proxy can run in two modes: transparent and standard.

Transparent Mode

In transparent mode, the HTTP proxy runs as superuser on port 80 and does not require modification to your application. Access URLs by appending the mydcos.directory domain. You can also use DNS SRV records as if they were URLs. The HTTP proxy cannot currently access HTTPS in transparent mode.

Standard Mode

Though you must configure your client to use the HTTP proxy in standard mode, it does not have any of the limitations of transparent mode. As in transparent mode, you can use DNS SRV records as URLs.

SRV Records

A SRV DNS record is a mapping from a name to a IP/port pair. DC/OS creates SRV records in the form _<port-name>._<service-name>._tcp.marathon.mesos. The HTTP proxy exposes these as URLs. This feature can be useful for communicating with DC/OS services.


DC/OS Tunnel provides you with full access to the DNS, masters, and agents from within the cluster. OpenVPN requires root privileges to configure these routes.

DC/OS Tunnel Options at a Glance

  Pros Cons
  • Specify ports
  • All protocols
  • Requires application configuration
HTTP (transparent)
  • SRV as URL
  • No application configuration
  • Cannot specify ports (except through SRV)
  • Only supports HTTP
  • Runs as superuser
HTTP (standard)
  • SRV as URL
  • Specify ports
  • Requires application configuration
  • Only supports HTTP/HTTPS
  • No application configuration
  • Full and direct access to cluster
  • Specify ports
  • All protocols
  • More prerequisites
  • Runs as superuser
  • May need to manually reconfigure DNS
  • Relatively heavyweight

Using DC/OS Tunnel


  • Only Linux and macOS are currently supported.
  • The DC/OS CLI.
  • The DC/OS Tunnel package. Run dcos package install tunnel-cli --cli.
  • SSH access (key authentication only).
  • The OpenVPN client for VPN functionality.

Example Application

All examples will refer to this sample application:
* Service Name: myapp
* Group: mygroup
* Port: 555
* Port Name: myport

myapp is a web server listening on port 555. We’ll be using curl
as our client application. Each successful example will result in the HTML
served by myapp to be output output as text.

Using DC/OS Tunnel to run a SOCKS Proxy

  1. Run the following command from the DC/OS CLI:
    dcos tunnel socks
    ## Example
    curl --proxy socks5h:// myapp-mygroup.marathon.agentip.dcos.thisdcos.directory:555
  2. Configure your application to use the proxy on port 1080.

Using DC/OS Tunnel to run a HTTP Proxy

Transparent Mode

  1. Run the following command from the DC/OS CLI:

    sudo dcos tunnel http
    ## Example
    curl _myport._myapp.mygroup._tcp.marathon.mesos.mydcos.directory
    ### Watch out!
    ## This won't work because you can't specify a port in transparent mode
    curl myapp-mygroup.marathon.agentip.dcos.thisdcos.directory.mydcos.directory:555
  2. In transparent mode, the HTTP proxy works by port forwarding. Append .mydcos.directory to the end of your domain when you enter commands. For instance, http://example.com/?query=hello becomes http://example.com.mydcos.directory/?query=hello. Note: In transparent mode, you cannot specify a port in a URL.

Standard mode

  1. To run the HTTP proxy in standard mode, without root privileges, use the --port flag to configure it to use another port:

    dcos tunnel http --port 8000
    ## Example
    curl --proxy _myport._myapp.mygroup._tcp.marathon.mesos
    curl --proxy myapp-mygroup.marathon.agentip.dcos.thisdcos.directory:555
  2. Configure your application to use the proxy on the port you specified above.

SRV Records

The HTTP proxy exposes DC/OS SRV records as URLs in the form _<port-name>._<service-name>._tcp.marathon.mesos.mydcos.directory (transparent mode) or _<port-name>._<service-name>._tcp.marathon.mesos (standard mode).

Find your Service Name

The <service-name> is the entry in the ID field of a service you create from the DC/OS web interface or the value of the id field in your Marathon application definition.

Add a Named Port from the DC/OS Web Interface

To name a port from the DC/OS web interface, go to the Services > Services tab, click the name of your service, and then click Edit. Enter a name for your port on the Networking tab.

Add a Named Port in a Marathon Application Definition

Alternatively, you can add name to the portMappings or portDefinitions field of a Marathon application definition. Whether you use portMappings or portDefinitions depends on whether you are using BRIDGE or HOST networking. Learn more about networking and ports in Marathon.

"portMappings": [
        "name": "<my-port-name>",
        "containerPort": 3000,
        "hostPort": 0,
        "servicePort": 10000,
        "labels": {
             "VIP_0": ""
"portDefinitions": [
      "name": "<my-port-name>",
      "protocol": "tcp",
      "port": 0,    

Using DC/OS Tunnel to run a VPN

Run the following command from the DC/OS CLI

sudo dcos tunnel vpn

## Example
curl myapp-mygroup.marathon.agentip.dcos.thisdcos.directory:555

The VPN client attempts to auto-configure DNS, but this functionality does not work on macOS. To use the VPN client on macOS, add the DNS servers that DC/OS Tunnel instructs you to use.

When you use the VPN, you are virtually within your cluster. You can access
your master and agent nodes directly:

ping master.mesos
ping slave.mesos

macOS OpenVPN Client Installation

  • If using homebrew then install with:
    brew install openvpn

    Then to use it:

    Either add /usr/local/sbin to your $PATH,

    or add the flag --client=/usr/local/sbin/openvpn like so:

    sudo dcos tunnel vpn --client=/usr/local/sbin/openvpn
  • Another option is to install TunnelBlick
    (don’t run it, we are only installing it for the openvpn executable)
    and add the flag --client=/Applications/Tunnelblick.app/Contents/Resources/openvpn/openvpn-*/openvpn like so:

    sudo dcos tunnel vpn --client=/Applications/Tunnelblick.app/Contents/Resources/openvpn/openvpn-*/openvpn

Linux OpenVPN Client Installation

openvpn should be available via your distribution’s package manager.

For example:
* Ubuntu: apt-get update && apt-get install openvpn
* ArchLinux: pacman -S openvpn