ansible.builtin.user 模块 - 管理用户帐户

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使没有指定 集合关键字，也可以使用简短的模块名称 user。但是，我们建议您使用 完全限定的集合名称 (FQCN) ansible.builtin.user，以便轻松链接到模块文档并避免与可能具有相同模块名称的其他集合冲突。

概要

• 管理用户帐户和用户属性。

• 对于 Windows 目标，请使用 ansible.windows.win_user 模块。

参数

参数	注释
append 布尔值	如果为 true，则将用户添加到 groups 中指定的组中。 如果为 false，则用户将仅添加到 groups 中指定的组中，并从所有其他组中删除。 选择 false ← (默认) true
authorization 字符串 在 Ansible 2.8 中添加	设置用户的授权。 可以使用逗号分隔设置多个授权。 要删除所有授权，请使用 authorization=''。 目前在 Illumos/Solaris 上受支持。在与其他平台一起使用时，不会执行任何操作。
comment 字符串	可选地设置用户帐户的描述（也称为GECOS）。 在 macOS 上，这默认为 name 选项。
create_home 别名：createhome 布尔值	除非设置为 false，否则在创建帐户时或如果主目录不存在，将为用户创建主目录。 从 Ansible 2.5 中的 createhome 更改为 create_home。 选择 false true ← (默认)
expires 浮点数	用户的到期时间（以纪元时间表示），它将在不支持此功能的平台上被忽略。 目前在 GNU/Linux、FreeBSD 和 DragonFlyBSD 上受支持。 从 Ansible 2.6 开始，您可以通过指定负值来删除到期时间。目前在 GNU/Linux 和 FreeBSD 上受支持。
force 布尔值	这仅影响 state=absent，它强制在受支持的平台上删除用户和关联目录。 行为与 userdel --force 相同，请检查系统上 userdel 的手册页以了解详细信息和支持。 当与 generate_ssh_key=yes 一起使用时，这将强制覆盖现有密钥。 选择 false ← (默认) true
generate_ssh_key 布尔值	是否为相关用户生成 SSH 密钥。 这将不会覆盖现有 SSH 密钥，除非与 force=yes 一起使用。 选择 false ← (默认) true
group 字符串	可选地设置用户的首要组（接受组名）。 在 macOS 上，这默认为 staff。
groups 列表 / 元素=字符串	用户也是其成员的辅助组列表。 默认情况下，用户将从所有其他组中删除。配置 append 以修改此行为。 当设置为空字符串 '' 时，用户将从除首要组之外的所有组中删除。 在 Ansible 2.3 之前，唯一允许的输入格式是逗号分隔的字符串。
hidden 布尔值	仅限 macOS，可选地从登录窗口和系统偏好设置中隐藏用户。 如果使用 system 选项，则默认值为 true。 选择 false true
home 路径	可选地设置用户的主目录。
local 布尔值	在实现它的平台上强制使用“本地”命令替代项。 这在使用集中式身份验证的环境中很有用，当您想要操作本地用户时（换句话说，它使用 luseradd 而不是 useradd）。 这将检查 /etc/passwd 以查看是否存在现有帐户，然后再调用命令。如果本地帐户数据库存在于除 /etc/passwd 之外的其他位置，则此设置将无法正常工作。 这要求目标主机上必须存在上述命令以及 /etc/passwd，否则将出现致命错误。 选择 false ← (默认) true
login_class 字符串	可选地设置用户的登录类别，这是大多数 BSD 操作系统的一项功能。
move_home 布尔值	如果与 home 一起使用时设置为 true，则尝试将用户的旧主目录移动到指定目录（如果该目录不存在，并且旧主目录存在）。 选择 false ← (默认) true
name 别名：user 字符串 / 必需	要创建、删除或修改的用户名称。
non_unique 布尔值	可选地，当与 -u 选项一起使用时，此选项允许将用户 ID 更改为非唯一值。 选择 false ← (默认) true
password 字符串	如果提供，则将用户的密码设置为提供的加密哈希（Linux）或纯文本密码（macOS）。 Linux/Unix/POSIX：输入哈希密码作为值。 有关生成密码哈希的各种方法的详细信息，请参阅 常见问题解答条目。 要在 Linux 系统上创建具有锁定/禁用密码的帐户，请将此设置为 '!' 或 '*'。 要在 OpenBSD 上创建密码被锁定/禁用的帐户，请将此设置为 '*************'。 OS X/macOS: 输入明文密码作为值。请务必采取相关的安全措施。 在 macOS 上，无论用户帐户是否已存在，password 选项中指定的密码都将始终被设置。 当密码作为参数传递时，ansible.builtin.user 模块将始终将 macOS 系统的 true 返回给 changed。因为 macOS 不再直接提供对哈希密码的访问权限。
password_expire_account_disable 整数 在 ansible-core 2.18 中添加	密码过期后帐户被禁用的天数。 目前支持 AIX、Linux、NetBSD、OpenBSD。
password_expire_max 整数 在 ansible-core 2.11 中添加	两次修改密码之间允许的最大天数。 仅支持 Linux。
password_expire_min 整数 在 ansible-core 2.11 中添加	两次修改密码之间允许的最小天数。 仅支持 Linux。
password_expire_warn 整数 在 ansible-core 2.16 中添加	密码过期前的警告天数。 仅支持 Linux。
password_lock 布尔值	锁定密码 (usermod -L，usermod -U，pw lock)。 平台的实现方式不同。此选项并不总是意味着用户无法通过其他方法登录。 此选项不会禁用用户，只会锁定密码。 要解锁当前被锁定的密码，必须将此设置为 false。缺少此参数将不会解锁密码。 目前支持 Linux、FreeBSD、DragonFlyBSD、NetBSD、OpenBSD。 选择 false true
profile 字符串 在 Ansible 2.8 中添加	设置用户的配置文件。 可以使用逗号分隔设置多个配置文件。 要删除所有配置文件，请使用 profile=''。 目前在 Illumos/Solaris 上受支持。在与其他平台一起使用时，不会执行任何操作。
remove 布尔值	此选项仅影响 state=absent，它尝试删除与用户关联的目录。 行为与 userdel --remove 相同，请查看手册页以了解详细信息和支持情况。 选择 false ← (默认) true
role 字符串 在 Ansible 2.8 中添加	设置用户的角色。 可以使用逗号分隔设置多个角色。 要删除所有角色，请使用 role=''。 目前在 Illumos/Solaris 上受支持。在与其他平台一起使用时，不会执行任何操作。
seuser 字符串	在启用 SELinux 的系统上，可以选择设置 seuser 类型 user_u。
shell 路径	可选地设置用户的 shell。 在 macOS 上，Ansible 2.5 之前，非系统用户的默认 shell 为 /usr/bin/false。从 Ansible 2.5 开始，macOS 上非系统用户的默认 shell 为 /bin/bash。 在其他操作系统上，默认 shell 由此模块调用的底层工具决定。请查看备注部分以了解每个平台调用的工具列表。 从 Ansible 2.18 开始，类型从 str 更改为 path。
skeleton 字符串	可选地设置主目录骨架目录。 需要 create_home 选项！
ssh_key_bits 整数	可以选择指定创建 SSH 密钥的位数。 默认值取决于 ssh-keygen。
ssh_key_comment 字符串	可选地定义 SSH 密钥的注释。 默认值： "ansible-generated on $HOSTNAME"
ssh_key_file 路径	可以选择指定 SSH 密钥的文件名。 如果这是一个相对文件名，那么它将相对于用户的家目录。 此参数默认为 .ssh/id_rsa。
ssh_key_passphrase 字符串	为 SSH 密钥设置密码。 如果没有提供密码，SSH 密钥将默认没有密码。
ssh_key_type 字符串	可以选择指定要生成的 SSH 密钥的类型。 可用的 SSH 密钥类型将取决于目标主机上存在的实现。 默认值： "rsa"
state 字符串	帐户是否应该存在，如果状态与声明的不同，则采取行动。 查看此 常见问题解答条目 以了解在 macOS 系统上删除用户时的其他要求。 选择 "absent" "present" ← (default)
system 布尔值	创建帐户 state=present 时，将其设置为 true 将使用户成为系统帐户。 此设置无法在现有用户上更改。 选择 false ← (默认) true
uid 整数	可选地设置用户的 UID。
uid_max 整数 在 ansible-core 2.18 中添加	设置用户创建的 UID_MAX 值。 覆盖 /etc/login.defs 的默认值。 目前支持 Linux。在使用其他平台时无效。 需要 local 被省略或为 False。
uid_min 整数 在 ansible-core 2.18 中添加	设置用户创建的 UID_MIN 值。 覆盖 /etc/login.defs 的默认值。 目前支持 Linux。在使用其他平台时无效。 需要 local 被省略或为 False。
umask 字符串 在 ansible-core 2.12 中添加	设置用户的 umask。 目前支持 Linux。在使用其他平台时无效。 需要 local 被省略或为 false。
update_password 字符串	always 将在密码不同时更新密码。 on_create 将仅为新创建的用户设置密码。 选择 "always" ← (default) "on_create"

