community.general.homectl module – Manage user accounts with systemd-homed
Note
This module is part of the community.general collection (version 8.6.4).
You might already have this collection installed if you are using the ansible
package.
It is not included in ansible-core
.
To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install community.general
.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.general.homectl
.
New in community.general 4.4.0
Synopsis
Manages a user’s home directory managed by systemd-homed.
Aliases: system.homectl
Requirements
The below requirements are needed on the host that executes this module.
Python 3.12 or earlier
Parameters
Parameter |
Comments |
---|---|
The intended home directory disk space. Human readable value such as |
|
The email address of the user. |
|
String separated by comma each containing an environment variable and its value to set for the user’s login session, in a format compatible with ``putenv()``. Any environment variable listed here is automatically set by pam_systemd for all login sessions of the user. |
|
Sets the gid of the user. If using Only used when a user is first created. |
|
Path to use as home directory for the user. This is the directory the user’s home directory is mounted to while the user is logged in. This is not where the user’s data is actually stored, see Only used when a user is first created. |
|
The name of an icon picked by the user, for example for the purpose of an avatar. Should follow the semantics defined in the Icon Naming Specification. See https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html for specifics. |
|
Path to place the user’s home directory. See https://www.freedesktop.org/software/systemd/man/homectl.html#–image-path=PATH for more information. Only used when a user is first created. |
|
The preferred language/locale for the user. This should be in a format compatible with the |
|
A free-form location string describing the location of the user. |
|
Whether the user account should be locked or not. Choices:
|
|
String separated by comma each indicating a UNIX group this user shall be a member of. Groups the user should be a member of should be supplied as comma separated list. |
|
String separated by comma each indicating mount options for a users home directory. Valid options are Homed by default uses |
|
The user name to create, remove, or update. |
|
A time since the UNIX epoch after which the record should be considered invalid for the purpose of logging in. |
|
A time since the UNIX epoch before which the record should be considered invalid for the purpose of logging in. |
|
Set the user’s password to this. Homed requires this value to be in cleartext on user creation and updating a user. The module takes the password and generates a password hash in SHA-512 with 10000 rounds of salt generation using crypt. See https://systemd.io/USER_RECORD/. This is required for |
|
Password hint for the given user. |
|
The ‘realm’ a user is defined in. |
|
The user’s real (‘human’) name. This can also be used to add a comment to maintain compatibility with |
|
When used with Choices:
|
|
Shell binary to use for terminal logins of given user. If not specified homed by default uses |
|
The absolute path to the skeleton directory to populate a new home directory from. This is only used when a home directory is first created. If not specified homed by default uses |
|
String separated by comma each listing a SSH public key that is authorized to access the account. The keys should follow the same format as the lines in a traditional |
|
The operation to take on the user. Choices:
|
|
Indicates the storage mechanism for the user’s home directory. If the storage type is not specified, ``homed.conf(5)`` defines which default storage to use. Only used when a user is first created. Choices:
|
|
Preferred timezone to use for the user. Should be a tzdata compatible location string such as |
|
Sets the UID of the user. If using Only used when a user is first created. |
|
Sets the umask for the user’s login sessions Value from |
Attributes
Attribute |
Support |
Description |
---|---|---|
Support: full |
Can run in |
|
Support: none |
Will return details on what has changed (or possibly needs changing in |
Notes
Note
This module does not work with Python 3.13 or newer. It uses the deprecated crypt Python module from the Python standard library, which was removed from Python 3.13.
Examples
- name: Add the user 'james'
community.general.homectl:
name: johnd
password: myreallysecurepassword1!
state: present
- name: Add the user 'alice' with a zsh shell, uid of 1000, and gid of 2000
community.general.homectl:
name: alice
password: myreallysecurepassword1!
state: present
shell: /bin/zsh
uid: 1000
gid: 1000
- name: Modify an existing user 'frank' to have 10G of diskspace and resize usage now
community.general.homectl:
name: frank
password: myreallysecurepassword1!
state: present
disksize: 10G
resize: true
- name: Remove an existing user 'janet'
community.general.homectl:
name: janet
state: absent
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
---|---|
A json dictionary returned from Returned: success Sample: |