Default variable details

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

users__groups

The users__groups, users__group_groups and 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 users__default_system variable will determine the group type.

gid
Optional. Specify the GID of the managed UNIX group.
state
Optional. If present, the UNIX group will be created. If absent, the specified group will be removed.

Examples

---
# Manage different UNIX groups
users__groups:

  # A normal group
  - name: 'group1'

  # A system group
  - name: 'group1_sys'
    system: True

  # This group will be removed
  - name: 'group_removed'
    state: 'absent'

users__accounts

The users__accounts, users__group_accounts, 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.

General account parameters

name
Required. Name of the UNIX user account to manage.
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 False, the user account and group will be a "normal" account and group with UID and GID >= 1000.

If not specified, the users__default_system variable will determine the account and group type.

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.
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. You can also specify shell for all user accounts managed by this role using the users__default_shell variable.
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.

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

Examples

---
# Manage UNIX user accounts
users__accounts:

  # A basic account
  - name: 'user1'

  # More elaborate account with SSH access and dotfiles
  - name: 'user2'
    groups: [ 'sshusers' ]
    shell: '/bin/zsh'
    dotfiles_enabled: True

  # An user account with a random password, stored in 'secret/'
  - name: 'user3'
    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'

users__resources

The users__resources, users__group_resources and users__host_resources lists can be used to manage directories, files and symlinks for specific UNIX accounts using Ansible inventory. This functionality is meant to be used to manage small amounts of data, like custom configuration files, private SSH keys and so on. For more advanced management, you should consider using debops.resources Ansible role, or even writing a custom Ansible role from scratch.

Tasks that manage the resources are executed with the privileges of a specific user account; this account should exist (presumably it was created by the role earlier). This allows the usage of ~/ in the paths to manage directories and files relative to the user's $HOME directory.

Each entry on the list is a YAML dictionary with specific parameters:

name
Required. Name of the user account which will be used to run the Ansible tasks using the "become" method.
state

Required. This variable defines the resource state and it's type:

  • absent: the resource will be removed
  • directory: the resource is a directory
  • file: the resource is a file
  • link: the resource is a symlink
  • touch: the resource will create an empty file, or "touch" an existing file on each Ansible run

If this parameter is not specified, the resource will be treated as a directory.

dest or path
Required. Path to the resource managed by this entry. Usually you want to specify it as relative to the user's $HOME directory.
src

If the resource type is a link, this parameter specifies the target of the symlink.

If the resource type is a file, this parameter can be used to specify the source file on the Ansible Controller to copy to the remote host. It shouldn't be specified together with the content parameter.

content
If the resource type is a file, this parameter can be used to specify the contents of the file that is managed by this entry, usually in the form of a YAML text block. It shouldn't be specified together with the src parameter.
force
Optional, boolean. If True, the files will be always overwritten, if False, files will be copied only if they don't exist. This parameter can also be used to force creation of symlinks.
mode
Optional. Set specific permissions for a given file/directory/symlink.
recurse
Optional, boolean. Recursively set specified permission for all directories in the directory tree that lead to a given directory/file, depending on user privileges.
parent
Optional, boolean. If True (default), the role will create the parent directories of a given resource as needed, depending on the privileges of a given user account. If False, role will not try to create the missing directories.
parent_mode
Optional. Specify the permissions of the parent directory of a given file resource.
parent_recurse
Optional, boolean. If True, parent permissions will be applied recursively to all parent directories.

Examples

---
# Manage user resources
users__resources:

  # Create a directory in user's $HOME
  - name: 'user1'
    dest: '~/Documents'
    state: 'directory'

  # Create a symlink to /tmp directory in user's $HOME
  - name: 'user1'
    dest: '~/tmp'
    state: 'link'
    src: '/tmp'

  # Copy your custom public and private SSH keys to remote user
  - name: 'user1'
    path: '~/.ssh/github_id_rsa'
    src: '~/.ssh/github_id_rsa'
    state: 'file'
    mode: '0600'
    parent_mode: '0700'

  - name: 'user1'
    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
  - name: 'user1'
    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 does not exist
  - name: 'user1'
    path: '~/removed'
    state: 'absent'

users__dotfiles_map

This is a YAML dictionary which can be used to define sets of user configuration files. These sets can then be enabled globally or per user account as needed. Each set is a YAML dictionary with specific parameters:

repo
Required. An URL to the git repository which holds the user configuration files.
command
Optional. A command executed by Ansible used to deploy the dotfiles. The command will be executed with a given user privileges, in the dotfiles directory (by default ~/.config/dotfiles/).
creates
Optional. Path to the file which will indicate that the dotfiles have been deployed. If not specified, the command set in the command parameter will be executed on each Ansible run.
shell
Optional. Specify the shell which should be enabled for users that use a given set of user configuration files.

Examples

---
# Manage user configuration files
users__dotfiles_map:

  # A custom set of dotfiles
  'custom':
    repo: 'https://github.com/example/dotfiles.git'
    command: 'make install'

  # Another set of dotfiles activated by a file
  'example':
    repo: 'https://github.com/example2/dotfiles.git'
    command: 'make install'
    creates: '~/.bashrc.local'
    shell: '/bin/bash'

# Create an user account with specific set of dotfiles
users__accounts:

  - name: 'example_user'
    dotfiles_enabled: True
    dotfiles_name: 'example'