Linux desktop access documentation (#490)

Export-Source-Commit: 64bc963663f614d8c1ff7fe5c4105774c23b76fe

docs/cspell.json

@@ -1188,8 +1188,10 @@
     "xgmx",
     "xlarge",
     "xlink",
+    "xorg",
     "xoxb",
     "xpack",
+    "xsessions",
     "ykman",
     "yourcompany",
     "yourdatabase",

docs/pages/enroll-resources/desktop-access/desktop-access.mdx

@@ -1,6 +1,6 @@
 ---
-title: Windows Desktops
+title: Desktop Access
-description: Protect Windows Resources with Teleport's passwordless access and other features.
+description: Protect Windows and Linux desktop resources with Teleport's passwordless access and other features.
 sidebar_position: 7
 template: doc-page
 page_type: landing
@@ -19,11 +19,12 @@ import slidersHorizontalSvg from "@site/src/components/Icon/svg/sliders-horizont
 import keyholeSvg from "@site/src/components/Icon/svg/keyhole.svg";
 import activeDirectorySvg from "@site/src/components/Icon/svg/active-directory.svg";
 import windowsSvg from "@site/src/components/Icon/svg/windows2.svg";
+import linuxSvg from "@site/src/components/Icon/svg/linux.svg";
 import windowsDesktopsSvg from "@site/src/components/Icon/teleport-svg/windows-desktops.svg";
 import folderNotchOpenSvg from "@site/src/components/Icon/svg/folder-notch-open.svg";
 
 <DocHero
-  title="Configure access for local Windows users"
+  title="Configure access for Windows and Linux desktops"
   youtubeVideoId={
     // cspell:disable-next-line
     "n2h0GisWdss"
@@ -35,12 +36,18 @@ import folderNotchOpenSvg from "@site/src/components/Icon/svg/folder-notch-open.
       variant: "secondary",
       arrow: true,
     },
+    {
+      title: "Get started with Linux access",
+      href: "./linux-desktop/",
+      variant: "secondary",
+      arrow: true,
+    },
   ]}
   linksDesktopColumnCount={3}
   links={[
     {
-      title: "Windows desktop RBAC",
+      title: "Desktop RBAC",
-      description: "Set up granular access policies for Windows desktops connected to Teleport.",
+      description: "Set up granular access policies for desktops connected to Teleport.",
       href: "./rbac/",
       icon: userCheckSvg,
     }, 
@@ -52,13 +59,13 @@ import folderNotchOpenSvg from "@site/src/components/Icon/svg/folder-notch-open.
     },
     {
       title: "Troubleshooting",
-      description: "Common Windows desktop access issues with Teleport and their solutions.",
+      description: "Common desktop access issues with Teleport and their solutions.",
       href: "./troubleshooting/",
       icon: questionSvg,
     },
   ]}
 >
-Provide secure, passwordless access to Microsoft Windows desktops and servers, backed by short-lived certificates, role-based access controls, clipboard and directory sharing, session recordings, and detailed audit logs.
+Provide secure, passwordless access to Windows and Linux desktops, backed by short-lived certificates, role-based access controls, clipboard and directory sharing, session recordings, and detailed audit logs.
 </DocHero>
 {/*vale messaging.protocol-products = NO*/}
 <Resources
@@ -67,8 +74,8 @@ Provide secure, passwordless access to Microsoft Windows desktops and servers, b
   desktopColumnsCount={3}
   resources={[
     {
-      title: "Intro to Windows desktop access",
+      title: "Intro to desktop access",
-      description: "Windows desktop and server access with clipboard and file sharing, session recording, and audit logs.",
+      description: "Windows and Linux desktop access with clipboard and file sharing, session recording, and audit logs.",
       iconComponent: keyholeSvg,
       href: "./introduction/"
     },
@@ -84,6 +91,12 @@ Provide secure, passwordless access to Microsoft Windows desktops and servers, b
       iconComponent: windowsSvg,
       href: "./getting-started/"
     },
+    {
+      title: "Linux desktops",
+      description: "Provide secure, audited access to Linux desktops running X11 desktop environments.",
+      iconComponent: linuxSvg,
+      href: "./linux-desktop/"
+    },
   ]}
 />
 {/*vale messaging.protocol-products = YES*/}

