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 samename
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. 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.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 to0751
.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 defaultsftponly
. 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 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.