Commit 42558b72 authored by Maciej Delmanowski's avatar Maciej Delmanowski

[debops.users] Convert config lists to merged list

parent 738a82b2
......@@ -71,11 +71,12 @@ users__default_system: '{{ (True
users__default_shell: ''
# ]]]
# ]]]
# Lists of managed UNIX groups [[[
# --------------------------------
# Lists of managed UNIX groups and accounts [[[
# ---------------------------------------------
# These lists can be used to manage UNIX groups through Ansible inventory. See
# :ref:`users__ref_groups` for more details.
# These lists can be used to manage UNIX groups as well as UNIX accounts
# through the Ansible inventory. See :ref:`users__ref_accounts` for more
# details.
# .. envvar:: users__groups [[[
#
......@@ -103,13 +104,18 @@ users__host_groups: []
users__dependent_groups: []
# ]]]
# ]]]
# Lists of managed UNIX accounts [[[
# ----------------------------------
# .. envvar:: users__default_accounts [[[
#
# List of default UNIX user accounts managed by Ansible.
users__default_accounts: []
# These lists can be used to manage UNIX user accounts through Ansible
# inventory. See :ref:`users__ref_accounts` for more details.
# ]]]
# .. envvar:: users__admin_accounts [[[
#
# List of UNIX administrator accounts managed by Ansible.
users__admin_accounts: '{{ lookup("template", "lookup/users__admin_accounts.j2") | from_yaml }}'
# ]]]
# .. envvar:: users__accounts [[[
#
# List of user accounts to manage on all hosts in Ansible inventory.
......@@ -128,18 +134,6 @@ users__group_accounts: []
# List of UNIX user accounts to manage on specific hosts in Ansible inventory.
users__host_accounts: []
# ]]]
# .. envvar:: users__default_accounts [[[
#
# List of default UNIX user accounts managed by Ansible.
users__default_accounts: []
# ]]]
# .. envvar:: users__admin_accounts [[[
#
# List of UNIX administrator accounts managed by Ansible.
users__admin_accounts: '{{ lookup("template", "lookup/users__admin_accounts.j2") | from_yaml }}'
# ]]]
# ]]]
# .. envvar:: users__dependent_accounts [[[
#
......@@ -148,6 +142,22 @@ users__admin_accounts: '{{ lookup("template", "lookup/users__admin_accounts.j2")
# in a playbook.
users__dependent_accounts: []
# ]]]
# .. envvar:: users__combined_accounts [[[
#
# This variable combines other group and account variables together and is used
# in the role tasks and templates.
users__combined_accounts: '{{ users__groups
+ users__group_groups
+ users__host_groups
+ users__dependent_groups
+ users__default_accounts
+ users__admin_accounts
+ users__accounts
+ users__group_accounts
+ users__host_accounts
+ users__dependent_accounts }}'
# ]]]
# ]]]
# Management of user resources [[[
# --------------------------------
......
This diff is collapsed.
......@@ -10,37 +10,16 @@ simple strings or lists, here you can find documentation and examples for them.
:local:
:depth: 1
.. _users__ref_groups:
users__groups
-------------
The :envvar:`users__groups`, :envvar:`users__group_groups` and :envvar:`users__host_groups` lists
can be used to manage UNIX groups on remote hosts using Ansible inventory. Each
list entry is a YAML dictionary that describes the state and parameters of
a given group. The group definition is a subset of the user definition
described below, and some parameters are shared in both cases.
List of known parameters:
``group`` or ``name``
Required. Name of the UNIX group to manage. If ``group`` is not specified,
``name`` will be used automatically.
``system``
Optional, boolean. If ``True``, a given group will be a "system" group, with
it's GID < 1000. If the value is ``False``, the group will be a "normal"
group with GID >= 1000.
If not specified, the :envvar:`users__default_system` variable will determine the
group type.
.. _users__ref_accounts:
``gid``
Optional. Specify the GID of the managed UNIX group.
users__accounts
---------------
``state``
Optional. If ``present``, the UNIX group will be created. If ``absent``, the
specified group will be removed.
The ``users__*_groups`` and ``users__*_accounts`` variables define the UNIX
group and UNIX user accounts which should be managed by Ansible. The
distinctive names can be used to order the UNIX group creation before the
account creation; otherwise both variable sets use the same content.
Examples
~~~~~~~~
......@@ -48,22 +27,31 @@ Examples
.. literalinclude:: examples/manage-groups.yml
:language: yaml
.. literalinclude:: examples/manage-accounts.yml
:language: yaml
.. _users__ref_accounts:
users__accounts
---------------
Syntax
~~~~~~
The :envvar:`users__accounts`, :envvar:`users__group_accounts`, :envvar:`users__host_accounts` as
well as some additional ``users__*_accounts`` lists are used to manage UNIX
user accounts. Each list entry is a YAML dictionary with parameters that define
a particular account.
The variables are lists of YAML dictionaries, each dictionary defines an UNIX
group or an UNIX account using specific parameters.
General account parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~
''''''''''''''''''''''''''
``name``
Required. Name of the UNIX user account to manage.
Required. Name of the UNIX user account to manage. If ``group`` parameter is
not specified, this value is also used to create a private UNIX group for
a given user. Configuration entries with the same ``name`` parameter are
merged in order of appearance, this can be used to modify existing
configuration entries conditionally.
``user``
Optional, boolean. If not specified or ``True``, a configuration entry will
manage both an UNIX account and its primary UNIX group. If ``False``, only
the UNIX group is managed; this can be used to define shared system groups.
You can also use the :ref:`debops.system_groups` Ansible role to define UNIX
groups with additional functionality like :command:`sudo` configuration, etc.
``system``
Optional, boolean. If ``True``, a given user account and primary group will
......@@ -85,6 +73,12 @@ General account parameters
a given account. If ``group`` is not specified, ``name`` will be used
automatically to create the corresponding UNIX group.
``private_group``
Optional, boolean. If specified and ``False``, the role will not try to
directly manage the specified UNIX ``group`` used with a given UNIX account.
This is useful if you want to set a primary UNIX group that's used in other
places and which you might not want to remove with the UNIX account.
``groups``
Optional. List of UNIX groups to which a given UNIX account should belong.
Only existing groups will be added to the account.
......@@ -126,7 +120,7 @@ General account parameters
disabled.
Parameters related to account state
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
'''''''''''''''''''''''''''''''''''
``state``
Optional. If ``present``, the UNIX user account and primary group will be
......@@ -145,7 +139,7 @@ Parameters related to account state
user account will be disabled.
Parameters related to home directories
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
''''''''''''''''''''''''''''''''''''''
``home``
Optional. Path to the home directory if a given user account.
......@@ -205,7 +199,7 @@ Parameters related to home directories
make sense in this context and shouldn't be used.
Parameters related to the account's private SSH key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
'''''''''''''''''''''''''''''''''''''''''''''''''''
``generate_ssh_key``
Optional, boolean. If ``True``, Ansible will generate a private SSH key for
......@@ -230,7 +224,7 @@ Parameters related to the account's private SSH key
will be generated automatically.
Parameters related to public SSH keys
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
'''''''''''''''''''''''''''''''''''''
``sshkeys``
Optional. String or a YAML list of public SSH keys to configure for a given
......@@ -248,7 +242,7 @@ Parameters related to public SSH keys
removed entirely.
Parameters related to mail forwarding
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
'''''''''''''''''''''''''''''''''''''
``forward``
Optional. String or YAML list of e-mail addresses which will be used to
......@@ -262,7 +256,7 @@ Parameters related to mail forwarding
file. If ``absent``, the entries will be removed from the configuration file.
Parameters related to user configuration files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
''''''''''''''''''''''''''''''''''''''''''''''
``dotfiles_enabled`` / ``dotfiles``
Optional, boolean. Enable or disable management of the user configuration
......@@ -277,13 +271,6 @@ Parameters related to user configuration files
role.
Examples
~~~~~~~~
.. literalinclude:: examples/manage-accounts.yml
:language: yaml
.. _users__ref_resources:
users__resources
......
......@@ -4,11 +4,14 @@ users__groups:
# A normal group
- name: 'group1'
user: False
# A system group
- name: 'group1_sys'
system: True
user: False
# This group will be removed
- name: 'group_removed'
user: False
state: 'absent'
......@@ -20,6 +20,22 @@ Redesigned OpenLDAP support
and import the LDAP directory afterwards. See the role documentation for more
details.
Changes to the UNIX group and account management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The :ref:`debops.users` Ansible role has been modernized and it now uses the
custom Ansible filter plugins included in DebOps to manage the UNIX groups
and accounts. The group and account management now uses the same merged list
of entries, which means that two new parameters have been added to control
when groups or accounts are created/removed. You might need to update your
inventory configuration if you use the role to create UNIX groups without
corresponding accounts, or you put UNIX accounts in shared primary groups.
The ``user`` parameter can be used to disable the account management, so that
only UNIX group is created. The ``private_group`` parameter controls the
management of the UNIX group for a given configuration entry. See the role
documentation for more details.
Inventory variable changes
~~~~~~~~~~~~~~~~~~~~~~~~~~
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment