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

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使不指定 collections 关键字，也可以使用简短模块名称 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 路径	可选地设置用户的 home 目录。
local 布尔值	强制在实现它的平台上使用“本地”命令替代方案。 这在使用集中式身份验证的环境中很有用，当您想要操作本地用户时（换句话说，它使用 luseradd 而不是 useradd）。 这将检查 /etc/passwd 以查看是否在调用命令之前存在现有帐户。如果本地帐户数据库存在于除 /etc/passwd 之外的其他地方，则此设置将无法正常工作。 这要求目标主机上必须存在上述命令以及 /etc/passwd，否则将出现致命错误。 选项 false ← (默认) true
login_class 字符串	可选地设置用户的登录类，这是大多数 BSD 操作系统的一项功能。
move_home 布尔值	如果与 home 一起使用时设置为 true，则尝试将用户的旧 home 目录移动到指定目录（如果该目录尚未存在且旧 home 存在）。 选项 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 模块将始终返回更改为 true 用于 macOS 系统。由于 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 密钥文件名。 如果这是一个相对文件名，则它将相对于用户的 home 目录。 此参数默认为 .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	支持：无	将在 diff 模式下返回有关更改内容（或可能需要在 check_mode 下更改的内容）的详细信息。
platform	平台： posix	可以对其进行操作的目标操作系统/系列

备注

注意

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

• 在 SunOS 平台上，影子文件会自动备份，因为此模块会直接对其进行编辑。在其他平台上，影子文件由此模块使用的底层工具备份。

• 在 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 布尔值	是否创建主目录。 返回：当用户不存在且不处于 check 模式时 示例： 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)

集合链接

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