SYSCONFTOOL(7)

📦
version 0.22 · 5 versions
, in ubuntu resolute, ubuntu stonking

💖 SYSCONFTOOL 💖 (that's the sysconftool(7) manual page, bestie)

okay so this is sysconftool(7) — the page that spills the tea on the format of configuration files installed by sysconftool. yes it's a whole section (7) page about vibes and files. come sit with me 🫶

✨ SYNOPSIS ✨

like, here's the shape of a config file, no cap:

#
##VERSION: $Id$

##NAME: configname1:configname1version
#
# Description

SETTING1=VALUE1

##NAME: configname2:configname2version
#
# Description

SETTING2=VALUE2

...

🌸 DESCRIPTION 🌸

This page describes the format of configuration files installed by sysconftool(1)[1]. And honestly? This format is so flexible it can accommodate any kind of application configuration file format. it's giving versatile ✨

sysconftool makes four assumptions about the configuration file, and they're literally just:

  1. It is a plain text file. no fancy binaries, bestie 💅
  2. Lines that begin with a single # character are comments that contain a description of the following configuration setting.
  3. Lines that do not begin with the # character contain the configuration setting described by the previous comment lines.
  4. Configuration settings are self contained, and completely independent — changing one configuration setting never requires that another, different, configuration setting must be changed too (perhaps any logical conflicts are automatically resolved by the application in a safe, fallback, manner).

the additional information that sysconftool uses is encoded as specially-formatted comment lines that begin with two # characters. two hashtags. very main character. iykyk 😌

🦋 FILENAMES 🦋

An application installs a default configuration file as filename.dist, when the actual name of the configuration file is really filename. So cute, so simple.

  • If there is no existing filename, sysconftool simply copies filename.dist to filename, and calls it a day. 🎀
  • Otherwise, sysconftool copies the existing filename to filename.bak and creates a new filename based on the contents of both files.

so here's the drama this tool is here to fix: sysconftool is designed to solve a common problem with application configuration. New versions of applications often include additional functionality that requires new configuration settings. Without the new configuration settings the application will not work, so new configuration files should be installed during the upgrade. However, when that happens, any changes to the existing configuration settings are lost. sysconftool is designed to solve this dillemma, and merge old configuration settings with new ones. 😭

and the way it's designed is fail-safe. Whenever there's a doubt as to what's The Right Thing To Do, sysconftool will use the configuration settings from the new file, that are supposedly known to be good, and leave it up to a physical being to sort out any conflicts and make any manual decisions. so it hands the messy part to a human. iconic, honestly 👑

👑 FILE VERSIONING 👑

The following line should appear at the beginning of filename.dist:

##VERSION: version

This doesn't have to be the very first line in filename.dist, but it should appear somewhere within the first twenty lines, right before the first configuration setting. ✨

version should be some kind of an identifier for this particular version of the configuration files. All that sysconftool cares about is that any change to the default configuration, in filename.dist, results in a different version. An excellent way to do this is to simply use the $Id$ RCS/CVS version identification strings, and have this little detail taken care of automatically. obsessed with automation fr fr 🤖

New revisions of an application should not necessarily have a new configuration file version. If the default application configuration settings have not changed from the previous release, version can remain the same. version is copied from filename.dist to filename.

okay now the branching logic, listen up:

  • If there's an existing filename, and it includes the same version identifier, sysconftool silently skips over this configuration file, and doesn't do anything, assuming that this configuration file has already been installed. Therefore, running sysconftool more than once (accidentally) will not break anything. 🫶 (cute-sy of it)
  • If there's an existing filename, but it's version is different, sysconftool backs it up to filename.bak, then creates a new filename.
  • If there's an existing filename, but it doesn't contain a recognizable ##VERSION: version line, sysconftool assumes that the previous version of the application did not use the sysconftool tool. That's not a problem. 💅 filename is copied to filename.bak, and filename.dist gets installed as the new filename, allowing sysconftool to work with the next version of this configuration file.

🎀 CONFIGURATION SETTING VERSIONING 🎀

Each configuration setting uses the following format in the configuration file:

##NAME: name:revision
#
# description

setting

sysconftool looks for a line that begins with ##NAME. This line gives the name and the revision of the following setting.

  • name must be unique within its configuration file (the same name can be used by different configuration files, sysconftool works with one file at a time). one file at a time besties, it's monogamous 💅
  • revision is used by sysconftool to decide when the configuration setting can be safely carried over from an older configuration file, and when it is better to reinstall the default setting from the new configuration file.

One or more comment lines — lines that begin with the # character — may follow ##NAME. The first line that does not begin with # is considered to be the first line that contains the value of the configuration setting, which lasts. The value can be spread over multiple lines. The configuration setting is considered to last until either the end of the file, or until the first following line that begins with another ##NAME. ✨

Aside from that, sysconftool does not care how the configuration setting is represented. It can be NAME=VALUE, it can be NAME: VALUE, or NAME<tab>VALUE, it can even be a base64-encoded binary object, and it can always have leading or trailing blank lines. no judgement, all formats welcome 🌈

sysconftool merely looks at which lines begin with the # comment character. After the ##NAME: line, sysconftool looks ahead until the first line that does not begin with #, and that's the first line of the configuration setting. Then, sysconftool looks ahead until the next line that starts with a ##NAME:, which marks the end of this configuration setting. peek-ahead queen 👀

For this reason it is important that all commented description lines that follow ##NAME: must begin with the # character. If a blank line follows the line with ##NAME: it is assumed to be the start of the corresponding configuration setting. For example, this is correct:

##NAME: flag1:0
#
#
# This is the first configuration flag
#

flag1=1

This is not correct:

##NAME: flag1:0

#
# This is the first configuration flag
#

flag1=1
⚠️ see that sneaky blank line after ##NAME: flag1:0? yeah. that one blank line changes everything and makes it wrong. do not do this bestie, the parser will read it as a setting 🙈

🌈 CONFIGURATION FILE CREATION 🌈

A new configuration file, filename, is created from its previous version, filename.bak and the new default configuration file, filename.dist, using the following, simple, two-step process. 🧚

  1. sysconftool begins with filename.dist in hand. This makes sure that sysconftool begins with a good, known, default configuration file. ✅
  2. sysconftool then takes each configuration setting in filename.dist, then searches filename.bak. If it finds a configuration setting that has an identical name and version, then the corresponding configuration setting value is taken from filename.bak, replacing the default in filename.dist. After all configuration settings in filename.dist are looked up (and potentially replaced), what's left becomes the new filename. 💖

⭐ THE END RESULT ⭐

The above process is a logical description. The actual technical implementation is slightly different (for example, filename is not backed up to filename.bak until the new configuration file has been already created), but is logically equivalent to this process. This process carries a number of consequences that must be considered. 👀

  • If a new application revision needs a new configuration setting, it will get a new name and version. Since filename.dist is used as a starting point for the new configuration file, the new configuration file will include the new configuration setting. ✨
  • When a configuration setting is removed, it will disappear from the new configuration file for the same exact reason. 💀

🌸 CONFIGURATION SETTING VERSION 🌸

okay so here's the tea bestie: sysconftool is not just looking at the setting's name. It looks at the name AND the version, together, always. Two settings with the same name but different versions? sysconftool treats them as completely different settings. Total strangers. Never met. And that's on purpose — the whole point of having a version is that it gives you finer-grained control over configuration upgrades, which is what the rest of this section is about. 💅

So when it upgrades stuff, sysconftool copies setting values that have the same name and the same version from the old configuration file over into the new configuration file. But — and this is the plot twist — the descriptive comments do not get copied. Nope. Those get taken fresh from the new filename.dist. ✨

Which means: if your new version of the config file has a shiny updated or embellished description of some setting, that new description will land in the new configuration file... but the existing configuration value gets preserved! 🎀 So you get the new words, the old data, everybody wins.

Generally speaking: if a configuration setting hasn't changed its meaning or function, then its name and version should stay exactly the same. You can still edit the comments to fix a typo, or even revise them in a more substantive fashion, and that's totally fine. Name and version should only be changed if there's an actual functional change in the configuration setting. No cap. 🫶

Now, what do you do with name and version after a functional change? Depends on the nature and the magnitude of the change. And here's the part people mess up: you have to consider that nature and magnitude not just against the most recent revision of the application, but against all the previous revisions too. 😭

When in doubt, go based upon the largest change in magnitude. That guarantees a functional default setting from filename.dist, and leaves it up to a living being to manually figure it out. 🙈

And if it's only the default value of a setting that should change — for brand-new application installs — but existing installations can keep right on using their existing value of the setting? Then leave both the name and the version alone. ✋ Existing configuration settings get preserved, new installations get the new default. Iconic. You can update the descriptive comment of this setting too (see above, bestie, it's all connected 💜).

