Skip to main content
Version: 18.x

Using VNet

Report an issue with this page

This guide explains how to use VNet to connect to TCP applications available through Teleport.

How it works​

VNet automatically proxies connections from your computer to TCP apps available through Teleport. A program on your device can securely connect to internal applications protected by Teleport without having to know about Teleport authentication details. Underneath, VNet authenticates the connection with your Teleport credentials and securely tunnels the TCP connection to your application. This is all done client-side – VNet sets up a local DNS name server that intercepts DNS requests for your internal apps and responds with a virtual IP address managed by VNet that will forward the connection to your application.

VNet delivers an experience like a VPN for your TCP applications through this local virtual network, while maintaining all of Teleport's identity verification and zero trust features that traditional VPNs cannot provide.

VNet is available on macOS and Windows in Teleport Connect and tsh, with plans for Linux support in a future version.

Prerequisites​

  • A client machine running macOS Ventura (13.0) or higher.
  • Teleport Connect, version 16.0.0 or higher.

Step 1/3. Start Teleport Connect​

Open Teleport Connect and log in to the cluster. Find the TCP app you want to connect to. TCP apps have tcp:// as the protocol in their addresses.

Step 2/3. Start VNet​

Click "Connect" next to the TCP app. This starts VNet if it's not already running. Alternatively, you can start VNet through the connection list in the top left.

Details

First launch on macOS During the first launch, macOS will prompt you to enable a background item for tsh.app. VNet needs this background item in order to configure DNS on your device. To enable the background item, either interact with the system notification or go to System Settings > General > Login Items and look for tsh.app under "Allow in the Background".

Step 3/3. Connect​

Once VNet is running, you can connect to the application using the application client you would normally use to connect to it.

psql postgres://postgres@tcp-app.teleport.example.com/postgres
Support for multiple ports

Unless the application specifies multiple ports, VNet proxies connections over any port used by the application client. For multi-port apps, the port number must match one of the target ports of the app. To see a list of target ports, click the three dot menu next to an application in Teleport Connect or execute tsh apps ls.

If per-session MFA is enabled, the first connection over each port triggers an MFA check.

VNet is going to automatically start on the next Teleport Connect launch, unless you stop VNet before closing Teleport Connect.

tsh support​

VNet is available in tsh as well. Using it involves logging into the cluster and executing the command tsh vnet.

tsh login --proxy=teleport.example.com
tsh vnet

Troubleshooting​

Conflicting IPv4 ranges​

On the client computer, VNet uses IPv4 addresses from the CGNAT IP range 100.64.0.0/10 by default, and needs to configure addresses and routes for this range. This can conflict with other VPN-like applications, notably Tailscale also uses this range.

If you are experiencing connectivity problems with VNet, check if you are running Tailscale or another VPN client, and try disabling it to see if the issue persists. To avoid the conflict and run VNet alongside Tailscale or another VPN client you can configure VNet to use a different IPv4 range, see our VNet configuration guide.

Connecting to the app without VNet​

Sometimes connectivity issues are not related to VNet, and you can narrow that down by trying to connect to your app without VNet. Make sure your app appears in the Connect resources view, or the output of tsh apps ls. Turn off VNet and try creating a local proxy to your app (with debug logging enabled) with tsh proxy app -d <app-name>.

Timeouts when trying to reach a Teleport cluster​

If VNet doesn't have a chance to clean up before stopping, such as during sudden device shut down, it may leave leftover DNS configuration files in /etc/resolver. Those files tell your computer to talk to a DNS server operated by VNet when connecting to your cluster. But since VNet is no longer running, there's no DNS server to answer those calls.

To clean up those files, simply start VNet again. Alternatively, you can remove the leftover files manually.

Verifying that VNet receives DNS queries​

Open Teleport Connect. From the Connections panel in the top left, select VNet. Make sure VNet is running, then select "Open Diag Report". Note the IPv6 prefix and the IPv4 CIDR range used by VNet.

Send a query for a TCP app available in your cluster, replacing tcp-app.teleport.example.com with the name of your app:

dscacheutil -q host -a name tcp-app.teleport.example.com
name: tcp-app.teleport.example.comipv6_address: fd60:67ec:4325::647a:547d
name: tcp-app.teleport.example.comip_address: 100.68.51.151

The returned addresses should belong to ranges listed in the VNet diag report.

Querying for anything other than an address of a TCP app should return the address belonging to the Proxy Service. Using macOS as an example:

dscacheutil -q host -a name dashboard.teleport.example.com
name: dashboard.teleport.example.comipv6_address: 2606:2800:21f:cb07:6820:80da:af6b:8b2c
name: dashboard.teleport.example.comip_address: 93.184.215.14

Querying for any of those hostnames should result in some output being emitted in the debug logs of VNet (see Submitting an issue on how to enable debug logs).

Submitting an issue​

When submitting an issue, make sure to include a VNet diag report and debug logs from VNet and Teleport Connect.

To save a diag report to a file, open Teleport Connect. From the Connections panel in the top left select VNet, then "Open Diag Report". In the new tab with the report that was opened click the "Save Report to File" icon.

To collect VNet and Teleport Connect logs use the instructions below:

To enable debug logs in VNet, first stop Teleport Connect and then run the following command. It enables debug logs just for the next invocation of VNet:

sudo launchctl debug system/com.gravitational.teleport.tsh.vnetd --environment TELEPORT_DEBUG=1

Next, start capturing logs from VNet into a file:

log stream --predicate 'subsystem ENDSWITH ".vnetd"' --style syslog --level debug > vnet.log

Then start Teleport Connect using the following command to enable debug logs for Teleport Connect:

open -a "Teleport Connect" --args --connect-debug

Next, attempt to reproduce the issue with VNet.

To gather logs from Teleport Connect, from the app menu select Help → Open Logs Directory which opens ~/Library/Application Support/Teleport Connect/logs in Finder. Attach all files together with vnet.log produced in the earlier step.

Before version 18.0.0, VNet logs were saved in /var/log/vnet.log.

If the error is related to Teleport Connect not being able to start VNet or issues with code signing, searching through /var/log/com.apple.xpc.launchd/launchd.log for tsh soon after attempting to start VNet might also bring up relevant information:

grep tsh /var/log/com.apple.xpc.launchd/launchd.log

Next steps​

  • Read our VNet configuration guide to learn how to configure VNet access to your applications.
  • Read RFD 163 to learn how VNet works on a technical level.