Platform Team/Server Kit/Mace

Summary

The mace is a tool to macke final configuration using source templates. Mace is supposed to help with configuration of services on Server based school servers.

These are the core differences compared with tools like Puppet or Cfengine:

• mace doesn't provide new metaphors, people need to follow the same configuration syntax for particular services;
• mace is not intended to be a unified system like Puppet or Cfenginei, it supports only a limited set of services (what Server based solution provides), but does it well, e.g., for iptables, just write rules, and the rest will be done by mace;
• mace doesn't function like a daemon, it just converts configuration sources to the final configuration on the final server, e.g., as a post procedure after installing packages;
• mace is designed to support intermediate customizing, i.e., the original configuration, provided by an upstream project, might be supplemented (not patched) in the downstream product before deploying to the final users.

Configuration sources

Sources for mace are stored in GNU/Linux distribution agnostic manner in form of:

[<arbitrary-path>]/<service-name>.d/[<service-confile>]/<configuration-file>.conf

The service-confile is optional and makes sense only if the configured service has several of them, e.g., Bind, or, if a singular configuration file was split at the Mace level into several parts to make it easy to configure, e.g., per IPTables table service-confiles. The configuration-file is a configuration file in a particular service configuration's syntax. All configuration-file files will be merged by mace to the singular service-confile file and placed in the appropriate distribution-specific directory.

The purpose in having arbitrary-path is that there might be several directories with the same service-names to make the configuration more flexible, i.e., it allows having several high-level configuration components in a project that configure the same service. Subsequent configuration might:

• supplement a previous configuration by adding new configuration-files,
• override a previous configuration by having the same configuration-file name with new content,
• hide previous configurations by having empty files with the same arbitrary-path or service-name name.

Such rules will be applied while walking within the root configuration directories tree when directory and file names are sorted alphabetically. The following example demonstrates the virtual tree of upstream configuration with several high-level components and shows how downstream tunes them:

<dir>    +upstrem
<dir>    |  +0100.base
<dir>    |  |  +iptables.d
<config> |  |     +0100.conf
<dir>    |  +0300.proxy
<dir>    |     +iptables.d
<config> |     |  +0300.squid.conf
<dir>    |     +squid.d
<dir>    +downstream
<dir>       +0100.base
<dir>       |  +iptables.d
<config>    |     +0110.addons.conf
<empty>     +0300.proxy

See sugar-server-base sources for a more complex example.

Configuration variables

In additions to configuration files, Mace can process files with .env suffix. These files contain variable declaration in Bash syntax. The values of this variables might be used in configuration files in form of @VARIABLE@ and will be expanded to real values while applying configuration.

There are several variables that being defined will have special meaning for the Mace:

• INCLUDE, a colon separated list of directory names to only include to the prossing list while applying;
• EXCLUDE, a colon separated list of directory names to exclude from the prossing list while applying.

Configuration application

Mace will apply a configuration sources tree to the real system by doing the following:

1. walk through the sources tree to collect all configuration source files for each supported service;
2. apply the configuration by writing the sources content to the proper configuration files for a particular service on the particular OS, the backup copies will be kept;
3. ask the mace provider of a particular service to make sure that everything, related to this service, is good, e.g., check if Prosody SSL keys/certificates exist and are not expired, or check if Squid's swap is created;
4. if a new configuration is different from a previous one, or if step 3 changed something in the system, restart this service;
5. make sure that service will be started at boot time;
6. if all the previous steps aborted due to failures, revert to the original configuration.

To start the applying process:

sudo mace apply -v

If the sources path is not the default, /etc/sugar-server, use the --input argument to specify the right one.

Testing routines

Before applying a configuration on a real system, it might be applied to a temporary directory (do not forget about --dry-services argument to not restart services):

mace apply -o /tmp/test -v -S

Mace also supports several listing commands that just walk though the sources tree and print useful information about it:

• mace ls, list sources status for a particular directory;
• mace dirs, list sources status by services;
• mace show, interpret services status given by mace dirs command;
• mace files, list all configuration files.

The status legend is:

Symbol	Note
-	there are configuration files
*	configuration files for the same service were found in more than one directory
o	some of configuration files are overridden by files with the same name but from a different directory
O	all configuration files are overridden by files with the same name but from a different directory
h	some of configuration files are hidden by empty files with the same name but from a different directory
H	all configuration files are hidden by empty files with the same name but from a different directory