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 密钥。 除非与 force=yes 一起使用，否则这 **不会** 覆盖现有的 SSH 密钥。 选项 false ← (默认) true
group 字符串	可选地设置用户的 primary group（需要一个组名）。 在 macOS 上，这默认为 'staff'
groups 列表 / 元素=字符串	用户也是其成员的辅助组列表。 默认情况下，用户将从所有其他组中删除。配置 append 可修改此设置。 设置为空字符串 '' 时，用户将从除 primary group 之外的所有组中删除。 在 Ansible 2.3 之前，只允许使用逗号分隔的字符串作为输入格式。
hidden 布尔值	仅限 macOS，可选地从登录窗口和系统偏好设置中隐藏用户。 如果使用了 system 选项，则默认为 true。 选项 false true
home 路径	可选地设置用户的 home directory。
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选项中指定的密码都将始终被设置。 当密码作为参数传递时，user模块将始终将 macOS 系统的 changed 返回为true。因为 macOS 现在不再直接提供对哈希密码的访问。
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 由此模块调用的底层工具确定。有关调用的工具的每个平台列表，请参见“注释”。
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" ← (默认)
system 布尔值	在创建帐户state=present时，将其设置为true会将用户设置为系统帐户。 此设置无法在现有用户上更改。 选项 false ← (默认) true
uid 整数	可选地设置用户的*UID*。
umask 字符串 在 ansible-core 2.12 中添加	设置用户的 umask。 当前在 Linux 上受支持。与其他平台一起使用时不起作用。 需要省略local或False。
update_password 字符串	always如果密码不同，将更新密码。 on_create仅为新创建的用户设置密码。 选项 "always" ← (默认) "on_create"

属性

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

注释

注意

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

• 在 SunOS 平台上，由于此模块直接编辑 shadow 文件，因此会自动备份 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

添加或删除 SSH 授权密钥。

ansible.builtin.group

添加或删除组。

ansible.windows.win_user

管理本地 Windows 用户帐户。

示例

- 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

返回值

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

键	描述
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
用户名 字符串	用户账户名。 返回值： 始终返回 示例： "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 字符串	运行命令的标准错误输出。 返回值： 当运行的命令返回标准错误输出时 示例： "Group wheels does not exist"
stdout 字符串	运行命令的标准输出。 返回值： 当运行的命令返回标准输出时
system 布尔值	账户是否为系统账户。 返回值： 当将 system 传递给模块且账户不存在时 示例：true
uid 整数	用户账户的用户ID。 返回值： 当将 uid 传递给模块时 示例： 1044

作者

• Stephen Fromm (@sfromm)

资源链接

• 问题追踪
• 代码仓库
• 通信