Repository navigation
NMS-11035: Documentation gaps - #8984
Closed
joseanesONMS wants to merge 62 commits into
Closed
joseanesONMS wants to merge 62 commits into
joseanesONMS wants to merge 62 commits into
Conversation
The JschSshMonitor is still registered on develop but had no reference page. It is a deprecated wrapper around SshMonitor (JschSshMonitor.java delegates every poll), so the page lists the SshMonitor parameters and points to it.
The LaTableMonitor is registered on develop but had no reference page. The page follows LaTableMonitor.java: it walks laErrorFlag in the UCD-SNMP-MIB laTable and only reads the port, retry/retries, and timeout overrides.
The LogMatchTableMonitor is registered on develop but had no reference page. The page follows LogMatchTableMonitor.java: it walks logMatchErrorFlag in the UCD-SNMP-MIB logMatchTable and only reads the port, retry/retries, and timeout overrides.
The banner parameter said "regular expression" without naming the flavour or how it is applied. SshMonitor.java compiles banner/match with java.util.regex.Pattern and calls find() on the server banner line, so the page now says so and gives tested examples.
…olokiaBeanMonitor, and WebMonitor The three pages had no complete service and monitor definition to copy from. Examples follow the monitor classes and the shipped poller-configuration.xml; the WebMonitor header and response-text rows are corrected to match WebMonitor.java.
The JmxMonitor had a reference page, but the Jsr160Detector, the only JMX detector registered for provisioning, had none. Parameters and defaults come from JMXDetector, GenericJMXDetectorFactory, and JmxConnectionConfigBuilder; examples follow default-foreign-source.xml.
Twenty-four detectors registered as ServiceDetectorFactory services on develop had no reference page, including the line-oriented, SNMP-based, DHCP, NTP, ICMP, SMB, SSH, RADIUS, and general purpose detectors. Parameters and defaults come from each detector class and its base classes in opennms-provision and protocols/radius; examples validate against foreign-sources.xsd.
The collectd package elements storeByIfAlias, ifAliasDomain, storeByNodeID, storFlagOverride, and ifAliasComment were undocumented; storFlagOverride only has meaning together with the others. Behavior is taken from collectd-configuration.xsd, CollectionSpecification, ServiceParameters, IfInfo, and AliasedResource.
org.opennms.netmgt.collectd.strictInterval has defaulted to true since NMS-14259, but neither the property nor its effect on collection scheduling was documented. Behavior and default are taken from CollectableService.
Service monitors and detectors have a common parameter section, but collectors did not, so thresholding-enabled, ttl, and the Minion targeting parameters were only partly documented per collector. The list is limited to parameters handled generically by CollectableService, CollectorRequestBuilderImpl, and RpcTargetHelper.
…ests
The XmlCollector page used placeholders such as {ipaddr} in examples but never listed which ones exist or where they apply, and linked to the unrelated filter parameters page.
The list comes from AbstractXmlCollectionHandler.parseString and XmlCollector.filterParameters.
The resourceLabel attribute of resource types supports subIndex, hex, and string expressions that shipped resource types such as cesServerFarmRserverEntry rely on, but none of them were documented. Semantics are taken from GenericIndexResourceType, with a worked example for the Cisco SLB resource type.
The SnmpCollector page showed datacollection-config.xml and an include example, but did not explain the elements of a data collection group (group, mibObj, systemDef, ipList) or the include-collection options. Element semantics are taken from datacollection-config.xsd, DataCollectionConfigParser, and DataCollectionConfigLookupUtils.
The file handler page did not say how the path is resolved; FileRequisitionProvider opens it with new File(path) and the external requisition UI rejects paths that do not start with a slash. The page now states that the path must be absolute and warns against using etc/imports as a source directory.
… adapter The SNMP metadata adapter page did not mention opennms:snmp-metadata-provisioning-adapter. The new section covers its node selection options, dry-run versus persist behavior, and caveats, taken from SnmpMetadataProvisioningAdapterCommand and SnmpMetadataProvisioningAdapter.
The docs did not explain how Provisiond picks a node label or what the label source flag means. The new Node Labels page covers requisition, discovered, and manually changed labels, based on DefaultProvisionService, ScanResource, SaveOrUpdateOperation, and NodeLabelDaoImpl.
The path outages page showed one example but provisioning had no procedure for defining node parents. The new section in Directed Discovery covers the UI and requisition attributes, parent lookup rules, and critical interface selection from CoreImportActivities and DefaultProvisionService, and cross-links with path outages.
There was no operator page describing the SNMP agent configuration: its structure, how an IP address is matched to a definition, or each attribute and its default. The new SNMP Configuration page is based on snmp-config.xsd, the JAXB Configuration and Definition classes, AddressSnmpConfigVisitor, and SnmpConfiguration defaults, and the quick start, profile, and XML sample pages now link to it.
The proxy-host attribute was listed without any explanation of its effect. SnmpPeerFactory replaces the request address with the proxy and keeps the agent as ProxyForAddress, and the SNMP4J strategy sends only to the proxy; the new section describes this, which settings apply to the proxy, and how to verify it.
Operators had no guidance on checking the effective SNMP configuration, testing requests, or tuning timeouts and PDU sizes for slow agents. The new section uses the snmp-show-config, snmp-get, snmp-walk, and snmp-fit Karaf commands and the matching, security level, and profile fitting rules in AddressSnmpConfigVisitor and NodeInfoScan.
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.
Only the scripting, ticket, and webhook strategies had pages; JavaMail, browser, HTTP, SNMP trap, and null were undocumented or only shown by example. The pages follow the strategy classes in opennms-services and the shipped notificationCommands.xml and javamail-configuration.properties.
The docs did not explain how notifd matches events to notifications, what match-all does, or how auto-acknowledge rules and resolution notices behave. The text follows BroadcastEventProcessor, NotificationManager, and the notifd-configuration.xsd model and shipped defaults.
Adds a PagerDuty Events API v2 example to the webhook strategy page, with trigger and resolve commands tied together by a dedup key. It uses only the existing WebhookNotificationStrategy switches and notification parameters.
…fic users The reference material for rules, groups, and destination paths existed, but nothing showed how to combine them for this common task. The procedure uses the filter rule syntax in JdbcFilterDao and the shipped notifications.xml and notifd-configuration.xml defaults.
The Minion docs described installation per broker but not the Sink and RPC patterns that carry Core, Minion, and Sentinel traffic. The new page follows the core/ipc sink and rpc APIs and the strategy selection in SinkStrategy and RpcStrategy.
The Twin pattern that replicates configuration from Core to Minions was only mentioned by name in the Kafka setup. The section follows the core/ipc/twin publisher and subscriber APIs, the keys registered by Trapd, telemetryd, and the IPFIX provider, and the twin-subscribe shell command.
The Debian package ships the real configuration directory at /opt/opennms/etc and makes /etc/opennms the link (debian/opennms-common.dirs, debian/opennms-common.links, debian/rules), so the mv and ln -s steps that assumed the reverse are replaced with the same commands as the RHEL tab, which also match the later etc.bak restore step.
The restore steps ran chown and the Debian apt-get install without sudo, and appended to /etc/passwd and /etc/group with a shell redirect that runs unprivileged even under sudo, so each step failed for a sudo user. They now use sudo, and sudo tee -a for the appends.
| .Create encrypted credentials for the PostgreSQL database connections | ||
| [source, console] | ||
| ---- | ||
| sudo -u opennms ${OPENNMS_HOME}/bin/scvcli set postgres opennms password <1> |
Contributor
There was a problem hiding this comment.
I don't know if we want to do this... we have standardized on the OPENNMS_HOME directory at this point so maybe this is ok? Need to get feedback from others. I'm ok with it though... I think.
| endif::[] | ||
| ==== | ||
|
|
||
| [[iplike]] |
Contributor
There was a problem hiding this comment.
I would drop the change for IPLIKE for now until we get #8634 merged in.
Contributor
|
@joseanesONMS - I started reviewing but this needs to be broken up a bit. It's a bit too much in too many different places in one PR. Like, if it were one liners throughout... maybe it would be ok but this is too much to review in one PR for the docs. Can you break this up a bit further? Maybe pick like 5 or so of these to put into one PR or group them based on the topic or something... |
joseanesONMS
changed the title
This was referenced Oct 22, 2026
Contributor
Author
|
@marshallmassengill Split by topic as you suggested, on branches without
The IPLIKE change (NMS-14932) is dropped until #8634 merges. The |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes open documentation tickets, led by NMS-11035, with content checked against the code on develop; one commit per ticket.
The docs build adds no warnings (develop's two existing ones remain), every new page is in a
nav.adoc, and XML examples validate against their XSDs.reference/…/monitors/JschSshMonitor.adoc(new),SshMonitor.adocfeatures/poller/monitors/core/…/JschSshMonitor.java,SshMonitor.javareference/…/monitors/LaTableMonitor.adoc(new)…/monitors/LaTableMonitor.java,SnmpMonitorStrategy.javareference/…/monitors/LogMatchTableMonitor.adoc(new)…/monitors/LogMatchTableMonitor.javareference/…/monitors/SshMonitor.adoc…/monitors/SshMonitor.javaDeviceConfigMonitor.adoc,JolokiaBeanMonitor.adoc,WebMonitor.adocfeatures/device-config/monitor/…/DeviceConfigMonitor.java,JolokiaBeanMonitor.java,WebMonitor.javareference/…/detectors/Jsr160Detector.adoc(new),JmxMonitor.adocopennms-provision/opennms-detector-jmx/…,core/jmx/api/…/JmxConnectionConfig*.javareference/…/detectors/*.adocopennms-provision/opennms-detector-*,protocols/radius/…/detector,opennms-provision-api/…/support/*Detector*.javastorFlagOverrideand the ifAlias storage optionsoperation/…/collectd/collection-packages.adoccollectd-configuration.xsd,CollectionSpecification.java,IfInfo.javastrictIntervaloperation/…/collectd/configuration.adoc,reference/…/system-properties.adocopennms-services/…/collectd/CollectableService.javareference/…/performance-data-collection/introduction.adocCollectableService.java,CollectorRequestBuilderImpl.java,RpcTargetHelper.javareference/…/collectors/xml.adocprotocols/xml/…/AbstractXmlCollectionHandler.java,XmlCollector.javasubIndexand other resource label expressionsoperation/…/resource-types.adocopennms-dao/…/GenericIndexResourceType.javareference/…/collectors/SnmpCollector.adocdatacollection-config.xsd,DataCollectionConfigParser.javareference/…/handlers/file.adocFileRequisitionProvider.java,ConfigurationHelper.tsreference/…/adapters/snmp-metadata.adocSnmpMetadataProvisioningAdapterCommand.javaoperation/…/provisioning/node-label.adoc(new)DefaultProvisionService.java,NodeLabelDaoImpl.javaoperation/…/provisioning/directed-discovery.adoc,path-outages.adocmodel-import.xsd,DefaultProvisionService.setNodeParentAndDependenciesoperation/…/provisioning/snmp-configuration.adoc(new)snmp-config.xsd,SnmpConfiguration.java,SnmpConfigManager.javaproxy-hostsnmp-configuration.adocSnmpPeerFactory.java,Snmp4JAgentConfig.javasnmp-configuration.adoccore/snmp/commands/*,NodeInfoScan.javaCORE_SERVICE_*_ENABLEDnamesreference/…/daemons/introduction.adocservice-configuration.xml.tmpl,service-configuration.xmloperation/…/daemon-config-files.adocand linksPollerEventProcessor.java,Collectd.java,SnmpPoller.java,ThresholdingServiceImpl.javareference/…/daemon-config-files/trapd.adoc,snmp-traps.adoc,core-docker.adocDefaultTrapdConfigDao.java,changelog-cm/36.0.0,ui/src/components/TrapdConfiguration/*operation/…/device-config-backup/dcb.adocDeviceConfigRestService.javaoperation/…/notifications/strategies/{javamail,http,snmp-trap,browser}.adoc(new),commands.adocopennms-services/…/notifd/*NotificationStrategy.java,notificationCommands.xmloperation/…/notifications/concepts.adoc,reference/…/notifd.adocBroadcastEventProcessor.java,NotificationManager.java,notifd-configuration.xsdoperation/…/strategies/webhook.adocWebhookNotificationStrategy.javaoperation/…/notifications/route-by-node.adoc(new)JdbcFilterDao.javadeployment/…/minion/ipc.adoc(new)core/ipc/sink/api,core/ipc/rpc/apideployment/…/minion/ipc.adoc,minion/message-broker/kafka.adoccore/ipc/twin/api,AbstractTwinPublisher.java.protodefinitionsoperation/…/kafka-producer/kafka-producer.adocfeatures/kafka/producer/src/main/proto/*.proto,OpennmsKafkaProducer.javaoperation/…/kafka-producer/configure-kafka.adocOpennmsKafkaProducer.java(SpEL filters)reference/…/tuning-kafka.adoc,system-properties.adocblueprint-ipc-server.xml,KafkaTopicProvider.javascvclireferenceoperation/…/scv-configuration.adocfeatures/scv/scvcli/*deployment/…/newts/configuration.adocfeatures/timeseries-evaluate/*deployment/…/core/{centos,debian-ubuntu}/initialize-core.adocdebian/rules,debian/opennms-common.linkssudoin the Debian upgradedeployment/…/upgrade/debian/up-debian.adocdeployment/…/core/install.adoc,filters.adoccore/schema/…/Migrator.java,iplike.sqldeployment/…/core/install.adoc,minion/install.adocdocs/antora.ymldeployment/…/core/docker/initialize.adocopennms-container/core/Dockerfile,entrypoint.shoperation/…/visualizations/dashboard.adocDefaultSurveillanceViewService.javaCorrections made to existing text while working these tickets: wrong
WebMonitorparameter rows, the Kafka event-record key, the SnmpTrap command example, the SNMP sample namespace inxml-samples.adoc, and the secondteein the Debian setup now appends instead of overwritingopennms.conf.Corrections to existing docs (separate
NMS-11035: Fix …commits, each can be dropped on its own)brokerURL,useNodeLabel,storedProcedure,supported,authEnablednames; JDBCurl, WQLserviceName, TCPbanner, HTTPS defaultsscheduledefault is daily at midnight,neveris the shipped valueDeviceConfigMonitor.java,DeviceConfigConstants.javaretryTimeoutTracker.shouldRetry()$\{…}backslashes in source blocks; DNSResolution{nodeLabel}caseParameterSubstitutingMonitor.javarrdRepositoryattribute namedatacollection-config.xsdProvisioner.java,FileRequisitionProvider.javaConfiguration.java,AddressSnmpConfigVisitor.javaServiceConfiguration.mergeWithDefaults(), defaultsservice-configuration.xmlInfoRestService.javaTrapdConfigFactory.java,DefaultSnmpConfigDao.java,SnmpPeerFactory.java/opt/opennmspaths, Debian Git-diff steps, dump file name, line continuations,sudoon privileged restore commands, supported PostgreSQL on Debian restore, stale CAP_NET_RAW stepdebian/rules,debian/opennms-common.links,opennms.spec,opennms.servicedocs/antora.yml(compatible-rhel: '9,10')git logofwhatsnew.adocAlready documented
deployment/…/core/system-requirements.adoc; this PR only aligns the page descriptions.Not addressed
reloadableattribute on develop; the code (NMS-10350) is unmerged.compatible-debian: '11, 12'), so install steps cannot be verified.External References