arensb.truenas.user module – Manage user accounts

Note

This module is part of the arensb.truenas collection (version 1.11.4).

To install it, use: ansible-galaxy collection install arensb.truenas.

To use it in a playbook, specify: arensb.truenas.user.

New in arensb.truenas 0.1.0

Synopsis

  • Add, change, and delete user accounts.

Parameters

Parameter

Comments

append

boolean

If true, the user will be added to the groups listed in groups, but not removed from any other groups.

If false, the user will be added to the groups listed in groups, and removed from any other groups.

Choices:

  • false ← (default)

  • true

append_pubkeys

boolean

If true, the keys specified in ssh_authorized_keys will be added to the user’s ~/.ssh/authorized_keys, but any others that might be there will not be removed.

If false, any keys not explicitly listed in ssh_authorized_keys will be removed from the user’s ~/.ssh/authorized_keys.

Choices:

  • false ← (default)

  • true

comment

string

The full name (GECOS field) of the user.

Default: ""

create_group

boolean

If true, create a new group with the same name as the user.

If such a group already exists, it is used and no new group is created.

Choices:

  • false

  • true ← (default)

delete_group

boolean

If true, delete the user’s primary group if it is not being used by any other users.

If false, the primary group stays, even if it is now empty.

Only used when deleting a user.

Choices:

  • false

  • true ← (default)

email

string

User’s email address, in the form user@dom.ain.

group

string

The name of the user’s primary group.

Required unless create_group is true.

groups

list / elements=string

List of additional groups user will be added to.

If append is true, the user will be added to all of the groups listed here.

If append is false, then in addition, the user will be removed from all other groups (except the primary).

home

string

User’s home directory.

Note that TrueNAS has restrictions on what this can be. As of this writing, the home directory has to begin with “/mnt”, or be “/nonexistent”.

Note that if you create a user with home directory "/nonexistent", then later change it to a real directory, that directory will not be populated with dot files.

Note: If you create an account with a home directory that does not end in the username (e.g., if name: bob and home: /mnt/pool0/homes), TrueNAS will append the username to form the real home directory (/mnt/pool0/homes/bob, in this example). This is not recommended. It is better to use the full home directory, ending with the username.

name

aliases: user

string / required

Name of the user to manage.

password

string

User’s password, as a crypted string.

Required unless password_disabled is true.

Note: Currently there is no way to check whether the password needs to be changed, so this is used only when the user is created.

password_disabled

boolean

If true, the user’s password is disabled.

They can still log in through other methods (e.g., ssh key).

This is not a flag: if you set password_disabled=true on a user, the password field in /etc/master.passwd is set to *, so if you set password_disabled=false again, they won’t be able to log in with their old password.

If you need that functionality, do something like prepend “*LOCK*” to the crypt string when locking a user, then remove it when unlocking.

Note that under TrueNAS SCALE, a user with password_disabled may not use SMB, so be sure to set smb: false.

Choices:

  • false ← (default)

  • true

shell

string

User’s shell.

Must be one of the allowed shells from /etc/shells.

smb

boolean

Specifies whether user should have access to SMB shares.

Under TrueNAS SCALE, a user with smb enabled may not have their password disabled.

Choices:

  • false

  • true ← (default)

ssh_authorized_keys

aliases: pubkeys

list / elements=string

List of ssh public keys to put in the user’s .ssh/authorized_keys file.

state

string

Whether the user should exist or not.

Choices:

  • "absent"

  • "present" ← (default)

sudo

boolean

Deprecated. Use sudo_commands and/or sudo_commands_nopasswd instead.

Whether the user is allowed to sudo (see also sudo_nopasswd and sudo_commands).

Note: this defaults to false. So if you create a user with sudo: yes, then comment out that line, the user will be removed from sudo.

Choices:

  • false

  • true

sudo_commands

list / elements=string

List of commands the user is allowed to execute using sudo.

Each command must use an absolute path, except for the special value “ALL”, which allows executing any command.

Commands may include options, e.g., "/bin/ls -l".

In TrueNAS CORE, and in older versions of SCALE, only one of sudo_commands and sudo_commands_nopasswd may be specified.

Default: []

sudo_commands_nopasswd

list / elements=string

List of commands the user is allowed to execute using sudo, without having to give a password.

Each command must use an absolute path, except for the special value “ALL”, which allows executing any command.

Commands may include options, e.g., "/bin/ls -l".

In TrueNAS CORE, and in older versions of SCALE, only one of sudo_commands and sudo_commands_nopasswd may be specified.

Default: []

sudo_nopasswd

boolean

Deprecated. Use sudo_commands_nopasswd instead.

Allows user to sudo without a password.

Choices:

  • false ← (default)

  • true

uid

integer

Set the UID of the user.

If the IUID is already taken, this will create a second user with the same UID.

Examples

- name: Create an ordinary user and their group
  arensb.truenas.user:
    name: bob
    comment: "Bob the User"
    create_group: yes
    password: "<encrypted password string>"

- name: Create an ordinary user and put them into an existing group
  arensb.truenas.user:
    name: bob
    comment: "Bob the User"
    group: users
    password: "<encrypted string>"

- name: Create a user without a working password
  arensb.truenas.user:
    name: bob
    comment: "Bob the User"
    group: bobsgroup
    password_disabled: yes

- name: Delete a user
  arensb.truenas.user:
    name: bob
    state: absent

- name: Delete a user, but keep their primary group, even if it's now empty.
  arensb.truenas.user:
    name: bob
    state: absent
    delete_group: no

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

user_id

integer

The ID of a newly-created user.

This is not the uid as found in /etc/passwd, but the database ID.

Returned: success