docs/pages/enroll-resources/desktop-access/introduction.mdx

@@ -1,7 +1,7 @@
 ---
-title: Manage Access to Windows Resources
+title: Manage Access to Desktop Resources
 sidebar_label: Introduction
-description: Demonstrates how you can manage access to Windows desktops with Teleport.
+description: Demonstrates how you can manage access to Windows and Linux desktops with Teleport.
 videoBanner: n2h0GisWdss
 tags:
  - conceptual
@@ -11,14 +11,14 @@ page_type: conceptual
 ---
 
 You can configure Teleport to provide secure, passwordless access to Microsoft
-Windows desktops and servers. For Windows, Teleport provides the following key
+Windows and Linux desktops and servers. Teleport provides the following key
 features:
 
-- Passwordless access to Windows hosts backed by secure cryptographic
+- Passwordless access to desktop hosts backed by secure cryptographic
   authentication and short-lived certificates.
 - Configurable role-based access controls (RBAC) for groups of hosts and users.
 - Configurable clipboard and directory sharing for copying and pasting to and
-  from remote Windows hosts.
+  from remote desktop hosts.
 - Session recording for all desktop activity.
 - Audit logs that track user activity.
 
@@ -71,11 +71,12 @@ ability to create users on-demand. The lack of automatic LDAP-based discovery
 and the requirement to install software on each host makes this approach less
 attractive for large environments.
 
-For more information about configuring basic access using Teleport Windows
+For more information about configuring basic access using Teleport Desktop
-Desktop Service, see the following topics:
+Services, see the following topics:
 
 - [Configure access for local Windows users](./getting-started.mdx)
 - [Configure access for Active Directory](./active-directory.mdx)
+- [Configure access for Linux desktops](./linux-desktop.mdx)
 
 ## Further reading
 

docs/pages/enroll-resources/desktop-access/linux-desktop.mdx

