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

Add OpenSSH Proxy Jump docs #13170

Merged
merged 10 commits into from
Jun 24, 2022
Merged

Add OpenSSH Proxy Jump docs #13170

Changes from 2 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
f430f20
Add openssh proxy jump docs.
Joerger Jun 3, 2022
0e5018c
Merge branch 'master' into joerger/prxtpl-docs
Joerger Jun 8, 2022
36553b1
Resolve comments; Update docs/rfd to reflect that %h:%p is replaced b…
Joerger Jun 13, 2022
5d6c3c2
Merge branch 'master' into joerger/prxtpl-docs
Joerger Jun 13, 2022
d4bdafd
Resolve comments; replace full host wording with host server address.
Joerger Jun 15, 2022
e8c1ee3
Merge branch 'master' into joerger/prxtpl-docs
Joerger Jun 15, 2022
cebf01c
Merge branch 'master' into joerger/prxtpl-docs
Joerger Jun 21, 2022
f8bed0a
Make docs more instructional.
Joerger Jun 22, 2022
2eecef3
Resolve comments.
Joerger Jun 24, 2022
26e7f78
Merge branch 'master' into joerger/prxtpl-docs
Joerger Jun 24, 2022
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
65 changes: 65 additions & 0 deletions docs/pages/server-access/guides/openssh.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -340,6 +340,71 @@ authenticate the host via the certificate we generated earlier.

</Details>

<Details title="Using Proxy Jump in Trusted Clusters?">
Joerger marked this conversation as resolved.
Show resolved Hide resolved

Normally, you connect to leaf cluster SSH nodes through the root cluster proxy,
Joerger marked this conversation as resolved.
Show resolved Hide resolved
which is provided in the `ProxyCommand` line of the SSH config generated above.

In scenarios where leaf proxies are reachable by SSH clients, you might prefer
Joerger marked this conversation as resolved.
Show resolved Hide resolved
to connect directly through the leaf proxies to avoid potential latency issues
Joerger marked this conversation as resolved.
Show resolved Hide resolved
of the connection being routed through the root cluster.

To support this scenario, the `tsh proxy ssh` command provides the `-J` flag.
This flag points at a cluster's web proxy address and indicates that the
Joerger marked this conversation as resolved.
Show resolved Hide resolved
OpenSSH client will be connecting through that proxy instead of the proxy
you're currently logged into:

```txt
Host *.{{ .NodeName }}.{{ .ClusterName }}
Port 3022
ProxyCommand tsh proxy ssh -J proxy.leaf1.example.com:443 %r@%h:%p
```

The jump proxy address and the node name to connect to can be dynamically
Joerger marked this conversation as resolved.
Show resolved Hide resolved
determined from the SSH config's full hostname spec (`%h:%p`) using `{{proxy}}`
Joerger marked this conversation as resolved.
Show resolved Hide resolved
template variable:
Joerger marked this conversation as resolved.
Show resolved Hide resolved

```txt
Host *.example.com
Port 3022
ProxyCommand tsh proxy ssh -J {{proxy}} %r@%h:%p
```

The rules of how to parse the proxy address and node name from the full host
Joerger marked this conversation as resolved.
Show resolved Hide resolved
spec can be defined in the `tsh` configuration file (`~/.tsh/config/config.yaml`
or a global `/etc/tsh.yaml`):

```yaml
Copy link
Contributor

Choose a reason for hiding this comment

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

This YAML snippet needs some introduction. I would add a paragraph that transitions from the last snippet. For example:

To configure the way `tsh` evaluates the `{{proxy}}` template variable when
using the `-J` flag, add a `proxy_templates` field to your `tsh` configuration
file (`~/.tsh/config/config.yaml` or `/etc/tsh.yaml` for all users on your system):

We could then delete the mention of the tsh configuration file location from above.

Again, if this configuration only applies to the -J flag, I'm guessing we need some explicit instructions for the user to edit their tsh config-created configuration to include the -J flag. Also, we should probably introduce the -J flag outside of this guide, since it looks like it's intended for all tsh commands, not just those involving legacy OpenSSH servers.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Also, we should probably introduce the -J flag outside of this guide, since it looks like it's intended for all tsh commands, not just those involving legacy OpenSSH servers.

We currently mention the -J flag in one other spot - https://goteleport.com/docs/ver/10.0/server-access/guides/tsh/#ssh-jump-host

And then there are there's the ssh man pages which are relevant as well:

     -J destination
             Connect to the target host by first making a ssh connection to the jump host described by destination and then establishing
             a TCP forwarding to the ultimate destination from there.  Multiple jump hops may be specified separated by comma charac‐
             ters.  This is a shortcut to specify a ProxyJump configuration directive.  Note that configuration directives supplied on
             the command-line generally apply to the destination host and not any specified jump hosts.  Use ~/.ssh/config to specify
             configuration for jump hosts.

Do you think we need to expand the tsh jump host section? If so, how will we fit in these docs to include the OpenSSH client integration with tsh config? Maybe that's where an OpenSSH Client guide would come in?

proxy_templates:
- template: '^(\w+)\.(leaf1\.example\.com):(.*)$'
proxy: "$2:443"
- template: '^(\w+)\.(leaf2\.example\.com):(.*)$'
proxy: "$2:3080"
host: "$1"
```

| Field | Description |
| ---------- | ----------- |
| `template` | (Required) Regular expression full SSH config host spec is matched against. |
Joerger marked this conversation as resolved.
Show resolved Hide resolved
| `proxy` | (Required) Web proxy address to use. Can reference regex groups from `template`. |
Joerger marked this conversation as resolved.
Show resolved Hide resolved
| `host` | (Optional) Node name to use. Can reference regex groups from `template`. Defaults to full host spec. |
Joerger marked this conversation as resolved.
Show resolved Hide resolved

Given the configuration above, the following command will connect to the node
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 use "host" instead of "node" when talking about servers that are running openssh but not Teleport. This way, there's no risk of confusion with Teleport Nodes.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

In this case we are talking about connecting to Teleport Nodes with ssh and the openssh configuration file, though it can also be used to connect to openssh hosts. I'll update it to fit both cases.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Actually in this example these are only Teleport nodes. I am adding an example of connecting to an openSSH host though.

Joerger marked this conversation as resolved.
Show resolved Hide resolved
`node-1.leaf1.example.com:3022` through the proxy `leaf1.example.com:443`:
Joerger marked this conversation as resolved.
Show resolved Hide resolved

```code
$ ssh -p 3022 root@node-1.leaf1.example.com
```

The following command will connect to the node `node-1:3022` through the proxy
Joerger marked this conversation as resolved.
Show resolved Hide resolved
`leaf2.example.com:3080`:

```code
$ ssh -p 3022 root@node-1.leaf2.example.com
```

</Details>

<Admonition
type="tip"
title="Multiple Clusters"
Expand Down