属性

属性	支持	描述
check_mode	支持：完全支持	可以在 check_mode 下运行，并在不修改目标的情况下返回已更改状态预测，如果不支持，则操作将被跳过。
diff_mode	支持：不支持	将在差异模式下返回有关已更改内容（或可能需要在 check_mode 下更改的内容）的详细信息
platform	平台： posix	可以针对其执行操作的目标操作系统/系列

备注

注意

• 用户管理实用程序在每个平台上都有特定要求。但是，它们通常预装在系统中，Ansible 将要求它们在运行时存在。如果它们不存在，将显示描述性的错误消息。

• 在 SunOS 平台上，由于此模块直接编辑 shadow 文件，因此该文件会自动备份。在其他平台上，shadow 文件由此模块使用的底层工具备份。

• 在 macOS 上，此模块使用 dscl 来创建、修改和删除帐户。 dseditgroup 用于修改组成员身份。通过修改 /Library/Preferences/com.apple.loginwindow.plist 将帐户从登录窗口中隐藏。

• 在 FreeBSD 上，此模块使用 pw useradd 和 chpass 来创建，pw usermod 和 chpass 来修改，pw userdel 来删除，pw lock 来锁定，pw unlock 来解锁帐户。

• 在所有其他平台上，此模块使用 useradd 来创建，usermod 来修改，userdel 来删除帐户。

