-
Notifications
You must be signed in to change notification settings - Fork 18
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update desktop docs #1374
Merged
Merged
Update desktop docs #1374
Changes from all commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
0f3edb3
updates desktop images and text
ZPain8464 ee8db8b
runs prettier
ZPain8464 9d0a8bb
removes tabs, adds better images
ZPain8464 3f58327
fixes links
ZPain8464 5a31df4
Update content/docs/capabilities/tcp/client.mdx
ZPain8464 aea56c1
Update content/docs/capabilities/tcp/client.mdx
ZPain8464 88fb5a8
Update content/docs/capabilities/tcp/client.mdx
ZPain8464 0509fe8
adds changes based on feedback
ZPain8464 9c27cb6
runs prettier
ZPain8464 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,7 +2,7 @@ | |
| # cSpell:ignore windowscentral | ||
|
|
||
| title: Pomerium TCP Clients | ||
| sidebar_label: Clients (Desktop / CLI) | ||
| sidebar_label: Desktop & CLI Clients | ||
| lang: en-US | ||
| keywords: | ||
| [ | ||
|
|
@@ -18,25 +18,32 @@ sidebar_position: 0 | |
|
|
||
| import Tabs from '@theme/Tabs'; | ||
| import TabItem from '@theme/TabItem'; | ||
| import LongLivedConnections from '@site/content/docs/admonitions/_long-lived-connections.mdx'; | ||
|
|
||
| # Pomerium Desktop and CLI Clients | ||
|
|
||
| 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. | ||
| This document describes how to use Pomerium's Desktop and CLI clients to connect to TCP routes in Pomerium. | ||
|
|
||
| ## Create a TCP Route | ||
| :::info What's a TCP route? | ||
|
|
||
| 1. Specify this new Route as a TCP Route by prefixing `tcp+` in the **From** field, along with a port suffix. | ||
| 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. | ||
|
|
||
| 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. | ||
| In Pomerium, TCP routes are denoted with a `tcp+` prefix in the route's **From** URL. | ||
|
|
||
| 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`. | ||
| ::: | ||
|
|
||
| ## Create a TCP route | ||
|
|
||
| 1. The **To** field uses `tcp://` as a protocol, and specifies the address and port the service listens on. | ||
| 1. Specify this new Route as a TCP Route by prefixing `tcp+` in the **From** field, along with a port number | ||
| 1. Set the **To** field using `tcp://` as the scheme, along with the address and port that the upstream service is listening on | ||
|
|
||
| The example below demonstrates a route to the SSH service on the host running the Pomerium Core or Pomerium Enterprise service: | ||
| The example below demonstrates a route to an SSH service on the host running Pomerium: | ||
|
|
||
| <Tabs> | ||
| <TabItem value="Pomerium Enterprise" label="Pomerium Enterprise"> | ||
|
|
||
|  | ||
|
|
||
| </TabItem> | ||
| <TabItem value="Pomerium Core" label="Pomerium Core"> | ||
|
|
||
| ```yaml | ||
|
|
@@ -49,116 +56,53 @@ The example below demonstrates a route to the SSH service on the host running th | |
| is: [email protected] | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| <TabItem value="Pomerium Enterprise" label="Pomerium Enterprise"> | ||
|
|
||
|  | ||
|
|
||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| See the "Configure Routes" section of [TCP Support](/docs/capabilities/tcp#configure-routes) for more detailed information on TCP routes. | ||
|
|
||
| ## TCP Client Software | ||
|
|
||
| You can connect to this route with either the Pomerium CLI or Pomerium Desktop client. | ||
|
|
||
| <Tabs> | ||
|
|
||
| <TabItem value="Pomerium Desktop" label="Pomerium Desktop"> | ||
|
|
||
| ### Install | ||
|
|
||
| Download the latest release from [GitHub](https://github.com/pomerium/desktop-client/releases). | ||
|
|
||
| - **Windows**: The installer `.exe` file will install and open the Desktop Client. Right click on the system tray icon to interact with it. | ||
| - **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. | ||
| - **macOS**: Open the `dmg` and move the binary to **Applications**. Interact with the client from the system tray icon. | ||
|
|
||
| <details> | ||
| <summary>Autostart Pomerium Desktop</summary> | ||
|
|
||
| If you want Pomerium Desktop to start automatically when you log in to your computer, follow the steps below for your operating system. | ||
|
|
||
| <Tabs> | ||
| <TabItem value="windows" label="Windows"> | ||
|
|
||
| #### Autostart for all users | ||
|
|
||
| Copy the shortcut for the Pomerium Desktop app into `C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Startup`. | ||
|
|
||
| #### Autostart for your user | ||
|
|
||
| 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. | ||
| :::tip | ||
|
|
||
| --- | ||
|
|
||
| Windows 11 also offers a GUI method, documented by [windowscentral.com](https://www.windowscentral.com/how-launch-apps-automatically-during-login-windows-11) | ||
|
|
||
| </TabItem> | ||
| <TabItem value="mac" label="MacOS"> | ||
|
|
||
| 1. From **System Preferences**, select **Users & Groups**. | ||
|
|
||
| 1. Click **Login Items** near the top, then the **+** button towards the bottom of the window. | ||
|
|
||
| 1. Select Pomerium Desktop from the Applications folder. | ||
|
|
||
| </TabItem> | ||
| <TabItem value="gnome" label="Linux (Gnome)"> | ||
|
|
||
| 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. | ||
|
|
||
| </TabItem> | ||
| <TabItem value="kde" label="Linux (KDE)"> | ||
|
|
||
| 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. | ||
|
|
||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| </details> | ||
| 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). | ||
|
|
||
| ### Add a Connection | ||
| 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. | ||
|
|
||
|  | ||
| 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`. | ||
|
|
||
| **Name**: A local name for the route. | ||
| ::: | ||
|
|
||
| **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. | ||
| See the "Configure Routes" section of [TCP Support](/docs/capabilities/tcp#configure-routes) for more detailed information on TCP routes. | ||
|
|
||
| **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. | ||
| ## Access TCP routes with a client | ||
|
|
||
| In most cases, you only need to specify the port (ex: `:2222`), and the client will listen on all available local addresses. | ||
| You can connect to this route with either the Pomerium CLI or Pomerium Desktop client. | ||
|
|
||
| **Tags**: Use tags to sort and organize your TCP routes. | ||
| ### Desktop client steps | ||
|
|
||
| :::note Long-lived connections behavior | ||
| If you haven't, install [Pomerium Desktop](/docs/deploy/clients/pomerium-desktop). | ||
|
|
||
| <LongLivedConnections /> | ||
| Then, add a connection by filling in the fields defined below: | ||
|
|
||
| ::: | ||
| - **Name**: A local name for the route | ||
| - **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. | ||
| - **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. | ||
| - **Tags**: Customizable tags to sort and organize TCP routes | ||
|
|
||
| --- | ||
|  | ||
|
|
||
| #### Advanced Settings | ||
|
|
||
| **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. | ||
| - **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. | ||
| - **Disable TLS Verification**: Allows untrusted certificates from the Pomerium gateway | ||
| - **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). | ||
|
|
||
| **Disable TLS Verification**: Allows untrusted certificates from the Pomerium gateway | ||
|  | ||
|
|
||
| **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. | ||
| ### Pomerium CLI steps | ||
|
|
||
| </TabItem> | ||
| <TabItem value="Pomerium CLI" label="Pomerium CLI"> | ||
| If you haven't, install [Pomerium CLI](/docs/deploy/clients/pomerium-cli). | ||
|
|
||
| ### Install | ||
| Then, connect to a TCP route: | ||
|
|
||
| See the [Pomerium CLI](/docs/deploy/clients/pomerium-cli) page to learn how to install `pomerium-cli` in your environment. | ||
|
|
||
| ### Connect to a TCP Route | ||
|
|
||
| 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). | ||
| 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). | ||
|
|
||
| ```shell-session | ||
| $ 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 | |
| ssh 127.0.0.1 -p 2222 | ||
| ``` | ||
|
|
||
| 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. | ||
| 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. | ||
|
|
||
| 1. In this example, since we are using SSH we can consolidate the TCP and SSH connections into a single command: | ||
|
|
||
| ```bash | ||
| ssh -o ProxyCommand='pomerium-cli tcp --listen - %h:%p' ssh.localhost.pomerium.io | ||
| ``` | ||
|
|
||
| </TabItem> | ||
| </Tabs> | ||
| :::info | ||
|
|
||
| For more examples and detailed usage information, see [TCP Support](/docs/capabilities/tcp) | ||
| For more examples and detailed usage information, see the following docs: | ||
|
|
||
| - [**TCP Reference**](/docs/capabilities/tcp/reference) | ||
| - [**Securing TCP-based Services**](/docs/guides/securing-tcp) | ||
|
|
||
| ::: | ||
|
|
||
| ## Advanced Configuration | ||
| ## Advanced configuration | ||
|
|
||
| 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: | ||
|
|
||
|
|
||
Binary file added
BIN
+53.2 KB
content/docs/capabilities/tcp/examples/img/desktop/advanced-settings.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed
BIN
-42.5 KB
content/docs/capabilities/tcp/examples/img/desktop/demo-new-connection.png
Binary file not shown.
Binary file added
BIN
+40.3 KB
content/docs/capabilities/tcp/examples/img/desktop/desktop-new-connection.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we should keep this information available somewhere, but I'd agree that this page might not be the best place for it.
What do you think about moving it onto the https://www.pomerium.com/docs/deploy/clients/pomerium-desktop page, along with the installation instructions?