diff --git a/docs/img/vnet/configure-ssh-clients.png b/docs/img/vnet/configure-ssh-clients.png
new file mode 100644
index 0000000000000..522856f80bfbb
Binary files /dev/null and b/docs/img/vnet/configure-ssh-clients.png differ
diff --git a/docs/img/vnet/how-it-works.svg b/docs/img/vnet/how-it-works.svg
index e37da9d95d0e8..c3f47d4d8d486 100644
--- a/docs/img/vnet/how-it-works.svg
+++ b/docs/img/vnet/how-it-works.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/docs/img/vnet/ssh-connect.png b/docs/img/vnet/ssh-connect.png
new file mode 100644
index 0000000000000..2baeee20e737f
Binary files /dev/null and b/docs/img/vnet/ssh-connect.png differ
diff --git a/docs/img/vnet/start-vnet.png b/docs/img/vnet/start-vnet.png
new file mode 100644
index 0000000000000..81d03e073624b
Binary files /dev/null and b/docs/img/vnet/start-vnet.png differ
diff --git a/docs/pages/connect-your-client/teleport-connect.mdx b/docs/pages/connect-your-client/teleport-connect.mdx
index bd666ab4ba784..94df94e6d9d22 100644
--- a/docs/pages/connect-your-client/teleport-connect.mdx
+++ b/docs/pages/connect-your-client/teleport-connect.mdx
@@ -87,6 +87,9 @@ A new tab will open with a shell session on the chosen server.
Alternatively, you can look for the server in the search bar and press `Enter` to connect to it.
+If you'd prefer to connect to SSH servers with a third-party SSH client or your
+editor's Remote Development feature, read the [VNet guide](./vnet.mdx) to learn how.
+
## Opening a local terminal
To open a terminal with a local shell session, either select "Open new terminal" from the additional
diff --git a/docs/pages/connect-your-client/vnet.mdx b/docs/pages/connect-your-client/vnet.mdx
index 62752c43c8fea..c5c497750b449 100644
--- a/docs/pages/connect-your-client/vnet.mdx
+++ b/docs/pages/connect-your-client/vnet.mdx
@@ -3,23 +3,31 @@ title: Using VNet
description: Using VNet
---
-This guide explains how to use VNet to connect to TCP applications available through Teleport.
+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 available
-through Teleport.
-A program on your device can securely connect to internal applications protected
+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 TCP connection to your application.
+securely tunnels the connection.
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.
+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](../admin-guides/access-controls/guides/per-session-mfa.mdx)
+and [Hardware Key Support](../admin-guides/access-controls/guides/hardware-key-support.mdx).
-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 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.
@@ -37,17 +45,21 @@ for Linux support in a future version.
-## Step 1/3. Start Teleport Connect
+## Step 1/3. Start VNet
-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.
+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.
-## 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.
+After VNet has been started once it will automatically start every time
+Teleport Connect is opened, unless you stop VNet before closing Teleport
+Connect.
First launch on macOS
@@ -59,15 +71,28 @@ tsh.app under "Allow in the Background".
-## Step 3/3. Connect
+## 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.
-Once VNet is running, you can connect to the application using the application client you would
+
+
+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://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](../enroll-resources/application-access/guides/tcp.mdx#configuring-access-to-multiple-ports),
@@ -79,19 +104,52 @@ If [per-session MFA](../admin-guides/access-controls/guides/per-session-mfa.mdx)
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.
+## 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.
+
+```code
+$ ssh @.
+```
+
+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 available in `tsh` as well. Using it involves logging into the cluster and executing the
-command `tsh vnet`.
+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.
+
## Troubleshooting
### Conflicting IPv4 ranges
@@ -234,3 +292,4 @@ Before version 18.0.0, VNet logs were saved in `C:\Program Files\Teleport Connec
- Read our VNet configuration [guide](../enroll-resources/application-access/guides/vnet.mdx)
to learn how to configure VNet access to your applications.
- Read [RFD 163](https://github.com/gravitational/teleport/blob/master/rfd/0163-vnet.md) to learn how VNet works on a technical level.
+- Read [RFD 207](https://github.com/gravitational/teleport/blob/master/rfd/0207-vnet-ssh.md) to learn how VNet SSH access works.
diff --git a/web/packages/teleterm/src/ui/Vnet/DocumentVnetInfo.tsx b/web/packages/teleterm/src/ui/Vnet/DocumentVnetInfo.tsx
index d21ed692f32a6..95481bd6aeaa0 100644
--- a/web/packages/teleterm/src/ui/Vnet/DocumentVnetInfo.tsx
+++ b/web/packages/teleterm/src/ui/Vnet/DocumentVnetInfo.tsx
@@ -236,8 +236,9 @@ export function DocumentVnetInfo(props: {
SSH Servers With 3rd-Party SSH Clients
- {/* TODO(nklaassen): link to new VNet SSH docs */}
- Learn More
+
+ Learn More
+