Модуль community.general.ini_file — настройка параметров в INI-файлах

Примечание

Этот модуль входит в коллекцию community.general (версия 12.6.1).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Чтобы установить её, используйте: ansible-galaxy collection install community.general.

Чтобы использовать её в плейбуке, укажите: community.general.ini_file.

Краткое описание
Параметры
Атрибуты
Примечания
См. также
Примеры

Краткое описание

Управляет отдельными параметрами в файле в формате INI (добавляет, удаляет и изменяет их), избавляя от необходимости управлять файлом целиком с помощью, например, ansible.builtin.template или ansible.builtin.assemble.
Добавляет отсутствующие разделы, если они не существуют.
Этот модуль добавляет в файлы отсутствующие завершающие символы новой строки в соответствии со стандартом POSIX, даже если других изменений не требуется.

Параметры

Параметр	Комментарии
allow_no_value boolean	Разрешить параметр без значения и без символа «=». Варианты: `false` ← (по умолчанию) `true`
attributes псевдонимы: attr string	Атрибуты, которые должен иметь результирующий объект файловой системы. Список поддерживаемых флагов см. на странице руководства для `chattr` в целевой системе. Эта строка должна содержать атрибуты в том же порядке, в каком они отображаются командой `lsattr`. По умолчанию предполагается оператор `=`; в противном случае в строку необходимо включить оператор `+` или `-`.
backup boolean	Создать резервную копию файла с информацией о временной метке, чтобы можно было восстановить исходный файл, если он был случайно перезаписан некорректным образом. Варианты: `false` ← (по умолчанию) `true`
create boolean	Если задано значение `false`, модуль завершится с ошибкой, если файл ещё не существует. По умолчанию модуль создаёт файл, если он отсутствует. Варианты: `false` `true` ← (по умолчанию)
exclusive boolean добавлено в community.general 3.6.0	Если задано значение `true` (по умолчанию), при `state=absent` удаляются все совпадающие строки `option`, а при `state=present` они заменяются. Если задано значение `false`, при `state=present` добавляются только указанные `value`/`values`, а при `state=absent` они удаляются; существующие строки не изменяются. Варианты: `false` `true` ← (по умолчанию)
follow boolean добавлено в community.general 7.1.0	Этот флаг указывает, следует ли переходить по существующим ссылкам файловой системы. `follow=true` может изменить `path` в сочетании с такими параметрами, как `mode`. Варианты: `false` ← (по умолчанию) `true`
group string	Имя группы, которой должен принадлежать объект файловой системы; это значение передаётся команде `chown`. Если параметр не указан, используется текущая группа текущего пользователя, а если вы работаете от имени root — может быть сохранено прежнее владение.
ignore_spaces boolean добавлено в community.general 7.5.0	Не изменять строку, если изменение заключается только в добавлении или удалении пробелов до или после символа `=`. Варианты: `false` ← (по умолчанию) `true`
mode any	Права доступа, которые должен иметь результирующий объект файловой системы. Если вы привыкли к `/usr/bin/chmod`, помните, что права доступа на самом деле задаются восьмеричными числами. Необходимо предоставить Ansible достаточно информации для их корректного разбора. Для единообразия заключайте восьмеричные числа в кавычки (например, `'644'` или `'1777'`), чтобы Ansible получил строку и самостоятельно преобразовал её в число. Добавление ведущего нуля (например, `0755`) иногда работает, но может завершиться ошибкой в циклах и некоторых других случаях. Если передать Ansible число, не соблюдая ни одно из этих правил, оно будет интерпретировано как десятичное, что приведёт к неожиданным результатам. Начиная с Ansible 1.8, режим можно задавать в символьном формате (например, `u+rwx` или `u=rw,g=r,o=r`). Если `mode` не задан и целевой объект файловой системы не существует, при создании объекта для установки режима будет использоваться значение `umask` по умолчанию в системе. Если `mode` не задан и целевой объект файловой системы существует, будет использоваться режим существующего объекта файловой системы. Указание `mode` — лучший способ гарантировать, что объекты файловой системы будут созданы с правильными правами доступа. Дополнительные сведения см. в CVE-2020-1736.
modify_inactive_option boolean добавлено в community.general 8.0.0	По умолчанию модуль заменяет закомментированную строку, соответствующую заданному параметру. Задайте для этого параметра значение `false`, чтобы этого избежать. Это полезно, если вы хотите сохранить закомментированные примеры пар `key=value` для документации. Варианты: `false` `true` ← (по умолчанию)
no_extra_spaces boolean	Не вставлять пробелы до и после символа «=». Варианты: `false` ← (по умолчанию) `true`
option string	Если задано (обязательно для изменения `value`), это имя параметра. Можно не указывать, если добавляется или удаляется целый `section`.
owner string	Имя пользователя, которому должен принадлежать объект файловой системы; это значение передаётся команде `chown`. Если параметр не указан, используется текущий пользователь, а если вы работаете от имени root — может быть сохранено прежнее владение. Числовое имя пользователя будет интерпретировано как идентификатор пользователя, а не как имя. Во избежание путаницы не используйте числовые имена пользователей.
path псевдонимы: dest path / обязательно	Путь к файлу в формате INI; при необходимости файл создаётся.
section string	Имя раздела в INI-файле. Оно добавляется автоматически, если `state=present`, когда задаётся одно значение. Если параметр не указан, `option` размещается перед первым `section`. Также необходимо не указывать `section`, если формат конфигурации не поддерживает разделы.
section_has_values list / элементы=dictionary добавлено в community.general 8.6.0	Если имеется несколько разделов с одинаковым именем, выбрать первый, содержащий соответствующие параметры и значения. При значении `state=present`, если подходящий раздел не найден, создаётся новый раздел с необходимыми параметрами. При значении `state=absent` удаляется не более одного `section`, если он содержит эти значения.
option string / обязательно	Соответствующий `section` должен содержать этот параметр.
value string	Соответствующий `section_has_values[].option` должен иметь это конкретное значение.
values list / элементы=string	Строковое значение, связываемое с `section_has_values[].option`. Взаимоисключающий параметр по отношению к `section_has_values[].value`. `section_has_values[].value=v` эквивалентен `section_has_values[].values=[v]`.
selevel string	Часть уровня контекста объекта файловой системы SELinux. Это атрибут MLS/MCS, иногда называемый `range`. Если задано значение `_default`, будет использоваться часть `level` политики, если она доступна.
serole string	Часть роли контекста объекта файловой системы SELinux. Если задано значение `_default`, будет использоваться часть `role` политики, если она доступна.
setype string	Часть типа контекста объекта файловой системы SELinux. Если задано значение `_default`, будет использоваться часть `type` политики, если она доступна.
seuser string	Часть пользователя контекста объекта файловой системы SELinux. По умолчанию используется политика `system`, если это применимо. Если задано значение `_default`, будет использоваться часть `user` политики, если она доступна.
state string	Если задано значение `absent` и для `exclusive` задано значение `true`, удаляются все соответствующие строки `option`. Если задано значение `absent` и для `exclusive` задано значение `false`, удаляются указанные строки `option=value`, но другие `option` с тем же именем не затрагиваются. Если задано значение `present` и для `exclusive` задано значение `false`, добавляются указанные строки `option=values`, но другие `option` с тем же именем не затрагиваются. Если задано значение `present` и для `exclusive` задано значение `true`, добавляются все заданные строки `option=values`, а остальные `option` с тем же именем удаляются. Варианты: `"absent"` `"present"` ← (по умолчанию)
unsafe_writes boolean	Определяет, когда использовать атомарную операцию, чтобы предотвратить повреждение данных или несогласованное чтение целевого объекта файловой системы. По умолчанию этот модуль использует атомарные операции для предотвращения повреждения данных или несогласованного чтения целевых объектов файловой системы, однако иногда настройки систем или их неисправности делают это невозможным. Например, смонтированные в Docker объекты файловой системы нельзя атомарно обновить из контейнера, и их можно записывать только небезопасным способом. Этот параметр позволяет Ansible при сбое атомарных операций прибегнуть к небезопасным способам обновления объектов файловой системы (однако он не заставляет Ansible выполнять небезопасную запись). ВАЖНО! Небезопасная запись подвержена гонкам и может привести к повреждению данных. Варианты: `false` ← (по умолчанию) `true`
value string	Строковое значение, связываемое с `option`. Можно не указывать при удалении `option`. Взаимоисключающий параметр по отношению к `values`. `value=v` эквивалентен `values=[v]`.
values list / элементы=string добавлено в community.general 3.6.0	Строковое значение, связываемое с `option`. Можно не указывать при удалении `option`. Взаимоисключающий параметр по отношению к `value`. `value=v` эквивалентен `values=[v]`.

