user

Содержание

user#

Модуль ansible.builtin.user управляет учетными записями пользователей и их атрибутами.

Особенности работы#

Для выполнения задач модуль использует системные утилиты управления учетными записями пользователей, которые, как правило, предустановлены в операционной системе. Если необходимые компоненты отсутствуют, выполнение завершится с ошибкой.

В macOS для управления учетными записями применяется утилита dscl, а для настройки групп – dseditgroup.

Во FreeBSD для управления учетными записями используются утилиты pw и chpass:

pw useradd и chpass для создания;
pw usermod и chpass для изменения;
pw userdel для удаления;
pw lock и pw unlock для блокирования и разблокирования.

В дистрибутивах Linux для управления учетными записями применяются стандартные команды:

useradd для создания;
usermod для изменения;
userdel для удаления.

В системах семейства SunOS модуль напрямую редактирует файл /etc/shadow, в котором хранятся зашифрованные пароли, и автоматически создает его резервную копию. В остальных платформах резервное копирование этого файла выполняется средствами используемых системных утилит.

Примечание

Для управления учетными записями пользователей в ОС Windows используйте модуль ansible.windows.win_user.

Параметры#

Модуль принимает следующие параметры:

append#

Способ обработки значения параметра groups.

Возможные значения:

true – учетная запись будет добавлена в указанные группы;
false – учетная запись будет включена только в перечисленные группы, а из всех остальных будет исключена.

Значение по умолчанию: false.

authorization#

Список привилегий для учетной записи пользователя.

Поддерживается в ОС Illumos и Solaris.

Можно указать несколько значений, разделенных запятыми, например:

---
- name: Assigning authorizations to the user
  ansible.builtin.user:
    name: ansible_user
    authorization: "solaris.admin.user.manage,solaris.admin.logsvc.read"

Для удаления всех привилегий используйте пустую строку ('').

comment#

Описание (GECOS) учетной записи.

Значение по умолчанию в macOS: значение параметра name. В остальных ОС значение по умолчанию не задано.

create_home, createhome#

Создание домашнего каталога (если отсутствует) при создании учетной записи пользователя.

Возможные значения:

false – домашний каталог не будет создан;
true – домашний каталог будет создан.

Значение по умолчанию: true.

expires#

Время окончания действия учетной записи пользователя в формате epoch.

Поддерживается в ОС GNU/Linux, DragonFly BSD (только положительные значения) и FreeBSD.

Чтобы снять ограничение по времени, укажите отрицательное значение.

force#

Принудительное выполнение действия.

Применяется в двух ситуациях:

state=absent

Принудительное удаление учетной записи пользователя и связанных с ним каталогов.

Применение параметра аналогично использованию утилиты userdel с параметром --force. Тонкости поведения зависят от используемой ОС. Подробности см. во встроенной справке:
```
man userdel
```
Возможные значения:
- false – безопасное удаление;
- true – принудительное удаление.
state=present и generate_ssh_key=yes

Перезаписывает существующий ключ SSH.

Возможные значения:
- false – ключ SSH не перезаписывается;
- true – перезапись ключа SSH.

Значение по умолчанию: false.

generate_ssh_key#

Генерация ключа SSH.

Возможные значения:

false – ключ не будет сгенерирован;
true – генерация ключа.

Предупреждение

Существующий ключ SSH будет перезаписан, если force=true.

Значение по умолчанию: false.

group#

Основная (первичная) группа.

Значение по умолчанию в macOS: staff. В остальных ОС значение по умолчанию не задано.

groups#

Дополнительные группы.

По умолчанию учетная запись пользователя исключается из всех остальных групп. Чтобы изменить это поведение, используйте параметр append.

Для исключения учетной записи пользователя из всех групп, кроме основной, используйте пустую строку ('').

hidden#

Скрытие учетной записи пользователя в окне авторизации и системных настройках.

Поддерживается только в macOS.

Чтобы скрыть учетную запись с экрана входа в систему, модуль изменяет конфигурационный файл /Library/Preferences/com.apple.loginwindow.plist.

Возможные значения:

false – учетная запись видна в указанных окнах;
true – скрытие учетной записи.

Значение по умолчанию (только при использовании параметра system): true.

home#: Путь к домашнему каталогу.

local#

Использование локальных аналогов утилит управления учетными записями пользователей (например, luseradd вместо useradd), если такие существуют в системе. При отсутствии нужных утилит и файлов выполнение задачи завершится с ошибкой.