另请参阅

另请参阅

ansible.posix.authorized_key

ansible.posix.authorized_key 模块的官方文档。

ansible.builtin.group

添加或删除组。

ansible.windows.win_user

ansible.windows.win_user 模块的官方文档。

示例

- name: Add the user 'johnd' with a specific uid and a primary group of 'admin'
  ansible.builtin.user:
    name: johnd
    comment: John Doe
    uid: 1040
    group: admin

- name: Create a user 'johnd' with a home directory
  ansible.builtin.user:
    name: johnd
    create_home: yes

- name: Add the user 'james' with a bash shell, appending the group 'admins' and 'developers' to the user's groups
  ansible.builtin.user:
    name: james
    shell: /bin/bash
    groups: admins,developers
    append: yes

- name: Remove the user 'johnd'
  ansible.builtin.user:
    name: johnd
    state: absent
    remove: yes

- name: Create a 2048-bit SSH key for user jsmith in ~jsmith/.ssh/id_rsa
  ansible.builtin.user:
    name: jsmith
    generate_ssh_key: yes
    ssh_key_bits: 2048
    ssh_key_file: .ssh/id_rsa

- name: Added a consultant whose account you want to expire
  ansible.builtin.user:
    name: james18
    shell: /bin/zsh
    groups: developers
    expires: 1422403387

