Template formats reference

Updated 5 November 2026

A page for anyone who is choosing the format= value for a configuration file. A format answers three questions: what a record looks like in the file, what separates one record from another, and how to change or delete one that already exists. Each section below is one format: first what the file looks like, then how the line is written, then how to edit a record.

This reference is current for cl-core 3.7.6.8. There are 29 working names: 26 formats, one alias (proftpd) and two built-in types (raw, bin); one more name from the old documentation, ldif, is taken apart at the end of the page.

The format name describes the syntax, not the program. The format= name is chosen by how the file is parsed, not by the name of the service being configured. Hence surprises like /etc/pulse/daemon.conf with format=postfix: the format suits any file of the "key = value" shape, whoever it belongs to.

Ini files with sections

What this group has in common: the file is split into groups in square brackets, and each line inside a group sets one parameter. A value is changed by repeating the same line in the template with the same key name in the same group; a record can be deleted by putting a `!`` перед именем ключа.

samba

The classic ini: groups of the form [group name], and inside them key = value lines. Spaces around = mean nothing. Records are separated by a line break, and # and ;``, стоящие в начале строки. A record can be deleted with a!key=;+key=adds a value to a delimited list. The default ++append++ isjoin`.

It configures /etc/samba/smb.conf and the *.env files of Calculate Utilities.

kde

It behaves like samba, with two differences: it understands nested groups of the form [A][B] (in samba the nested part is lost) and it knows only deletion through !ключ=. These are KDE and GNOME configuration files, and also *.desktop and *.src. The line is key=value, and spaces around = do not go anywhere: they are visible as part of the name and of the value. The comment is only #, and records are separated by a line break. The default append is join.

A trap at the key level: the format does not understand the + and - prefixes. The +key=value entry will not add values, it will create a new parameter named +key, which will never match an existing one; the same goes for -key. Delete through !ключ=.

compiz

Despite its place in the old documentation, this is an ini format, not XML: the file looks like [name] groups with key = value lines in them. Spaces around = mean nothing, the comment is #, and records are separated by a line break. The default append is join.

ldap

Parsing directory records: the line looks like key value - the name and the value are separated by spaces, and there may be several of them. The comment is #, records are separated by a line break, and the default append is join. Values that behave like lists are written as seplist: the type="seplist" attribute together with the join action.

For directory records use exactly this format: ldif is not shipped (see below).

plasma

It behaves like samba, but a group header can be a chain: [AC][DPMSControl] describes one nested group, not two neighbouring ones. The line is key=value, the comment is #, records are separated by a line break, and the default append is join.

