[v9] docs backports (#14339)

* Add tsh docs for x11 forwarding (#13647)
* Clarify session joining prerequisites (#14149)

Co-authored-by: Brian Joerger <bjoerger@goteleport.com>

docs/pages/server-access/guides/tsh.mdx

@@ -345,7 +345,7 @@ CI/CD pipeline.
 For this kind of automation, it is recommended to create a separate Teleport
 user for bots and request a certificate for them with a long time to live (TTL).
 
-In this example, we're creating a certificate with a TTL of one hour for the 
+In this example, we're creating a certificate with a TTL of one hour for the
 `jenkins` user and storing it in a `jenkins.pem` file, which can be later used with
 `-i` (identity) flag for `tsh`.
 
@@ -373,7 +373,7 @@ $ tctl auth sign --ttl=1h --user=jenkins --out=jenkins.pem
 [CLI Docs - tctl auth sign](../../setup/reference/cli.mdx#tctl-auth-sign)
 
 Now `jenkins.pem` can be copied to the Jenkins server and passed to the `-i`
-(identity file) flag of `tsh`. 
+(identity file) flag of `tsh`.
 
 `tctl auth sign` is an admin's equivalent of `tsh login --out` and allows for
 unrestricted certificate TTL values.
@@ -627,6 +627,11 @@ other user can join you through their terminal by typing:
 $ tsh join <session_ID>
 ```
 
+The Teleport user joining the session must have access to the same SSH principal
+used to start the session. In this case, Teleport user `joe` is logged in to the
+SSH Node as Unix user `joe`, so only Teleport users with a role allowing login `joe`
+will be able to join.
+
 <Notice type="note" scope={["oss", "enterprise"]}>
   Joining sessions is not supported in recording proxy mode (where `session_recording` is set to `proxy`).
 </Notice>
@@ -727,5 +732,37 @@ Service, and this tunnel is used to establish inbound SSH connections.
 
 </ScopedBlock>
 
+## X11 forwarding
+
+In order to run graphical programs within an SSH session, such as an IDE like
+Virtual Studio Code, you'll need to request X11 forwarding for the session with
+the `-X` flag.
+
+```code
+$ tsh ssh -X node01
+```
+
+X11 forwarding provides the server with secure access to your local X Server
+so that it can communicate directly with your local display and I/O devices.
+
+<Notice type="note">
+  The `-Y` flag can be used to start Trusted X11 forwarding. This is needed
+  in order to enable more "unsafe" features, such as running clipboard or
+  screenshot utilities like `xclip`. However, it provides the server with
+  unmitigated access to your local X Server and puts your local machine at
+  risk of X11 attacks, so it should only be used with extreme caution.
+</Notice>
+
+In order to use X11 forwarding, you'll need to enable it on the Teleport Node.
+You'll also need to ensure that your user has the `permit_x11_forwarding` role option:
+
+```code
+$ tsh status
+> Profile URL:        https://proxy.example.com:3080
+  Logged in as:       dev
+  ...
+  Extensions:         permit-X11-forwarding
+```
+
 ## Further reading
 - [CLI Reference](../../setup/reference/cli.mdx).

docs/pages/setup/reference/cli.mdx

@@ -206,6 +206,9 @@ $ tsh ssh [<flags>] <[user@]host> [<command>...]
 | `-o, --option` | `local` | | OpenSSH options in the format used in the configuration file |
 | `--enable-escape-sequences` | | | Enable support for SSH escape sequences. Type `~?` during an SSH session to list supported sequences. |
 | `--no-use-local-ssh-agent` | | | Do not load generated SSH certificates into the local ssh-agent (specified via `$SSH_AUTH_SOCK`). Useful when using `gpg-agent` or Yubikeys. You can also set the `TELEPORT_USE_LOCAL_SSH_AGENT` environment variable to `false` (default `true`) |
+| `-X, --x11-untrusted` | none | none | Requests untrusted (secure) X11 forwarding for this session. |
+| `-Y, --x11-trusted` | none | none | Requests trusted (insecure) X11 forwarding for this session. This can make your local machine vulnerable to attacks, use with caution. |
+| `--x11-untrusted-timeout` | 10m | duration | Sets a timeout for untrusted X11 forwarding, after which the client will reject any forwarding requests from the server. |
 
 #### Global flags
 

tool/tsh/tsh.go

@@ -486,7 +486,7 @@ func Run(args []string, opts ...cliOption) error {
 	ssh.Flag("option", "OpenSSH options in the format used in the configuration file").Short('o').AllowDuplicate().StringsVar(&cf.Options)
 	ssh.Flag("no-remote-exec", "Don't execute remote command, useful for port forwarding").Short('N').BoolVar(&cf.NoRemoteExec)
 	ssh.Flag("x11-untrusted", "Requests untrusted (secure) X11 forwarding for this session").Short('X').BoolVar(&cf.X11ForwardingUntrusted)
-	ssh.Flag("x11-trusted", "Requests trusted (insecure) X11 forwarding for this session. This can make your local displays vulnerable to attacks, use with caution").Short('Y').BoolVar(&cf.X11ForwardingTrusted)
+	ssh.Flag("x11-trusted", "Requests trusted (insecure) X11 forwarding for this session. This can make your local machine vulnerable to attacks, use with caution").Short('Y').BoolVar(&cf.X11ForwardingTrusted)
 	ssh.Flag("x11-untrusted-timeout", "Sets a timeout for untrusted X11 forwarding, after which the client will reject any forwarding requests from the server").Default("10m").DurationVar((&cf.X11ForwardingTimeout))
 	ssh.Flag("participant-req", "Displays a verbose list of required participants in a moderated session.").BoolVar(&cf.displayParticipantRequirements)