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
- Examples
- Syntax
- General account parameters
- Parameters related to account state
- Parameters related to home directories
- Parameters related to the account's private SSH key
- Parameters related to public SSH keys
- Parameters related to mail forwarding
- Parameters related to user configuration files
- Parameters related to directory and file resources
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.