You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Pomerium is capable of creating secure connections to services like SSH, Redis, and more by creating a TCP tunnel to the service with a local client. This article describes configuring a route to accept TCP connections, and using either the CLI or GUI client to connect to it.
24
+
This document describes how to use Pomerium's Desktop and CLI clients to connect to TCP routes in Pomerium.
26
25
27
-
## Create a TCP Route
26
+
:::info What's a TCP route?
28
27
29
-
1. Specify this new Route as a TCP Route by prefixing `tcp+` in the **From** field, along with a port suffix.
28
+
A TCP route is for use with upstream services that don't speak HTTP — for example SSH, Redis, or MySQL. With a TCP route, the entire connection is proxied to the upstream service, rather than each individual request separately.
30
29
31
-
The port is not used to connect to the Pomerium Proxy service from the internet; this will always be port 443 (unless otherwise defined in `config.yaml`). Rather, the port defined in **From**is part of the mapping to the individual route. In this way, you can create multiple routes that share a DNS entry, differentiated by the port to determine which route they use.
30
+
In Pomerium, TCP routes are denoted with a `tcp+` prefix in the route's **From**URL.
32
31
33
-
For example, suppose we have a server called `augur` running behind Pomerium that has a MySQL server and also listens for SSH connections. We can create routes for `tcp+https://augur.example.com:22` and `tcp+https://augur.example.com:3306`.
32
+
:::
33
+
34
+
## Create a TCP route
34
35
35
-
1. The **To** field uses `tcp://` as a protocol, and specifies the address and port the service listens on.
36
+
1. Specify this new Route as a TCP Route by prefixing `tcp+` in the **From** field, along with a port number
37
+
1. Set the **To** field using `tcp://` as the scheme, along with the address and port that the upstream service is listening on
36
38
37
-
The example below demonstrates a route to the SSH service on the host running the Pomerium Core or Pomerium Enterprise service:
39
+
The example below demonstrates a route to an SSH service on the host running Pomerium:
Download the latest release from [GitHub](https://github.com/pomerium/desktop-client/releases).
73
-
74
-
- **Windows**: The installer `.exe` file will install and open the Desktop Client. Right click on the system tray icon to interact with it.
75
-
- **Linux**: We provide Linux binaries as `.AppImage` files, which can be executed in place or managed with a tool like [AppImageLauncher](https://github.com/TheAssassin/AppImageLauncher). Interact with the client from the system tray icon.
76
-
- **macOS**: Open the `dmg` and move the binary to **Applications**. Interact with the client from the system tray icon.
77
-
78
-
<details>
79
-
<summary>Autostart Pomerium Desktop</summary>
80
-
81
-
If you want Pomerium Desktop to start automatically when you log in to your computer, follow the steps below for your operating system.
82
-
83
-
<Tabs>
84
-
<TabItem value="windows" label="Windows">
85
-
86
-
#### Autostart for all users
87
-
88
-
Copy the shortcut for the Pomerium Desktop app into `C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Startup`.
89
-
90
-
#### Autostart for your user
91
-
92
-
Copy the shortcut for the Pomerium Desktop app into `C:\Users\username\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup`, replacing `username` with your username.
62
+
:::tip
93
63
94
-
---
95
-
96
-
Windows 11 also offers a GUI method, documented by [windowscentral.com](https://www.windowscentral.com/how-launch-apps-automatically-during-login-windows-11)
97
-
98
-
</TabItem>
99
-
<TabItem value="mac" label="MacOS">
100
-
101
-
1. From **System Preferences**, select **Users & Groups**.
102
-
103
-
1. Click **Login Items** near the top, then the **+** button towards the bottom of the window.
104
-
105
-
1. Select Pomerium Desktop from the Applications folder.
106
-
107
-
</TabItem>
108
-
<TabItem value="gnome" label="Linux (Gnome)">
109
-
110
-
The easiest way to autostart user applications in the Gnome Desktop Environment is by using the Tweaks application. Gnome documents this process well, so we won't replicate it here. See [Gnome's documentation](https://help.gnome.org/users/gnome-help/stable/shell-apps-auto-start.html) for more information.
111
-
112
-
</TabItem>
113
-
<TabItem value="kde" label="Linux (KDE)">
114
-
115
-
KDE's documentation covers auto-starting applications well: see [System Settings/Autostart](https://userbase.kde.org/System_Settings/Autostart) from the KDE UsersBase Wiki for more information.
116
-
117
-
</TabItem>
118
-
</Tabs>
119
-
120
-
</details>
64
+
The port number in the route **From** URL is not used in the initial connection to Pomerium itself. This connection will still use port 443, unless you use a bastion host (see [**Advanced configuration**](#advanced-configuration) below).
121
65
122
-
### Add a Connection
66
+
Rather, the port defined in **From** is part of the mapping to the individual route. In this way, you can create multiple routes that share a DNS entry, differentiated by the port to determine which route they use.
123
67
124
-
68
+
For example, suppose we have a server called `augur` running behind Pomerium that has a MySQL server and also listens for SSH connections. We can create routes for `tcp+https://augur.example.com:22` and `tcp+https://augur.example.com:3306`.
125
69
126
-
**Name**: A local name for the route.
70
+
:::
127
71
128
-
**Destination**: Matches the [From](/docs/reference/routes/from) value of the route, without the protocol. Always include the port specified in the route, and do not include the `https://` protocol.
72
+
See the "Configure Routes" section of [TCP Support](/docs/capabilities/tcp#configure-routes) for more detailed information on TCP routes.
129
73
130
-
**Local Address**: The local address and port number from which to access the service locally. If left blank, the client will choose a random port to listen to on the loopback address.
74
+
## Access TCP routes with a client
131
75
132
-
In most cases, you only need to specify the port (ex: `:2222`), and the client will listen on all available local addresses.
76
+
You can connect to this route with either the Pomerium CLI or Pomerium Desktop client.
133
77
134
-
**Tags**: Use tags to sort and organize your TCP routes.
78
+
### Desktop client steps
135
79
136
-
:::note Long-lived connections behavior
80
+
If you haven't, install [Pomerium Desktop](/docs/deploy/clients/pomerium-desktop).
137
81
138
-
<LongLivedConnections />
82
+
Then, add a connection by filling in the fields defined below:
139
83
140
-
:::
84
+
- **Name**: A local name for the route
85
+
- **Destination**: Matches the [From](/docs/reference/routes/from) value of the route, without the protocol. Always include the port specified in the route, and do not include the `https://` protocol.
86
+
- **Local Address**: The local address and port number from which to access the service locally. If left blank, the client will choose a random port to listen to on the loopback address.
87
+
- **Tags**: Customizable tags to sort and organize TCP routes
141
88
142
-
---
89
+
143
90
144
91
#### Advanced Settings
145
92
146
-
**Pomerium URL**: The Pomerium Proxy service address. This is required if the **Destination URL** can't be resolved from DNS or a local `hosts` entry, or if the Proxy service uses a non-standard port.
93
+
- **Pomerium URL**: The Pomerium Proxy service address. This is required if the **Destination URL** can't be resolved from DNS or a local `hosts` entry, or if the Proxy service uses a non-standard port.
94
+
- **Disable TLS Verification**: Allows untrusted certificates from the Pomerium gateway
95
+
- **Client Certificates**: For routes that enforce [mTLS](/docs/concepts/mutual-auth), you can **set a client certificate manually** or automatically [**search the OS certificate store**](/docs/capabilities/tcp#client-certificates) for a trusted certificate (note: macOS and Windows only).
147
96
148
-
**Disable TLS Verification**: Allows untrusted certificates from the Pomerium gateway
97
+
149
98
150
-
**Client Certificate & Certificate Key File or Text**: For routes that require client certificates for [mTLS](/docs/concepts/mutual-auth.md), you can provide the certificate and key file to the Pomerium Desktop client.
If you haven't, install [Pomerium CLI](/docs/deploy/clients/pomerium-cli).
154
102
155
-
### Install
103
+
Then, connect to a TCP route:
156
104
157
-
See the [Pomerium CLI](/docs/deploy/clients/pomerium-cli) page to learn how to install `pomerium-cli` in your environment.
158
-
159
-
### Connect to a TCP Route
160
-
161
-
1. Invoke `pomerium-cli` with the `tcp` option, and provide the route to your service (As defined in [`from`](/docs/reference/routes/from) in your Route specification).
105
+
1. Invoke `pomerium-cli` with the `tcp` option, and provide the route to your service (as defined in [`from`](/docs/reference/routes/from) in your Route specification).
162
106
163
107
```shell-session
164
108
$ pomerium-cli tcp ssh.localhost.pomerium.io:22
@@ -178,20 +122,24 @@ See the [Pomerium CLI](/docs/deploy/clients/pomerium-cli) page to learn how to i
178
122
ssh 127.0.0.1 -p 2222
179
123
```
180
124
181
-
1. When the connection starts, the cli will open your browser and direct you to your Identity Provider to authenticate your session. Once authenticated the connection will continue and you can close the browser window.
125
+
1. When the connection starts, the CLI will open your browser and direct you to your Identity Provider to authenticate your session. Once authenticated, the connection will continue and you can close the browser window.
182
126
183
127
1. In this example, since we are using SSH we can consolidate the TCP and SSH connections into a single command:
If Pomerium is listening on a port other than `443` (set with the [`address` key](/docs/reference/address)), the full TCP URL can be specified with a bastion host:
Copy file name to clipboardexpand all lines: content/docs/deploy/clients/pomerium-desktop.mdx
+9-3
Original file line number
Diff line number
Diff line change
@@ -21,16 +21,22 @@ keywords:
21
21
sidebar_position: 4
22
22
---
23
23
24
-
# Pomerium Desktop (GUI)
24
+
# Pomerium Desktop
25
25
26
-
Pomerium desktop (optional, optional, Pomerium is clientless for HTTP based protocols) does everything `pomerium-cli` does, but is geared towards users who prefer a graphical user interface. Functions include acting as an authentication helper for tools like [kubectl](/docs/deploy/k8s/configure.md) or TCP [based applications](/docs/capabilities/tcp/).
26
+
Pomerium Desktop does everything `pomerium-cli` does, but is designed for users who prefer a graphical user interface.
27
+
28
+
Functions include acting as an authentication helper for tools like [kubectl](/docs/deploy/k8s/configure.md) or TCP [based applications](/docs/capabilities/tcp/).
The Desktop Client is available from [GitHub](https://github.com/pomerium/desktop-client/releases) as an `exe`, `dmg`, and `AppImage`.
35
+
Download the latest release from [GitHub](https://github.com/pomerium/desktop-client/releases).
36
+
37
+
-**Windows**: The installer `.exe` file will install and open the Desktop Client. Right click on the system tray icon to interact with it.
38
+
-**Linux**: We provide Linux binaries as `.AppImage` files, which can be executed in place or managed with a tool like [AppImageLauncher](https://github.com/TheAssassin/AppImageLauncher). Interact with the client from the system tray icon.
39
+
-**macOS**: Open the `dmg` and move the binary to **Applications**. Interact with the client from the system tray icon.
0 commit comments