Installation and configuration Objectives Install all required OpenNMS Horizon components including PostgreSQL on a single node Run Horizon Core and PostgreSQL with the default configuration (which is not optimized to run in production and monitor large networks) By default your time series storage is JRobin, which persists RRD files on the local file system Log in to the web UI and change the default admin password Requirements Linux physical server or a virtual machine running a supported Linux operating system Internet access to download the installation packages DNS works and localhost and your server’s host name resolve properly System user with administrative permissions (sudo) to perform installation To run services in Docker you need Docker Compose for the service stacks from our examples On Debian, you must install and configure sudo yourself. See the Debian Wiki for more information. Set up PostgreSQL CentOS/RHEL 8 CentOS/RHEL 7 Debian/Ubuntu Docker Install PostgreSQL client and server sudo dnf -y install postgresql-server postgresql Initialize the PostgreSQL database sudo postgresql-setup --initdb --unit postgresql Enable PostgreSQL on system boot and start immediately sudo systemctl enable --now postgresql Create an opennms database user and password sudo -i -u postgres createuser -P opennms You must provide a password for the opennms database user. This guide uses YOUR-OPENNMS-PASSWORD as a placeholder. Please set a secure password. Create an empty database and set the owner to the opennms user sudo -i -u postgres createdb -O opennms opennms Set a password for PostgreSQL superuser sudo -i -u postgres psql -c "ALTER USER postgres WITH PASSWORD 'YOUR-POSTGRES-PASSWORD';" Change YOUR-POSTGRES-PASSWORD to a secure one. The superuser is required to be able to initialize and change the database schema for installation and updates. Change the access policy for PostgreSQL sudo vi /var/lib/pgsql/data/pg_hba.conf Allow Horizon to access the database over the local network with an MD5 hashed password host all all 127.0.0.1/32 md5(1) host all all ::1/128 md5(1) 1 Change method from ident to md5 for IPv4 and IPv6 on localhost. Apply configuration changes for PostgreSQL sudo systemctl reload postgresql Add PostgreSQL 12 package repository sudo yum -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm Install PostgreSQL 12 client and server sudo yum -y install postgresql12-server postgresql12 Initialize PostgreSQL database sudo /usr/pgsql-12/bin/postgresql-12-setup initdb Enable PostgreSQL on system boot and start immediately sudo systemctl enable --now postgresql-12 Create an opennms database user and password sudo -i -u postgres createuser -P opennms You must provide a password for the opennms database user. This guide uses YOUR-OPENNMS-PASSWORD as a placeholder. Please set a secure password. Create an empty database and set the owner to the opennms user sudo -i -u postgres createdb -O opennms opennms Set a password for PostgreSQL superuser sudo -i -u postgres psql -c "ALTER USER postgres WITH PASSWORD 'YOUR-POSTGRES-PASSWORD';" Change YOUR-POSTGRES-PASSWORD to a secure one. The superuser is required to initialize and change the database schema for installation and updates. Change the access policy for PostgreSQL sudo vi /var/lib/pgsql/12/data/pg_hba.conf Allow Horizon to access the database over the local network with an MD5 hashed password host all all 127.0.0.1/32 md5(1) host all all ::1/128 md5(1) 1 Change method from ident to md5 for IPv4 and IPv6 on localhost. Apply configuration changes for PostgreSQL sudo systemctl reload postgresql-12 Install PostgreSQL client and server sudo apt -y install postgresql Create an opennms database user and password sudo -u postgres createuser -P opennms You must provide a password for the opennms database user. This guide uses YOUR-OPENNMS-PASSWORD as a placeholder. Please set a secure password. Create an empty database and set the owner to the opennms user sudo -u postgres createdb -O opennms opennms Set a password for PostgreSQL superuser sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD 'YOUR-POSTGRES-PASSWORD';" Change YOUR-POSTGRES-PASSWORD to a secure one. The superuser is required to initialize and change the database schema for installation and updates. Create a project directory for PostgreSQL and create a docker-compose.yml file mkdir postgres cd postgres vi docker-compose.yml Create the PostgreSQL service and publish the port on your local host --- version: '3' volumes: data-postgres: {}(1) services: database:(2) image: postgres:13(3) container_name: database environment:(4) TZ: 'America/New_York' POSTGRES_USER: 'postgres' POSTGRES_PASSWORD: 'my-postgres-password' volumes:(5) - 'data-postgres:/var/lib/postgresql/data' healthcheck:(6) test: [ "CMD-SHELL", "pg_isready -U postgres" ] interval: 10s timeout: 3s retries: 3 ports: - '5432:5432/tcp' 1 Persist the PostgreSQL database in a local volume. 2 PostgreSQL service is named database with a friendly container_name. 3 Image reference using the official PostgreSQL image. 4 Set the time zone and the postgres credentials for administrative tasks (for example, creating and changing database schemas for upgrades). 5 Mount the volume for persisting the PostgreSQL database files. 6 Run an internal health check to see if the PostgreSQL instance is ready. Start the service and run it in background docker-compose up -d Verify the PostgreSQL process is up and running docker-compose ps The state should be Up (healthy) and the TCP port should be available on all interfaces Name Command State Ports -------------------------------------------------------------------------------- database docker-entrypoint.sh postgres Up (healthy) 0.0.0.0:5432->5432/tcp Install the Core instance CentOS/RHEL 8 CentOS/RHEL 7 Ubuntu Debian Docker Add repository and import GPG key sudo dnf -y install https://yum.opennms.org/repofiles/opennms-repo-stable-rhel8.noarch.rpm sudo rpm --import https://yum.opennms.org/OPENNMS-GPG-KEY Install Horizon with all built-in dependencies sudo dnf -y install opennms If you want time series trending and forecast functions you must install the R project packages. The additional download size for packages is ~390 MB. Install R-core packages for time series trending and forecasting (optional) sudo dnf -y install epel-release sudo dnf -y install R-core Disable the OpenNMS Horizon repository after installation to prevent unwanted upgrades when upgrading other packages on the server. After upgrade, Horizon requires manual steps to upgrade configuration files or migrate database schemas to a new version. We recommend that you exclude the Horizon packages from update except when you plan to perform an upgrade. Disable auto updates for OpenNMS Horizon sudo dnf config-manager --disable opennms-repo-stable-* Verify directory structure with the tree command sudo dnf -y install tree tree /opt/opennms -L 1 Directory structure after successful installation /opt/opennms ├── bin ├── contrib ├── data ├── deploy ├── etc ├── jetty-webapps ├── lib ├── logs -> /var/log/opennms ├── share -> /var/opennms └── system Add repository and import GPG key sudo yum -y install https://yum.opennms.org/repofiles/opennms-repo-stable-rhel7.noarch.rpm sudo rpm --import https://yum.opennms.org/OPENNMS-GPG-KEY Install Horizon with all built-in dependencies sudo yum -y install opennms If you want time series trending and forecast functions you must install the R project packages. The additional download size for packages is ~390 MB. Install R-core packages for time series trending and forecasting (optional) sudo yum -y install epel-release sudo yum -y install R-core Disable the OpenNMS Horizon repository after installation to prevent unwanted upgrades when upgrading other packages on the server. After upgrade, Horizon requires manual steps to upgrade configuration files or migrate database schemas to a new version. We recommend that you exclude the Horizon packages from update except when you plan to perform an upgrade. Disable auto updates for OpenNMS Horizon sudo yum -y install yum-utils sudo yum-config-manager --disable opennms-repo-stable-* Verify directory structure with the tree command sudo yum -y install tree tree /opt/opennms -L 1 Directory structure after successful installation /opt/opennms ├── bin ├── contrib ├── data ├── deploy ├── etc ├── jetty-webapps ├── lib ├── logs -> /var/log/opennms ├── share -> /var/opennms └── system Add OpenNMS repository GPG key sudo apt-key adv --fetch-keys https://debian.opennms.org/OPENNMS-GPG-KEY Add apt repository sudo add-apt-repository -s 'deb https://debian.opennms.org stable main' You can safely ignore the message about conflicting distributions (expected stable but got opennms-xx). Install OpenNMS Horizon with built-in dependencies (optional) sudo apt -y install opennms Installing R package for trending and forcasting (optional) If you want time series trending and forecast functions you have to install the R project packages. The additional download size for packages is ~152 MB. sudo apt -y install r-recommended Disable the OpenNMS Horizon repository after installation to prevent unwanted upgrades when upgrading other packages on the server. After upgrade, Horizon requires manual steps to upgrade configuration files or migrate database schemas to a new version. We recommend that you exclude the Horizon packages from update except when you are planning on performing an upgrade. sudo apt-mark hold libopennms-java \ libopennmsdeps-java \ opennms-common \ opennms-db Verify directory structure with the tree command sudo apt -y install tree tree /usr/share/opennms -L 1 Directory structure after successful installation /usr/share/opennms ├── bin ├── data ├── deploy ├── etc -> /etc/opennms ├── jetty-webapps ├── lib -> ../java/opennms ├── logs -> /var/log/opennms ├── share -> /var/lib/opennms └── system Install GnuPG and add OpenNMS repository GPG key sudo apt -y install gnupg ca-certificates sudo apt-key adv --fetch-keys https://debian.opennms.org/OPENNMS-GPG-KEY Add Apt repository sudo apt -y install software-properties-common sudo add-apt-repository -s 'deb https://debian.opennms.org stable main' sudo apt update You can safely ignore the message about conflicting distributions (expected stable but got opennms-xx). Install OpenNMS Horizon with built-in dependencies sudo apt -y install opennms Install R packages for trending and forcasting (optional) If you want time series trending and forecast functions you must install the R project packages. The additional download size for packages is ~134 MB. sudo apt -y install r-recommended Disable the OpenNMS Horizon repository after installation to prevent unwanted upgrades when upgrading other packages on the server. After upgrade, Horizon requires manual steps to upgrade configuration files or migrate database schemas to a new version. We recommend that you exclude the Horizon packages from update except when you plan perform an upgrade. sudo apt-mark hold libopennms-java \ libopennmsdeps-java \ opennms-common \ opennms-db Verify directory structure with the tree command sudo apt -y install tree tree /usr/share/opennms -L 1 Directory structure after successful installation /usr/share/opennms ├── bin ├── data ├── deploy ├── etc -> /etc/opennms ├── jetty-webapps ├── lib -> ../java/opennms ├── logs -> /var/log/opennms ├── share -> /var/lib/opennms └── system Create a project directory for Horizon Core and create a docker-compose.yml file. mkdir horizon cd horizon vi docker-compose.yml --- version: '3' volumes: data-opennms: {}(1) services: horizon:(2) image: opennms/horizon:bleeding(3) container_name: horizon environment:(4) TZ: 'America/New_York' POSTGRES_HOST: 'my-database-host'(5) POSTGRES_PORT: 5432 POSTGRES_USER: 'postgres' POSTGRES_PASSWORD: 'my-postgres-password' OPENNMS_DBNAME: 'opennms-core-db' OPENNMS_DBUSER: 'opennms' OPENNMS_DBPASS: 'my-opennms-db-password' volumes:(6) - data-opennms:/opennms-data - ./etc:/opt/opennms/etc(7) command: ["-s"] ports:(8) - '8980:8980/tcp' - '8101:8101/tcp' healthcheck: test: [ 'CMD', 'curl', '-f', '-I', 'http://localhost:8980/opennms/login.jsp' ](9) interval: 1m timeout: 5s retries: 3 1 Volume definitions to persist the Horizon Core data; for example, RRD files and PDF reports. 2 The Horizon Core instance service is named horizon with a friendly container_name. 3 Image reference using the Horizon container image with the Core services. 4 Set the time zone and the postgres credentials to initialize the database that the Horizon Core instance uses. To list all available time zones, use timedatectl list-timezones. 5 Set the host or IP address of the host that runs the PostgreSQL database. 6 Persist performance data PDF reports in a volume. 7 Mount the volumes for data persistence and bind mount the configuration in a local directory. 8 Publish ports to access the web UI and the Karaf shell. 9 Run an internal health check against the web UI to verify service health status. Validate your Docker Compose file docker-compose config -q Set up the Core instance CentOS/RHEL 7/8 Debian/Ubuntu Docker Configure PostgreSQL database access sudo vi /opt/opennms/etc/opennms-datasources.xml Set credentials to access the PostgreSQL database <jdbc-data-source name="opennms" database-name="opennms"(1) class-name="org.postgresql.Driver" url="jdbc:postgresql://localhost:5432/opennms" user-name="** YOUR-OPENNMS-USERNAME **"(2) password="** YOUR-OPENNMS-PASSWORD **" />(3) <jdbc-data-source name="opennms-admin" database-name="template1" class-name="org.postgresql.Driver" url="jdbc:postgresql://localhost:5432/template1" user-name="postgres"(4) password="** YOUR-POSTGRES-PASSWORD **" />(5) 1 Set the database name Horizon should use. 2 Set the user name to access the opennms database table. 3 Set the password to access the opennms database table. 4 Set the postgres user for administrative access to PostgreSQL. 5 Set the password for administrative access to PostgreSQL. Detect and assign Java environment and persist in /opt/opennms/etc/java.conf sudo /opt/opennms/bin/runjava -s Initialize the database and detect system libraries persisted in /opt/opennms/etc/libraries.properties sudo /opt/opennms/bin/install -dis Enable Horizon core instance on system boot and start immediately sudo systemctl enable --now opennms Allow connection to the web UI from your network sudo firewall-cmd --permanent --add-port=8980/tcp sudo systemctl reload firewalld To receive SNMP Traps or Syslog messages you must allow incoming traffic on your host firewall as well. By default, the OpenNMS Horizon SNMP trap daemon listens on 162/udp and the Syslog daemon listens on 10514/udp. The SNMP Trap daemon is enabled by default, the OpenNMS Syslog daemon is disabled. Configure PostgreSQL database access sudo vi /usr/share/opennms/etc/opennms-datasources.xml Set credentials to access the PostgreSQL database <jdbc-data-source name="opennms" database-name="opennms"(1) class-name="org.postgresql.Driver" url="jdbc:postgresql://localhost:5432/opennms" user-name="** YOUR-OPENNMS-USERNAME **"(2) password="** YOUR-OPENNMS-PASSWORD **" />(3) <jdbc-data-source name="opennms-admin" database-name="template1" class-name="org.postgresql.Driver" url="jdbc:postgresql://localhost:5432/template1" user-name="postgres"(4) password="** YOUR-POSTGRES-PASSWORD **" />(5) 1 Set the database name Horizon should use. 2 Set the user name to access the opennms database table. 3 Set the password to access the opennms database table. 4 Set the postgres user for administrative access to PostgreSQL. 5 Set the password for administrative access to PostgreSQL. Detect Java environment and persist in /usr/share/opennms/etc/java.conf sudo /usr/share/opennms/bin/runjava -s Initialize the database and detect system libraries persisted in /opt/opennms/etc/libraries.properties sudo /usr/share/opennms/bin/install -dis Enable Horizon core instance on system boot and start immediately sudo systemctl enable --now opennms By default the OpenNMS SNMP Trap daemon listens on 162/udp and the Syslog daemon listens on 10514/udp. The SNMP Trap daemon is enabled by default, the OpenNMS Syslog daemon is disabled. Prepare a local configuration directory to run as an unprivileged user mkdir etc chown 10001:10001 -R etc Initialize the database and schema and a configuration directory docker-compose run horizon -i Start service in background docker-compose up -d You can also use this command when you run upgrades. You must delete the file etc/configured file first. It works as a guard to prevent unnecessary database migration runs on startup. Show configuration changes from a pristine system with docker-compose exec -w /opt/opennms/bin horizon ./config-diff.sh -d. If you changed your configuration files manually you can run the configuration tester with docker-compose exec horizon bin/config-tester -a First login After you start the Horizon Core services, access the web application at http://core-instance-ip:8980/opennms. The default login and password is admin. Immediately change the password to a secure one. Open http://core-instance-ip:8980/opennms in your web browser. Log in with with admin/admin. Click admin → Change Password in the navigation bar. Use admin as the current password then type and confirm a new password in the appropriate boxes. Click Submit. Log out, then log in with your new password. Minimum system requirements Set up Message Broker