Using VNet
This guide explains how to use VNet to connect to TCP applications and SSH servers available through Teleport.
How it works
VNet automatically proxies connections from your computer to TCP apps and SSH servers available through Teleport. A program on your device can securely connect to resources protected by Teleport without having to know about Teleport authentication details. Underneath, VNet authenticates the connection with your Teleport credentials and securely tunnels the connection. This is all done client-side – VNet sets up a local DNS name server that intercepts DNS requests for your Teleport resources and responds with a virtual IP address managed by VNet that will handle the connection.
VNet's SSH support enables third-party SSH clients to connect to Teleport SSH servers with minimal configuration required, while still offering Teleport access controls and features like Per-session MFA and Hardware Key Support.
VNet delivers an experience like a VPN 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
- macOS
- Windows
- A client machine running macOS Ventura (13.0) or higher.
- Teleport Connect, version 16.0.0 or higher.
- A client machine running Windows 10 or higher.
- Teleport Connect, version 17.3.0 or higher.
Step 1/3. Start VNet
Open Teleport Connect and log in to your cluster. See Using Teleport Connect if you haven't used the Teleport Connect app before.
Open the connection list in the top left and click the icon to start VNet. Or, skip this step and VNet will start automatically when you click "Connect" on a TCP app or "Connect with VNet" on an SSH server.
After VNet has been started once it will automatically start every time Teleport Connect is opened, unless you stop VNet before closing Teleport Connect.
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 2/3. Connect to a TCP app
Find the TCP app you want to connect to.
TCP apps have tcp://
as the protocol in their address.
Click "Connect" next to the TCP app. This will start VNet if it's not already running, and then copy the app's address to your clipboard. You can now 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
As long as VNet is running in the background, clicking "Connect" next to each app is not necessary. You can directly connect to all of your TCP apps without any actions in Teleport Connect.
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.
Step 3/3. Connect to an SSH server
Find the SSH server you want to connect to, open the menu next to the "Connect" dropdown, and click "Connect with VNet". This will start VNet if it's not already running, and then copy the VNet address for the server to your clipboard.
There is a one-time configuration step required before SSH clients will be able to connect to Teleport SSH servers through VNet. When you click "Connect with VNet" on an SSH server, Teleport Connect will automatically check if this configuration is present and walk you through it if necessary.
Once the configuration step is complete, any OpenSSH-compatible client that
reads configuration options from ~/.ssh/config
should be able to connect to
Teleport SSH servers.
Try connecting with the standard ssh
client or the Remote Development feature
in editors like Visual Studio Code or Zed.
ssh <username>@<hostname>.<clustername>
As long as VNet is running in the background, clicking "Connect with VNet" next to each SSH server is not necessary, you can directly connect to all of your Teleport SSH servers without any actions in Teleport Connect.
tsh
support
VNet is also available in tsh
without running Teleport Connect.
To use it, log in and then run tsh vnet
.
tsh login --proxy=teleport.example.comtsh vnet
While tsh
support is available, Teleport Connect is the preferred application
for running VNet.
Teleport Connect offers better visibility for MFA prompts and cluster logins, and
automatically runs diagnostics that are useful for troubleshooting.
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:
- macOS
- Windows
dscacheutil -q host -a name tcp-app.teleport.example.comname: tcp-app.teleport.example.comipv6_address: fd60:67ec:4325::647a:547d
name: tcp-app.teleport.example.comip_address: 100.68.51.151
In PowerShell.
Resolve-DnsName tcp-app.teleport.example.com
Name Type TTL Section IPAddress---- ---- --- ------- ---------tcp-app.teleport.example.com AAAA 10 Answer fd60:67ec:4325::647a:547dtcp-app.teleport.example.com A 10 Answer 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.comname: 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:
- macOS
- Windows
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
To enable debug logs in VNet, first stop Teleport Connect. Then in the Start menu look for Command Prompt and from the right click menu select Run as administrator. The following command enables debug logs in VNet and immediately closes the admin command prompt to prevent you from starting Teleport Connect as an admin by mistake.
reg.exe ADD HKLM\SYSTEM\CurrentControlSet\Services\TeleportVNet /v Environment /t REG_MULTI_SZ /d TELEPORT_DEBUG=1 /f && exit
Next, from the Start menu open the Run app. Execute the following to start Teleport Connect with debug logs enabled:
"%PROGRAMFILES%\Teleport Connect\Teleport Connect.exe" --connect-debug
Next, attempt to reproduce the issue with VNet.
Once that's done, execute the following command from the administrator Command Prompt to disable debug logs in VNet:
reg.exe DELETE HKLM\SYSTEM\CurrentControlSet\Services\TeleportVNet /v Environment /f
The last step is collecting the logs. Let's start with the VNet logs. From the Start menu, open Event Viewer. From the sidebar on the left, select Event Viewer (Local) → Applications and Services Logs → Teleport. From the sidebar on the right, select "Save All Events As…". Save the logs as .evtx file. If Event Viewer asks about Display Information, choose "No display information".
To gather logs from Teleport Connect, press Alt
while in the app, then select Help → Open Logs
Directory. This opens C:\Users\%UserName%\AppData\Roaming\Teleport Connect\logs
. Attach all files
together with the .evtx file from the previous step.
Outside of submitting an issue, VNet logs can be quickly saved to a file with the following PowerShell command. However, when submitting an issue please attach the .evtx file instead.
Get-WinEvent -LogName Teleport -FilterXPath "*[System[Provider[@Name='vnet']]]" -Oldest | Format-Table -Property TimeCreated,LevelDisplayName,Message -Wrap | Out-File vnet.log
Before version 18.0.0, VNet logs were saved in C:\Program Files\Teleport Connect\resources\bin\logs.txt
.