community.general.homectl 模块 – 使用 systemd-homed 管理用户账户

注意

此模块是 community.general 集合（版本 10.1.0）的一部分。

如果您正在使用 ansible 包，您可能已经安装了此集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.general。您需要其他要求才能使用此模块，请参阅 要求 了解详细信息。

要在 playbook 中使用它，请指定：community.general.homectl。

community.general 4.4.0 中的新增功能

概要

• 管理由 systemd-homed 管理的用户的主目录。

要求

在执行此模块的主机上需要以下要求。

• legacycrypt（在 Python 3.13 或更新版本上）

参数

参数	注释
disksize 字符串	预期主目录磁盘空间。 人类可读的值，例如 10G、10M 或 10B。
email 字符串	用户的电子邮件地址。
environment 别名：setenv 字符串	以逗号分隔的字符串，每个字符串都包含一个环境变量及其值，以 ``putenv()`` 兼容的格式为用户的登录会话设置。 此处列出的任何环境变量都由 pam_systemd 为用户的所有登录会话自动设置。
gid 整数	设置用户的 gid。 如果使用 uid，则 homed 要求该值相同。 仅在首次创建用户时使用。
homedir 路径	用作用户主目录的路径。 这是用户登录时其主目录挂载到的目录。 这不是用户数据的实际存储位置，请参阅 imagepath。 仅在首次创建用户时使用。
iconname 字符串	用户选择的图标名称，例如用于头像。 应遵循图标命名规范中定义的语义。 有关详细信息，请参阅 https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html。
imagepath 路径	放置用户主目录的路径。 有关详细信息，请参阅 https://www.freedesktop.org/software/systemd/man/homectl.html#–image-path=PATH。 仅在首次创建用户时使用。
language 字符串	用户的首选语言/区域设置。 这应采用与 LANG 环境变量兼容的格式。
location 字符串	描述用户位置的自由格式位置字符串。
locked 布尔值	是否应锁定用户帐户。 选项 false true
memberof 别名：groups 字符串	以逗号分隔的字符串，每个字符串都指示此用户应成为成员的 UNIX 组。 用户应成为成员的组应以逗号分隔的列表形式提供。
mountopts 字符串	以逗号分隔的字符串，每个字符串都指示用户主目录的挂载选项。 有效选项为 nosuid、nodev 或 noexec。 默认情况下，Homed 使用 nodev 和 nosuid，而 noexec 处于关闭状态。
name 别名：user, username 字符串 / 必需	要创建、删除或更新的用户名。
notafter 整数	自 UNIX 纪元以来的时间，在此时间之后，该记录应被视为无效，无法用于登录。
notbefore 整数	自 UNIX 纪元以来的时间，在此时间之前，该记录应被视为无效，无法用于登录。
password 字符串	将用户的密码设置为此值。 Homed 要求此值在用户创建和更新用户时为明文。 该模块获取密码，并使用 crypt 生成 SHA-512 的密码哈希，并进行 10000 轮 salt 生成。 请参阅 https://systemd.io/USER_RECORD/。 这是 state=present 所必需的。当更新现有用户时，会根据 homed 中存储的哈希检查此值。
passwordhint 字符串	给定用户的密码提示。
realm 字符串	用户定义的“领域”。
realname 别名：comment 字符串	用户的真实（“人类”）姓名。 这也可以用于添加注释，以保持与 useradd 的兼容性。
resize 布尔值	当与 disksize 一起使用时，这将尝试立即调整主目录的大小。 选项 false ← (默认) true
shell 字符串	用于给定用户的终端登录的 Shell 二进制文件。 如果未指定，默认情况下，homed 使用 /bin/bash。
skeleton 别名: skel 路径	用于填充新主目录的骨架目录的绝对路径。 仅在首次创建主目录时使用。 如果未指定，默认情况下，homed 使用 /etc/skel。
sshkeys 字符串	以逗号分隔的字符串，其中每个字符串列出一个被授权访问该帐户的 SSH 公钥。 这些密钥应遵循传统 ~/.ssh/authorized_key 文件中行的格式。
state 字符串	要对用户执行的操作。 选项 "absent" "present" ← (默认)
storage 字符串	指示用户主目录的存储机制。 如果未指定存储类型，``homed.conf(5)`` 将定义要使用的默认存储。 仅在首次创建用户时使用。 选项 "classic" "luks" "directory" "subvolume" "fscrypt" "cifs"
timezone 字符串	用户首选的时区。 应该是一个与 tzdata 兼容的位置字符串，例如 America/New_York。
uid 整数	设置用户的 UID。 如果使用 gid，则 homed 要求该值相同。 仅在首次创建用户时使用。
umask 整数	设置用户登录会话的 umask。 值从 0000 到 0777。

属性

属性	支持	描述
check_mode	支持: 完全	可以在 check_mode 中运行并返回更改状态预测，而无需修改目标。
diff_mode	支持: 无	当处于 diff 模式时，将返回有关已更改的内容（或可能需要在 check_mode 中更改的内容）的详细信息。

说明

注意

• 此模块需要已弃用的 crypt Python 模块库，该库已从 Python 3.13 中删除。对于 Python 3.13 或更高版本，您需要安装 legacycrypt。

示例

- 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

返回值

常见的返回值记录在此处，以下是此模块特有的字段

键

描述

数据 字典

从 homectl inspect -j 返回的 json 字典。 返回: 成功 示例: {"data": {"binding": {"e9ed2a5b0033427286b228e97c1e8343": {"fileSystemType": "btrfs", "fileSystemUuid": "7bd59491-2812-4642-a492-220c3f0c6c0b", "gid": 60268, "imagePath": "/home/james.home", "luksCipher": "aes", "luksCipherMode": "xts-plain64", "luksUuid": "7f05825a-2c38-47b4-90e1-f21540a35a81", "luksVolumeKeySize": 32, "partitionUuid": "5a906126-d3c8-4234-b230-8f6e9b427b2f", "storage": "luks", "uid": 60268}}, "diskSize": 3221225472, "disposition": "regular", "lastChangeUSec": 1641941238208691, "lastPasswordChangeUSec": 1641941238208691, "privileged": {"hashedPassword": ["$6$ov9AKni.trf76inT$tTtfSyHgbPTdUsG0CvSSQZXGqFGdHKQ9Pb6e0BTZhDmlgrL/vA5BxrXduBi8u/PCBiYUffGLIkGhApjKMK3bV."]}, "signature": [{"data": "o6zVFbymcmk4YTVaY6KPQK23YCp+VkXdGEeniZeV1pzIbFzoaZBvVLPkNKMoPAQbodY5BYfBtuy41prNL78qAg==", "key": "-----BEGIN PUBLIC KEY----- MCowBQYDK2VwAyEAbs7ELeiEYBxkUQhxZ+5NGyu6J7gTtZtZ5vmIw3jowcY= -----END PUBLIC KEY----- "}], "status": {"e9ed2a5b0033427286b228e97c1e8343": {"diskCeiling": 21845405696, "diskFloor": 268435456, "diskSize": 3221225472, "service": "io.systemd.Home", "signedLocally": true, "state": "inactive"}}, "userName": "james"}}

作者

• James Livulpi (@jameslivulpi)

集合链接

• 问题跟踪器
• 存储库（源代码）
• 请求帮助
• 提交错误报告
• 请求新功能
• 沟通