DEBOPS.SYSTEM_GROUPS(5)

NAME
debops.system_groups - Manage UNIX system groups with Ansible

SYNOPSIS

debops service/system_groups [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The UNIX system groups are used on Linux hosts for low level access control mechanism for different system services. Debian by default creates a a set of UNIX system groups <https://wiki.debian.org/SystemGroups> which control access to various parts of the system.

The debops.system_groups Ansible role is used to configure additional UNIX system groups that are used on hosts managed by DebOps. It can also be used to define sudo and systemd-tmpfiles configuration for these UNIX groups.

Additionally, a simple Access Control List managed by the role in the Ansible local facts can be used by other Ansible roles to configure access for selected UNIX groups to the services managed by these roles.

GETTING STARTED

  Access Control List

The debops.system_groups role maintains a simple Access Control List in the Ansible local facts, under ansible_local.system_groups.access.* variable hierarchy. Other roles can inspect it to get a list of UNIX group names which they can use to configure access in their respective applications.

The ansible_local.system_groups.access variable is a YAML dictionary. Each key of this dictionary corresponds to a particular resource, and the value is a list of UNIX group names. The resources are user-defined, by default the role creates:

root
    Members of these UNIX groups have full, privileged access to the root account on a given host. This resource should be reserved to system administrators.

sshd
    Members of these UNIX groups can login to the host via the SSH service. See debops.sshd role for more details.

webserver
    Members of these UNIX groups can manipulate various webserver-related services. See debops.nginx and debops.php roles for more details.

  Example inventory

The debops.system_groups role is included by default in the common.yml DebOps playbook; you don't need to add hosts to any Ansible groups to enable it.

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.system_groups role:

---
- name: Configure UNIX system groups
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_all_hosts', 'debops_service_system_groups' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: python
      tags: [ 'role::python', 'skip::python', 'role::ldap' ]
      python__dependent_packages3:
        - '{{ ldap__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ ldap__python__dependent_packages2 }}'
    - role: ldap
      tags: [ 'role::ldap', 'skip::ldap' ]
      ldap__dependent_tasks:
        - '{{ sudo__ldap__dependent_tasks }}'
    - role: sudo
      tags: [ 'role::sudo', 'skip::sudo' ]
    - role: system_groups
      tags: [ 'role::system_groups', 'skip::system_groups' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::system_groups
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

  Other resources

List of other useful resources related to the debops.system_groups Ansible role:

•   Manual pages: group(5) <https://manpages.debian.org/group(5)>, sudoers(5) <https://manpages.debian.org/sudoers(5)>, tmpfiles.d(5) <https://manpages.debian.org/tmpfiles.d(5)>

•   Debian System Groups <https://wiki.debian.org/SystemGroups> documentation on Debian Wiki

•   UNIX permissions <https://wiki.debian.org/Permissions> documentation on Debian Wiki

•   User Private Groups <https://wiki.debian.org/UserPrivateGroups> documentation on Debian Wiki

•   Security privileges <https://wiki.ubuntu.com/Security/Privileges> documentation on Ubuntu Wiki

•   Multi User Management <https://wiki.ubuntu.com/MultiUserManagement> documentation on Ubuntu Wiki

•   UNIX group identifier <https://en.wikipedia.org/wiki/Group_identifier> page on Wikipedia

DEFAULT VARIABLE DETAILS

Some of debops.system_groups default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  system_groups__list

The system_groups__*_list variables define what UNIX system groups should be present on a given host, and can optionally create or modify configuration of selected services. The variables are list of YAML dictionaries, each dictionary defining one UNIX group.

The lists are combined together in the order specified by the system_groups__combined_list variable and the entries with the same name parameters will be merged. This can be used to change the configuration of existing entries via Ansible inventory.

Each entry can specify a set of parameters:

name
    Required. The name of the UNIX group to manage. This should be an alphanumeric string, you can check the groupadd(8) <https://manpages.debian.org/groupadd(8)> manpage for allowed characters. This parameter is used as a key for merging multiple configuration entries together in order of appearance.

gid Optional. Specify the group ID (GID) of a given UNIX group. If not specified, it will be selected automatically.

system
    Optional, boolean. If True (default), the created UNIX group will be a "system" group with GID < 1000.

state
    Optional. If present, the specified UNIX group will be created and its configuration in different services will be set. If absent, the UNIX group will not be created, but existing configuration will be left in place.

    If init, the configuration for a given UNIX group will be prepared but it will not be active - this can be done conditionally in a later configuration entry. If ignore, a given configuration entry will be ignored by the role and its parameters will not affect a given UNIX group.

members
    Optional. List of UNIX accounts that should be the members of a given UNIX group. Only existing UNIX accounts will be added by the role.

sudoers
    Optional. A string or YAML text block which specifies the sudo configuration for a given UNIX group. It will be saved as /etc/sudoers.d/system_groups-<group> configuration file.

    If the value is False, or the parameter is not specified, the sudo configuration file will be removed.

    See sudoers(5) <https://manpages.debian.org/sudoers(5)> manual page for information about the configuration syntax. The role does not ensure that the configuration is related to the specified UNIX group, you should ensure that independently using the sudo configuration options.

sudoers_filename
    Optional. Override the filename of the sudo configuration file in the /etc/sudoers.d/ directory. This might be useful if you need to change the order of the sudo configuration options. You shouldn't change the filename of existing configuration, because the role will lose track of it.

tmpfiles
    Optional. A string or YAML text block which specifies the configuration of temporary files and directories maintained by the system-tmpfiles command. It will be saved as /etc/tmpfiles.d/system_groups-<group>.conf configuration file.

    If the value is False, or the parameter is not specified, the systemd-tmpfiles configuration file will be removed.

    See tmpfiles.d(5) <https://manpages.debian.org/tmpfiles.d(5)> manual page for information about the configuration syntax. The role does not ensure that the configuration is related to the specified UNIX group, you should ensure that independently using the systemd-tmpfiles configuration options.

tmpfiles_filename
    Optional. Override the filename of the systemd-tmpfiles configuration file in the /etc/tmpfiles.d/ directory. This might be useful if you need to change the order of the systemd-tmpfiles configuration options. You shouldn't change the filename of existing configuration, because the role will lose track of it. The filename should contain the .conf suffix, otherwise it will be ignored by systemd-tmpfiles command.

    The role maintains a simple Access Control List using Ansible local facts which can be used by other Ansible roles to augment their configuration. The parameters below control the ACL configuration.

access
    Optional. A string or a list of resources which correspond to Access Control List entries. A given UNIX group will be added to all of the ACL entries with corresponding resources.

    The access parameter should be used in default or initial configuration, using it in the inventory will override the default list of resources of a given UNIX group.

allow
    Optional. A string or a list of resources which correspond to Access Control List entries. A given UNIX group will be added to all of the ACL entries with corresponding resources.

    The allow parameter should be used in additional configuration entries to augment an existing ACL entries. Currently the configuration of ACL from multiple entries is not merged automatically, but existing ACL entries are preserved.

deny
    Optional. A string or a list of resources which corresdpond to Access Control List entries. A given UNIX group will be removed from all of the ACL entries specified here.

    The deny parameter should be used in additional configuration entries to augment an existing ACL entries. Currently the configuration of ACL from multiple entries is not merged automatically, but existing ACL entries are preserved.

  Examples

Create a system UNIX group for an application that is composed of multiple UNIX accounts for better access control. The group will use a temporary directory as a shared communication channel and will allow its members to reload system services via sudo commands. Members of the group will be allowed to connect to the host via SSH.

system_groups__list:
  - name: 'application'
    members: [ 'app-core', 'app-webui', 'app-admin1', 'app-admin2' ]
    sudoers: |
      User_Alias  APP_ADMINS   = app-admin1, app-admin2
      Runas_Alias APP_SERVICES = app-core, app-webui
      Cmnd_Alias  APP_RELOAD   = /bin/systemctl reload app-core.service,\
                                 /bin/systemctl reload app-webui.service
      Cmnd_Alias  APP_RESTART  = /bin/systemctl restart app-core.service,\
                                 /bin/systemctl restart app-webui.service
      Cmnd_Alias  APP_STATUS   = /bin/systemctl status app-core.service,\
                                 /bin/systemctl status app-webui.service
      # Allow service reloads for all members, even services
      %application ALL = (root) NOPASSWD: APP_RELOAD
      # Allow more control over services for application administrators
      APP_ADMINS ALL = (root) NOPASSWD: APP_RESTART, APP_STATUS
      # Allow administrators to switch to the service UNIX accounts and run
      # commands on their behalf, after authentication
      APP_ADMINS ALL = (APP_SERVICES) ALL
    tmpfiles: |
      # Temporary directory for UNIX sockets
      d   /run/application   2771 root application  - -
    access: [ 'sshd' ]

You might need to add the individual accounts to the UNIX group in your role if they don't exist before the debops.system_groups role is executed, afterwards the role will ensure that the specified members are present in the group.

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2022, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others