Stable UNIX users: docs (gravitational#51662)

* Stable user UID addition to the host user creation guide

* tctl stable-unix-users-ls docs

* CAP resource reference

* auth service reference

* Uncomment defaulted field in fileconf

* Clarify conditions for stable uids

docs/pages/enroll-resources/server-access/guides/host-user-creation.mdx

@@ -218,6 +218,45 @@ If multiple entries are specified in the `host_user_uid` or `host_user_gid` only
 
 </Admonition>
 
+For Teleport users that don't have a `host_user_uid` trait, starting from Teleport 17.3, it's possible to configure the cluster to assign the same UID for any given username for automatically created host users across all Teleport SSH instances.
+
+Edit your cluster authentication preference using the following command:
+
+```code
+$ tctl edit cluster_auth_preference
+```
+
+In your editor, ensure that your `cluster_auth_preference` includes a `stable_unix_user_config` field similar to the following:
+
+```yaml
+kind: cluster_auth_preference
+version: v2
+metadata:
+  name: cluster-auth-preference
+spec:
+  # ...
+  stable_unix_user_config:
+    enabled: true
+    first_uid: 90000
+    last_uid: 95000
+```
+
+The range of UIDs between `first_uid` and `last_uid` (inclusive) will be used by Teleport to assign UIDs for new users, and you should make sure it's not a range of UIDs already in use by other services or workloads across your fleet of servers. While UID allocations in Linux can vary, we recommend sticking to one of the available ranges listed in the [systemd documentation for "Users, Groups, UIDs and GIDs on systemd Systems"](https://github.com/systemd/systemd/blob/main/docs/UIDS-GIDS.md).
+
+Once enabled, all Teleport SSH instances (of version 17.3 and newer) will use the UID provided by the control plane when automatically creating a new host user, if no other UID is specified by the user trait.
+
+<Admonition type="note">
+
+Teleport will only use the UID defined by the control plane if the `create_host_user_mode` is `keep` (and not `insecure-drop`), and only for automatically created host users that were created after the feature was enabled. The UID will not be applied to users that already exist, and it will not take effect for static host users.
+
+</Admonition>
+
+You can inspect the list of assigned UIDs with the following command:
+
+```code
+$ tctl stable-unix-users ls
+```
+
 ### Step 3/4. Configure sudoers on your Linux servers
 
 Teleport host user creation leverages the `sudoers.d` directory for new users. 

docs/pages/includes/config-reference/auth-service.yaml

@@ -266,6 +266,16 @@ auth_service:
         # "14h30m", "1h" etc.
         default_session_ttl: 12h
 
+        stable_unix_user_config:
+            # If set to true, SSH instances will use the same UID for each given
+            # username when automatically creating users. Defaults to false.
+            enabled: false
+
+            # The range of UIDs (including both ends) used for automatic UID
+            # assignment. Ignored if enabled is set to false.
+            #first_uid: 90000
+            #last_uid: 95000
+
     # IP and the port to bind to. Other Teleport Nodes will be connecting to
     # this port (AKA "Auth API" or "Cluster API") to validate client
     # certificates

docs/pages/reference/cli/tctl.mdx

@@ -1549,6 +1549,36 @@ $ tctl get saml/your-connector-name --with-secrets | tctl sso test
   Make sure to include `--with-secrets` flag, or the exported auth connector will not be testable.
 </Admonition>
 
+## tctl stable-unix-users ls
+
+List the stored usernames and UIDs for automatically created users:
+
+```code
+$ tctl stable-unix-users ls
+```
+
+### Arguments
+
+This command accepts no arguments.
+
+### Flags
+
+| Name | Default Value(s) | Allowed Value(s) | Description |
+| - | - | - | - |
+| `--format` | `text` | `json` or `text` | Output format |
+
+### Examples
+
+```code
+$ tctl stable-unix-users ls
+Username UID
+-------- -----
+alice    90000
+bob      90002
+carol    90003
+dan      90001
+```
+
 ## tctl status
 
 Report cluster and Certificate Authority status:

docs/pages/reference/resources.mdx

@@ -308,6 +308,15 @@ spec:
   # Possible values: "local", "oidc", "saml" and "github"
   type: local
 
+  stable_unix_user_config:
+    # If set to true, SSH instances will use the same UID for each given
+    # username when automatically creating users.
+    enabled: false
+
+    # The range of UIDs (including both ends) used for automatic UID assignment.
+    first_uid: 90000
+    last_uid: 95000
+
 version: v2
 ```