@@ -0,0 +1,285 @@
+---
+title: Configure Access for Linux Desktops
+sidebar_label: Linux Desktop Access
+description: Use Teleport to configure secure, audited access to Linux desktops running X11 desktop environments.
+tags:
+ - how-to
+ - zero-trust
+ - infrastructure-identity
+---
+
+This guide demonstrates how to configure Teleport to provide secure, audited access
+to Linux desktops running X11 desktop environments.
+
+## How it works
+
+The Teleport Linux Desktop Service runs directly on the Linux host you want to access.
+When a user connects, the service starts a virtual X11 display using
+[Xvfb](https://www.x.org/releases/X11R7.6/doc/man/man1/Xvfb.1.xhtml) (X virtual
+framebuffer) and launches the user's chosen desktop environment inside it.
+
+The Linux Desktop Service establishes a reverse tunnel to the Teleport Proxy Service,
+so only a single outbound connection from the host is required—no inbound firewall
+rules are needed.
+
+Available desktop sessions are discovered from `.desktop` files in
+`/usr/share/xsessions`. You can restrict which sessions are offered using the
+`xsessions.included` and `xsessions.excluded` filters in the service configuration.
+
+## Prerequisites
+
+To complete the steps in this guide, verify your environment meets the following requirements:
+
+(!docs/pages/includes/edition-prereqs-tabs.mdx!)
+
+- A Linux host running an X11-compatible desktop environment with session definitions
+  in `/usr/share/xsessions`.
+
+- **Xvfb** installed on the Linux host. Xvfb provides the virtual framebuffer that
+  Teleport uses to render the desktop. Install it with your distribution's package
+  manager:
+
+  <Tabs>
+  <TabItem label="Debian/Ubuntu">
+
+  ```code
+  $ sudo apt-get install xvfb
+  ```
+
+  </TabItem>
+  <TabItem label="Fedora/RHEL/CentOS/Amazon Linux">
+
+  ```code
+  $ sudo dnf install xorg-x11-server-Xvfb
+  ```
+
+  </TabItem>
+  </Tabs>
+
+  Verify that `Xvfb` is available in `PATH`:
+
+  ```code
+  $ sudo -i which Xvfb
+  ```
+
+- (!docs/pages/includes/tctl.mdx!)
+
+## Step 1/3. Configure the Linux Desktop Service
+
+The Linux Desktop Service runs on the Linux host that users will connect to.
+
+To configure the Linux Desktop Service:
+
+1. Sign in to the Teleport cluster from your administrative workstation.
+
+1. Generate an invitation token for the Linux Desktop Service:
+
+   ```code
+   $  tctl tokens add --type=linux_desktop --format=text > /tmp/token
+   ```
+
+   Copy `/tmp/token` to the target Linux host
+
+1. Verify that Teleport is installed on the Linux host:
+
+   ```code
+   $ teleport version
+   ```
+
+   If Teleport isn't installed, follow the appropriate [Installation
+   instructions](../../installation/single-machine/linux.mdx) for your environment.
+
+1. Configure `/etc/teleport.yaml` on the Linux host:
+
+   ```yaml
+   version: v3
+   teleport:
+     nodename: <Var name="linux-desktop.example.com" />
+     proxy_server: <Var name="teleport.example.com" />:443
+     auth_token: "/tmp/token"
+   linux_desktop_service:
+     enabled: true
+
+   auth_service:
+     enabled: false
+   proxy_service:
+     enabled: false
+   ssh_service:
+     enabled: false
+   ```
+
+   Set `proxy_server` to the address of your Teleport cluster.
+
+1. (Optional) Add labels to the Linux Desktop Service. Labels are used to control
+   which users can connect to this host.
+
+   ```diff
+   version: v3
+   teleport:
+     nodename: <Var name="linux-desktop.example.com" />
+     proxy_server: <Var name="teleport.example.com" />:443
+     auth_token: "/tmp/token"
+   linux_desktop_service:
+     enabled: true
+   + labels:
+   +   datacenter: us-east
+   +   env: production
+   ```
+
+1. (Optional) Filter the desktop sessions available to users. Teleport discovers
+   available session types from `.desktop` files in `/usr/share/xsessions`. You
+   can restrict which sessions are offered using regular expressions matched against
+   the session name (the filename without the `.desktop` extension):
+
+   ```diff
+   linux_desktop_service:
+     enabled: true
+   + xsessions:
+   +   # Only expose GNOME, KDE, and XFCE sessions.
+   +   included: "^(gnome|kde|xfce4)$"
+   +   # Exclude classic or fallback variants.
+   +   excluded: ".*-classic$"
+   ```
+
+   The `included` pattern is applied first. If set, only sessions whose name
+   matches the pattern are offered. The `excluded` pattern is applied next and
+   removes sessions whose name matches it.
+
+1. (!docs/pages/includes/start-teleport.mdx service="the Teleport Linux Desktop Service"!)
+
+<Checkpoint
+  title="Verify the Linux Desktop Service is running"
+  description="Confirm that the Teleport Linux Desktop Service has started and connected to your cluster."
+>
+  Here are some troubleshooting tips:
+
+  - Check the service status:
+
+    ```code
+    $ systemctl status teleport
+    ```
+
+  - Review logs for connection errors:
+
+    ```code
+    $ sudo journalctl -u teleport
+    ```
+
+  - Verify that `Xvfb` is available in `PATH`:
+
+    ```code
+    $ sudo -i which Xvfb
+    ```
+
+    If the command returns no output, Xvfb is not installed. See the Prerequisites
+    section above for installation instructions.
+
+  - Confirm that at least one `.desktop` file exists in `/usr/share/xsessions`:
+
+    ```code
+    $ ls /usr/share/xsessions/
+    ```
+
+  - Ensure the token hasn't expired (tokens are valid for 60 minutes by default).
+
+</Checkpoint>
+
+## Step 2/3. Configure a role for Linux desktop access
+
+To access a Linux desktop, a Teleport user must have a role that grants the
+appropriate permissions.
+
+To configure a role for Linux desktop access:
+
+1. Sign in to the Teleport cluster from your administrative workstation.
+
+1. Create a `linux-desktop-admins.yaml` file to define a new role:
+
+   ```yaml
+   kind: role
+   version: v6
+   metadata:
+     name: linux-desktop-admins
+   spec:
+     allow:
+       linux_desktop_labels:
+         "*": "*"
+       linux_desktop_logins: ["alice"]
+   ```
+
+   In this file:
+
+   - Set `linux_desktop_labels` to specify which Linux desktops users assigned
+     to this role can access. Use `"*": "*"` to allow access to all desktops, or
+     specify labels to restrict access to desktops with matching labels.
+   - Set `linux_desktop_logins` to the Linux user accounts that members of this
+     role can connect as. The specified user must already exist on the Linux host.
+
+1. Apply the new role to your cluster:
+
+   ```code
+   $ tctl create -f linux-desktop-admins.yaml
+   ```
+
+   (!docs/pages/includes/create-role-using-web.mdx!)
+
+1. (\!docs/pages/includes/add-role-to-user.mdx role="linux-desktop-admins" \!)
+
+## Step 3/3. Connect
+
+Now that the Linux Desktop Service is running and a role has been configured, you
+can connect to the Linux desktop from the Teleport Web UI or Teleport Connect.
+
+To connect to a Linux desktop:
+
+1. Sign in to the Teleport cluster using an account assigned the
+   `linux-desktop-admins` role.
+
+1. Select **Resources**.
+
+1. Click **Type**, then select **Desktops**.
+
+1. Click **Connect** for the Linux desktop you want to access, then select the
+   Linux user account to use for the connection.
+
+   Teleport opens a remote desktop connection and starts recording the desktop
+   session. When you are finished, click the **More items** menu, then click
+   **Disconnect**.
+
+   To view the recording, select **Audit** in the Teleport Web UI, then click
+   **Session Recordings**.
+
+<Checkpoint
+  title="Verify Linux desktop access"
+  description="Confirm that you can connect to the Linux desktop and see the desktop environment."
+>
+  Here are some troubleshooting tips:
+
+  - Ensure your Teleport user is assigned the `linux-desktop-admins` role (or an
+    equivalent role with Linux desktop permissions).
+
+  - Verify that the Linux user account you selected exists on the host.
+
+  - Confirm that Xvfb is installed and in `PATH` on the Linux host.
+
+  - Check that at least one session type is available after applying your
+    `xsessions` filters: review `/usr/share/xsessions/` and compare against
+    the `included`/`excluded` patterns in your configuration.
+
+  - If the connection fails, review the Linux Desktop Service logs on the host:
+
+    ```code
+    $ sudo journalctl -u teleport
+    ```
+
+</Checkpoint>
+
+## Next steps
+{/* vale messaging.protocol-products = NO */}
+- To learn more about controlling who can access which desktops, see
+  [Role-Based Access Control for Desktops](./rbac.mdx).
+- To configure session recording options, see
+  [Session Recording and Playback](reference/sessions.mdx).
+- For a full list of `linux_desktop_service` configuration options, see the
+  [Desktop Access Configuration Reference](reference/configuration.mdx).
+{/* vale messaging.protocol-products = YES */}

docs/pages/enroll-resources/desktop-access/rbac.mdx

@@ -13,7 +13,7 @@ This page describes the capabilities that Teleport provides for managing
 role-based access controls for protected remote desktops.
 
 Teleport's RBAC allows administrators to set up granular access policies for
-Windows desktops connected to Teleport.
+Windows and Linux desktops connected to Teleport.
 
 Teleport's `role` resource provides the following options for controlling
 desktop access:
@@ -48,16 +48,23 @@ spec:
 
     # Specify whether local users should be created automatically at connection
     # time. By default, this feature is disabled, and the user must already exist.
-    # Note: this is applicable to local users only and is not supported in Active
+    # Note: this is applicable to local Windows users only and is not supported in
-    # Directory environments.
+    # Active Directory environments.
     create_desktop_user: true
   allow:
-    # Label selectors for desktops this role has access to.
+    # Label selectors for Windows desktops this role has access to.
     windows_desktop_labels:
       environment: ["dev", "stage"]
 
     # Windows user accounts this role can connect as.
     windows_desktop_logins: ["Administrator", "{{internal.windows_logins}}"]
+
+    # Label selectors for Linux desktops this role has access to.
+    linux_desktop_labels:
+      environment: ["dev", "stage"]
+
+    # Linux user accounts this role can connect as.
+    linux_desktop_logins: ["alice", "{{internal.linux_desktop_logins}}"]
 ```
 
 <Admonition type="warning" title="Active Directory Configuration">
@@ -211,8 +218,43 @@ windows_desktop_service:
 In this example, all hosts in the Engineering OU would have `team: engineering`
 while the hosts in the Sales OU would have `team: sales`.
 
+## Linux Desktop Labeling
+
+Both `allow` and `deny` rules support `linux_desktop_labels` selectors. These
+selectors are matched against the labels set on the Linux desktop resource.
+Wildcards (`"*"`) can be used to match all label values.
+
+Linux desktops acquire labels from the `labels` field in the
+`linux_desktop_service` section of the Teleport configuration file on the host:
+
+```yaml
+linux_desktop_service:
+  enabled: true
+  labels:
+    environment: dev
+    datacenter: us-east
+```
+
+These labels are then used in role `allow` and `deny` rules:
+
+```yaml
+allow:
+  # Allow access to all Linux desktops in the dev environment.
+  linux_desktop_labels:
+    environment: dev
+```
+
+```yaml
+deny:
+  # Deny access to production Linux desktops.
+  linux_desktop_labels:
+    environment: prod
+```
+
 ## Logins
 
+### Windows logins
+
 The `windows_desktop_logins` role setting lists the Windows user accounts that
 the role permits access to. For local users, the `{{internal.windows_logins}}`
 variable can be used as a placeholder for the user's `windows_logins` trait. The
@@ -226,6 +268,24 @@ allow:
   windows_desktop_logins: ["{{internal.windows_logins}}"]
 ```
 
