Core Docker

Startup arguments

Argument Description

Argument	Description
`-h`	Display help with available arguments.
`-f`	Start the process in the foreground and use existing data and configuration.
`-i`	One-time command to initialize or update database and configuration files and do NOT start.
`-s`	Command to initialize or update database and configuration files and start OpenNMS in the foreground.
`-t`	One-time command to run the config-tester against the configuration.

-h

Display help with available arguments.

-f

Start the process in the foreground and use existing data and configuration.

-i

One-time command to initialize or update database and configuration files and do NOT start.

-s

Command to initialize or update database and configuration files and start OpenNMS in the foreground.

-t

One-time command to run the config-tester against the configuration.

Environment variables

Table 1. Java options
Environment variable	Description	Required	Default value
`JAVA_OPTS`	Allows you to add additional Java options.	optional	`-`
`PROM_JMX_EXPORTER_ENABLED`	Enable the JMX Prometheus Exporter agent.	required	`false`
`PROM_JMX_EXPORTER_PORT`	TCP port for the JMX Prometheus Exporter.	optional	`9299`
`PROM_JMX_EXPORTER_CONFIG`	Path to the JMX Prometheus Exporter configuration file	optional	`/opt/prom-jmx-exporter/config.yaml`
`PROM_JMX_EXPORTER_JAR`	Path to the JMX Prometheus agent	optional	`/opt/prom-jmx-exporter/jmx_prometheus_javaagent.jar`

By default, the JVM temp directory (java.io.tmpdir) is ${OPENNMS_HOME}/tmp and the embedded ActiveMQ broker’s on-disk store (activemq.data) is ${OPENNMS_HOME}/var/activemq. To use different paths, pass them via JAVA_OPTS, e.g. JAVA_OPTS="-Djava.io.tmpdir=/some/path -Dactivemq.data=/some/other/path".

Table 2. PostgreSQL connection configuration in opennms-datasources.xml
Environment variable	Description	Required	Default value
`OPENNMS_DBNAME`	Database name used for Meridian Core instance	required	-
`OPENNMS_DBUSER`	Username with access to the database	required	-
`OPENNMS_DBPASS`	Password for user with access to the database	required	-
`POSTGRES_HOST`	Host with the PostgreSQL server instance running	required	-
`POSTGRES_USER`	PostgreSQL super user to initialize database schema specified in `OPENNMS_DBNAME`	required	-
`POSTGRES_PASSWORD`	PostgreSQL super user password	required	-
`POSTGRES_PORT`	PostgreSQL server port	optional	`5432`
`POSTGRES_SSL_MODE`	Encryption for database communication	optional	`prefer`
`POSTGRES_SSL_FACTORY`	PostgreSQL SSL factory for certificate validation	optional	`org.postgresql.ssl.LibPQFactory`
`OPENNMS_DATABASE_CONNECTION_IDLETIMEOUT`	Global database connection pool idle timeout	optional	`600`
`OPENNMS_DATABASE_CONNECTION_LOGINTIMEOUT`	Global database connection pool login timeout	optional	`3`
`OPENNMS_DATABASE_CONNECTION_MINPOOL`	Global minimal connection pool size	optional	`25`
`OPENNMS_DATABASE_CONNECTION_MAXPOOL`	Global maximum connection pool size	optional	`50`
`OPENNMS_DATABASE_CONNECTION_MAXSIZE`	Global maximum connections	optional	`50`

Table 3. Timeseries storage configuration
Environment variable	Description	Required	Default value
`OPENNMS_TIMESERIES_STRATEGY`	Used Timeseries storage strategy	optional	`rrd`
`OPENNMS_RRD_STOREBYFOREIGNSOURCE`	Store timeseries data by foreign source instead of the database node id	optional	`true`
`OPENNMS_RRD_STRATEGYCLASS`	Java RRD Strategy class	optional	`org.opennms.netmgt.rrd.rrdtool.MultithreadedJniRrdStrategy`
`OPENNMS_RRD_INTERFACEJAR`	Java RRD Interface library	optional	`/usr/share/java/jrrd2.jar`
`OPENNMS_LIBRARY_JRRD2`	JRRD2 library path	optional	`/usr/lib/jni/libjrrd2.so`

Table 4. SNMP Trap receiver configuration in trapd-configuration.xml
Environment variable	Description	Required	Default value
`OPENNMS_TRAPD_ADDRESS`	Listen interface for SNMP Trapd	optional	`*`
`OPENNMS_TRAPD_PORT`	Port to listen for SNMP traps	optional	`1162`
`OPENNMS_TRAPD_NEW_SUSPECT_ON_TRAP`	Create new suspect event-based trap recipient for unknown devices.	optional	`false`
`OPENNMS_TRAPD_INCLUDE_RAW_MESSAGE`	Preserve raw messages in SNMP traps.	optional	`false`
`OPENNMS_TRAPD_THREADS`	Set maximum thread size to process SNMP traps.	optional	`0`
`OPENNMS_TRAPD_QUEUE_SIZE`	Set maximum queue for SNMP trap processing.	optional	`10000`
`OPENNMS_TRAPD_BATCH_SIZE`	Set batch size for SNMP trap processing.	optional	`1000`
`OPENNMS_TRAPD_BATCH_INTERVAL`	Set batch processing interval in milliseconds.	optional	`500`

The earlier names OPENNMS_TRAPD_NEWSUSPECTONTRAP, OPENNMS_TRAPD_INCLUDERAWMESSAGE, OPENNMS_TRAPD_QUEUESIZE, OPENNMS_TRAPD_BATCHSIZE, and OPENNMS_TRAPD_BATCHINTERVAL are still accepted as a fallback. If both the old and new name are set, the new name wins.

The Trapd variables only take effect when the database is first initialized or upgraded. At that point, the database installer imports etc/trapd-configuration.xml into the database and moves the file to etc_archive/. From then on, Meridian reads the Trapd configuration from the database, so changing these variables does not affect the running Trapd configuration. To change the Trapd configuration of an existing installation, use the Integrations → Trap Configuration page or the Trapd REST API (v2).

The container still writes etc/trapd-configuration.xml from these variables at every startup. The legacy REST v1 endpoint /rest/config/trapd reads that file, so it can show values that differ from the configuration Trapd actually uses. Use the REST v2 API to see the active configuration. If the database is reset, the installer imports the newly written etc/trapd-configuration.xml again, so the current variable values apply once more.

Table 5. Karaf Shell configuration in org.apache.karaf.shell.cfg
Environment variable	Description	Required	Default value
`OPENNMS_KARAF_SSH_HOST`	Listen interface for Karaf shell.	optional	`0.0.0.0`
`OPENNMS_KARAF_SSH_PORT`	SSH port for Karaf shell.	optional	`8101`

Table 6. Cassandra and Newts configuration
Environment variable	Description	Required	Default value
`REPLICATION_FACTOR`	Set Cassandra replication factor for the newts keyspace if Newts is used.	optional	`1`
`OPENNMS_CASSANDRA_HOSTNAME`	A comma-separated list with Cassandra hosts for Newts	optional	`hostname`
`OPENNMS_CASSANDRA_KEYSPACE`	Name of the keyspace used by Newts	optional	`newts`
`OPENNMS_CASSANDRA_PORT`	Cassandra server port	optional	`9042`
`OPENNMS_CASSANDRA_USERNAME`	Username with access to Cassandra	optional	`cassandra`
`OPENNMS_CASSANDRA_PASSWORD`	Password for user with access to Cassandra	optional	`cassandra`
`OPENNMS_CASSANDRA_DATACENTER`	Set this to the value of your local datacenter for the best performance	optional	`datacenter1`

The service toggles below are read by Meridian itself from the placeholders in service-configuration.xml, so they work the same way outside containers. Any value other than true (in any case) disables the service. The Manager and Eventd services are always enabled.

Table 7. Service toggles in service-configuration.xml
Environment variable	Description	Default value
`CORE_SERVICE_ALARMD_ENABLED`	Enable the Alarm daemon.	`true`
`CORE_SERVICE_BSMD_ENABLED`	Enable Business Service monitoring.	`true`
`CORE_SERVICE_TICKETER_ENABLED`	Enable the Ticketer service.	`true`
`CORE_SERVICE_CORRELATOR_ENABLED`	Enable the event correlator.	`false`
`CORE_SERVICE_QUEUED_ENABLED`	Enable the Queued service.	`true`
`CORE_SERVICE_ACTIOND_ENABLED`	Enable the Action daemon.	`true`
`CORE_SERVICE_NOTIFD_ENABLED`	Enable the Notification daemon.	`true`
`CORE_SERVICE_SCRIPTD_ENABLED`	Enable the Script daemon.	`true`
`CORE_SERVICE_RTCD_ENABLED`	Enable the Real-Time Console daemon.	`true`
`CORE_SERVICE_POLLERD_ENABLED`	Enable the Poller daemon.	`true`
`CORE_SERVICE_SNMPPOLLER_ENABLED`	Enable the SNMP Poller.	`false`
`CORE_SERVICE_ENHANCEDLINKD_ENABLED`	Enable Enhanced Linkd.	`true`
`CORE_SERVICE_COLLECTD_ENABLED`	Enable the Collector daemon.	`true`
`CORE_SERVICE_DISCOVERY_ENABLED`	Enable auto-discovery.	`true`
`CORE_SERVICE_VACUUMD_ENABLED`	Enable the Vacuum daemon.	`true`
`CORE_SERVICE_EVENTTRANSLATOR_ENABLED`	Enable the Event Translator.	`true`
`CORE_SERVICE_PASSIVESTATUSD_ENABLED`	Enable the Passive Status daemon.	`true`
`CORE_SERVICE_STATSD_ENABLED`	Enable the Statistics daemon.	`true`
`CORE_SERVICE_PROVISIOND_ENABLED`	Enable the Provisioning daemon.	`true`
`CORE_SERVICE_ACKD_ENABLED`	Enable the Acknowledgment daemon.	`true`
`CORE_SERVICE_JETTYSERVER_ENABLED`	Enable the embedded Jetty web server.	`true`
`CORE_SERVICE_KARAFSTARTUPMONITOR_ENABLED`	Enable the Karaf startup monitor.	`true`
`CORE_SERVICE_SYSLOGD_ENABLED`	Enable the Syslog daemon.	`false`
`CORE_SERVICE_TELEMETRYD_ENABLED`	Enable the Telemetry daemon.	`true`
`CORE_SERVICE_TRAPD_ENABLED`	Enable the SNMP Trap daemon.	`true`
`CORE_SERVICE_PERSPECTIVEPOLLER_ENABLED`	Enable the Perspective Poller.	`true`

