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 轮盐生成。 请参阅 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	支持: 不支持	在差异模式下，将返回有关已更改内容（或可能需要在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)

集合链接

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