Commit c4882063 authored by Maciej Delmanowski's avatar Maciej Delmanowski

Add new role, 'debops.system_users'

parent c3837ee5
......@@ -1357,6 +1357,13 @@ stages:
JANE_DIFF_PATTERN: '.*/debops.system_groups/.*'
JANE_LOG_PATTERN: '\[debops\.system_groups\]'
'system_users role':
<<: *test_role_no_deps
JANE_TEST_PLAY: '${DEBOPS_PLAYBOOKS}/service/system_users.yml'
JANE_DIFF_PATTERN: '.*/debops.system_users/.*'
JANE_LOG_PATTERN: '\[debops\.system_users\]'
'swapfile role':
<<: *test_role_no_deps
......@@ -45,6 +45,10 @@ Added
.. __:
- :ref:`debops.system_users` role replaces the ``debops.bootstrap`` role and
is used to manage the local system administrator accounts. It is included
in the :file:`common.yml` playbook as well as the bootstrap playbooks.
- [debops.nginx] The role will automatically generate configuration which
redirects short hostnames or subdomains to their FQDN equivalents. This
allows HTTP clients to reach websites by specifying their short names via DNS
......@@ -125,9 +125,8 @@
- role: debops.system_groups
tags: [ 'role::system_groups', 'skip::system_groups' ]
# This role will be replaced by a new role that manages UNIX system accounts
#- role: debops.bootstrap
# tags: [ 'role::bootstrap', 'skip::bootstrap' ]
- role: debops.system_users
tags: [ 'role::system_users', 'skip::system_users' ]
- role: debops.pam_access
tags: [ 'role::pam_access', 'skip::pam_access' ]
......@@ -65,5 +65,5 @@
- role: debops.system_groups
tags: [ 'role::system_groups', 'skip::system_groups' ]
- role: debops.bootstrap
tags: [ 'role::bootstrap', 'skip::bootstrap' ]
- role: debops.system_users
tags: [ 'role::system_users', 'skip::system_users' ]
......@@ -124,6 +124,9 @@
- role: debops.system_groups
tags: [ 'role::system_groups', 'skip::system_groups' ]
- role: debops.system_users
tags: [ 'role::system_users', 'skip::system_users' ]
- role: debops.pam_access
tags: [ 'role::pam_access', 'skip::pam_access' ]
- name: Manage local users and groups
hosts: [ 'debops_all_hosts', 'debops_service_system_users' ]
become: True
environment: '{{ inventory__environment | d({})
| combine(inventory__group_environment | d({}))
| combine(inventory__host_environment | d({})) }}'
- role: debops.system_users
tags: [ 'role::system_users', 'skip::system_users' ]
debops.system_users - Manage admin accounts using Ansible
Copyright (C) 2019 Maciej Delmanowski <>
Copyright (C) 2019 DebOps
This Ansible role is part of DebOps.
DebOps is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3, as
published by the Free Software Foundation.
DebOps is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with DebOps. If not, see
This diff is collapsed.
- role: debops.secret
- role: debops.ansible_plugins
role_name: 'system_users'
author: 'Maciej Delmanowski'
description: 'Manage UNIX system accounts'
company: 'DebOps'
license: 'GPL-3.0'
min_ansible_version: '2.7.0'
- name: Ubuntu
- precise
- trusty
- xenial
- bionic
- name: Debian
- wheezy
- jessie
- stretch
- buster
- system
- users
- admins
- acl
This diff is collapsed.
#!{{ ansible_python['executable'] }}
# {{ ansible_managed }}
from __future__ import print_function
from json import loads, dumps
from sys import exit
output = loads("""{{ {'configured': True,
'prefix': system_users__prefix
} | to_nice_json }}""")
print(dumps(output, sort_keys=True, indent=4))
{% set system_users__tpl_shells = [] %}
{% for shell in (system_users__combined_accounts | parse_kv_items | selectattr("state", "equalto", "present") | selectattr("shell", "defined") | map(attribute="shell") | unique | list) %}
{% if shell in system_users__shell_package_map.keys() %}
{% set _ = system_users__tpl_shells.append(system_users__shell_package_map[shell]) %}
{% endif %}
{% endfor %}
{{ system_users__tpl_shells | to_json }}
......@@ -257,6 +257,7 @@ Security
- :ref:`debops.sshd`
- :ref:`debops.sudo`
- :ref:`debops.system_groups`
- :ref:`debops.system_users`
- :ref:`debops.tcpwrappers`
- ``debops-contrib.apparmor``
- ``debops-contrib.firejail``
......@@ -289,6 +290,7 @@ System configuration
- :ref:`debops.sysfs`
- :ref:`debops.sysnews`
- :ref:`debops.system_groups`
- :ref:`debops.system_users`
- :ref:`debops.users`
- :ref:`debops.yadm`
- ``debops.console``
This diff is collapsed.
# Manage system UNIX user accounts
# A basic account
- name: 'user1'
group: 'user1'
# More elaborate account with system administrator access and dotfiles
- name: 'user2'
group: 'user2'
admin: True
shell: '/bin/zsh'
dotfiles_enabled: True
dotfiles_repo: ''
# An user account with a random password, stored in 'secret/'. This user
# account will be added in the 'users' UNIX group instead of its own group.
- name: 'user3'
group: 'users'
update_password: 'on_create'
password: '{{ lookup("password", secret + "/credentials/" + ansible_fqdn
+ "/users/user3/password encrypt=sha512_crypt length=30") }}'
# Remove an user account if it exists
- name: 'user_removed'
state: 'absent'
# Manage different system UNIX 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'
# Manage user resources
- name: 'user1'
group: 'user1'
# Create a directory in user's $HOME
- 'Documents'
# Create a symlink to /tmp directory in user's $HOME. Owner and group
# need to be specified for symlinked resources owned by other accounts
# (for example ``root``), otherwise the role will change the owner/group
# of the link source.
- dest: 'tmp'
state: 'link'
src: '/tmp'
owner: 'root'
group: 'root'
# Copy your custom public and private SSH keys to remote user
- path: '.ssh/github_id_rsa'
src: '~/.ssh/github_id_rsa'
state: 'file'
mode: '0600'
parent_mode: '0700'
- path: '.ssh/'
src: '~/.ssh/'
state: 'file'
mode: '0644'
parent_mode: '0700'
# Add custom SSH configuration on an user account
- path: '.ssh/config'
state: 'file'
mode: '0640'
parent_mode: '0700'
content: |-
User git
IdentityFile ~/.ssh/github_id_rsa
# Make sure a file in the user's $HOME directory does not exist
- path: 'removed'
state: 'absent'
Getting started
.. contents::
.. _system_users__ref_libuser:
Support for ``libuser`` library
The role uses the ``libuser`` library, supported by the ``group`` and ``user``
Ansible modules, to manage the UNIX groups and accounts present on the hosts.
The library is used to ensure that the groups and accounts created locally on
the host that uses the LDAP directory as the user/group database have UID/GID
values in the correct ranges, thus avoiding collisions with the LDAP directory
UID/GID ranges. Without the ``libuser`` these local groups and accounts would
be created in the LDAP UID/GID ranges, since the normal UNIX user management
tools pick the next UID/GID based on the contents of the ``getent`` output, and
not from the local user and group databases.
This behaviour can be controlled using the ``item.local`` parameter, which by
default is enabled and shouldn't be specified directly unless you want to
override the use of the ``libuser`` library for some reason. Due to issues with
the Ansible modules, additional UNIX groups are managed using normal UNIX tools
instead of their ``libuser`` equivalents.
LDAP integration
The role checks if the LDAP support has been configured on a host, via the
:ref:`debops.ldap`. If LDAP support is enabled, local UNIX groups, local UNIX
accounts and their home directory names will have the ``_`` prefix prepended to
them, to avoid clashes with the LDAP-based groups and accounts. This is
controlled by the :envvar:`system_users__prefix` variable.
LDAP support also affects the default home directory paths. By default home
directories will be put in :file:`/home`; with LDAP support enabled that will
change to :file:`/var/local`, to avoid clashes with remote filesystems that
might be mounted at the :file:`/home` path, for example via NFS.
Example inventory
The ``debops.system_users`` Ansible role is included by default in the
:file:`common.yml` DebOps playbook; you don't need to do anything to have it
executed. It's also included in the :file:`bootstrap.yml` and
:file:`bootstrap-ldap.yml` playbooks to create sysadmin accounts during host
If you don’t want to let ``debops.system_users`` manage user accounts, you can
disable it with the following setting in your inventory:
.. code-block:: yaml
system_users__enabled: False
Example playbook
If you are using this role without DebOps, here's an example Ansible playbook
that uses the ``debops.system_users`` role:
.. literalinclude:: ../../../../ansible/playbooks/service/system_users.yml
:language: yaml
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 host is first
configured to speed up playbook execution, when you are sure that most of the
configuration has not been changed.
Common role tags:
Main role tag, should be used in the playbook to execute all of the role
tasks as well as role dependencies.
Main role tag, should be used in the playbook to skip all of the role tasks.
Used in specific tasks that might break in the Ansbible ``--check`` mode on
first run of the role on a host, but not subsequent runs. It can be used to
skip these tasks in such case.
You can see full list of available role tags by executing the command:
.. code-block:: console
debops service/system_users --list-tags
.. _debops.system_users:
The ``debops.system_users`` Ansible role can be used to manage local user
accounts and groups. The role allows for certain operations inside of the home
directories, like configuration of the mail forwarding, SSH public keys or
automatic deployment of user configuration files (dotfiles).
This role is designed to manage the local system administrator accounts, and
its behaviour will change if the support for LDAP is configured on a host. You
can also use the :ref:`debops.users` role which provides similar functionality,
but is designed to manage regular user accounts and application accounts,
without special modifications related to LDAP support.
.. toctree::
:maxdepth: 2
.. literalinclude:: ../../../../ansible/roles/debops.system_users/COPYRIGHT
Local Variables:
mode: rst
ispell-local-dictionary: "american"
......@@ -8,6 +8,11 @@ groups. The role allows for certain operations inside of the home directories,
like configuration of the mail forwarding, SSH public keys or automatic
deployment of user configuration files (dotfiles).
This role is designed to manage regular user accounts and application accounts.
In a LDAP-enabled environment, it might be better to configure these using LDAP
directory, and manage local system administrator accounts using the
:ref:`debops.system_users` Ansible role.
.. toctree::
:maxdepth: 2
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