Using VNet

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 connect to tcp-app.teleport.example.com, without having to know about Teleport. Underneath, VNet authenticates the connection with your credentials, using the same TLS routing technology as tsh proxy app. This is all done client-side – VNet sets up a local DNS name server and a virtual network device.

VNet is available in Teleport Connect and tsh on macOS, with Windows and Linux version in the works.

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.

VNet needs to set up a network device and configure DNS on your device, so it'll ask for admin permissions. For now your password is needed each time you start VNet, but we're working on showing the prompt only once.

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. The port number is inconsequential. VNet forwards connections over any port number under the public address of the app to the app itself.

psql postgres://[email protected]/postgres

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

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

Start VNet with tsh vnet -d. Look at /var/log/vnet.log and note the IPv6 and IPv4 CIDR range used by VNet.

From tsh vnet -d:INFO [VNET]      Running Teleport VNet. ipv6_prefix:fd60:67ec:4325:: vnet/vnet.go:317
From /var/log/vnet.log:INFO  Setting an IP route for the VNet. netmask:100.64.0.0/10 vnet/osconfig_darwin.go:47

Send a query for a TCP app available in your cluster:

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 addresses reported by dscacheutil should belong to ranges reported by VNet above.

Querying for anything other than an address of a TCP app should return the address belonging to the Proxy Service.

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 both addresses should result in some output being emitted by tsh vnet -d.

Submitting an issue

When submitting an issue, make sure to include logs from /var/log/vnet.log, as well as Teleport Connect logs or the output of tsh vnet -d, depending on which client you use.

Next steps

• Read RFD 163 to learn how VNet works on a technical level.