Атрибуты

Атрибут	Поддержка	Описание
check_mode	Поддержка: полная	Модуль может работать в режиме `check_mode` и возвращать прогноз статуса изменений, не изменяя целевой объект.
diff_mode	Поддержка: полная	В режиме сравнения возвращает сведения об изменениях (или о том, какие изменения могут потребоваться в `check_mode`).

Примечания

Примечание

Хотя можно добавить option, не указывая value, это не имеет смысла.
Начиная с community.general 3.2.0, маркеры UTF-8 BOM отбрасываются при чтении файлов.

См. также

ansible.builtin.ini — плагин поиска: Читает данные из INI-файла.
community.general.from_ini — плагин фильтра: Преобразует текст в формате INI в словарь.
community.general.to_ini — плагин фильтра: Преобразует словарь в формат INI-файла.

Примеры

- name: Ensure "fav=lemonade is in section "[drinks]" in specified file
  community.general.ini_file:
    path: /etc/conf
    section: drinks
    option: fav
    value: lemonade
    mode: '0600'
    backup: true

- name: Ensure "temperature=cold is in section "[drinks]" in specified file
  community.general.ini_file:
    path: /etc/anotherconf
    section: drinks
    option: temperature
    value: cold
    backup: true

- name: Add "beverage=lemon juice" is in section "[drinks]" in specified file
  community.general.ini_file:
    path: /etc/conf
    section: drinks
    option: beverage
    value: lemon juice
    mode: '0600'
    state: present
    exclusive: false

- name: Ensure multiple values "beverage=coke" and "beverage=pepsi" are in section "[drinks]" in specified file
  community.general.ini_file:
    path: /etc/conf
    section: drinks
    option: beverage
    values:
      - coke
      - pepsi
    mode: '0600'
    state: present

- name: Add "beverage=lemon juice" outside a section in specified file
  community.general.ini_file:
    path: /etc/conf
    option: beverage
    value: lemon juice
    state: present

- name: Remove the peer configuration for 10.128.0.11/32
  community.general.ini_file:
    path: /etc/wireguard/wg0.conf
    section: Peer
    section_has_values:
      - option: AllowedIps
        value: 10.128.0.11/32
    mode: '0600'
    state: absent

- name: Add "beverage=lemon juice" outside a section in specified file
  community.general.ini_file:
    path: /etc/conf
    option: beverage
    value: lemon juice
    state: present

- name: Update the public key for peer 10.128.0.12/32
  community.general.ini_file:
    path: /etc/wireguard/wg0.conf
    section: Peer
    section_has_values:
      - option: AllowedIps
        value: 10.128.0.12/32
    option: PublicKey
    value: xxxxxxxxxxxxxxxxxxxx
    mode: '0600'
    state: present

- name: Remove the peer configuration for 10.128.0.11/32
  community.general.ini_file:
    path: /etc/wireguard/wg0.conf
    section: Peer
    section_has_values:
      - option: AllowedIps
        value: 10.4.0.11/32
    mode: '0600'
    state: absent

- name: Update the public key for peer 10.128.0.12/32
  community.general.ini_file:
    path: /etc/wireguard/wg0.conf
    section: Peer
    section_has_values:
      - option: AllowedIps
        value: 10.4.0.12/32
    option: PublicKey
    value: xxxxxxxxxxxxxxxxxxxx
    mode: '0600'
    state: present

Авторы

Jan-Piet Mens (@jpmens)
Ales Nosek (@noseka1)

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/general/ini_file_module.html