DEBOPS.LIBUSER(5)

NAME
debops.libuser - Install libuser on a Debian/Ubuntu host using Ansible

SYNOPSIS

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

DESCRIPTION

The libuser <https://pagure.io/libuser/> library and its corresponding package provides a set of commands and an API which can be used by tools like Ansible to manage UNIX account and group configuration in different NSS databases (local /etc/passwd and /etc/group databases, LDAP, NIS, etc.). This allows to abstract away user and group management and make it independent from the underlying database.

The debops.libuser role installs and configures the libuser package on Debian or Ubuntu hosts. The library is used by some other DebOps roles like debops.users, debops.system_users to manage local UNIX accounts and groups when the hosts are joined to an LDAP environment. The default configuration set up by the role ensures that Ansible user and group modules, when instructed, can correctly create local account and group entries in the passwd and group databases.

GETTING STARTED

  Example inventory

The debops.libuser Ansible role is included by default in the common.yml DebOps playbook; you don't need to do anything to have it executed. It's also included in the bootstrap.yml and the bootstrap-ldap.yml playbooks to help create the local sysadmin accounts during host bootstrapping.

If you don’t want to let debops.libuser manage user accounts, you can disable it with the following setting in your inventory:

libuser__enabled: False

  Example playbook

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

---
- name: Manage local users and groups
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_all_hosts', 'debops_service_libuser' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: libuser
      tags: [ 'role::libuser', 'skip::libuser' ]

  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:

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

skip::libuser
    Main role tag, should be used in the playbook to skip all of the role tasks.

DEFAULT VARIABLE DETAILS

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

  libuser__configuration

  Examples

See the libuser__original_configuration variable for the original contents of the /etc/libuser.conf file and how they are represented in the role configuration.

  Syntax

Each entry in the list is a YAML dictionary that describes the configuration file in the /etc/libuser.conf, using specific parameters:

name
    Required. This parameter defines the option name, and it needs to be unique in a given configuration file. Parameters from different options lists with the same name are merged together when the configuration entries are merged.

options
    Optional. A YAML list of libuser configuration options defined in the configuration file. The options parameters from different configuration entries are merged together, therefore it's easy to modify specific parameters without the need to copy the entire value to the inventory.

    Each element of the options list is a YAML dictionary with specific parameters:

name
    Required for the main options. The Name of the libuser option to add.

option
    Optional. Override the name parameter to allow for multiple configuration options with the same parameter.

state
    Optional. If not specified or present, the entry will be added in the configuration file. If absent, the entry will be removed from the configuration file. If comment, the entry will be included in the configuration file, but commented out.

comment
    Optional. String or a YAML text block with a comment added to a given configuration entry.

separator
    Optional, boolean. If True, add an empty line before the configuration parameter, useful for visually separating configuration options.

value
    Optional for main options. If specified, set a value of a given option.

AUTHOR
Leonardo Bechea, Alin Alexandru

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