Skip to content
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.

Sign up for GitHub

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 9 commits into from
Apr 26, 2024
Merged

Update desktop docs #1374

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
0f3edb3
updates desktop images and text
ZPain8464 Apr 25, 2024
ee8db8b
runs prettier
ZPain8464 Apr 25, 2024
9d0a8bb
removes tabs, adds better images
ZPain8464 Apr 26, 2024
3f58327
fixes links
ZPain8464 Apr 26, 2024
5a31df4
Update content/docs/capabilities/tcp/client.mdx
ZPain8464 Apr 26, 2024
aea56c1
Update content/docs/capabilities/tcp/client.mdx
ZPain8464 Apr 26, 2024
88fb5a8
Update content/docs/capabilities/tcp/client.mdx
ZPain8464 Apr 26, 2024
0509fe8
adds changes based on feedback
ZPain8464 Apr 26, 2024
9c27cb6
runs prettier
ZPain8464 Apr 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 52 additions & 94 deletions content/docs/capabilities/tcp/client.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
[
Expand All @@ -22,21 +22,32 @@ import LongLivedConnections from '@site/content/docs/admonitions/_long-lived-con

# 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
:::note TCP Terminology

1. Specify this new Route as a TCP Route by prefixing `tcp+` in the **From** field, along with a port suffix.
In this document, a "TCP route" refers to a route configured to accept TCP connections.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is a good idea — it's natural for a reader to have the question "what's a TCP route" here.

I think we could make this even clearer by comparing with "regular" http/https routes.

What do you think of something like this?

:::info What's a TCP route?

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.

In Pomerium, TCP routes are denoted with a `tcp+` prefix in the route's **From** URL.


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

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. The **To** field uses `tcp://` as a protocol, and specifies the address and port the service listens 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 Zero" label="Pomerium Zero">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the Zero screenshot, but I think it might be better to add this in a separate PR, so we can go ahead and backport this one.


![Creating a TCP route in the Zero Console](./examples/img/desktop/zero-ssh-route-example.png)

</TabItem>
<TabItem value="Pomerium Enterprise" label="Pomerium Enterprise">

![Example TCP route for SSH](./img/tcp-ssh-route.png)

</TabItem>
<TabItem value="Pomerium Core" label="Pomerium Core">

```yaml
Expand All @@ -49,116 +60,59 @@ 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">

![Example TCP route for SSH](./img/tcp-ssh-route.png)

</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>
Copy link
Contributor

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?


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
:::note

Copy the shortcut for the Pomerium Desktop app into `C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Startup`.
The port suffix appended to the **From** route is not used to connect to the Pomerium Proxy service from the internet; this will always be port 443 (unless otherwise defined in the configuration file).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I think I deleted a pending comment somehow. I think this could be made a little clearer, along the lines of:

:::tip

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


#### Autostart for your user
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.

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

---

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>
See the "Configure Routes" section of [TCP Support](/docs/capabilities/tcp#configure-routes) for more detailed information on TCP routes.

### Add a Connection
## Access TCP routes with a client

![A new connection to an SSH gateway](examples/img/desktop/demo-new-connection.png)
You can connect to this route with either the Pomerium CLI or Pomerium Desktop client.

**Name**: A local name for the route.
### Desktop client steps

**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.
If you haven't, install [Pomerium Desktop](/docs/deploy/clients/pomerium-desktop).

**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.
Then, add a connection by filling in the fields defined below:

In most cases, you only need to specify the port (ex: `:2222`), and the client will listen on all available local addresses.
- **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

**Tags**: Use tags to sort and organize your TCP routes.
![Adding a new connection in the Pomerium Desktop client](./examples/img/desktop/desktop-new-connection.png)

:::note Long-lived connections behavior
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This admonition feels out of place to me. I think it might make sense to remove it, so this section can focus on the "how-to".


<LongLivedConnections />

:::

---

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

**Disable TLS Verification**: Allows untrusted certificates from the Pomerium gateway
- **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**: The client certificates options allow you to **set client certificates manually** or to [**search the OS certificate store**](/docs/capabilities/tcp#client-certificates) for trusted CA names. Use these options to add client certificates to routes that enforce [mTLS](/docs/concepts/mutual-auth).

**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.
![Reviewing the Advanced Settings in the Pomerium Desktop client](./examples/img/desktop/advanced-settings.png)

</TabItem>
<TabItem value="Pomerium CLI" label="Pomerium CLI">

### Install
### Pomerium CLI steps

See the [Pomerium CLI](/docs/deploy/clients/pomerium-cli) page to learn how to install `pomerium-cli` in your environment.
If you haven't, install [Pomerium CLI](/docs/deploy/clients/pomerium-cli).

### Connect to a TCP Route
Then, 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
Expand All @@ -178,20 +132,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:

Expand Down
Binary file added content/docs/capabilities/tcp/examples/img/desktop/advanced-settings.png
View file
Open in desktop
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 content/docs/capabilities/tcp/examples/img/desktop/demo-new-connection.png
View file
Open in desktop
Binary file not shown.
Binary file added content/docs/capabilities/tcp/examples/img/desktop/desktop-new-connection.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added content/docs/capabilities/tcp/examples/img/desktop/zero-ssh-route-example.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading