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 浮点数	以 epoch 为单位的用户过期时间，它将在不支持此功能的平台上被忽略。 目前在 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 路径	可选地设置用户的主目录。
local 布尔值	在实现它的平台上强制使用“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" ← (默认)
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" ← (默认) "on_create"

属性

属性	支持	描述
check_mode	支持：完全支持	可以在 check_mode 下运行并返回更改状态预测，而无需修改目标，如果不受支持，则操作将被跳过。
diff_mode	支持：不支持	将在差异模式下返回有关已更改内容（或可能需要在 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

返回值

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

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

作者

• Stephen Fromm (@sfromm)

集合链接

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