- name: Starting at Ansible 2.6, modify user, remove expiry time
  ansible.builtin.user:
    name: james18
    expires: -1

- name: Set maximum expiration date for password
  ansible.builtin.user:
    name: ram19
    password_expire_max: 10

- name: Set minimum expiration date for password
  ansible.builtin.user:
    name: pushkar15
    password_expire_min: 5

- name: Set number of warning days for password expiration
  ansible.builtin.user:
    name: jane157
    password_expire_warn: 30

- name: Set number of days after password expires until account is disabled
  ansible.builtin.user:
    name: jimholden2016
    password_expire_account_disable: 15

返回值

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

Key	描述
append 布尔值	是否将用户追加到组。 返回值： 当 state 为 present 且用户存在时 示例： true
comment 字符串	来自 passwd 文件的注释部分，通常是用户名。 返回值： 当用户存在时 示例： "Agent Smith"
create_home 布尔值	是否创建主目录。 返回： 当用户不存在且未处于检查模式时 示例： true
force 布尔值	用户帐户是否被强行删除。 返回： 当 state 为 absent 且用户存在时 示例： false
group 整数	主用户组 ID 返回值： 当用户存在时 示例： 1001
groups 字符串	用户所属的组列表。 返回： 当 groups 不为空且 state 为 present 时 示例： "chrony,apache"
home 字符串	用户主目录的路径。 返回： 当 state 为 present 时 示例： "/home/asmith"
move_home 布尔值	是否移动现有的主目录。 返回： 当 state 为 present 且用户存在时 示例： false
name 字符串	用户帐户名称。 返回： 始终 示例： "asmith"
password 字符串	密码的掩码值。 返回： 当 state 为 present 且 password 不为空时 示例： "NOT_LOGGING_PASSWORD"
remove 布尔值	是否删除用户帐户。 返回： 当 state 为 absent 且用户存在时 示例： true
shell 字符串	用户登录 Shell。 返回： 当 state 为 present 时 示例： "/bin/bash"
ssh_fingerprint 字符串	生成的 SSH 密钥的指纹。 返回： 当 generate_ssh_key 为 True 时 示例： "2048 SHA256:aYNHYcyVm87Igh0IMEDMbvW0QDlRQfE0aJugp684ko8 ansible-generated on host (RSA)"
ssh_key_file 字符串	生成的 SSH 私钥文件的路径。 返回： 当 generate_ssh_key 为 True 时 示例： "/home/asmith/.ssh/id_rsa"
ssh_public_key 字符串	生成的 SSH 公钥文件。 返回： 当 generate_ssh_key 为 True 时 示例： "'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC95opt4SPEC06tOYsJQJIuN23BbLMGmYo8ysVZQc4h2DZE9ugbjWWGS1/pweUGjVstgzMkBEeBCByaEf/RJKNecKRPeGd2Bw9DCj/bn5Z6rGfNENKBmo 618mUJBvdlEgea96QGjOwSB7/gmonduC7gsWDMNcOdSE3wJMTim4lddiBx4RgC9yXsJ6Tkz9BHD73MXPpT5ETnse+A3fw3IGVSjaueVnlUyUmOBf7fzmZbhlFVXf2Zi2rFTXqvbdGHKkzpw1U8eB8xFPP7y d5u1u0e6Acju/8aZ/l17IDFiLke5IzlqIMRTEbDwLNeO84YQKWTm9fODHzhYe0yvxqLiK07 ansible-generated on host'\n"
stderr 字符串	运行命令的标准错误。 返回： 当运行的命令返回 stderr 时 示例： "Group wheels does not exist"
stdout 字符串	运行命令的标准输出。 返回： 当运行的命令返回标准输出时
system 布尔值	帐户是否为系统帐户。 返回： 当 system 传递给模块且帐户不存在时 示例： true
uid 整数	用户帐户的用户 ID。 返回： 当 uid 传递给模块时 示例： 1044

作者

• Stephen Fromm (@sfromm)

集合链接

• 问题追踪器
• 仓库（源代码）
• 通信