cc_users_groups:
  description: |
    This module configures users and groups. For more detailed information
    on user options, see the :ref:`Including users and groups <yaml_examples>`
    config example.

    Groups to add to the system can be specified under the ``groups`` key as a
    string of comma-separated groups to create, or a list. Each item in the
    list should either contain a string of a single group to create, or a
    dictionary with the group name as the key and string of a single user as a
    member of that group or a list of users who should be members of the group.

    .. note::
       Groups are added before users, so any users in a group list must already
       exist on the system.

    Users to add can be specified as a string or list under the ``users`` key.
    Each entry in the list should either be a string or a dictionary. If a
    string is specified, that string can be comma-separated usernames to
    create, or the reserved string ``default`` which represents the primary
    admin user used to access the system. The ``default`` user varies per
    distribution and is generally configured in ``/etc/cloud/cloud.cfg`` by the
    ``default_user key``.

    Each ``users`` dictionary item must contain either a ``name`` or
    ``snapuser`` key, otherwise it will be ignored. Omission of ``default`` as
    the first item in the ``users`` list skips creation the default user. If
    no ``users`` key is provided, the default behavior is to create the
    default user via this config:

    .. code-block:: yaml

       users:
       - default

    .. note::
       Specifying a hash of a user's password with ``passwd`` is a security
       risk if the cloud-config can be intercepted. SSH authentication is
       preferred.

    .. note::
       If specifying a ``doas`` rule for a user, ensure that the syntax for
       the rule is valid, as the only checking performed by cloud-init is to
       ensure that the user referenced in the rule is the correct user.

    .. note::
       If specifying a ``sudo`` rule for a user, ensure that the syntax for
       the rule is valid, as it is not checked by cloud-init.
    
    .. note::
       Most of these configuration options will not be honored if the user
       already exists. The following options are the exceptions, and are
       applied to already-existing users; ``plain_text_passwd``, ``doas``,
       ``hashed_passwd``, ``lock_passwd``, ``sudo``, ``ssh_authorized_keys``,
       ``ssh_redirect_user``.
       
    The ``user`` key can be used to override the ``default_user`` configuration
    defined in ``/etc/cloud/cloud.cfg``. The ``user`` value should be a
    dictionary which supports the same config keys as the ``users`` dictionary
    items.
  examples:
  - comment: >
      Example 1: Add the ``default_user`` from ``/etc/cloud/cloud.cfg``. This
      is also the default behavior of cloud-init when no ``users`` key is
      provided.
    file: cc_users_groups/example1.yaml
  - comment: >
      Example 2: Add the ``admingroup`` with members ``root`` and ``sys``, and
      an empty group ``cloud-users``.
    file: cc_users_groups/example2.yaml
  - comment: >
      Example 3: Skip creation of the ``default`` user and only create
      ``newsuper``. Password-based login is rejected, but the GitHub user
      ``TheRealFalcon`` and the Launchpad user ``falcojr`` can SSH as
      ``newsuper``. The default shell for ``newsuper`` is bash instead of
      system default.
    file: cc_users_groups/example3.yaml
  - comment: >
      Example 4: Skip creation of the ``default`` user and only create
      ``newsuper``. Password-based login is rejected, but the GitHub user
      ``TheRealFalcon`` and the Launchpad user ``falcojr`` can SSH as
      ``newsuper``. ``doas``/``opendoas`` is configured to permit this user to
      run commands as other users (without being prompted for a password)
      except not as root.
    file: cc_users_groups/example4.yaml
  - comment: >
      Example 5: On a system with SELinux enabled, add ``youruser`` and set the
      SELinux user to ``staff_u``. When omitted on SELinux, the system will
      select the configured default SELinux user.
    file: cc_users_groups/example5.yaml
  - comment: >
      Example 6: To redirect a legacy username to the ``default`` user for a
      distribution, ``ssh_redirect_user`` will accept an SSH connection and
      emit a message telling the client to SSH as the ``default`` user.
      SSH clients will get the message;
    file: cc_users_groups/example6.yaml
  - comment: >
      Example 7: Override any ``default_user`` config in
      ``/etc/cloud/cloud.cfg`` with supplemental config options. This config
      will make the default user ``mynewdefault`` and change the user to not
      have ``sudo`` rights.
    file: cc_users_groups/example7.yaml
  - comment: >
      Example 8: Avoid creating any ``default_user``.
    file: cc_users_groups/example8.yaml
  name: Users and Groups
  title: Configure users and groups
