modality-reflector Configuration File

# Summary

The modality-reflector command runs a reflector, either for data import or for live data collection. It uses a TOML configuration file to control how it operates. This file can provide configuration both for modality-reflector itself and for any plugins it may use. Some configuration options can also be overridden with command line options.

# Configuration File Locations

Each time you run a command modality-reflector will look for a configuration file in the following locations. They are listed in descending order of precedence, i.e. number 1 takes precedence over numbers 2-4. modality-reflector will not merge config files, it simply uses the highest-precedence config file.

  1. Passed with the --config option.
  2. Set in the MODALITY_REFLECTOR_CONFIG environment variable.
  3. In user config directory, i.e. ~/.config/modality-reflector/config.toml.
  4. In /etc/modality-reflector/config.toml.

# modality-reflector Configuration File Fields

The modality-reflector configuration file is split using TOML tables.

[ingest]
table
Top-level configuration to apply to all data collection operations.
  • additional-timeline-attributes
    string[]
    Array of key-value attribute pairs to add to every timeline seen by this reflector.
  • override-timeline-attributes
    string[]
    Array of key-value attribute pairs to override on every timeline seen by this reflector.
  • protocol-child-port
    int
    Port on which the reflector will listen for incoming data. Defaults to 14188.
  • protocol-parent-url
    string
    URL to which this reflector will send its collected data. This should either be a URL for modalityd or for another reflector in a chain. Defaults to modality-ingest://127.0.0.1:14182 for insecure connections and modality-ingest-tls://127.0.0.1:14184 for secure TLS connections.
  • allow-insecure-tls
    bool
    Whether to allow insecure connections. If set to false the reflector will only attempt to connect to a parent over a secure TLS connection. Defaults to true.
[mutation]
table
Top-level configuration to apply to all mutation operations. Mutation is a feature of Auxon Deviant.
  • protocol-parent-url
    string
    Parent URL for this reflector to connect to for mutation operations. This should either be a URL for modalityd or for another reflector in a chain. Defaults to modality-mutation://127.0.0.1:14192 for insecure connections and modality-mutation-tls://127.0.0.1:14194 for secure TLS connections.
[plugins]
table
General purpose plugin configuration.
  • plugins-dir
    string
    Path to the directory where plugin binaries are installed. This directory should have two subdirectories, collectors and importers. Plugins for the run command should go in the collectors directory, and plugins for the import command should go in the importers directory.
[plugins.available-ports]
table
Information about which ports are available for plugins to use.
  • any-local
    bool
    Whether plugins can use any local port.
  • ranges
    int[][]
    Available ports for plugins to use. This should be an array of two element arrays, where the two elements specify the start and end of a range of available ports, inclusive.

# Example modality-reflector Configuration File

# /etc/modality-reflector/config.toml

[ingest]
additional-timeline-attributes = [
    'a = 1',
    'b = "foo"',
]
override-timeline-attributes = ['c = true']
protocol-child-port = 9079
protocol-parent-url = 'modality-ingest-tls://auxon.io:9077'
allow-insecure-tls = false

[mutation]
protocol-parent-url = 'modality-mutation://auxon.io:9078'

[plugins]
plugins-dir = 'path/to/custom/plugins/dir'

[plugins.available-ports]
any-local = false
ranges = [
    [
    9081,
    9097,
],
    [
    10123,
    10123,
],
]

[plugins.ingest.collectors.lttng-live]
additional-timeline-attributes = [
    'a = 2',
    'r = 3',
]
override-timeline-attributes = [
    'c = false',
    'q = 99',
]

[plugins.ingest.collectors.lttng-live.metadata]
all-the-custom = true
bag = 41

[plugins.ingest.collectors.my-collector]
plugin = 'socketcan'
[plugins.ingest.collectors.my-collector.metadata]
interface = 'can0'

[plugins.ingest.importers.ctf]
additional-timeline-attributes = ['s = 4']
override-timeline-attributes = ['t = "five"']

# Plugin Configuration

Additional metadata and configuration can be provided for each individual plugin. In the table names below, <plugin type> is one of ingest.importers or ingest.collectors, or mutation.mutatators.

[plugins.<plugin type>.<plugin name>]
table
Reflector configuration for the given plugin. The <plugin name> can be either a plugin executable name (fully qualified or alias) or an arbitrary string when combined with the <plugin> field below.
  • plugin
    string
    The fully qualified or aliased plugin executable name. This field can be used to disambiguate configurations with multiple instances of the same plugin.
  • additional-timeline-attributes
    string[]
    Array of key-value attribute pairs to add to each timeline from the given plugin.
  • override-timeline-attributes
    string[]
    Array of key-value attribute pairs to override on each timeline from the given plugin.
  • shutdown-signal
    string
    The shutdown signal name to send to the plugin process. Defaults to SIGINT. Only available on supported platforms.
  • shutdown-timeout-millis
    int
    The shutdown signal timeout (ms). If the plugin process doesn't shutdown within the timeout period, it will be killed. Defaults to 2000. Only available on supported platforms.
[plugins.<plugin type>.<plugin name>.metadata]
table
Plugin-specific configuration for the given plugin. For individual plugin configuration options see the reference for the plugin you are interested in.

← modalityd Configuration File →