Default variable details

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

system_users__accounts

The system_users__*_groups and system_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

---

# Manage different system UNIX groups
system_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'

---

# Manage system UNIX user accounts
system_users__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: 'https://git.example.org/user2/dotfiles'

  # 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 user resources
system_users__accounts:

  - name: 'user1'
    group: 'user1'
    resources:

      # 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/github_id_rsa.pub'
        src: '~/.ssh/github_id_rsa.pub'
        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: |-
          Host github.com
              User git
              IdentityFile ~/.ssh/github_id_rsa

      # Make sure a file in the user's $HOME directory does not exist
      - path: 'removed'
        state: 'absent'

Syntax

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. 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.

prefix

Optional. An additional string prepended to the UNIX group name, UNIX account name, and the home directory name. If not specified, the system_users__prefix value is used instead. This functionality is used to separate the local users (with the _) prefix from the LDAP users, when the host is configured with the debops.ldap role. To override the prefix when LDAP support is enabled, set the parameter to an empty string ('').

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 debops.system_groups Ansible role to define UNIX groups with additional functionality like sudo configuration, etc.

local

Optional, boolean. If not specified or True, the role will use the libuser library to manage the UNIX groups and accounts in the local account and group database. If False, the role will use standard UNIX tools to manage accounts, which might have unintended effects. On normal operation you shouldn't need to define this parameter, it's enabled or disabled by the role as needed.

See Support for libuser library for more details.

system

Optional, boolean. If True, a given user account and primary group will be a "system" account and group, with it's UID and GID < 1000. If the value is not specified or False, the user account and group will be a "normal" account and group with UID and GID >= 1000.

admin

Optional, boolean. If defined and True, a given user account is configured as a "system administrator" account. This account will be automatically added to the UNIX groups managed by the debops.system_groups role, usually admins. The UNIX group name may change depending on the presence of the LDAP configuration to include a _ prefix do distinguish locally managed UNIX groups to those defined in LDAP.

uid

Optional. Specify the UID of the UNIX user account.

gid

Optional. Specify the GID of the primary group for a given user account.

group

Optional. Name of the UNIX group which will be set as the primary group of 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.

append

Optional, boolean. If True (default), the specified groups will be added to the list of existing groups the account belongs to. If False, all other groups than those present on the group list will be removed stripped.

comment

Optional. A comment, or GECOS field configured for a specified UNIX account.

shell

Optional. Specify the default shell to run when a given UNIX account logs in. If not specified, the default system shell (usually /bin/sh will be used instead).

password

Optional. Specify the encrypted hash of the user's password which will be set for a given UNIX account. You can use the lookup("password") lookup to generate the hash. See examples for more details.

update_password

Optional. If set to on_create, the password will be set only one on initial user creation. If set to always, the password will be updated on each Ansible run if it's different.

The module default is to always update the password, the debops.users default is to only update the password on initial user creation.

no_log

Optional, boolean. If defined and True, a given entry will not be logged during the Ansible run. If not specified, if the password parameter is specified, the role will automatically disable logging as well.

non_unique

Optional, boolean. If True, allows setting the UID to a non-unique value.

linger

Optional, boolean. If True, the UNIX account will be allowed to linger when not logged in and manage private services via it's own systemd user instance. If False, the linger option will be disabled.