ansible.builtin.user 模块 – 管理用户账户

注意

此模块是 ansible-core 的一部分，并包含在所有 Ansible 安装中。在大多数情况下，即使不指定集合关键字，您也可以使用短模块名称 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 路径	可选地设置用户的主目录。
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`
密码字符串	如果提供，则将用户的密码设置为提供的加密哈希（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` 相同，请查看 man 手册以了解详细信息和支持。选项 `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 系统上删除用户的其他要求，请参阅此 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 平台上，由于此模块直接编辑影子文件，因此会自动备份影子文件。在其他平台上，影子文件由该模块使用的底层工具备份。
在 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"`
密码字符串	密码的掩码值。返回: 当 `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)

ansible.builtin.user 模块 – 管理用户账户

概要

参数

属性

注释

参见

示例

返回值

作者

集合链接

概要 

参数 

属性 

注释 

参见 

示例 

返回值 