teleport/docs/pages/connect-your-client/teleport-clients/vnet.mdx

---
title: Using VNet
sidebar_label: VNet
description: Using VNet
tags:
 - how-to
 - zero-trust
 - infrastructure-identity
page_type: how-to
---

This guide shows you 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](../../zero-trust-access/authentication/per-session-mfa.mdx)
and [Hardware Key Support](../../zero-trust-access/authentication/hardware-key-support.mdx).

![Diagram showing VNet architecture](../../../img/vnet/how-it-works.svg)

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, Windows, and Linux in Teleport Connect and tsh.

<Admonition type="warning">
VNet's VPN-like experience for app access means that any software running on
the client machine can access Teleport apps at local DNS or IP addresses.

**Avoid running VNet on shared or multi-user machines.**
If multiple OS users share the same machine, any user could access Teleport TCP
apps at their local VNet DNS or IP address.

**Protect HTTP services behind VNet.**
Untrusted websites can potentially use DNS rebinding attacks to bypass the
browser’s Same-Origin Policy and issue plain HTTP requests to VNet IP addresses.
If your Teleport cluster contains TCP apps serving plain HTTP APIs, it is
strongly recommended to either avoid VNet or implement one or more of the
following mitigations for DNS rebinding attacks:
- upgrade these APIs to HTTPS or another protocol
- enforce a Host header allowlist at the HTTP server
- block browser access to HTTP websites
</Admonition>

## Prerequisites

<Tabs>
<TabItem label="macOS">
- A client machine running macOS Ventura (13.0) or higher.
- [Teleport Connect](teleport-connect.mdx).
</TabItem>
<TabItem label="Windows">
- A client machine running Windows 10 or higher.
- [Teleport Connect](teleport-connect.mdx), version 17.3.0 or higher, installed in per-machine mode ("Anyone who uses this computer").
</TabItem>
<TabItem label="Linux">
- A client machine running a Linux distro with systemd, systemd-resolved, polkit, and D-Bus.
- [Teleport Connect](teleport-connect.mdx), version 18.8.0 or higher.
</TabItem>
</Tabs>

## Step 1/3. Start VNet

Open Teleport Connect and log in to your cluster.
See [Using Teleport Connect](./teleport-connect.mdx) 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.

![VNet shown in connection list](../../../img/vnet/start-vnet.png)

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>
<summary>First launch on macOS</summary>

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".

![VNet starting up](../../../img/use-teleport/[email protected])
</details>

## 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.

![Resource list in Teleport Connect with a TCP app hovered over](../../../img/use-teleport/[email protected])

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.

```code
$ psql postgres://[email protected]/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.

<Admonition type="note" title="Support for multiple ports">
Unless the application specifies [multiple
ports](../../enroll-resources/application-access/protect-apps/tcp.mdx#configuring-access-to-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](../../zero-trust-access/authentication/per-session-mfa.mdx) is enabled, the
first connection over each port triggers an MFA check.
</Admonition>

## 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.

![SSH server in Teleport Connect with "Connect with VNet" menu open](../../../img/vnet/ssh-connect.png)

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.

![SSH client configuration modal in Teleport Connect](../../../img/vnet/configure-ssh-clients.png)

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.

```code
$ 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`.

```code
$ tsh login --proxy=teleport.example.com
$ tsh 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.

<details>
<summary>Running tsh vnet on Linux without Teleport Connect</summary>

