yaq-yeps/102


Daemon Configuration Files

Abstract

This YEP describes the configuration file format for yaq daemons. This is a TOML file with some reserved and required keys. A single config file has a 1-to-1 relationship with an invocation of the entry point. This MAY be a 1-to-many relationship with individual daemons. Typically, there is ONE configuration per <kind> of daemon. For example, if you have multiple of the same make and model translation stage, you can configure all of them in a single configuration file.

Table of Contents

Motivation

A standard for configuration makes it easy to know how one configures their daemon. TOML is a well defined, human readable configuration file format. This provides a flexible configuration format, including the ability to share settings across multiple daemons.

Specification

The configuration file is a TOML file.

File Location

The default configuration file location SHALL be:

Where <kind> is a lowercase name for the daemon with words separated by hyphens, as returned by the id method. <kind> SHOULD NOT begin with "yaq".

If the desired config file is located elsewhere, it MUST be explicitly provided.

Shared Settings

An optional top level table, shared-settings, which (if present) provides defaults that apply to all other tables. These defaults are higher priority than protocol defined defaults, but lower than configuration for individual daemon ports.

Individual Daemon Configuration

Every other top-level key MUST be a table, for which the name indicates the name of the daemon which MUST be exposed on the given port. These names MUST be unique at the level of <kind>.

Each table MUST include a key port which provides the globally-unique (among all daemons) TCP port. Additional fields MAY be added, as needed for configuring the daemon. Keys which are required (or optional) MAY be specified by the daemon protocol.

ALL tables other than those that are disabled, and shared-settings MUST be started when invoking a daemon entry point with the config file. They MAY (and in many cases must for technical reasons) start several daemons listening in the same process. A special key, enable (defaults to true) allows you to selectively turn off individual daemons.

The configuration file MUST NOT be written by the daemon. Any runtime dynamic fields SHOULD be written in the state file and have ways of detecting and/or expose setting over the TCP communication protocol described above.

Additional identifying information SHOULD be included, as applicable. Common identifying information include: make (manufacturer), model (identifies the kind as described by the manufacturer), serial (individual serial number of the device represented).

The configuration file MUST be read from the file at daemon startup ONLY (restarting is considered "startup", and MUST re-read the configuration file in case changes were made).

Discussion

Discussion can be found on the gitlab issue for this YEP.

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.


built 2020-10-03 01:33:36                                      CC0: no copyright