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 字符串	可选地设置用户的主组（采用组名）。 在 macOS 上，此选项默认为 staff。
groups 列表 / 元素=字符串	用户也是其成员的补充组的列表。 默认情况下，用户将从所有其他组中删除。配置 append 以修改此设置。 当设置为空字符串 '' 时，用户将从除主组之外的所有组中删除。 在 Ansible 2.3 之前，唯一允许的输入格式是逗号分隔的字符串。
hidden 布尔值	仅限 macOS，可选地从登录窗口和系统偏好设置中隐藏用户。 如果使用了 system 选项，则默认值为 true。 选项 false true
home 路径	可选地设置用户的 home 目录。
local 布尔值	强制在实现“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：输入哈希密码作为值。 有关生成密码哈希值的各种方法的详细信息，请参阅 FAQ 条目。 要在 Linux 系统上创建具有锁定/禁用密码的帐户，请将其设置为 '!' 或 '*'。 要在 OpenBSD 上创建具有锁定/禁用密码的帐户，请将其设置为 '*************'。 OS X/macOS：输入纯文本密码作为值。请务必采取相关的安全预防措施。 在 macOS 上，无论用户帐户是否已存在，都将始终设置 password 选项中指定的密码。 当密码作为参数传递时，ansible.builtin.user 模块对于 macOS 系统始终会返回 changed 为 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 字符串	可选地设置一个 home 骨架目录。 需要 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 系统上删除用户的其他要求，请参阅此 FAQ 条目。 选项 "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 中运行并返回 changed 状态预测，而无需修改目标，如果不受支持，则将跳过操作。
diff_mode	支持：无	当处于 diff 模式时，将返回有关已更改的内容（或在 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

添加或删除 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

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

作者

• Stephen Fromm (@sfromm)

集合链接

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