Если база локальных учетных записей пользователей размещена не в /etc/passwd, параметр может работать некорректно.

Возможные значения:

false – использование стандартных утилит;
true – принудительное использование утилит для управление локальными учетными записями.

Значение по умолчанию: false.

login_class#

Класс учетной записи пользователя.

Применимо для большинства BSD-систем.

move_home#

Перемещение домашнего каталога учетной записи пользователя в новое место, если такой каталог существует.

Используется только совместно с параметром home.

Возможные значения:

false – домашний каталог не будет перенесен;
true – перенос домашнего каталога в расположение, указанное в значении параметра home.

Значение по умолчанию: false.

name, user#

Обязательный параметр.

Название учетной записи пользователя.

non_unique#

Разрешение использования неуникального идентификатора пользователя (UID).

Возможные значения:

false – использование неуникального UID запрещено;
true – использование неуникального UID разрешено.

Значение по умолчанию: false.

password#

Пароль учетной записи пользователя.

Возможные значения зависят от операционной системы:

Для Linux, Unix и POSIX-совместимых ОС указывается хеш пароля, а не открытый текст (plain text).

Чтобы создать учетную запись пользователя с заблокированным паролем:
- в Linux установите значение ! или *;
- в OpenBSD установите значение *************.
Для macOS укажите пароль в открытом виде (plain text).
Предупреждение
- Хранение паролей в открытом виде (особенно в сценариях) небезопасно. Для их защиты рекомендуется использовать Ansible Vault.
- Заданный пароль для macOS всегда перезаписывает существующий, даже если учетная запись уже создана.
- Ansible будет считать, что объект изменен (changed=true), даже если пароль совпадает с предыдущим.

password_expire_account_disable#

Количество дней после истечения срока действия пароля до отключения учетной записи.

Поддерживается в следующих ОС:

AIX;
Linux;
NetBSD;
OpenBSD.

password_expire_max#

Максимальное количество дней, в течение которых пользователь может использовать один и тот же пароль. После истечения указанного времени система потребует его сменить.

Поддерживается только в Linux.

password_expire_min#

Количество дней, которое должно пройти после смены пароля, в течение которого запрещено повторно изменять пароль.

Поддерживается только в Linux.

password_expire_warn#

Количество дней до истечения срока действия пароля, когда пользователь начинает получать предупреждение при входе в систему.

Поддерживается только в Linux.

password_lock#

Блокирование или разблокирование пароля.

Примечание

Применение параметра не блокирует учетную запись.

Действует аналогично утилитам:

usermod с параметрами -L или -U;
pw lock.

Поддерживается в следующих ОС:

DragonFly BSD;
FreeBSD;
Linux;
NetBSD;
OpenBSD.

Чтобы разблокировать пароль укажите false. Параметр не обладает значением по умолчанию и не разблокирует пароль без явного указания.

Возможные значения:

false – разблокирование пароля;
true – блокирование пароля.

profile#

Профиль учетной записи пользователя.

Поддерживается в ОС Illumos и Solaris.

Можно указать несколько значений, разделенных запятыми, например:

---
- name: Assigning profiles to a user
  ansible.builtin.user:
    name: ansible_user
    profile: "Basic,Admin"

Для удаления всех профилей используйте пустую строку ('').

remove#

Удаление связанных каталогов учетной записи пользователя.

Применение параметра аналогично использованию утилиты userdel с параметром --remove. Подробности см. во встроенной справке:

man userdel

Используется только при state=absent.

Возможные значения:

false – связанные каталоги не удаляются;
true – удаление связанных каталогов.

Значение по умолчанию: false.

role#

Роль учетной записи пользователя.

Поддерживается в ОС Illumos и Solaris.

Можно указать несколько значений, разделенных запятыми, например:

---
- name: Assigning roles to a user
  ansible.builtin.user:
    name: ansible_user
    role: "Operator,NetworkAdmin"

Для удаления всех ролей используйте пустую строку ('').

seuser#

Тип seuser, например:

---
- name: Create a user with seuser user_u
  ansible.builtin.user:
    name: devuser
    seuser: user_u

Поддерживается в ОС с SELinux.

shell#

Путь к оболочке, используемой пользователем.

Значение по умолчанию зависит от операционной системы:

macOS – /bin/bash;
остальные ОС – определяется системой.

skeleton#

Путь к шаблону домашнего каталога, содержимое которого копируется в создаваемый домашний каталог учетной записи пользователя.

