Справочник форматов шаблонов

Обновлено 5 ноября 2026

Страница для того, кто выбирает значение format= для своего конфигурационного файла. Формат отвечает на три вопроса: как выглядит запись в файле, чем одна запись отделена от другой и как изменить или удалить уже существующую. В каждом разделе ниже — один формат: сначала как выглядит файл, затем как пишется строка, затем как править запись.

Справочник актуален для cl-core 3.7.6.8. Рабочих имён 29: 26 форматов, один алиас (proftpd) и два встроенных типа (raw, bin); ещё одно имя из старой документации, ldif, разобрано в конце страницы.

Название формата описывает синтаксис, а не программу. Имя format= выбрано по тому, как разбирается файл, а не по названию настраиваемого сервиса. Отсюда сюрпризы вроде /etc/pulse/daemon.conf с format=postfix: формат подходит любому файлу вида «ключ = значение», кому бы он ни принадлежал.

Ini-файлы с секциями

Общее для этой группы: файл разбит на группы в квадратных скобках, и каждая строка внутри группы задаёт один параметр. Значение меняют, повторив в шаблоне ту же строку с тем же именем ключа в той же группе; удалить запись можно, поставив ! перед именем ключа.

samba

Классический ini: группы вида [имя группы], внутри них строки ключ = значение. Пробелы вокруг = не значат ничего. Записи разделяются переводом строки, комментарием служат # и ;, стоящие в начале строки. Удалить запись можно записью !ключ=, добавить значение к разделяемому списку — записью +ключ=. append по умолчанию — join.

По нему настраиваются /etc/samba/smb.conf и файлы *.env утилит Calculate.

kde

Ведёт себя как samba, но с двумя отличиями: понимает вложенные группы вида [A][B] (у samba вложенная часть теряется) и знает только удаление через !ключ=. Это файлы конфигураций KDE и GNOME, а также *.desktop и *.src. Строка — ключ=значение, причём пробелы вокруг = никуда не деваются: их видно как часть имени и значения. Комментарий — только #, записи разделяются переводом строки. append по умолчанию — join.

Ловушка на уровне ключа: префиксы + и - формат не понимает. Запись +ключ=значение не сложит значения, а создаст новый параметр с именем +ключ, который никогда не совпадёт с существующим; то же самое с -ключ. Удаляйте через !ключ=.

compiz

Несмотря на место в старой документации, это ini-формат, а не XML: файл выглядит как группы [имя] и строки ключ = значение в них. Пробелы вокруг = не значат ничего, комментарий — #, записи разделяются переводом строки. append по умолчанию — join.

ldap

Разбор записей каталога: строка выглядит как ключ значение — имя и значение разделяются пробелами, их может быть несколько. Комментарий — #, записи разделяются переводом строки, append по умолчанию — join. Значения, которые ведут себя как списки, оформляются как seplist: атрибут type="seplist" вместе с действием join.

Для записей каталога используйте именно этот формат: ldif в поставке нет (см. ниже).

plasma

Ведёт себя как samba, но заголовок группы может быть цепочкой: [AC][DPMSControl] описывает вложенную группу, а не две соседние. Строка — ключ=значение, комментарий — #, записи разделяются переводом строки, append по умолчанию — join.

Используется для файлов .config/*rc; образец — powermanagementprofilesrc в 6_ac_desktop_profile.

Файлы «ключ = значение» без секций

От ini-семейства эти форматы отличаются отсутствием групп: каждая строка задаёт параметр целиком, и искать его внутри секции не нужно. Различаются они тем, что стоит между именем и значением (=, один пробел или несколько), чем одна запись отделяется от другой (переводом строки или ;) и какой символ служит комментарием. Значение меняют, повторив строку с тем же именем.

openrc

Файлы /etc/conf.d/*: без групп, по одной строке на параметр, строка выглядит как КЛЮЧ="значение". Комментарий — #, записи разделяются переводом строки, append по умолчанию — join.

Ведёт себя как procmail (ниже), с одним отличием: имена параметров нечувствительны к регистру, поэтому одно и то же имя в верхнем и в нижнем регистре — это одна и та же запись.

procmail

Файл без групп: плоские пары КЛЮЧ=значение, где имя и значение разделяет =. Комментарий — #, записи разделяются переводом строки, append по умолчанию — join. Строка, в которой знак = встречается не ровно один раз, параметром не считается: она не участвует в сопоставлении и при наложении шаблона из результата выпадает. Если такая строка должна сохраниться, её нужно относить к формату, который её понимает, или защищать append-режимом цели.

Реальные образцы — файлы настроек ядра в 2_ac_install_merge/sys-apps/openrc/ (desktop_performance.conf, network_buffers.conf) с path=/etc/sysctl.d:

# Calculate path=/etc/sysctl.d format=procmail os_subsystem!=lxc os_linux_system==desktop
vm.vfs_cache_pressure=50
net.ipv4.tcp_fin_timeout=15

postfix

Плоские пары ключ = значение: пробелы вокруг = не значат ничего, комментарий — #, записи разделяются переводом строки, append по умолчанию — join. Основан на формате apache (описан ниже) и берёт от него разбор пар «имя — значение», но блочные конструкции родителя не использует: весь файл воспринимается как один плоский список параметров.

Живой пример — /etc/pulse/daemon.conf (resample-method = speex-float-3): его налагает шаблон именно с format=postfix. Это не опечатка в заголовке и не попытка настроить почтовый сервер: имя описывает синтаксис файла, а настройки PulseAudio устроены парами «ключ = значение» — ровно тем, для чего этот формат и предназначен.

dovecot

Плоские пары ключ = значение: имя и значение разделяет = с необязательными пробелами, комментарий — #, записи разделяются переводом строки, append по умолчанию — join. Основан на формате bind (описан ниже) и отличается от него двумя вещами: записи отделяются друг от друга переводом строки, а не ;, и комментарий у него #, а не //.

Особенность: у формата свои правила для директив включения — нормализация пробелов заодно переписывает !include_try в !include _try, после чего директива перестаёт узнаваться. Для таких строк лучше подставлять готовый текст целиком, а не править их по частям.

dhcp

Записи идут подряд и разделяются ;, имя и значение разделяются пробелом. Комментарий — #, но распознаётся он только в начале строки, поэтому решётка внутри значения сохраняется как часть значения. Многословные опции склеиваются в одно имя: option routers X; читается форматом как одна запись, а не как три отдельных слова. Строка без значения (hostname) — легитимная запись.

Основан на формате bind (описан ниже) и наследует от него разделитель записей ; и разбиение по пробелу, меняя комментарий с // на #. append по умолчанию — join.

Используется для файлов dhcpcd.conf.

squid

Ведёт себя как procmail (выше), но имя и значение разделяются одиночным пробелом, а не =: запись выглядит как PermitRootLogin yes, без знака равенства. Комментарий — #, записи разделяются переводом строки, append по умолчанию — join.

Используется для sshd_config.d.

bind

Записи разделяются ;, а не перевод строки: в одной строке может стоять несколько записей. Имя и значение разделяются пробелами, комментарий — //. Запись меняют, переписав её целиком с тем же именем.

Формат есть в движке и служит основой для apache, а через него — для dovecot и dhcp (см. выше).

apache

Плоские строки имя значение, где имя и значение разделяются пробелом или табуляцией; комментарий — #, записи разделяются переводом строки. Основан на формате bind (выше) и отличается от него комментарием и разделителем записей, а взамен понимает блочные конструкции: строка-заголовок блока и вложенные в него директивы читаются как одна область, а имя директивы может собираться из нескольких слов, склеенных в одно имя.

Формат есть в движке и служит основой для postfix, а также для алиаса proftpd (см. ниже).

XML

Все четыре формата этого раздела работают не со строками, а с деревом элементов: запись находится по тегу и его атрибутам, а не по тексту строки. Отсюда главное правило — в шаблоне нужно повторить атрибуты, которые идентифицируют запись (name, type и тому подобные): без них существующий узел не будет найден, и вместо обновления в файле появится второй такой же узел-дубликат.

xml_xfce

Конфигурации Xfce: свойства вида <property name="…" type="…">, у которых обновляется атрибут value. В шаблоне повторяют name и type нужного свойства — иначе вместо изменения значения добавится новое свойство.

xml_gconf_tree

Основан на формате xml_gconf (описан ниже), а отличие в том, где ищется узел: сопоставление идёт на любой глубине дерева, а не только на уровне списка записей. Применяйте его, когда нужное свойство лежит во вложенных группах. Правила идентификации узла для него те же, что для всего раздела.

xml_gconf

Основан на формате xml_xfce (выше) и так же ищет узел по атрибутам, но значение хранится не в атрибуте, а в дочернем элементе: запись выглядит как <entry name="…" type="…"> со вложенным <stringvalue> и подобными. Служебный атрибут mtime отбрасывается перед сравнением, чтобы расхождение во времени не мешало найти нужную запись.

xml_xfcepanel

Ведёт себя как xml_xfce, но узлы <panel> сопоставляются позиционно, то есть по порядку следования, а не по атрибутам; узел <items> заменяется целиком.

Формат есть в движке и продолжает xml_xfce для настройки панелей.

Структурные и служебные форматы

Эти форматы нужны, когда содержимое файла описывается не парами «ключ — значение», а своей структурой: текстом правок, списком пакетов, деревом настроек или запросом к базе.

patch

Тело шаблона — не конфигурация, а пары тегов: <reg> задаёт регулярное выражение, <text> — на что его заменить.

# Calculate comment=# format=patch
<reg>^#(s[01])</reg>
<text>\1</text>

Только этот формат читает параметры заголовка multiline и dotall, которые меняют правила поиска по многострочному тексту. Без multiline якорь ^ привязан к началу всего файла, а не его строк: из одинаково подходящих строк заменится только первая. Если правка должна коснуться всех строк, начинающихся с #s0 или #s1, добавьте multiline в заголовок. Значение append обязано быть patch — это и есть значение по умолчанию.

diff

Тело шаблона — обычный вывод diff, который накладывается внешней программой /usr/bin/patch: проверьте, что она установлена в системе. Значение append обязано быть patch.

В основном применяется в 6_ac_install_patch с патчами к исходникам пакетов.

kernel

Файл .config ядра: строки вида CONFIG_…=y|m|n. Отключённый параметр записывается как # CONFIG_… is not set, и эта форма распознаётся отдельно от строки со значением: выключать параметр нужно именно ею.

dconf

Настройки пользовательской службы dconf: путь схемы задаётся параметром заголовка dconf=/org/gnome/…, а наложение идёт от имени пользователя через su с dbus-run-session и /usr/bin/dconf. Физически файл настроек лежит в ~/.config/dconf/user (это база SQLite) и создаётся при первом запуске сеанса. Значение append обязано быть patch.

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

backgrounds

Создание фоновых изображений: в теле шаблона указываются размеры (640x480), исходное изображение задаётся параметром link=, обработку выполняет ImageMagick (параметры convert=, stretch=). Значение append обязано быть patch.

json

Тело шаблона — валидный JSON; комментариев формат не поддерживает ни в каком виде, символ комментария у него отсутствует. Объединение выполняется только по верхнему уровню: ключи верхнего уровня, которых нет в шаблоне, сохраняются, а вложенный объект заменяется целиком — поэтому всё вложенное, что должно остаться, нужно переписать в шаблоне. Результат сериализуется с отступом в 4 пробела, так что побайтовой идентичности с исходным файлом ждать не стоит.

world

Список /var/lib/portage/world: по атому на строку, допускаются слоты и подстановки (dev-db/postgresql:#-core.cl_core_pkg_slot-#).

contents

Не изменяет текст файлов вообще — этот формат управляет принадлежностью файлов пакетам (базы CONTENTS). Строка задаёт пакет и путь, в пути допускается маска; ! в начале строки исключает файл из состава пакета. Значение append обязано быть patch.

Формат работает во время события слияния пакета: пока install.ac_install_merge выключен, шаблон не наложится, и утилита подскажет это строкой # Calculate ac_install_merge==on. Проверить состояние переменной можно командой cl-core-variables-show.

# Calculate format=contents \
mergepkg(sys-apps/calculate-utils)!=&&ini(merge-calculate.utils)<3.6.0_alpha1
!sys-apps/openrc /etc/runlevels/default/net.*

sqlite

Тело шаблона — SQL-скрипт (PRAGMA, CREATE TABLE, INSERT), который выполняет стандартный модуль sqlite3 над указанной базой. Значение append обязано быть patch.

Примеры — в 6_ac_desktop_profile, базы libaccounts-glib.

Встроенные типы и алиасы

raw

Значение по умолчанию: если format= в заголовке не указан, файл накладывается как raw. Объединение не выполняется: целевой файл переписывается целиком (append=replace). Нужен параметр comment= с символом комментария целевого файла, чтобы служебная строка # Calculate не сломала его синтаксис.

ldif

Имя ldif перечислено в списке «исполняемых» форматов движка и встречается в старой документации, но модуля формата с таким именем в поставке нет. Поэтому шаблон с format=ldif без env= завершается явной ошибкой заголовка: Неправильный параметр заголовка 'format=ldif' в шаблоне <файл>. Для записей каталога используйте ldap (см. выше).

Эти два случая легко смешать. Шаблон, у которого указан env= с модулем, который в данной системе недоступен (например env=ldap на машине без настроенного LDAP-модуля), пропускается молча — ни файла, ни сообщения. Так происходит с любым значением format=, даже с заведомо несуществующим: format=nosuchthing вместе с env=ldap тоже не накладывается и не выдаёт ничего. Причина в том, что проверка доступности модуля выполняется раньше разбора заголовка. Значит это две разные болезни: «формат не поддерживается» всегда даёт явную ошибку заголовка, а «ничего не произошло и вывода нет» — признак недоступного модуля, и искать надо в env=, а не в format=.

Все готовые шаблоны этого формата лежат в каталоге 7_ac_server_ldif/ и несут env=ldap или env=unix; на системе без этих модулей они молча не создают файлов, что есть штатное поведение env=, а не поломка формата.

bin

Двоичный файл. Определяется автоматически по содержимому (проверка на «бинарность»), отдельного указания в заголовке не требуется; шаблоны этого типа всегда append=replace.

proftpd

Второе имя формата apache: ведёт себя точно так же и годится там, где конфигурация proftpd совпадает с синтаксисом Apache.

Что общего у всех форматов

Разметка шаблона — подстановки #-переменная-#, условные блоки #?условие# … #условие#, заголовок # Calculate … с переносом через \ — работает одинаково независимо от формата: она разбирается ещё до выбора формата. Формат влияет только на тело файла.

Отдельное заблуждение старой документации: «для пустого файла действует append=delete». Такого значения нет; удаление выполняется append=remove, а «пустой» результат — это append=clear для файла (обнуление) или для директории (очистка содержимого).

Для читающих исходники движка

Раздел обращён к тем, кто читает код утилит, а не настраивает файлы: здесь собраны имена из исходников, которые в описаниях выше заменены поведением.

• Каждый формат — класс с тем же именем в модуле src/calculate/lib/format/<имя>.py (26 модулей), и format= в заголовке разрешается так: утилита импортирует модуль и берёт из него класс с тем же именем. Алиас proftpd задаётся таблицей прототипов newObjProt в cl_template.py.
• Корневой класс — TemplateFormat в cl_template.py; objShare в generic.py — общая база плоских «ключ = значение» файлов и, прямо или через цепочку, форматов bind, apache, postfix, dovecot, dhcp, procmail, squid, openrc, а также samba с потомками kde, ldap, compiz, plasma.
• Чем разделены имя и значение, задаёт регулярка reSeparator; чем разделены записи — sepFields (обычно перевод строки, у bind и dhcp — ;); символ комментария — атрибут _comment; заголовок блока у ini-семейства и у apache — reHeader.
• reExecStr в cl_template.py находит в теле шаблона строку интерпретатора (#!/…) и сохраняет её; нормализация пробелов в dovecot сделана re.sub (отсюда и превращение !include_try в !include _try).
• Тип файла из заголовка отдаёт _getType (по умолчанию raw), способ присоединения — _getAppend класса заголовка; сами параметры заголовка лежат в HParams, а prevDictIni хранит переменные, прочитанные из конфигурационного файла для функции ini().
• XML-форматы обходят дерево через lxml, свойства узлов вроде nodeType принадлежат этой библиотеке, а не движку.

См. также

• Как выбрать формат
• Синтаксис шаблона
• Кто и когда налагает шаблоны