Used for .config/*rc files; the sample is powermanagementprofilesrc in 6_ac_desktop_profile.

Key = value files without sections

These formats differ from the ini family by having no groups: each line sets a parameter on its own, and there is no need to look for it inside a section. They differ by what stands between the name and the value (=, one space or several), by what separates one record from another (a line break or ;) и какой символ служит комментарием. A value is changed by repeating the line with the same name.

openrc

Files in /etc/conf.d/*: no groups, one line per parameter, the line looks like KEY="value". The comment is #, records are separated by a line break, and the default append is join.

It behaves like procmail (below), with one difference: parameter names are case-insensitive, so the same name in upper and in lower case is one and the same record.

procmail

A file without groups: flat KEY=value pairs, where = separates the name from the value. The comment is #, records are separated by a line break, and the default append is join. A line in which the = sign occurs not exactly once is not counted as a parameter: it takes no part in matching and drops out of the result when the template is merged. If such a line has to survive, it must be assigned to a format that understands it, or protected by the append mode of the target.

Real samples are the kernel settings files in 2_ac_install_merge/sys-apps/openrc/ (desktop_performance.conf, network_buffers.conf) with 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

Flat key = value pairs: spaces around = mean nothing, the comment is #, records are separated by a line break, and the default append is join. It is based on the apache format (described below) and takes from it the parsing of "name - value" pairs, but it does not use the parent's block structures: the whole file is read as one flat list of parameters.

A live example is /etc/pulse/daemon.conf (resample-method = speex-float-3): it is merged by a template with exactly format=postfix. This is not a typo in the header and not an attempt to configure a mail server: the name describes the syntax of the file, and PulseAudio settings are built as "key = value" pairs - exactly what this format is meant for.

dovecot

Flat key = value pairs: = with optional spaces separates the name from the value, the comment is #, records are separated by a line break, and the default append is join. It is based on the bind format (described below) and differs from it in two ways: records are separated from one another by a line break, not by ;``, и комментарий у него#, а не//`.

One peculiarity: the format has its own rules for include directives - whitespace normalization rewrites !include_try в !include _try, after which the directive is no longer recognized. For such lines it is better to substitute the finished text as a whole than to edit them by parts.

dhcp

Records follow one another and are separated by ;, and the name and the value are separated by a space. The comment is #, but it is recognized only at the start of a line, so a hash inside a value is kept as part of the value. Multi-word options are glued into a single name: option routers X; is read by the format as one record, not as three separate words. A line without a value (hostname) is a legitimate record.

It is based on the bind format (described below) and inherits from it the record separator ;`` и разбиение по пробелу, меняя комментарий с//на#. The default ++append++ isjoin`.

Used for dhcpcd.conf files.

squid

It behaves like procmail (above), but the name and the value are separated by a single space, not by =: a record looks like PermitRootLogin yes, without an equals sign. The comment is #, records are separated by a line break, and the default append is join.

Used for sshd_config.d.

bind

Records are separated by ;, not by a line break: several records can stand on one line. The name and the value are separated by spaces, and the comment is //. A record is changed by rewriting it entirely with the same name.

The format is in the engine and serves as the base for apache, and through it for dovecot and dhcp (see above).

apache

Flat name value lines, where the name and the value are separated by a space or a tab; the comment is #, and records are separated by a line break. It is based on the bind format (above) and differs from it by the comment and by the record separator, but in return it understands block structures: a block header line and the directives nested in it are read as one scope, and a directive name can be built from several words glued into a single name.

The format is in the engine and serves as the base for postfix, and also for the proftpd alias (see below).

XML

All four formats of this section do not work with lines but with a tree of elements: a record is found by its tag and the attributes of that tag, not by the text of the line. Hence the main rule - in the template you must repeat the attributes that identify the record (name, type and the like): without them the existing node will not be found, and instead of an update a second duplicate node appears in the file.

xml_xfce

Xfce configurations: properties of the form <property name="…" type="…">, where the value attribute is the one updated. In the template you repeat the name and type of the property you need - otherwise, instead of changing the value, a new property is added.

xml_gconf_tree

It is based on the xml_gconf format (described below), and the difference is where the node is searched for: matching runs at any depth of the tree, not only at the level of the record list. Apply it when the property you need sits inside nested groups. The node identification rules for it are the same as for the whole section.

xml_gconf

It is based on the xml_xfce format (above) and likewise looks for the node by attributes, but the value is stored not in an attribute but in a child element: a record looks like <entry name="…" type="…"> with a nested <stringvalue> and the like. The service attribute mtime is dropped before comparison, so that a difference in time does not keep the needed record from being found.

xml_xfcepanel

It behaves like xml_xfce, but <panel> nodes are matched positionally, that is by the order in which they follow one another, not by attributes; the <items> node is replaced entirely.

The format is in the engine and continues xml_xfce for configuring panels.

Structural and service formats

These formats are needed when the content of the file is described not by "key - value" pairs but by its own structure: the text of edits, a list of packages, a settings tree or a query to a database.

patch

The template body is not a configuration but pairs of tags: <reg> sets the regular expression, <text> - what to replace it with.

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

Only this format reads the header parameters multiline and dotall, which change the rules for searching through multiline text. Without multiline the ^ anchor is bound to the start of the whole file, not of its lines: of equally suitable lines only the first is replaced. If the edit has to touch every line that starts with #s0 or #s1, add multiline to the header. The append value must be patch - that is also the default value.

diff

The template body is ordinary diff output, which is applied by the external program /usr/bin/patch: check that it is installed on the system. The append value must be patch.

It is mostly used in 6_ac_install_patch with patches to package sources.

kernel

The kernel .config file: lines of the form CONFIG_…=y|m|n. A disabled parameter is written as # CONFIG_… is not set, and this form is recognized separately from a line with a value: a parameter has to be switched off with exactly this form.

dconf

Settings of the user dconf service: the schema path is set by the header parameter dconf=/org/gnome/…, and the merge runs as the user through su with dbus-run-session and /usr/bin/dconf. Physically the settings file lies in ~/.config/dconf/user (it is a SQLite database) and is created at the first start of the session. The append value must be patch.

It is used in configuring the user profile.

backgrounds

Creating background images: the sizes are given in the template body (640x480), the source image is set by the link= parameter, and ImageMagick does the processing (the convert= and stretch= parameters). The append value must be patch.

json

The template body is valid JSON; the format supports no comments in any form and has no comment character. The merge runs only at the top level: top-level keys that are absent from the template are kept, and a nested object is replaced entirely - so everything nested that has to remain must be rewritten in the template. The result is serialized with an indent of 4 spaces, so do not expect byte-for-byte identity with the original file.

world

The /var/lib/portage/world list: one atom per line, slots and substitutions are allowed (dev-db/postgresql:#-core.cl_core_pkg_slot-#).

contents

It does not change the text of files at all - this format manages the belonging of files to packages (the CONTENTS databases). The line sets a package and a path, and a mask is allowed in the path; ! at the start of a line excludes the file from the package. The append value must be patch.

The format works during the package merge event: while install.ac_install_merge is off, the template will not be merged, and the utility points this out with the line # Calculate ac_install_merge==on. You can check the state of the variable with the command 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

The template body is a SQL script (PRAGMA, CREATE TABLE, INSERT), which the standard sqlite3 module runs over the database given. The append value must be patch.

Examples are in 6_ac_desktop_profile, the libaccounts-glib databases.

Built-in types and aliases

raw

The default value: if format= is not given in the header, the file is merged as raw. No merge is performed: the targeted file is rewritten entirely (append=replace). The comment= parameter is needed, with the comment character of the targeted file, so that the control record # Calculate does not break its syntax.

ldif

The name ldif is listed among the "executable" formats of the engine and occurs in the old documentation, but no format module of that name is shipped. So a template with format=ldif without env= ends in an explicit header error: Wrong header parameter 'format=ldif' in template <file>. For directory records use ldap (see above).

These two cases are easy to confuse. A template whose env= names a module that is unavailable on the given system (for example env=ldap on a machine without a configured LDAP module) is omitted without any message - no file, no output. This happens with any format= value, even a plainly nonexistent one: format=nosuchthing together with env=ldap is likewise not merged and produces nothing. The reason is that the availability of the module is checked before the header is parsed. So these are two different ailments: "format not supported" always gives an explicit header error, while "nothing happened and there is no output" is the sign of an unavailable module, and the place to look is env=, not format=.

All ready-made templates of this format lie in the 7_ac_server_ldif/ directory and carry env=ldap or env=unix; on a system without these modules they create no files and report nothing, which is the expected behavior of env=, not a broken format.

bin

A binary file. It is detected automatically from the content (a "binary" check), and no separate mention in the header is needed; templates of this type are always append=replace.

proftpd

A second name for the apache format: it behaves exactly the same and fits where the proftpd configuration matches the Apache syntax.

Common to all formats

The markup of the template - the #-variable-# substitutions, the conditional blocks #?condition# … #condition#, the # Calculate … header with a \ line continuation - works the same regardless of the format: it is parsed even before the format is chosen. The format affects only the body of the file.

A separate misconception of the old documentation: "for an empty file append=delete applies". No such value exists; deletion is done with append=remove, and an "empty" result is append=clear for a file (zeroing it) or for a directory (clearing its contents).

For readers of the engine sources

This section addresses those who read the code of the utilities rather than configure files: it collects the names from the sources that the descriptions above replaced with behavior.

• Every format is a class with the same name in the src/calculate/lib/format/<name>.py module (26 modules), and format= in the header is resolved like this: the utility imports the module and takes from it the class with the same name. The proftpd alias is defined by the prototype table newObjProt in cl_template.py.
• The root class is TemplateFormat in cl_template.py; objShare in generic.py is the common base of flat "key = value" files and, directly or through a chain, of the bind, apache, postfix, dovecot, dhcp, procmail, squid and openrc formats, as well as samba with its descendants kde, ldap, compiz and plasma.
• What separates the name from the value is set by the reSeparator regular expression; what separates records - by sepFields (usually a line break, for bind and dhcp it is ;); the comment character is the _comment attribute; the block header of the ini family and of apache is reHeader.
• reExecStr in cl_template.py finds the interpreter line (#!/…) in the template body and keeps it; the whitespace normalization in dovecot is done by re.sub (hence also the rewriting of !include_try into !include _try).
• The file type from the header is returned by _getType (raw by default), the append method by _getAppend of the header class; the header parameters themselves lie in HParams, and prevDictIni stores the variables read from the configuration file for the ini() function.
• The XML formats walk the tree through lxml; node properties such as nodeType belong to that library, not to the engine.

See also

• How to choose a format
• Template syntax
• Who and when merges templates