
[[minion-confd]]
= Configuring Minion via confd
:description: Learn how to configure the Minion via confd in OpenNMS {page-component-title}: mount, YAML file contents, Kafka sink, and so on.

For information on testing confd templates, see xref:configuration/minion-confd/test-confd.adoc#confd-template-test[Test confd templates].

== Mounting

When starting the Minion container, mount a yaml file to the following path: `$\{MINION_HOME}/minion-config.yaml`.

Any configuration settings provided to confd overwrite the settings specified as environment variables.
Directly overlaying specific configuration files overwrites corresponding configurations provided by confd.

== YAML file contents

The following sections describe the keys in `minion-config.yaml` that configure the Minion via confd.

[[minion-oci-confd]]
=== Minion controller config

[source, yaml]
----
broker-url: "<broker url>"
id: "<id>"
location: "<location>"
----

Writes specified configuration to `$\{MINION_HOME}/etc/org.opennms.minion.controller.cfg`.

=== User/Password

It is not possible to supply the http or broker username or password via the `minion-config.yaml` file.

=== Instance ID

[source, yaml]
----
org.opennms.instance.id: "<instance id>"
----

Writes specified configuration to `$\{MINION_HOME}/etc/instance-id.properties`.

=== Kafka

When using Kafka instead of the embedded Active MQ, settings for Kafka IPC (Twin) will take precedence over any RPC- and Sink-specific settings.

[source, yaml]
----
ipc:
    kafka:
        bootstrap.servers: "127.0.0.1:9092"
        # Any other keys necessary can be specified here
----

Writes the specified configuration settings to `$\{MINION_HOME}/etc/org.opennms.core.ipc.kafka.cfg`.
If the `bootstrap.servers` key is specified, `$\{MINION_HOME}/etc/featuresBoot.d/kafka-ipc.boot` is also updated.

==== Kafka RPC

NOTE: This is optional if you are not using Twin settings via `ipc.kafka`.

[source, yaml]
----
ipc:
    rpc:
        kafka:
            bootstrap.servers: "127.0.0.1:9092"
            acks: 1
            max.request.size: 5000000
            # Any other keys necessary can be specified here
----

Writes the specified configuration settings to `$\{MINION_HOME}/etc/org.opennms.core.ipc.rpc.kafka.cfg`.
If the `bootstrap.servers` key is specified, `$\{MINION_HOME}/etc/featuresBoot.d/kafka-rpc.boot` is also updated.

==== Kafka Sink

NOTE: This is optional if you are not using Twin settings via `ipc.kafka`.

[source, yaml]
----
ipc:
    sink:
        kafka:
            bootstrap.servers: "127.0.0.1:9092"
            compression.type: "gzip"
            request.timeout.ms: 30000
            max.partition.fetch.bytes: 5000000
            auto.offset.reset: "latest"
            max.request.size: 5000000
            # Any other keys necessary can be specified here
----

Writes the specified configuration settings to `$\{MINION_HOME}/etc/org.opennms.core.ipc.sink.kafka.cfg`.
If the `bootstrap.servers` key is specified, `$\{MINION_HOME}/etc/featuresBoot.d/kafka-sink.boot` is also updated.

=== Sink off heap

[source, yaml]
----
ipc:
    sink:
        offheap:
            offHeapSize: "1GB"
            entriesAllowedOnHeap: 100000
            offHeapFilePath: ""
----

Writes the specified configuration settings to `$\{MINION_HOME}/etc/org.opennms.core.ipc.sink.offheap.cfg`.

=== Single port flows

To configure flows on a single port, set the following `enabled` key to `true`.
Optionally, you can also provide parameters to include in the generated configuration.

[source, yaml]
----
telemetry:
    flows:
        single-port-listener:
            # Set to true to add single port listener config, omit or set to false to disable
            enabled: true
            # Parameters can be optionally provided
            parameters:
                # This translates to parameters.port=50000 in the generated config
                port: 50000
----

Writes the specified configuration settings to `$\{MINION_HOME}/etc/org.opennms.features.telemetry.listeners-udp-single-port-flows.cfg`.