Directory conventions

Mountpoint Description

Mountpoint	Description
`/opt/opennms-overlay`	Allows you to overwrite files relative to `/opt/opennms`.
`/opennms-data`	Directory with RRDTool files and generated PDF reports sent to the file system.

/opt/opennms-overlay

Allows you to overwrite files relative to /opt/opennms.

/opennms-data

Directory with RRDTool files and generated PDF reports sent to the file system.

JMX Prometheus Exporter

When PROM_JMX_EXPORTER_ENABLED=true and PROM_JMX_EXPORTER_CONFIG is left at its default, the container generates /opt/prom-jmx-exporter/config.yaml at startup from the following variables. To supply a fully custom configuration (for example, custom rules), mount your own file and set PROM_JMX_EXPORTER_CONFIG to its path. A file you mount at the default path is used as is and never overwritten. Nothing is generated while the exporter is disabled.

Table 8. JMX exporter configuration knobs
Environment variable	Description	Default value
`PROM_JMX_START_DELAY_SECONDS`	Delay in seconds before the exporter starts scraping.	`0`
`PROM_JMX_LOWERCASE_OUTPUT_NAME`	Lowercase metric output names.	`true`
`PROM_JMX_LOWERCASE_OUTPUT_LABEL_NAMES`	Lowercase label names.	`true`
`PROM_JMX_AUTO_EXCLUDE_OBJECT_NAME_ATTRIBUTES`	Automatically exclude object name attributes.	`true`

Migrating from confd

Earlier images rendered the configuration files above with confd, which read the same environment variables. Most variable names are unchanged, so existing deployments keep working. When upgrading, note the following:

The five Trapd variables listed above were renamed. The old names are still accepted as a fallback.
The Trapd variables are imported into the database only when the database is initialized or upgraded; later changes do not affect the running configuration. This was also the case with confd. See the note under the Trapd variables above.
OPENNMS_NOTIFD_SLACK_CHANNEL and OPENNMS_NOTIFD_MATTERMOST_CHANNEL are no longer supported, because the Slack and Mattermost notification strategies were removed. Use the webhook notification strategy instead, as described in Migrating from Slack and Mattermost.
Legacy _confd.*.properties files left in a mounted etc/ volume are removed at startup to prevent stale settings.
A _confd.<name>.properties file supplied through an overlay still replaces the generated settings, as it did with confd: the matching _container.<name>.properties file is removed and a warning is logged. Rename the file in your overlay to _container.<name>.properties (for example, _container.timeseries.properties) to silence the warning.
service-configuration.xml is no longer generated by the container. Meridian reads the CORE_SERVICE_*_ENABLED variables directly; any value other than true (in any case) disables the service, without an error.
If you mount a persistent etc/ volume from an earlier image, it still holds the service-configuration.xml that confd wrote, with fixed true and false values. Those values take precedence, so the CORE_SERVICE_*_ENABLED variables have no effect, and the container logs a WARNING: that names the ignored variables. To use the variables, replace the file with /opt/opennms/share/etc-pristine/service-configuration.xml and reapply any changes you made to it.
Boolean and numeric variables (for example, OPENNMS_TRAPD_*, OPENNMS_CASSANDRA_PORT, and OPENNMS_RRD_STOREBYFOREIGNSOURCE, plus PROM_JMX_* when the exporter config is generated) are validated at startup. Booleans must be true or false in any case (for example, True is accepted); other values such as 1 or yes are rejected. An invalid value prints an ERROR: message and the container stops before Meridian starts. The file that uses the invalid value is not written, but files rendered earlier in the same startup may already have been updated.