Minion Docker

The Minion container image reads its configuration from environment variables at startup. For settings not covered by environment variables, you can overlay individual configuration files directly (see Directory conventions).

Startup arguments

Argument Description

-h

Display help with available arguments.

-c

Start Minion using environment variables for credentials. WARNING: credentials may be exposed via docker inspect and logs; use -s for production deployments.

-s

One-time command to initialize an encrypted keystore file with credentials in /keystore/scv.jce.

-f

Initialize and start Minion in foreground.

Controller configuration

Variable Description Default value

MINION_ID

Unique identifier for this Minion instance.

00000000-0000-0000-0000-deadbeef0001

MINION_LOCATION

Location name associated with this Minion instance.

MINION

OPENNMS_BROKER_URL

ActiveMQ broker URL.

tcp://127.0.0.1:61616
You cannot supply credentials via environment variables without exposing them in docker inspect output and container logs. To store credentials securely, initialize a keystore file using the -s flag and mount it to ${MINION_HOME}/etc/scv.jce.
Table 1. Credentials (use only in non-production environments)
Variable Description Default value

OPENNMS_HTTP_USER

Username for the OpenNMS HTTP API.

minion

OPENNMS_HTTP_PASS

Password for the OpenNMS HTTP API.

minion

OPENNMS_BROKER_USER

Username for ActiveMQ authentication.

minion

OPENNMS_BROKER_PASS

Password for ActiveMQ authentication.

minion

IPC strategy

Set MINION_IPC to choose the inter-process communication transport.

Value Description

(unset)

Use JMS (ActiveMQ). This is the default when MINION_IPC is not set.

jms

Use JMS (ActiveMQ) explicitly.

kafka

Use Apache Kafka. Requires additional Kafka variables (see Kafka configuration).

grpc

Use gRPC. Requires additional gRPC variables (see gRPC configuration).

Kafka configuration

Environment variables prefixed with KAFKA_IPC_ are written to ${MINION_HOME}/etc/org.opennms.core.ipc.kafka.cfg. The prefix is stripped, the remainder is lowercased, and underscores are converted to dots before being written as property keys. The file is regenerated on every startup, so changes to KAFKA_IPC_* variables take effect after a restart even when etc is persisted. Manual edits to this file are overwritten; use an etc overlay to customize it instead.

Variable Description Example value

KAFKA_IPC_BOOTSTRAP_SERVERS

Comma-separated list of Kafka broker addresses.

kafka-1:9092,kafka-2:9092

KAFKA_IPC_*

Any additional Kafka client property.

KAFKA_IPC_COMPRESSION_TYPE=gzip

For example, setting KAFKA_IPC_BOOTSTRAP_SERVERS=192.168.1.1:9092 produces the following in org.opennms.core.ipc.kafka.cfg:

bootstrap.servers=192.168.1.1:9092

gRPC configuration

Variable Description Default value

IPC_GRPC_HOST

Hostname of the gRPC server.

horizon

IPC_GRPC_PORT

Port of the gRPC server.

8990

Optional features

Variable Description Default value

JAEGER_ENABLED

Set to true to enable the Jaeger tracing agent feature.

false

DOMINION_SCV_ENABLED

Set to true to enable the Dominion secure credentials vault.

false

JVM memory

Variable Description Default value

JAVA_MIN_MEM

Minimum JVM heap size.

2g

JAVA_MAX_MEM

Maximum JVM heap size.

2g

Prometheus JMX exporter

For full details on the JMX exporter and customizing its configuration file, see Prometheus JMX exporter.

Variable Description Default value

PROM_JMX_EXPORTER_ENABLED

Set to true to enable the Prometheus JMX exporter.

false

PROM_JMX_EXPORTER_PORT

Port on which the JMX exporter listens.

9299

PROM_JMX_EXPORTER_CONFIG

Path to the exporter configuration file inside the container.

/opt/prom-jmx-exporter/config.yaml

Listeners and network settings

Variable Description Default value

OPENNMS_INSTANCE_ID

Instance ID used as prefix for queue and topic names.

OpenNMS

MINION_SYSLOG_LISTEN_INTERFACE

Interface the Syslog listener binds to.

0.0.0.0

MINION_SYSLOG_LISTEN_PORT

Port the Syslog listener binds to.

1514

MINION_TRAPD_LISTEN_INTERFACE

Interface the SNMP trap listener binds to.

0.0.0.0

MINION_TRAPD_LISTEN_PORT

Port the SNMP trap listener binds to.

