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 samename
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. IfFalse
, 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 thelibuser
library to manage the UNIX groups and accounts in the local account and group database. IfFalse
, 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 orFalse
, 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, usuallyadmins
. 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 UNIXgroup
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. IfFalse
, 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 toalways
, 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 thepassword
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. IfFalse
, the linger option will be disabled.