+### Linux logins
+
+The `linux_desktop_logins` role setting lists the Linux user accounts that the
+role permits access to. The specified accounts must already exist on the Linux
+host. The `{{internal.linux_desktop_logins}}` variable can be used as a placeholder for
+the user's `linux_desktop_logins` trait. The `linux_desktop_logins` trait can be specified when
+the user is created:
+
+```code
+$ tctl users add alice --linux-desktop-logins=alice,admin
+```
+
+Or updated for an existing user:
+
+```code
+$ tctl users update alice --set-linux-desktop-logins=alice,admin
+```
+
 ## Clipboard Access
 
 In order for a user to copy and paste between a remote desktop and their local

docs/pages/enroll-resources/desktop-access/reference/configuration.mdx

@@ -12,8 +12,19 @@ page_type: reference
 This page lists the Teleport configuration fields that you can use to configure
 the Teleport Desktop Service.
 
+`teleport.yaml` fields for the Linux Desktop Service:
+
 ```yaml
-# Main service responsible for desktop access.
+# Service responsible for Linux desktop access.
+# The Linux Desktop Service runs directly on the Linux host being accessed
+# and requires Xvfb to be installed on that host.
+(!docs/pages/includes/config-reference/linux-desktop-config.yaml!)
+```
+
+`teleport.yaml` fields for the Windows Desktop Service:
+
+```yaml
+# Main service responsible for Windows desktop access.
 #
 # You can have multiple Desktop Service instances in your cluster (but not in the
 # same teleport.yaml), connected to the same or different Active Directory

docs/pages/includes/config-reference/linux-desktop-config.yaml

@@ -0,0 +1,20 @@
+linux_desktop_service:
+  enabled: true
+
+  # (optional) Labels to attach to this Linux Desktop Service instance.
+  labels:
+    "env": "staging"
+
+  # (optional) Filters for available X sessions.
+  # X session types are discovered from .desktop files in /usr/share/xsessions.
+  # The filter patterns are Go regular expressions matched against the filename
+  # of each .desktop file, without the .desktop extension.
+  # For example, a file named "gnome.desktop" is matched as "gnome".
+  xsessions:
+    # (optional) Only expose X sessions whose name matches this pattern.
+    # If unset, all sessions are included (subject to excluded below).
+    included: "^(gnome|kde|xfce4)$"
+
+    # (optional) Exclude X sessions whose name matches this pattern.
+    # Applied after included. If unset, no sessions are excluded.
+    excluded: ".*-classic$"

docs/pages/includes/role-spec.mdx

@@ -145,9 +145,12 @@ spec:
     # both strings and template variables are supported in this field
     logins: [root, '{{internal.logins}}']
 
-    # Windows logins a user is allowed to use for desktop sessions.
+    # Windows logins a user is allowed to use for Windows desktop sessions.
     windows_desktop_logins: [Administrator, '{{internal.logins}}']
 
+    # Linux desktop logins a user is allowed to use for Linux desktop sessions.
+    linux_desktop_logins: [root, '{{internal.linux_desktop_logins}}']
+
     # node_labels: a user with this role will be allowed to connect to
     # SSH nodes with labels matching below.
     node_labels:
@@ -342,6 +345,7 @@ spec:
     db_labels_expression: 'labels["env"] == "staging"'
     db_service_labels_expression: 'labels["env"] == "staging"'
     windows_desktop_labels_expression: 'labels["env"] == "staging"'
+    linux_desktop_labels_expression: 'labels["env"] == "staging"'
     group_labels_expression: 'labels["env"] == "staging"'
     workload_identity_labels_expression: 'labels["env"] == "staging"'
     beam_labels_expression: 'labels["env"] == "staging"'

docs/pages/reference/access-controls/roles.mdx

@@ -275,6 +275,7 @@ conditions:
 - `db_labels_expression`
 - `db_service_labels_expression`
 - `windows_desktop_labels_expression`
+- `linux_desktop_labels_expression`
 - `group_labels_expression`
 - `workload_identity_labels_expression`
 - `beam_labels_expression`
@@ -878,7 +879,8 @@ Labels for resources enrolled with Teleport:
 |`db_service_labels`|[Database Service](../../enroll-resources/database-access/database-access.mdx) instances|
 |`kubernetes_labels`|[Kubernetes clusters](../../enroll-resources/kubernetes-access/controls.mdx)|
 |`node_labels`|[SSH Servers](../../enroll-resources/server-access/server-access.mdx)|
-|`windows_desktop_labels`|[Windows desktops](../../enroll-resources/server-access/server-access.mdx)|
+|`windows_desktop_labels`|[Windows desktops](../../enroll-resources/desktop-access/desktop-access.mdx)|
+|`linux_desktop_labels`|[Linux desktops](../../enroll-resources/desktop-access/linux-desktop.mdx)|
 |`workload_identity_labels`|[Workload Identities](../machine-workload-identity/workload-identity/workload-identity-resource.mdx)|
 |`beam_labels`|Beams|
 
@@ -896,6 +898,7 @@ Principals a user can assume on infrastructure resources:
 - `kubernetes_users`
 - `logins`
 - `windows_desktop_logins`
+- `linux_desktop_logins`
 
 Teleport principals that a user can impersonate:
 - `impersonate.roles`
@@ -931,6 +934,7 @@ sign-on provider.
 |`{{internal.kubernetes_users}}`|List of allowed Kubernetes users for the user.|
 |`{{internal.logins}}` | Substituted with a value stored in Teleport's local user database and logins from a root cluster. <br/><br/>For local users, Teleport will substitute this with the "allowed logins" parameter used in the `tctl users add [user] <allowed logins>` command. <br/><br/>If the role is within a leaf cluster in a [trusted cluster](../../zero-trust-access/management/trustedclusters.mdx), Teleport will substitute the logins from the root cluster whether the user is a local user or from an SSO provider. <br/><br/>As an example, if the user has the `ubuntu` login in the root cluster, then `ubuntu` will be substituted in the leaf cluster with this variable. |
 |`{{internal.windows_logins}}`|List of allowed Windows logins for the user.|
+|`{{internal.linux_desktop_logins}}`|List of allowed Linux desktop logins for the user.|
 |`{{external.xyz}}` | Substituted with a value from an external [SSO provider](https://en.wikipedia.org/wiki/Single_sign-on). If using SAML, this will be expanded with "xyz" assertion value. For OIDC, the variable is expanded to the value of the "xyz" claim. See the next section for more information on referring to the `external` variable in Teleport roles. |
 
 #### Referring to internal traits in Teleport roles