Document create_host_user_mode

docs/pages/access-controls/reference.mdx

@@ -116,7 +116,7 @@ The table below documents the behavior of each option if multiple roles are assi
 | `desktop_clipboard` | Allow clipboard sharing for desktop sessions | Logical "AND" i.e. evaluates to "yes" if all roles enable clipboard sharing |
 | `pin_source_ip` | Enable source IP pinning for SSH certificates. **Note:** IP pinning is currently in Preview mode | Logical "OR" i.e. evaluates to "yes" if at least one role requires session termination |
 | `cert_extensions` | Specifies extensions to be included in SSH certificates | |
-| `create_host_user` | Allow users to be automatically created on a host |  Logical "AND" i.e. evaluates to "yes" if all roles matching a Node enable host user creation |
+| `create_host_user_mode` | Allow users to be automatically created on a host |  Logical "AND" i.e. if all roles matching a server specify host user creation (`off`, `drop`, `keep`), it will evaluate to the option specified by all of the roles. If some roles specify both `drop` or `keep` it will evaluate to `keep`|
 
 ## Preset roles
 

docs/pages/includes/role-spec.mdx

@@ -98,7 +98,9 @@ spec:
        name: login@github.com
        value: "{{ external.github_login }}"
     # Controls whether this role supports auto provisioning of SSH users.
-    create_host_user: true
+    # Options: drop (remove user on session end), keep (keep users at session end)
+    #          and off (disable host user creation)
+    create_host_user_mode: drop    create_host_user: true
     # Controls whether this role requires automatic database user provisioning.
     create_db_user: true
     # Specifies role specific options for identity provider access.

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

@@ -28,8 +28,11 @@ since it must execute these commands in order to create transient users:
 
 ## Step 1/2. Configure a role
 
-First, create a role with `create_host_user` set to `true`. This will allow users
-with this role to have transient host users created at login time.
+First, create a role with `create_host_user_mode` set to `drop` or `keep`.
+
+Setting the option to `drop` will create transient users that are deleted once the
+session ends. Setting it to `keep` will create permanent users on the host at
+login time.
 
 The following role specification will allow users to log in as `nginxrestarter` on
 any matching Node. The host user will be created and added to the groups listed in
@@ -46,7 +49,7 @@ metadata:
 spec:
   options:
     # Allow automatic creation of users.
-    create_host_user: true
+    create_host_user_mode: drop
   allow:
     logins: [ "nginxrestarter" ]
     # List of host groups the created user will be added to. Any that don't already exist are created.
@@ -74,10 +77,15 @@ of the Linux distribution being used. See [User/Group Name Syntax](https://syste
 
 <Admonition type="warning">
 
-When a Teleport user accesses an SSH Service instance, Teleport checks each of
-the user's roles that match the instance. If at least one role matches the
-instance but does not include `create_host_user: true`, automatic user creation
-will be disabled. Roles that do not match the Node will not be checked.
+When a Teleport user accesses an SSH Service instance, Teleport checks each of the
+user's roles that match the instance. If at least one role matches the instance
+but does not specify `create_host_user_mode` to be either `keep` or `drop`,
+automatic user creation will be disabled. Roles that do not match the server will
+not be checked.
+
+If multiple roles match where one might specify `keep` and another `drop`,
+Teleport will default to `keep`, retaining the user on the server after the session
+ends.
 
 </Admonition>
 
@@ -99,7 +107,7 @@ metadata:
   name: auto-users
 spec:
   options:
-    create_host_user: true
+    create_host_user_mode: drop
   deny:
     host_sudoers: [
        "*" # ensure that users in this role never have sudoers files created on matching Nodes
@@ -164,9 +172,10 @@ contents of the `host_sudoers` file written with one entry per line, each
 prefixed with the username of the user that has logged in.
 
 The session can then proceed as usual, however once the SSH session ends, the user
-will be automatically removed and their home directory will be deleted. Files owned
-by the deleted user, created outside the home directory, will remain in place. Groups
-that were created will remain on the system after the session ends.
+will be automatically removed and their home directory will be deleted, as the
+matching role specified they should be dropped. Files owned by the deleted user,
+created outside the home directory, will remain in place. Groups that were created
+will remain on the system after the session ends.
 
 Should a Teleport SSH instance be restarted while a session is in progress, the user
 will be cleaned up at the next Teleport restart.

docs/pages/server-access/rbac.mdx

@@ -132,7 +132,9 @@ spec:
     #....
   options:
     # Controls whether this role supports auto provisioning of users.
-    create_host_user: true
+    # Options: drop (remove user on session end), keep (keep users at session end)
+    #          and off (disable host user creation)
+    create_host_user_mode: drop
     # forward_agent controls whether SSH agent forwarding is allowed
     forward_agent: true
     # port_forwarding controls whether TCP port forwarding is allowed for SSH