VNet on Linux requires a systemd unit, a polkit policy, and a D-Bus service
file to be installed on the system. These files are bundled with the
[Teleport Connect](teleport-connect.mdx) package and deployed during installation.
If you use `tsh vnet` without Teleport Connect, you should install these files
manually.
See [`examples/systemd/vnet`](https://github.com/gravitational/teleport/tree/branch/v(=teleport.major_version=)/examples/systemd/vnet)
in the Teleport repository.
</details>

## 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](../../enroll-resources/application-access/vnet.mdx#configuring-ipv4-cidr-range).

### 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 on macOS

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 <Var
name="tcp-app.teleport.example.com" /> with the name of your app:

<Tabs>
<TabItem label="macOS">
```code
$ dscacheutil -q host -a name <Var name="tcp-app.teleport.example.com" />
name: tcp-app.teleport.example.com
ipv6_address: fd60:67ec:4325::647a:547d

name: tcp-app.teleport.example.com
ip_address: 100.68.51.151
```
</TabItem>
<TabItem label="Windows">
```code
# In PowerShell.
$ Resolve-DnsName <Var name="tcp-app.teleport.example.com" />

Name                                           Type   TTL   Section    IPAddress
----                                           ----   ---   -------    ---------
tcp-app.teleport.example.com                   AAAA   10    Answer     fd60:67ec:4325::647a:547d
tcp-app.teleport.example.com                   A      10    Answer     100.68.51.151
```
</TabItem>
<TabItem label="Linux">
```code
$ resolvectl query <Var name="tcp-app.teleport.example.com" />
tcp-app.teleport.example.com: 100.68.51.151               -- link: TeleportVNet
                              fd60:67ec:4325::647a:547d   -- link: TeleportVNet

-- Information acquired via protocol DNS in 3.9ms.
-- Data is authenticated: no; Data was acquired via local or encrypted transport: no
-- Data from: network
```
</TabItem>
</Tabs>

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:

```code
$ dscacheutil -q host -a name dashboard.teleport.example.com
name: dashboard.teleport.example.com
ipv6_address: 2606:2800:21f:cb07:6820:80da:af6b:8b2c

name: dashboard.teleport.example.com
ip_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](#submitting-an-issue) on how to enable debug logs).

### Submitting an issue

When [submitting an
issue](https://github.com/gravitational/teleport/issues/new?assignees=&labels=bug,vnet&template=bug_report.md),
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:

<Tabs>
<TabItem label="macOS">
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:

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

Next, start capturing logs from VNet into a file:

```code
$ 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:

```code
$ 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.

{/* TODO: DELETE IN 21.0.0 */}
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:

```code
$ grep tsh /var/log/com.apple.xpc.launchd/launchd.log
```
</TabItem>
<TabItem label="Windows">
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.

```code
$ 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:

```code
$ "%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:

```code
$ 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.

```code
$ Get-WinEvent -LogName Teleport -FilterXPath "*[System[Provider[@Name='vnet']]]" -Oldest | Format-Table -Property TimeCreated,LevelDisplayName,Message -Wrap | Out-File vnet.log
```

{/* TODO: DELETE IN 21.0.0 */}
Before version 18.0.0, VNet logs were saved in `C:\Program Files\Teleport Connect\resources\bin\logs.txt`.
</TabItem>
<TabItem label="Linux">
To enable debug logs in VNet, first stop Teleport Connect. Then edit the VNet systemd service to
add a debug environment variable:

```code
$ sudo systemctl edit teleport-vnet.service
```

In the editor add the following, then save and exit:

```
[Service]
Environment=TELEPORT_DEBUG=1
```

Restart the service to pick up the new setting:

```code
$ sudo systemctl restart teleport-vnet.service
```

Next, start capturing VNet logs into a file:

```code
$ journalctl -fu teleport-vnet.service > vnet.log
```

In a separate terminal, start Teleport Connect with debug logs enabled:

```code
$ teleport-connect --connect-debug
```

Next, attempt to reproduce the issue with VNet.

Once that's done, stop capturing `journalctl` output, then disable debug logs in VNet with:

```code
$ sudo systemctl revert teleport-vnet.service
```

To gather logs from Teleport Connect, attach all files from
`~/.config/Teleport Connect/logs/` together with `vnet.log` produced in the earlier step.
</TabItem>
</Tabs>

## Next steps

- Read our VNet configuration [guide](../../enroll-resources/application-access/vnet.mdx)
  to learn how to configure VNet access to your applications.
- Read [RFD 163](https://github.com/gravitational/teleport/blob/8ff3d34581424302182c217e4d8d3be45bf2b0b7/rfd/0163-vnet.md) to learn how VNet works on a technical level.
- Read [RFD 207](https://github.com/gravitational/teleport/blob/8ff3d34581424302182c217e4d8d3be45bf2b0b7/rfd/0207-vnet-ssh.md) to learn how VNet SSH access works.