NMS-19449: Daemon configuration docs by joseanesONMS · Pull Request #9002 · OpenNMS/opennms

joseanesONMS · 2026-10-22T12:44:29Z

Documents the daemon configuration and reloads, split out of #8984; content checked against the code on develop, one commit per ticket.

Ticket	Topic	Page(s) added/changed	Source of truth
NMS-20473	Correct `CORE_SERVICE_*_ENABLED` names	`reference/…/daemons/introduction.adoc`	`service-configuration.xml.tmpl`, `service-configuration.xml`
NMS-16398	Reloads after package filter changes	`operation/…/daemon-config-files.adoc` and links	`PollerEventProcessor.java`, `Collectd.java`, `SnmpPoller.java`, `ThresholdingServiceImpl.java`
NMS-19449	Trapd configuration in the database and its page	`reference/…/daemon-config-files/trapd.adoc`, `snmp-traps.adoc`, `core-docker.adoc`	`DefaultTrapdConfigDao.java`, `changelog-cm/36.0.0`, `ui/src/components/TrapdConfiguration/*`
NMS-14422	Deleting device configuration backups (REST)	`operation/…/device-config-backup/dcb.adoc`	`DeviceConfigRestService.java`

Corrections to existing docs (separate NMS-19449: Fix … commits, each can be dropped on its own)

Topic	Change	Source of truth
Reportd, Tl1d, TL1 events	Pages and remaining mentions removed: the daemons cannot be enabled on develop	`ServiceConfiguration.mergeWithDefaults()`, defaults `service-configuration.xml`
Info REST example	No Reportd in the services map	`InfoRestService.java`
Meta-data page	Trapd entry reflects database-stored configuration	`TrapdConfigFactory.java`

Not addressed

NMS-10411: there is no reloadable attribute on develop; the code (NMS-10350) is unmerged.

The docs build adds no warnings (develop's two existing ones remain).

External References

Jira (Issue Tracker): https://opennms.atlassian.net/browse/NMS-19449
Related: NMS-20473, NMS-16398, NMS-14422

The daemon table listed CORE_SERVICE_ENLINKD_ENABLED instead of CORE_SERVICE_ENHANCEDLINKD_ENABLED, a variable for Eventd that has no effect, and rows for the removed Reportd and Tl1d daemons. The names now match etc/service-configuration.xml and the container confd template exactly.

Pollerd, Collectd, SnmpPoller, and the thresholding service evaluate package filters only when they schedule an interface, and the docs did not say that a filter change needs a reload or restart. The new section lists, per daemon, what a reload re-evaluates and which node events trigger a partial re-evaluation, based on PollerEventProcessor, Collectd, SnmpPoller, and ThresholdingServiceImpl.

…ation page The trapd pages still described trapd-configuration.xml as a live file, although the configuration now lives in the database and is managed through the Trap Configuration page and /api/v2/trapd. The trapd reference now covers the one-time import, the reload behavior, and the three tabs of the page, based on DefaultTrapdConfigDao, the 36.0.0 changelog-cm, Trapd, and ui/src/containers/TrapdConfiguration.vue.

The DCB pages did not say how to delete a backup. The Device Configs page has no delete action on develop (NMS-14276 is open), so the new section covers the DELETE endpoints of DeviceConfigRestService and their effect on the Device Configs list.

…pages Both services were dropped from service-configuration.xml (NMS-18164, NMS-18169) and are absent from defaults/service-configuration.xml, so ServiceConfiguration.mergeWithDefaults() ignores any entry that tries to enable them.

Trapd reads its configuration from the database through TrapdConfigDao (TrapdConfigFactory), not from trapd-configuration.xml, and Trapd.interpolateUser() resolves the SNMPv3 user fields with a SecureCredentialsVaultScope only.

The Manager starts only services that ServiceConfiguration.mergeWithDefaults() keeps, and Tl1d is absent from defaults/service-configuration.xml with no Karaf feature to start it, so TL1 reception cannot be enabled.

InfoRestService reports the services that Manager.status() takes from ServiceConfigFactory, which no longer includes Reportd since it was dropped from defaults/service-configuration.xml.

marshallmassengill

I think this is all good to go. Would wait on an additional review before merging though.

dino2gnt · 2026-10-22T15:10:45Z

+|===
+
+Use the name in the *Daemon name* column as the `daemonName` parameter of the reload event, or as the argument of the `reload-daemon` command.
+Tab completion does not offer Threshd, but the command accepts it:


Suggested change

Tab completion does not offer Threshd, but the command accepts it:

Make an NMS to extend DaemonReloadEnum.java and I'll add it.

Removed in 0ab11ba. I kept the opennms:reload-daemon Threshd example and introduced it as a plain example, so it doesn't sit there without a lead-in.

The reload-daemon completer is driven by DaemonReloadEnum, which does not list Threshd yet; that is a code fix, not something to document. The Threshd example stays, introduced as a plain example.

dino2gnt

looks fine

marshallmassengill

LGTM!

cgorantla · 2026-10-22T21:06:26Z

+
+NOTE: The mappings between OIDs and UEIs are stored in the database and can be configured using the Web-UI.
+
+[[trapd-config-ui]]


Not sure if we need UI walk through docs. UI can change anytime and docs won't be up to date.

Removed in 4cddc53. The trapd page now only names the Trap Configuration page and the REST API, and keeps which settings apply to the core and which to Minions.

cgorantla · 2026-10-22T21:36:40Z

 https://tools.ietf.org/html/rfc3584#page-42[RFC 3584] defines an optional varbind `snmpTrapAddress (.1.3.6.1.6.3.18.1.3.0)` that you can add to forwarded traps to convey the original source IP address.

-To configure {page-component-title} to honor `snmpTrapAddress` when present, set `use-address-from-varbind="true"` in the top-level element of `$\{OPENNMS_HOME}/etc/trapd-configuration.xml` and restart {page-component-title}.
+To configure {page-component-title} to honor `snmpTrapAddress` when present, set `use-address-from-varbind="true"` in the trapd configuration and restart {page-component-title}.


don't think we need restart for trapd configuration changes. It should be auto loading config any time we update from UI or Rest API

The reload event only reloads part of the config. Trapd.handleConfigurationChanged() reloads TrapdConfigFactory and restarts the listener, so address, port and SNMPv3 users take effect. TrapdConfigFactory.reload() builds a new singleton, but the trapdConfig Spring bean injected into TrapSinkConsumer and the TrapSinkModule held by the listener's dispatcher (created once) keep the old instance. use-address-from-varbind, new-suspect, raw message, threads and queue/batch settings stay at their old values until a restart, so I kept the restart. If those should apply live, that is a code fix rather than a docs change.

I believe @cgorantla is correct... A) I tested it and B) Claude seems to have confirmed it via the code:

A save goes through DefaultTrapdConfigDao.replaceConfig() to the config manager's updateConfiguration(), which runs the DAO's update callback (ConfigurationReloadEventCallback).

That callback calls loadConfig() first, and only then sends the Trapd reload event.

loadConfig() does not swap in a new object. It copies every field of the new config into the already-cached TrapdConfiguration and keeps the same reference (AbstractCmJaxbConfigDao.java:108, BeanFieldCopyUtil.copyFields). The copy skips only static and final fields, and TrapdConfiguration has none apart from serialVersionUID.

Every TrapdConfigFactory instance wraps that same cached object, because the constructor just calls trapdConfigDao.getConfig(), which returns the cached one. Its getters read it on every call.

The REST service uses the same DAO bean through an onmsgi:reference, so there is only one cache.

You and @cgorantla are right: loadConfig() copies the new values into the cached object, and the reload also recreates the listener's sink dispatcher. Fixed in 5523aea: the trapd and SNMP traps pages now say changes take effect without a restart.

…d docs The field-by-field description of the Trap Configuration page would go stale as the UI changes. The trapd reference now only names the page and the REST API, keeps the core versus Minion scope of the settings, and the SNMP traps page links to the configuration storage section instead.

marshallmassengill

Fix the trapd thing and I think this will be good to go.

A save through the UI or the REST API copies the new values into the cached TrapdConfiguration that every TrapdConfigFactory wraps, and the reload event then closes and recreates the trap listener and its sink dispatcher, so every trapd setting takes effect live. Drop the restart instructions from the trapd and SNMP traps pages.

marshallmassengill

Good to go I think!

joseanesONMS added 8 commits October 22, 2026 08:25

NMS-19449: Fix the event sources by removing the TL1 page

480ae39

The Manager starts only services that ServiceConfiguration.mergeWithDefaults() keeps, and Tl1d is absent from defaults/service-configuration.xml with no Karaf feature to start it, so TL1 reception cannot be enabled.

NMS-19449: Fix the services map in the info REST example response

47b9e27

InfoRestService reports the services that Manager.status() takes from ServiceConfigFactory, which no longer includes Reportd since it was dropped from defaults/service-configuration.xml.

joseanesONMS requested review from cgorantla and marshallmassengill October 22, 2026 12:44

github-actions Bot added the docs label Oct 22, 2026

github-actions Bot requested a review from indigo423 October 22, 2026 12:44

This was referenced Oct 22, 2026

NMS-19449: Daemon configuration docs #8992

Closed

NMS-11035: Documentation gaps #8984

Closed

marshallmassengill previously approved these changes Oct 22, 2026

View reviewed changes

dino2gnt requested changes Oct 22, 2026

View reviewed changes

NMS-19449: Drop the Threshd tab-completion remark from the reload docs

0ab11ba

The reload-daemon completer is driven by DaemonReloadEnum, which does not list Threshd yet; that is a code fix, not something to document. The Threshd example stays, introduced as a plain example.

joseanesONMS dismissed marshallmassengill’s stale review via 0ab11ba October 23, 2026 13:30

joseanesONMS requested a review from dino2gnt October 23, 2026 13:30

dino2gnt previously approved these changes Oct 23, 2026

View reviewed changes

marshallmassengill self-requested a review October 23, 2026 15:22

marshallmassengill previously approved these changes Oct 23, 2026

View reviewed changes

cgorantla requested changes Oct 23, 2026

View reviewed changes

joseanesONMS dismissed stale reviews from marshallmassengill and dino2gnt via 4cddc53 October 23, 2026 17:37

joseanesONMS requested a review from cgorantla October 23, 2026 17:38

marshallmassengill self-requested a review October 23, 2026 17:52

marshallmassengill requested changes Oct 23, 2026

View reviewed changes

joseanesONMS requested a review from marshallmassengill October 23, 2026 18:15

marshallmassengill approved these changes Oct 23, 2026

View reviewed changes


		NOTE: The mappings between OIDs and UEIs are stored in the database and can be configured using the Web-UI.

		[[trapd-config-ui]]

Conversation

joseanesONMS commented Oct 22, 2026 • edited by atlassian Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

External References

Uh oh!

marshallmassengill left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dino2gnt left a comment

Choose a reason for hiding this comment

Uh oh!

marshallmassengill left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marshallmassengill left a comment

Choose a reason for hiding this comment

Uh oh!

marshallmassengill left a comment

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

joseanesONMS commented Oct 22, 2026 •

edited by atlassian Bot

Loading