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 路径	可选地设置用户的主目录。
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返回为已更改。因为 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" ← (默认)
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 布尔值	是否创建 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"
标准错误输出 字符串	运行命令的标准错误输出。 返回：当命令返回标准错误输出时 示例： "Group wheels does not exist"
标准输出 字符串	运行命令的标准输出。 返回：当命令返回标准输出时
system 布尔值	该账户是否为系统账户。 返回：当system传递给模块且账户不存在时 示例：true
uid 整数	用户账户的用户ID。 返回：当uid传递给模块时 示例： 1044

作者

• Stephen Fromm (@sfromm)

资源链接

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