Используется только при create_home=true.

ssh_key_bits#

Длина ключа SSH в битах.

Значение по умолчанию определяется утилитой ssh-keygen на целевом узле.

ssh_key_comment#

Комментарий к ключу SSH.

Значение по умолчанию: ansible-generated on $HOSTNAME.

ssh_key_file#

Путь к создаваемому ключу SSH, включая его название.

Относительный путь применяется к домашнему каталогу учетной записи пользователя. Например, если для этого параметра задано значение .ssh/ansible/key, то абсолютный путь для создания ключа SSH будет /home/$USER/.ssh/ansible/key.

Значение по умолчанию: .ssh/id_rsa.

ssh_key_passphrase#

Парольная фраза для закрытого ключа SSH.

Если значение не задано, ключ создается без нее.

ssh_key_type#

Тип ключа SSH.

Возможные значения зависят от системы целевого узла.

Значение по умолчанию: rsa.

state#

Требуемое состояние учетной записи.

Возможные значения:

absent – если учетная запись существует, она будет удалена.
present – учетная запись должна существовать. Если это не так, она будет создана.

Значение по умолчанию: present.

system#

Тип учетной записи (обычная или системная).

Используется только при state=present в значении создания новой учетной записи.

Предупреждение

Параметр не влияет на уже существующие учетные записи.

Возможные значения:

false – создание обычной учетной записи;
true – создание системной учетной записи.

Значение по умолчанию: false.

uid#: Идентификатор (UID) учетной записи пользователя.

uid_max#

Максимальное значение UID.

Поддерживается только в Linux.

Переопределяет значение параметра UID_MAX, указанное в конфигурационном файле /etc/login.defs.

Используется только при local=false.

uid_min#

Минимальное значение UID.

Поддерживается только в Linux.

Переопределяет значение параметра UID_MIN, указанное в конфигурационном файле /etc/login.defs.

Используется только при local=false.

umask#

Маска (umask) учетной записи пользователя.

Поддерживается только в Linux.

Используется только при local=false.

Пример использования:

---
- name: Create a user with umask 027
  ansible.builtin.user:
    name: ansible_user
    umask: "027"

Задача установит маску 027 для учетной записи. Именно такие права доступа будут задаваться по умолчанию для новых файлов и каталогов, которые пользователь создаст в системе.

update_password#

Управление обновлением пароля учетной записи пользователя.

Возможные значения:

always – пароль будет обновлен при каждом запуске задачи, если отличается от текущего;
on_create – пароль будет установлен только при создании новой учетной записи.

Значение по умолчанию: always.

Пример использования:

---
- name: Create a user and set a password only when creating
  ansible.builtin.user:
    name: ansible_user
    password: "{{ 'mypass' | password_hash('sha512') }}"
    update_password: on_create

В этом примере:

если учетная запись уже существует, ее пароль не изменится;
если учетная запись новая, ей будет установлен заданный пароль.

Возвращаемые значения#

В этом списке указаны только возвращаемые значения, специфичные для модуля ansible.builtin.user.

append – учетная запись добавлена в группы.

Условия: state=present и учетная запись уже существует.
comment – комментарий из файла /etc/passwd. Обычно содержит название учетной записи.

Условия: учетная запись существует.
create_home – домашний каталог создан.

Условия: учетная запись не существует и не включен режим проверки (check mode).
force – учетная запись была удалена принудительно.

Условия: state=absent и учетная запись существует.
group – идентификатор основной группы учетной записи.

Условия: учетная запись существует.
groups – список дополнительных групп, в которые входит учетная запись.

Условия: значение groups не пустое и state=present.
home – путь к домашнему каталогу учетной записи.

Условия: state=present.
move_home – указано ли перемещение домашнего каталога.

Условия: state=present и учетная запись существует.
name – название учетной записи пользователя.

Условия: всегда.
password – значение пароля в зашифрованном виде.

Условия: state=present и значение password не пустое.
remove – учетная запись была удалена.

Условия: state=absent и учетная запись существует.
shell – путь к оболочке пользователя.

Условия: state=present.
ssh_fingerprint – отпечаток (fingerprint) сгенерированного ключа SSH.

Условия: generate_ssh_key=true.
ssh_key_file – путь к приватному ключу SSH.

Условия: generate_ssh_key=true.
ssh_public_key – содержимое сгенерированного публичного ключа SSH.

