# The configuration file afm-unit.conf

## Brief overview

The integration of the framework with systemd
mainly consists of creating the systemd unit
files corresponding to the need and requirements
of the installed packages.

This configuration file named `afm-unit.conf` installed
on the system with the path `/etc/afm/afm-unit.conf`
describes how to generate all units from the *config.xml*
configuration files of packages.
The description uses an extended version of the templating
formalism of [mustache](http://mustache.github.io/) to describes all the units.

Let present how it works using the following diagram that
describes graphically the workflow of creating the unit
files for systemd `afm-unit.conf` from the configuration
file of the package `config.xml`:

![make-units](pictures/make-units.svg){:width="60%"}

In a first step, and because [mustache](http://mustache.github.io/) is intended
to work on JSON representations, the configuration file is
translated to an internal JSON representation.
This representation is shown along the examples of the documentation
of the config files of packages.

In a second step, the mustache template `afm-unit.conf`
is instantiated using the C library [mustach](https://gitlab.com/jobol/mustach) that follows
the rules of [mustache](http://mustache.github.io/) and with all its available
extensions:

- use of colon (:) for explicit substitution
- test of values with = or =!

In a third step, the result of instantiating `afm-unit.conf`
for the package is split in units.
To achieve that goal, the lines containing specific directives are searched.
Any directive occupy one full line.
The directives are:

- %nl

  Produce an empty line at the end

- %begin systemd-unit

  Begins of a systemd produced unit

- %end systemd-unit

  Ends of a systemd produced unit

- %systemd-unit user

  Tells that the current systemd unit is user

- %systemd-unit system

  Tells that the current systemd unit is system

- %systemd-unit service NAME

  Tells that the current systemd unit is
  is a service and give its name

  The extension is automatically computed from the type
  and must not be set in the name.

- %systemd-unit socket NAME

  Tells that the current systemd unit is
  is a socket and give its name

  The extension is automatically computed from the type
  and must not be set in the name.

- %systemd-unit wanted-by NAME

  Tells to install a link to the unit in the wants of NAME

Then the computed units are then written to the filesystem
and inserted in systemd.

The generated unit files will contain variables for internal
use of the framework.
These variables are starting with `X-AFM-`.

The variables starting with `X-AFM-` but not with `X-AFM--` are
the public variables.

These variables will be returned by the
framework as the details of an application (see **afm-util detail ...**).

Variables starting with `X-AFM--` are private to the framework.
By example, the variable  `X-AFM--http-port` is used to
record the allocated port for applications.

## Generation of afm-unit.conf

The file **afm-unit.conf** is not written using mustache templating
because it is very fastidious.

The file **afm-unit.conf** is generated by composition of several files
using the macro processor M4.

This can be seen in the sub-directory
[master/conf](https://github.com/redpesk-core/afb-app-manager/tree/master/conf/unit)

