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__accounts

The users__*_groups and 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 UNIX groups
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 UNIX user accounts
users__accounts:

  # A basic account
  - name: 'user1'

  # More elaborate account with SSH access and dotfiles
  - name: 'user2'
    group: 'user2'
    groups: [ 'sshusers' ]
    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'

  # An example SFTPonly application account with custom ACL entries for the web
  # server access. SFTPonly configuration is managed in the 'debops.sshd' role,
  # SSH keys need to be set up with 'debops.authorized_keys', home directory is
  # owned by the 'root' account and users don't have write permissions there,
  # only in subdirectories.
  - name: 'application'
    group: 'application'
    chroot: True
    comment: 'SFTPonly application account'
    home: '/home/application'
    home_mode: '0750'
    home_acl:

      - entity: 'www-data'
        etype: 'group'
        permissions: 'x'

    # Create directories in the home directory that are owned by the
    # application account, where a given user can create their own files. The
    # home directory is owned by 'root' and not writable by the user to allow
    # chrooting.
    resources:
      - 'files'
      - 'sites/example.org/public'
---

# Manage user resources
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.

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.

chroot

Optional, boolean. If defined and True, a given user account is configured to support SFTPonly operation, and certain defaults are changed if not overridden by other parameters.

The owner of the home directory will be the root account instead of the user, to allow chrooting to that directory, the home directory group will be the primary group of a given user. The default permissions are set to 0751.

The default shell is set based on the users__chroot_shell variable, by default it will be /usr/sbin/nologin. Any dotfiles configured globally or for that UNIX account are not installed due to permission issues in the home directory.

The account will be added to UNIX groups specified in the users__chroot_groups variable, by default sftponly. See the debops.sshd role for details about configuring the SFTPonly access in OpenSSH server.

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.