Условия: generate_ssh_key=true.
stderr – вывод ошибок от команды, вызванной модулем.

Условия: при наличии ошибок выполнения.
stdout – стандартный вывод команды, вызванной модулем.

Условия: при наличии стандартного вывода.
system – системная ли учетная запись.

Условия: значение system задано, и учетная запись еще не создана.
uid – идентификатор учетной записи (UID).

Условия: значение параметра uid задано.

Атрибуты#

Атрибуты определяют функции Ansible, которые может использовать модуль.

Атрибут	Описание
`check_mode`	Модуль работает в режиме проверки (`check_mode`) в полном объеме. Режим проверки позволяет узнать что произойдет при выполнении указанных действий с пакетами.
`diff_mode`	Модуль не поддерживает режим сравнения (`diff_mode`).
`platform`	Модуль поддерживает только POSIX-совместимые ОС.

Примеры#

Для изучения возможностей модуля ознакомьтесь с приведенными ниже примерами.

Создание учетной записи с заданным UID и основной группой#

Следующий пример описывает создание учетной записи test_user с UID 1040, описанием и основной группой admin:

---
- name: Add user 'test_user' with UID 1040 and primary group
  ansible.builtin.user:
    name: test_user
    comment: user for testing
    uid: 1040
    group: admin

Создание учетной записи с домашним каталогом#

Следующий пример описывает создание учетной записи test_user с домашним каталогом, оболочкой Bash и комментарием:

---
- name: Create user 'test_user' with home directory and shell
  ansible.builtin.user:
    name: test_user
    create_home: yes
    shell: /bin/bash
    comment: project manager

Добавление учетной записи в несколько групп#

Следующий пример описывает добавление учетной записи devops в группы admins и developers, не удаляя ее из уже назначенных групп:

---
- name: Add user 'devops' to multiple groups
  ansible.builtin.user:
    name: devops
    groups: admins,developers
    append: yes
    shell: /bin/bash
    comment: DevOps account

Удаление учетной записи и домашнего каталога#

Следующий пример описывает удаление учетной записи пользователя test_user вместе с домашним каталогом:

---
- name: Remove user 'test_user' and home directory
  ansible.builtin.user:
    name: test_user
    state: absent
    remove: yes

Создание ключа SSH для пользователя#

Следующий пример описывает создание пользовательского ключа SSH длиной 2048 бит для пользователя devops в каталоге /home/devops/.ssh/:

---
- name: Generate SSH key for user 'devops'
  ansible.builtin.user:
    name: devops
    generate_ssh_key: yes
    ssh_key_bits: 2048
    ssh_key_file: .ssh/id_rsa

Создание учетной записи с ограниченным сроком действия#

Следующий пример описывает создание учетной записи consultant, срок действия которой истекает в заданный момент времени:

---
- name: Add temporary user 'consultant' with expiration
  ansible.builtin.user:
    name: consultant
    shell: /bin/zsh
    groups: developers
    comment: External consultant
    expires: 1767214740  # 31 декабря 2025 года, 23:59

Снятие срока действия учетной записи#

Следующий пример описывает снятие ограничения на срок действия учетной записи пользователя consultant:

---
- name: Remove expiration for user 'consultant'
  ansible.builtin.user:
    name: consultant
    expires: -1

Настройка максимального срока действия пароля#

Следующий пример описывает установку срока действия пароля для учетной записи пользователя accountant:

---
- name: Set maximum password age for user 'accountant'
  ansible.builtin.user:
    name: accountant
    password_expire_max: 10

Настройка минимального срока действия пароля#

Следующий пример описывает запрет смены пароля пользователем accountant ранее чем через 5 дней после установки:

---
- name: Set minimum password age for user 'accountant'
  ansible.builtin.user:
    name: accountant
    password_expire_min: 5

Предупреждение об истечении срока действия пароля#

Следующий пример описывает настройку предупреждения за 1 день до истечения срока действия пароля учетной записи пользователя accountant:

---
- name: Set password expiration warning for user 'accountant'
  ansible.builtin.user:
    name: accountant
    password_expire_warn: 1

Отключение учетной записи после истечения пароля#

Следующий пример описывает настройку отключения учетной записи пользователя consultant через 15 дней после истечения срока действия его пароля. Учетная запись будет отключена только в том случае, если после окончания срока действия пароля он не будет обновлен.

---
- name: Disable account after password expires for user 'consultant'
  ansible.builtin.user:
    name: consultant
    password_expire_account_disable: 15