Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
407 lines (313 sloc) 15.7 KB

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

.. literalinclude:: examples/manage-groups.yml
   :language: yaml

.. literalinclude:: examples/manage-accounts.yml
   :language: yaml

.. literalinclude:: examples/manage-resources.yml
   :language: yaml

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 :ref:`debops.system_groups` Ansible role to define UNIX groups with additional functionality like :command:`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 :ref:`users__ref_libuser` 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 :envvar:`users__chroot_shell` variable, by default it will be :file:`/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 :envvar:`users__chroot_groups` variable, by default sftponly. See the :ref:`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 :file:`/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 :command:`systemd` user instance. If False, the linger option will be disabled.

Parameters related to account state

state
Optional. If present, the UNIX user account and primary group will be created. If absent, the specified account and group will be removed.
force
Optional, boolean. If used with state parameter being absent, Ansible will execute the userdel --force command.
remove
Optional, boolean. If used with state parameter being absent, Ansible will execute the userdel --remove command.
expires
Optional. Specify the time in the UNIX epoch format, at which a given UNIX user account will be disabled.

Parameters related to home directories

home
Optional. Path to the home directory of a given user account. If not specified, the role will check the home directory path of an existing account defined on the host.
home_owner
Optional. Specify the owner of the home directory of a given UNIX account.
home_group
Optional. Specify the group of the home directory of a given UNIX account.
home_mode
Optional. Specify the mode of the home directory of a given UNIX account. If not specified, the value of the :envvar:`users__default_home_mode` will be used instead.
create_home
Optional, boolean. If True, the role will create the home directory for a given user account if it doesn't exist already. If not specified, home directory is created by default by the `Ansible user module`_.
move_home
Optional, boolean. If True and the managed user account already exists, Ansible will try to move it's home directory to the location specified in the home parameter if it isn't there already.
skeleton
Optional. Specify path to the directory, contents of which will be copied to the newly created home directory.
home_acl

Optional. Configure filesystem ACL entries of the home directory of a given UNIX user account. This parameter is a list of YAML dictionaries, each element uses a specific set of parameters derived from the acl Ansible module, see its documentation for details, as well as the 👨`acl(5)`, 👨`setfacl(1)` and 👨`getfacl` manual pages. Some useful parameters:

default
Optional, boolean. If True, set a given ACL entry as the default for new files and directories inside a given directory. Only works with directories.
entity
Name of the UNIX user account or group that a given ACL entry applies to.
etype
Specify the ACL entry type to configure. Valid choices: user, group, mask, other.
permissions
Specify the permission to apply for a given ACL entry. This parameter cannot be specified when the state of an ACL entry is set to absent.
recursive
Apply a given ACL entry recursively to all entities in a given path.
state
Optional. If not specified or present, the ACL entry will be created. If absent, the ACL entry will be removed. The query state doesn't make sense in this context and shouldn't be used.

Parameters related to the account's private SSH key

generate_ssh_key
Optional, boolean. If True, Ansible will generate a private SSH key for the specified account.
ssh_key_bits
Optional. Number of bits to use for the user's private SSH key. If not specified, role will use the `Ansible user module`_ default value.
ssh_key_comment
Optional. Add a custom comment to the generated SSH key.
ssh_key_file
Optional. Path where the private SSH key will be stored.
ssh_key_passphrase
Optional. Set a passphrase which will be required to decrypt the private SSH key.
ssh_key_type
Optional. Specify the SSH key type to generate. If not specified, RSA keys will be generated automatically.

Parameters related to public SSH keys

sshkeys
Optional. String or a YAML list of public SSH keys to configure for a given user account. The keys will be stored in the ~/.ssh/authorized_keys file.
sshkeys_exclusive
Optional, boolean. If True, the role will remove all keys from the user's ~/.ssh/authorized_keys file that are not specified in the sshkeys parameter.
sshkeys_state
Optional. If not specified or present, the SSH keys will be set on the user's account. If absent, the ~/.ssh/authorized_keys file will be removed entirely.

Parameters related to mail forwarding

forward
Optional. String or YAML list of e-mail addresses which will be used to forward mail directed to a given UNIX account. They will be stored in the ~/.forward file. This is only valid for MTAs that support this mechanism, for example Postfix MTA when local mail is enabled.
forward_state
Optional. If not specified or present, the e-mail addresses specified in the forward parameter will be added to the ~/.forward configuration file. If absent, the entries will be removed from the configuration file.

Parameters related to user configuration files

dotfiles_enabled / dotfiles
Optional, boolean. Enable or disable management of the user configuration files.
dotfiles_repo
Optional. An URL or an absolute path on the host to the :command:`git` repository with the user configuration files to deploy. If not specified, the default dotfiles repository, defined in the :envvar:`users__dotfiles_repo` variable, will be used instead. The repository will be deployed or updated using the :command:`yadm` script, installed by the :ref:`debops.yadm` Ansible role.

Parameters related to directory and file resources

resources

This parameter 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 :ref:`debops.resources` Ansible role, or even writing a custom Ansible role from scratch.

Tasks that manage the resources are executed as the root account, but the owner and group of the files is automatically set to those used by a given UNIX account. Directory and file paths will be prepended with a path to the $HOME directory of a given user, and should be defined as relative, without / at the beginning.

The resources parameter should contain a list of entries, each entry should be defined as either a path string which denotes a directory relative to the user's $HOME directory, or a YAML dictionary that describes a given resource using specific parameters:

dest or path
Required. Path to the resource managed by this entry, relative to the user's $HOME directory. All subdirectories specified in the path will be created automatically.
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.
src

If the resource type is a link, this parameter specifies the target of the symlink. In case of symlinks to resources owned by other UNIX accounts than the user, you need to specify the owner and group parameters to that of the symlinked file (for example root for files or directories owned by the root account), otherwise the role will change them to the owner/group of a given user.

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.

state

Optional. 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.

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.
owner
Optional. Specify the UNIX account which should be the owner of a given file/directory. For symlinks, this defines the owner of the link source and might be needed if the owner is different than the current user.
group
Optional. Specify the UNIX group which should be the primary group of a given file/directory. For symlinks, this defines the group of the link source and might be needed if the group is different than the primary group of the current user.
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_owner
Optional. Specify the UNIX account that should be the owner of a parent directory of a given resource.
parent_group
Optional. Specify the UNIX group that should be the main group of a parent directory of a given resource.
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.
You can’t perform that action at this time.