Get OpenNMS
Get Involved
Get to Know Us
From OpenNMS
| |||||
This tutorial covers installation for Linux distributions that make use of the YUM packaging system, including Fedora® , Red Hat Enterprise Linux® and CentOS.
Contents |
Select Your Release and Distribution
In order to tailor this tutorial to your distribution, please specify the release you decided upon previously, as well as your distribution version:
Hint: Please make sure you've Java Script activated to have a more convenient wiki page for your linux distribution. Release in OpenNMS means: stable, testing, unstable, snapshot
Installing the Repository RPM
The first step is to install the "opennms-repo" RPM appropriate for your distribution. This contains the information YUM needs to get OpenNMS package information for installing.
To do so, find the appropriate release RPM from http://yum.opennms.org/.
Then all you should need to do is install that repo package (as root):
rpm -Uvh http://yum.opennms.org/repofiles/opennms-repo-RELEASE-DISTRIBUTION.noarch.rpm
Try It! Check for OpenNMS Packages
Once you've installed the distribution-specific RPM package of your choice, a query of the YUM database should show OpenNMS as an available install option when you run yum search opennms:
[user@opennms -]$ rpm -Uvh \ http://yum.opennms.org/repofiles/opennms-repo-RELEASE-DISTRIBUTION.noarch.rpm Preparing... ####################################### [100%] 1:opennms-repo-RELEASE-DISTRIBUTION ####################################### [100%] [user@opennms ~]$ yum search opennms Loaded plugins: fastestmirror ====================== Matched: opennms ================================= mib2opennms.i386: Generate OpenNMS Events from MIB Traps mib2opennms.x86_64: Generate OpenNMS Events from MIB Traps opennms.noarch: Enterprise-grade Network Management Platform opennms-core.noarch: The core OpenNMS backend. ...
Preparing the Database for OpenNMS
Before installing OpenNMS itself, you will want to install PostgreSQL, and do a few things to make sure PostgreSQL is working properly.
Installing PostgreSQL
First, you'll want to install PostgreSQL. It is included in all of the major YUM-based distributions. To install, just run the "yum install" command (as root):
yum install postgresql postgresql-server
Startup
Onec PostgreSQL is installed, the first thing you'll need to do is making sure PostgreSQL starts up properly. On most distributions, you can just run (as root):
/sbin/service postgresql start
Some distributions will require you to first initialize the database. If you see an error when running that command, try initdb first, and then start again:
/sbin/service postgresql initdb /sbin/service postgresql start
Then, to ensure that PostgreSQL will start after a reboot, use the "chkconfig" command to enable start on bootup:
/sbin/chkconfig postgresql on
Allowing User Access to the Database
By default, PostgreSQL only allows you to connect if you are logged in to the local account name that matches the PostgreSQL user. Since OpenNMS runs as root, it cannot connect as a "postgres" or "opennms" user by default, so we have to change the configuration to allow that.
To do so, you will need to edit your database's pg_hba.conf file. On many default installations it can be found in the directory /var/lib/pgsql/data/, however you may need to consult your distribution's PostgreSQL documentation for the location of this file if this is not the case.
By default pg_hba.conf should have entries similar to the following at the bottom of the file:
local all all ident sameuser host all all 127.0.0.1/32 ident sameuser host all all ::1/128 ident sameuser
You will need to change these entries to resemble the following:
local all all trust host all all 127.0.0.1/32 trust host all all ::1/128 trust
Once you have finished making changes, restart the database (as root):
/sbin/service postgresql restart
Additionally, while it's beyond the scope of this beginning tutorial, you may want to check the PostgreSQL section of the Performance Tuning page to get the most out of your database installation.
Security Implications
The above changes to the default PostgreSQL configuration will make it easy to install OpenNMS on your server, but it also allows for anyone with a local user account to have full access to said DB. As this guide is a quick start, the assumption is that the server is limited to users of the OpenNMS system. If this is not the case, you should consult the PostgreSQL documentation for setting a more restrictive environment.
Installing the JDK
While we provide a JDK in our YUM repository as a fallback, it is very much recommended that you install the latest stable JDK from SunOracle for the best performance.
To do so, go to the Oracle Java SE download page, click the "Java Platform (JDK)" link, choose the platform and architecture that's appropriate to your distribution (Linux or Linux x64), and then download the jdk-*-rpm.bin file.
Once it has finished downloading, execute it from the command-line (it is a shell archive), and then install the resulting JDK rpm.
Try It! Install the JDK
After downloading the appropriate JDK file from Oracle, run the shell archive and install the RPM that gets unpacked.
[user@host tmp]$ sh jdk-6u24-linux-i586-rpm.bin -x Unpacking... Checksumming... Extracting... UnZipSFX 5.50 of 17 February 2002, by Info-ZIP (Zip-Bugs@lists.wku.edu). inflating: jdk-6u24-linux-i586.rpm inflating: sun-javadb-common-10.6.2-1.1.i386.rpm inflating: sun-javadb-core-10.6.2-1.1.i386.rpm inflating: sun-javadb-client-10.6.2-1.1.i386.rpm inflating: sun-javadb-demo-10.6.2-1.1.i386.rpm inflating: sun-javadb-docs-10.6.2-1.1.i386.rpm inflating: sun-javadb-javadoc-10.6.2-1.1.i386.rpm Extraction of RPM Done. Done. [user@host tmp]$ sudo rpm -ivh jdk-6u24-linux-i586.rpm
Installing OpenNMS
With all the prerequisites taken care of, you can now install OpenNMS. The OpenNMS software is not a single package, but a combination of many components. The YUM packaging system will download and install all of these components and their dependencies, if they are not already installed on your system.
There are many packages available in the OpenNMS YUM repository, but the easiest way to get started is to install the "opennms" package. This will pull in everything you need to have a working OpenNMS, including the OpenNMS core, web UI, and a set of common plugins.
Try It! Install OpenNMS
Install OpenNMS, using the "yum install" command (as root):
yum -y install opennms
You should see something like this:
...
Resolving Dependencies
--> Running transaction check
---> Package opennms.noarch 0:{{StableVersion}}-1 will be installed
---> Package jicmp.x86_64 0:1.2.1-1 will be installed
---> Package jicmp6.x86_64 0:1.0.1-1 will be installed
--> Finished Dependency Resolution
Dependencies Resolved
===========================================================================
Package Arch Version Repository Size
===========================================================================
Installing:
opennms noarch {{StableVersion}}-1 opennms-stable-common 2.2 k
Installing for dependencies:
jicmp x86_64 1.2.1-1 opennms-stable-rhel6 44 k
jicmp6 x86_64 1.0.1-1 opennms-stable-rhel6 27 k
opennms-core noarch {{StableVersion}}-1 opennms-stable-common 230 M
Transaction Summary
===========================================================================
Install 9 Package(s)
Total download size: 378 M
Installed size: 693 M
Downloading Packages:
...
(8/9): opennms-core-{{StableVersion}}-1.noarch.rpm | 230 MB 07:23
(9/9): opennms-webapp-jetty-{{StableVersion}}-1.noarch.rpm | 75 MB 02:16
---------------------------------------------------------------------------
Total 528 kB/s | 378 MB 12:13
Running rpm_check_debug
Running Transaction Test
Transaction Test Succeeded
Running Transaction
Installing : jicmp6-1.0.1-1.x86_64 1/9
Installing : jicmp-1.2.1-1.x86_64 2/9
...
Installing : opennms-{{StableVersion}}-1.noarch 9/9
Installed:
opennms.noarch 0:{{StableVersion}}-1
Dependency Installed:
jicmp.x86_64 0:1.2.1-1
jicmp6.x86_64 0:1.0.1-1
opennms-core.noarch 0:{{StableVersion}}-1
opennms-webapp-jetty.noarch 0:{{StableVersion}}-1
Complete!
Post-Install Configuration
Disable YUM Updates
Some distributions that use YUM/RPM as a package management system will attempt an automatic update at regular intervals. A system administrator could potentially run a manual update and inadvertently upgrade OpenNMS resulting in a misconfiguration or complete failure.
To avoid these scenarios, you may want to disable the OpenNMS repositories after a successful installation by editing the "/etc/yum.repos.d/opennms*" file and adding enabled=0 inside each [opennms-*] section. This can just as easily be changed back when it's time to upgrade.
Configure Java
Next, you need to tell OpenNMS which Java you want it to use, using the "$OPENNMS_HOME/bin/runjava" command. If you installed the recommended Sun/Oracle JDK, all you should need to do is point it at /usr/java/latest:
$OPENNMS_HOME/bin/runjava -S /usr/java/latest/bin/java
Create/Update the OpenNMS Database
Whenever you install OpenNMS or upgrade it, you should run the "$OPENNMS_HOME/bin/install" command, to create the OpenNMS database, or update it to the latest version. The install command takes many options, but in most cases all you should need is:
- -d - to update the database
- -i - to insert any default data that belongs in the database
- -s - to create or update the stored procedures OpenNMS uses for certain kinds of data access
Try It! Create the Database
Now it's time to create and configure the OpenNMS database. To do so, run the following command (as root):
$OPENNMS_HOME/bin/install -dis
You should get output something like this:
========================================================================= OpenNMS Installer ========================================================================= Configures PostgreSQL tables, users, and other miscellaneous settings. - searching for jicmp: - trying to load /usr/lib64/libjicmp.so: OK - searching for jicmp6: - trying to load /usr/lib64/libjicmp6.so: OK ... - Running migration for changelog: URL [...] INFO 2/1/12 12:48 PM:liquibase: Successfully acquired change log lock INFO 2/1/12 12:48 PM:liquibase: Creating database history table INFO 2/1/12 12:48 PM:liquibase: Reading from databasechangelog INFO 2/1/12 12:48 PM:liquibase: Reading from databasechangelog INFO 2/1/12 12:48 PM:liquibase: ChangeSet ran successfully in 54ms ... INFO 2/1/12 12:49 PM:liquibase: Successfully released change log lock - inserting PL/pgSQL iplike function... OK Installer completed successfully!
(Optional) Configure IPLIKE
OpenNMS uses a PostgreSQL stored procedure called "IPLIKE" which provides an API for easily performing complicated IP address queries. By default, OpenNMS installs a version of IPLIKE that is compatible with all versions of PostgreSQL, but there is a platform-specific version of IPLIKE with much better performance. While it is optional, it is recommended that you install the "iplike" package from YUM for performance reasons.
Try It! Install IPLIKE
To do so, install the "iplike" package with yum, like so (as root):
yum -y install iplike
You should see it finish with something like this:
Installed size: 30 k Downloading Packages: iplike-2.0.2-1rhel6.x86_64.rpm | 16 kB 00:00 Running rpm_check_debug Running Transaction Test Transaction Test Succeeded Running Transaction Installing : iplike-2.0.2-1.el6.x86_64 1/1 - installing iplike into the opennms db (if it exists)... OK Installed: iplike.x86_64 0:2.0.2-1.el6 Complete!
If you don't see "OK" next to the "installing iplike into the opennms db" line, for example if you changed the default PostgreSQL authentication options for security reasons, then you may have to run the script manually. For details on the options available to you when running manually, run:
/usr/sbin/install_iplike.sh -h
Configure Your Firewall
Depending on your installation, some distributions will disable connecting to unknown IP ports by default.
Assuming that the iptables service is enabled, in order to permit connections from IP address other than the localhost (127.0.0.1), it is necessary to add a rule to the configuration file to allow OpenNMS.
Add a Firewall Exception for OpenNMS
In the case of RHEL and CentOS, this file is: /etc/sysconfig/iptables. If you edit this file, you should see 1 or more lines starting with "-A INPUT" and containing a destination port ("--dport"). You will want to make a copy of one of these lines, and changed the destination port to 8980, like so:
... -A INPUT -p icmp -j ACCEPT -A INPUT -i lo -j ACCEPT -A INPUT -m state --state NEW -m tcp -p tcp --dport 22 -j ACCEPT -A INPUT -m state --state NEW -m tcp -p tcp --dport 8980 -j ACCEPT -A INPUT -j REJECT --reject-with icmp-host-prohibited ...
Note that some versions of CentOS and RHEL, instead of "INPUT" you will see something like "RH-Firewall-1-INPUT". These are equivalent. For the technical details, see the man page for iptables.
Restricting Connections to a Specific Subnet
It is common, however to restrict such connections only from a trusted range of IP addresses, and the addition to iptables of an optional -s address/mask is probably a better practice:
... -A INPUT -p icmp -j ACCEPT -A INPUT -i lo -j ACCEPT -A INPUT -m state --state NEW -m tcp -p tcp --dport 22 -j ACCEPT -A INPUT -m state --state NEW -m tcp -p tcp -s 12.34.56.00/24 --dport 8980 -j ACCEPT -A INPUT -j REJECT --reject-with icmp-host-prohibited ...
This example would add permitted access from the C-class network at: 12.34.56.00 through 12.34.56.255, being specified using CIDR notation.
Restart the Firewall
Once you have made your edits, you can restart the firewall by running the service command (as root):
/sbin/service iptables restart
Before logging out, try connecting to your server again to confirm connectivity.
Start OpenNMS and Connect to the Web UI
You can now start OpenNMS using the "service" command (as root):
/sbin/service opennms start
Try It! Connect to the Web UI
Try starting OpenNMS, and connecting to the web UI.
/sbin/service opennms start
You should be able to go to http://YOUR-OPENNMS-IP:8980/opennms/ in your browser and see the web UI. The default username and password are both "admin" so enter them in when you see the login prompt.
Change the Administrator Password
As mentioned above, the default username is "admin" and the default password is "admin" as well. It is recommended that you change the administrator user's password, for security reasons. To do so, log in to the web UI and then click on the username (admin) in the upper-right corner, and then click "Change Password." Enter the old and new passwords in the prompt, and click "OK."
Try It! Change the Default Password
To change the default password, browse to http://YOUR-OPENNMS-IP:8980/opennms/ and log in as administrator:
...then click the admin username in the upper-right corner:
...and finally, click "Change Password," then fill out the form.
Next Step: Scan Your First Device
Now that OpenNMS is installed, it's time to scan your first device! Let's move on to the Capability Scanning tutorial.