=== Telemetry flow listeners

You can configure individual flow listeners and define any number of uniquely named listeners.
The example below shows how to specify parameters and parsers.

[source, yaml]
----
telemetry:
    flows:
        listeners:
            NXOS-Listener:
                class-name: "org.opennms.netmgt.telemetry.listeners.UdpListener"
                parameters:
                    # List all the parameters you wish to specify here
                    port: 50002
                parsers:
                    # List all the parsers you wish to specify here
                    NXOS:
                        class-name: "org.opennms.netmgt.telemetry.protocols.common.parser.ForwardParser"
                        # Parsers can also have parameters specified
                        #parameters:
----

Writes the specified configuration settings to `etc/org.opennms.features.telemtry.listeners-<Listener-Name>.cfg`.

=== Syslog

[source, yaml]
----
netmgt:
    syslog:
        syslog.listen.interface: "0.0.0.0"
        syslog.listen.port: 1514
        # Any other keys necessary can be specified here
----

Writes the specified configuration settings to `$\{MINION_HOME}/etc/org.opennms.netmgt.syslog.cfg`.

=== Traps

[source, yaml]
----
netmgt:
    traps:
        trapd.listen.interface: "0.0.0.0"
        trapd.listen.port: 1162
        # Any other keys necessary can be specified here
----

Writes the specified configuration settings to `$\{MINION_HOME}/etc/org.opennms.netmgt.trapd.cfg`.

=== System properties

[source, yaml]
----
system:
    properties:
        JAEGER_AGENT_HOST: "<host>"
        org.opennms.snmp.snmp4j.allowSNMPv2InV1: true
        # Any other keys necessary can be specified here
----

Writes the specified configuration settings to `$\{MINION_HOME}/etc/confd.system.properties`.
`$\{MINION_HOME}/ect/confd.system.properties` is automatically appended to `etc/system.properties`.
If the `JAEGER_AGENT_HOST` or `JAEGER_ENDPOINT` keys are specified, `$\{MINION_HOME}/etc/featuresBoot.d/jaeger.boot` is also updated.

=== Karaf properties

[source, yaml]
----
karaf:
    shell:
        ssh:
            host: "0.0.0.0"
            port: 8201
    management:
        rmi:
            registry:
                host: "127.0.0.1"
                port: 1299
            server:
                host: "127.0.0.1"
                port: 45444
----

Writes the specified configuration settings to the following files:

* `$\{MINION_HOME}/etc/org.apache.karaf.shell.cfg` for content under `shell`.
* `$\{MINION_HOME}/etc/org.apache.karaf.management.cfg` for content under `management`.

=== Jetty properties

[source, yaml]
----
jetty:
    web:
        host: "0.0.0.0"
        port: 8181
----

Writes the specified configuration settings to `$\{MINION_HOME}/etc/org.ops4j.pax.web.cfg`.

=== Secure credentials vault provider

[source, yaml]
----
scv:
    provider: "dominion"
----

Overrides the default SCV provider from the JCEKS implementation (which uses the file system) to a gRPC-based implementation, which requests credentials from Dominion.
If the SCV provider is not specified, the default JCEKS implementation is used.

=== Java options

[source, yaml]
----
process-env:
    java-opts:
        - -Xmx4096m
        - -Xdebug
        - -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=7896
----

Use to specify an arbitrary list of Java options.
Writes the specified configuration settings to `$\{MINION_HOME}/etc/minion-process.env`, which contains `key=value` pairs that are set in the Minion process environment.

=== JMX Prometheus Exporter

.JMX Exporter with a Confd YAML configuration file
[source, yaml]
----
java:
  agent:
    prom-jmx-exporter:
      startDelaySeconds: 0
      lowerCaseOutputName: true
      lowercaseOutputLabelNames: true
      autoExcludeObjectNameAttributes: true
      includeObjectNames:
        - "java.lang:*"
        - "org.opennms.*:*"
        - "kafka.producer:*"
      excludeObjectNames:
        - "org.apache.camel:*"
----