But do this only as long as ALL previous values of this configuration setting will ALWAYS be valid in the new application revision. If some possible values of this configuration setting will no longer be valid? Then version should be changed. Periodt. 🔥

ngl sysconftool does not care at all how name and version are formatted. Both are opaque labels. The one and only requirement is that the label is different. That's it.

So let's talk about the difference between changing the version versus changing both name and version:

  • If there's an old configuration setting with the same name but a different version, sysconftool will still use the new, safe, default value from filename.dist. However — and this is the important bit — sysconftool will also append an additional comment, on its own accord, reminding the reader that this configuration value has been reset, and that the reader should consider whether to manually restore the configuration value from the old configuration. ⭐

🌈 MISCELLANEA 🌈

And when sysconftool decides to keep an existing setting — same name, same value — it will also drop in a short comment to that effect, reminding the reader to go check the default in filename.dist. 🦋 Little note, big help. She's thoughtful like that.

👑 SEE ALSO 👑

💖 AUTHORS 💖

S. Varshavchik.

🎀 NOTES 🎀

  1. sysconftool(1) https://www.courier-mta.org/sysconftool/sysconftool.1.html

aaand that's a wrap on SYSCONFTOOL(7) bestie!! 🫶 this whole thing comes to you from the Courier Mail Server, dated 01/11/2026, and it's page SYSCONFTOOL(7) obviously. slay, go read your configs, ily, bye!! 💅✨🌸💖

📦 where this page comes from