Add OpenSSH Proxy Jump docs

[Joerger]

Adds docs for RFD 62: Proxy templates

Implemented in #12848

[ptgott]

Thanks for documenting this! I've restructured the OpenSSH guide so it's easier to follow step by step. I don't think this new section will work with the new structure, as it requires the reader to break away from the sequence of steps. Would it be possible to include these instructions in a new guide, i.e., with its own "Prerequisites" section and "Step n/d" body sections?

[Joerger]

Thanks for documenting this! I've restructured the OpenSSH guide so it's easier to follow step by step. I don't think this new section will work with the new structure, as it requires the reader to break away from the sequence of steps. Would it be possible to include these instructions in a new guide, i.e., with its own "Prerequisites" section and "Step n/d" body sections?

@ptgott I've moved it into it's own details section as I believe this spot in the openssh guide makes the most sense, what do you think?

[ptgott]

I think using a Details section for this is a good idea. I've left some comments.

[Joerger]

@r0mant Can you take a quick look at the RFD updates I added? It was saying that we replace %h with proxy_template.host, but we actually replace the full %h:%p.

[ptgott]

A smaller round of comments this time

[ptgott]

Suggested change

	that the OpenSSH client will be connecting through that proxy instead of the proxy
	that the OpenSSH client will be connecting through that Proxy Service instead of the Proxy Service

To distinguish the Teleport Proxy Service from other proxies

[ptgott]

After looking into this feature a little more, I think we might need to rework these instructions a bit.

• It looks like the -J flag applies to the tsh command as a whole, not just tsh proxy ssh. Should docs re: the -J flag be in a more visible location? This guide is intended for infrastructure with legacy OpenSSH servers, and it looks like the -J flag is more generally applicable.

• It seems like there haven't been any changes to the template used in writeSSHConfig. Should we be instructing users to run tsh config, then manually edit the resulting config to include the ProxyCommand with the -J flag as shown below? Otherwise, I'm not sure this guide is the best place to put the -J flag instructions.

[Joerger]

It looks like the -J flag applies to the tsh command as a whole, not just tsh proxy ssh. Should docs re: the -J flag be in a more visible location? This guide is intended for infrastructure with legacy OpenSSH servers, and it looks like the -J flag is more generally applicable.

The main intention of the proxy templates change is to [improve] tsh proxy command interoperability with ssh client and connecting to leaf cluster proxies directly - https://github.com/gravitational/teleport/blob/master/rfd/0062-tsh-proxy-template.md.

While the -J flag is usable through other commands like tsh ssh -J {{proxy}}, I believe the only use case we explicitly support is tsh proxy ssh -J {{proxy}}, which is specifically intended for use in the SSH config's ProxyCommand field.

So in my opinion the OpenSSH guide is the best spot that we currently have, unless we want to split the OpenSSH guide into an OpenSSH Server guide and OpenSSH Client guide`.

It seems like there haven't been any changes to the template used in writeSSHConfig. Should we be instructing users to run tsh config, then manually edit the resulting config to include the ProxyCommand with the -J flag as shown below? Otherwise, I'm not sure this guide is the best place to put the -J flag instructions.

The current template is still the best default template for users to use. To use Proxy templates, they'd need to edit the config and proxy templates themselves to fit their naming conventions etc. This guide is intended for users who want to customize their ssh config beyond the default config we provide with tsh config to improve latency or reduce config size/complexity.

To me it makes sense to provide these "next step" instructions right here. However, I'll try adding some more context in the guide to make it fit better.

[ptgott]

Thanks for clarifying! I think the best way to go would be to edit the text into a more explicit set of steps. We should tell the reader to edit the config generated by tsh config to use the {{proxy}} template, then add a proxy_templates field to the tsh config file. Right now, these sound more like general possibilities, and it can be clearer how they fit into the workflow we describe in this guide.

[ptgott]

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.

[Joerger]

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?

[ptgott]

Approved with suggestions for clarifying the language.

[github-actions]

@Joerger See the table below for backport results.

Branch	Result
branch/v10	Create PR
branch/v9	Create PR