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
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.
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
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.
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.
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.
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.
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
(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.
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 220.127.116.11, 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
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."