1162

MINION_TRAPD_USE_ADDRESS_FROM_VARBIND

Use the agent address from the trap varbind instead of the packet source address.

false

FLOWS_LISTENER_ENABLED

Set to true to enable the single-port flows listener.

false

JTI_LISTENER_ENABLED

Set to true to enable the Junos Telemetry Interface listener on port 50001/udp.

false

NXOS_LISTENER_ENABLED

Set to true to enable the Cisco NX-OS telemetry listener on port 50002/udp.

false

KARAF_SSH_HOST, KARAF_SSH_PORT

Address and port of the Karaf shell SSH server.

0.0.0.0, 8201

JETTY_HOST, JETTY_PORT

Address and port of the embedded web server.

0.0.0.0, 8181

KARAF_MGMT_RMI_REGISTRY_HOST, KARAF_MGMT_RMI_REGISTRY_PORT

Address and port of the JMX RMI registry.

0.0.0.0, 1299

KARAF_MGMT_RMI_SERVER_HOST, KARAF_MGMT_RMI_SERVER_PORT

Address and port of the JMX RMI server.

0.0.0.0, 45444

DOMINION_GRPC_HOST, DOMINION_GRPC_PORT, DOMINION_GRPC_CLIENT_SECRET

Dominion gRPC endpoint and client secret, used when DOMINION_SCV_ENABLED=true.

horizon, 8990, (empty)

Directory conventions

Mountpoint Description

/opt/minion-etc-overlay

Files copied into ${MINION_HOME}/etc/ at startup, after environment variable processing. Direct file overlays take precedence over the corresponding environment variable settings.

/keystore

Directory for the encrypted keystore file initialized with the -s flag.

Migrating from minion-config.yaml

Earlier Minion images rendered configuration from a ${MINION_HOME}/minion-config.yaml file. This file is no longer supported, and the container refuses to start if it is present. To migrate, move each setting to its environment variable or overlay file, then remove the file:

minion-config.yaml key Replacement

broker-url, id, location

OPENNMS_BROKER_URL, MINION_ID, MINION_LOCATION

org.opennms.instance.id

OPENNMS_INSTANCE_ID

ipc.kafka.*

MINION_IPC=kafka and KAFKA_IPC_* (see Kafka configuration)

ipc.rpc.kafka., ipc.sink.kafka., ipc.twin.kafka.*

No longer supported; use KAFKA_IPC_* for all Kafka communication

ipc.grpc.*

MINION_IPC=grpc, IPC_GRPC_HOST, IPC_GRPC_PORT; overlay org.opennms.core.ipc.grpc.client.cfg for other keys

dominion.grpc.*

DOMINION_GRPC_HOST, DOMINION_GRPC_PORT, DOMINION_GRPC_CLIENT_SECRET

server-certs

Overlay minion-server-certs.env with one certificate ID per line, and mount each certificate at /opt/minion/server-certs/<id>

ipc.sink.offheap.*

Overlay org.opennms.core.ipc.sink.offheap.cfg

netmgt.syslog., netmgt.traps.

MINION_SYSLOG_* and MINION_TRAPD_* (see Listeners and network settings); overlay org.opennms.netmgt.syslog.cfg or org.opennms.netmgt.trapd.cfg for other keys

telemetry.flows.single-port-listener

FLOWS_LISTENER_ENABLED=true; overlay org.opennms.features.telemetry.listeners-single-port-flows.cfg to change its parameters

telemetry.flows.listeners.*

JTI_LISTENER_ENABLED, NXOS_LISTENER_ENABLED, or overlay one org.opennms.features.telemetry.listeners-<name>.cfg file per listener

system.properties.*

Pass each property as -D<name>=<value> in JAVA_OPTS

system.properties.JAEGER_*

JAEGER_ENABLED=true; set JAEGER_ENDPOINT or JAEGER_AGENT_HOST as environment variables, and JAEGER_SAMPLER_TYPE and JAEGER_SAMPLER_PARAM as -D options in JAVA_OPTS

scv.provider: dominion

DOMINION_SCV_ENABLED=true and DOMINION_GRPC_*

karaf.shell., karaf.management., jetty.web.*

KARAF_SSH_*, KARAF_MGMT_RMI_*, JETTY_*

process-env.java-opts

JAVA_OPTS, JAVA_MIN_MEM, JAVA_MAX_MEM

java.agent.prom-jmx-exporter.*

Mount your own exporter configuration file and set PROM_JMX_EXPORTER_CONFIG