Tomloader

Tomloader is an utility designed to facilitate the creation of multiple systemd unit files through grouping and reuse of systemd fields.

Installation

Tomloader can be installed through cargo:

cargo install tomloader

Documentation generation

To generate info/plaintext/html/epub3/docbook documentation you can use the texi2any command on texinfo/tomloader.texi. For example, to generate info pages which can be then installed with install-info

texi2any texinfo/main.texi

To generate PDF documentation you can use the texi2pdf command:

texi2pdf --clean --output=tomloader.pdf texinfo/main.texi

or

texi2pdf --tidy --output=tomloader.pdf texinfo/main.texi

Documentation of the last tag is also available as a single HTML page at https://loara.codeberg.page/tomloader.

Overview

The primary purpose of Tomloader is to simplify the managment of multiple systemd unit files that share configuration fields.

Systemd already provides native support for configuration reuse through .conf files inside drop-in directories (.d/) which can be hierarchically organized (for example, unit A-B-C.unit inherits all drop-in configurations listed in A-B-.unit.d/ and A-.unit.d/). While useful, it present some limitations:

• inheritance follows a single linear hierarchy, preventing composition from multiple unrelated sources;
• .conf files cannot be templated;
• the final result heavily depends on file ordering inside the drop-in directories, making outcomes sensitive to file naming;
• dependencies between .conf files cannot be explicitly expressed.

Although symlinks may be used the first issue, they do no address the lack of parametrization. Additionally, ordering constraints remain a source of potential misconfiguration even with naming conventions like numeric prefixes.

Tomloader addresses these limitations with the introduction of groups. A group is a collection of systemd configuration fields which may declare dependencies on other groups. Despite .conf files in drop-in directories:

• multiple groups are not allowed to modify the same fiel; such conflicts are detected and will prevent unit generation unless resolved;
• groups may define parameters that may change the values set by configuration fields.

Groups may declare dependencies of two distinct types:

• pull dependencies: automatically included whenever the parent group is used;
• replace dependencies: explicitly excluded whenever the parent group is used, even if references elsewhere.

Examples

Folder examples/ contains some examples.