Repository navigation
NMS-20453: Setup, upgrade and restore docs - #9006
Merged
Merged
Conversation
The vault step used a generic "password" placeholder, so it was unclear that these are the opennms and postgres passwords from the PostgreSQL setup, and the Debian/Ubuntu steps used an undefined $OPENNMS_HOME although the Debian package installs to /opt/opennms (debian/rules). The second opennms.conf line now appends instead of overwriting the first.
The Debian upgrade steps mixed sudo and plain root commands, so some apt and installer commands failed when run as a regular user. Every privileged command now uses sudo, and the first step asks for a user with sudo privileges instead of a root login.
The Debian package installs to /opt/opennms (debian/rules sets opennms.home and install.dir; debian/opennms-common.links) and does not export OPENNMS_HOME, so the commands now use absolute paths.
docs/antora.yml lists CentOS and RHEL 9 and 10 as the only compatible releases, so the RHEL 7 RRDtool tab and the RHEL 8-only PostgreSQL restore steps are removed and the remaining RHEL tabs and notes are relabelled. The restore page now points to the supported PostgreSQL setup instead of the distribution package, which is older than the compatible PostgreSQL range on RHEL 9.
The initialize-core-cap section was removed in #7907 because the shipped opennms.service unit sets AmbientCapabilities=CAP_NET_RAW CAP_NET_BIND_SERVICE (opennms-base-assembly/src/main/filtered/etc/opennms.service), and the restore copies that unit back into place, so the step pointing at the missing anchor is dropped.
The RHEL backup steps write /tmp/opennms-postgres.dmp with pg_dumpall, but the restore read /tmp/opennms_postgres.dmp; the restore now uses the same name, as the Debian/Ubuntu pair already does.
Two commands ended in "&& /" instead of "&& \", so the shell treats "/" as a command instead of continuing on the next line.
The RPM installs to /opt/opennms (tools/packages/opennms/opennms.spec instprefix, with /opt/opennms/share linked to the directory holding etc-pristine) and exports OPENNMS_HOME only for login shells through /etc/profile.d/opennms.sh, so the commands now use absolute paths that also work in non-login and sudo shells and match the Debian pages.
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.
This was referenced Oct 22, 2026
dino2gnt
requested changes
Oct 22, 2026
| @@ -28,7 +29,7 @@ NOTE: **Optional**: Define any necessary xref:operation:deep-dive/admin/configur | |||
| [source, console] | |||
| ---- | |||
| echo "JAVA_HEAP_SIZE=16384" | sudo tee /opt/opennms/etc/opennms.conf | |||
Contributor
There was a problem hiding this comment.
Suggested change
| echo "JAVA_HEAP_SIZE=16384" | sudo tee /opt/opennms/etc/opennms.conf | |
| echo "JAVA_HEAP_SIZE=16384" | sudo tee -a /opt/opennms/etc/opennms.conf |
Might as well do both.
| ---- | ||
| echo "JAVA_HEAP_SIZE=16384" | sudo tee ${OPENNMS_HOME}/etc/opennms.conf | ||
| echo "MAXIMUM_FILE_DESCRIPTORS=512000" | sudo tee ${OPENNMS_HOME}/etc/opennms.conf | ||
| echo "JAVA_HEAP_SIZE=16384" | sudo tee /opt/opennms/etc/opennms.conf |
Contributor
There was a problem hiding this comment.
Suggested change
| echo "JAVA_HEAP_SIZE=16384" | sudo tee /opt/opennms/etc/opennms.conf | |
| echo "JAVA_HEAP_SIZE=16384" | sudo tee -a /opt/opennms/etc/opennms.conf |
# Conflicts: # docs/modules/deployment/pages/upgrade/debian/up-debian.adoc # docs/modules/deployment/pages/upgrade/restore/debian-ubuntu/restore-debian-ubuntu.adoc
…g it The first tee replaced opennms.conf, discarding any settings already in it; both the RHEL and Debian setup pages now append, like the next line does.
Contributor
Author
marshallmassengill
previously approved these changes
Oct 22, 2026
marshallmassengill
left a comment
marshallmassengill
left a comment
Contributor
There was a problem hiding this comment.
I think this is good to go.
…ge too The CentOS/RHEL initialize-core page still wrote JAVA_HEAP_SIZE with a plain tee, which replaces any existing opennms.conf. Append it with tee -a, as the CentOS and Debian/Ubuntu pages now do.
Contributor
Author
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.
Documents the core setup, upgrade, backup and restore steps
deployment/…/core/{centos,debian-ubuntu}/initialize-core.adocdebian/rules,debian/opennms-common.linkssudoin the Debian upgradedeployment/…/upgrade/debian/up-debian.adocThe second
teein the Debian setup now appends instead of overwritingopennms.conf.Corrections to existing docs (separate
NMS-20453: Fix …commits, each can be dropped on its own)/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.adocThe docs build adds no warnings (develop's two existing ones remain).
External References