Get OpenNMS
Get Involved
Get to Know Us
From OpenNMS
| |||||
This tutorial covers installation of OpenNMS on Debian, and Debian-derived distributions like Ubuntu.
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:
Configure APT
Adding a Repository
To set up APT to talk to the OpenNMS repository, you'll need to create a file called "opennms.list" within the "/etc/apt/sources.list.d" directory, with the following contents:
# contents of /etc/apt/sources.list.d/opennms.list
deb http://debian.opennms.org RELEASE main
deb-src http://debian.opennms.org RELEASE main
Adding the OpenNMS PGP Key to APT
Packages within the APT system are cryptographically signed to ensure their integrity. This step ensures the integrity of the file you've downloaded, as well as a reference to guarantee that the file is provided by who it says it was. These features are useful at install-time as well as during future upgrades.
To install the OpenNMS PGP key into your system, type the following at a command prompt:
wget -O - http://debian.opennms.org/OPENNMS-GPG-KEY | sudo apt-key add -
Then you should be able to run "apt-get update" to get the latest list of packages in your APT repositories, including those in the OpenNMS repo.
Try It! Check for OpenNMS Packages
Once you've configured APT for the release of your choice, a query of the APT database should show OpenNMS as an available install option when you run "apt-cache search opennms":
sudo apt-get update apt-cache search opennms
You should see a list of OpenNMS-related packages:
[user@host tmp] apt-cache search opennms opennms-doc - Enterprise-grade Open-source Network Mana... (Documentation) opennms-common - Enterprise-grade Open-source Network Ma... (Common Files) libopennms-java - Enterprise-grade Open-source Netw... (OpenNMS Libraries) opennms-webapp-jetty - Enterprise-grade Open-source Netw... (Jetty Web UI) opennms - Enterprise-grade Open-source Network Managemen... (Full Install) opennms-server - Enterprise-grade Open-source Network Manageme... (Daemon)
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
The first thing you'll want to do is install the PostgreSQL database itself. On any Debian-based distribution, all you should have to do is install the "postgresql" package, and it will pull in anything it needs.
sudo apt-get update sudo apt-get install postgresql
Determining Your PostgreSQL Version
The version of PostgreSQL that gets installed depends upon what version distribution you're running. You can see the version of PostgreSQL installed with the "pg_lsclusters" command. For the purposes of this tutorial, we'll set an environment variable on the shell to make things easier:
PGVERSION=`pg_lsclusters -h | head -n 1 | cut -d' ' -f1`
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 allow the postgres user to authenticate without a password, you first must change options in the pg_hba.conf file. On Debian-derived systems, this will be located at /etc/postgresql/$PGVERSION/main/pg_hba.conf, where "$PGVERSION" is the environment variable we set earlier containing the version of your PostgreSQL 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.
Edit your "/etc/postgresql/$PGVERSION/main/pg_hba.conf" file now, as root. It should have entries similar to the following at the bottom:
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):
sudo /usr/sbin/service postgresql restart
(On older releases of Debian, you may need to run "service postgresql-$PGVERSION restart" instead.)
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
It is recommended that you install the the latest Sun/Oracle JDK.
To do so, on Debian, you will need to enable the "non-free" repository. In most cases, you should be able to edit "/etc/apt/sources.list" and add "non-free" to any of the distribution's entries, next to main.
For example, if your sources.list contains this:
deb http://http.us.debian.org/debian/ squeeze main deb-src http://http.us.debian.org/debian/ squeeze main deb http://security.debian.org/ squeeze/updates main deb-src http://security.debian.org/ squeeze/updates main # squeeze-updates, previously known as 'volatile' deb http://http.us.debian.org/debian/ squeeze-updates main deb-src http://http.us.debian.org/debian/ squeeze-updates main
...you would change it to look like this:
deb http://http.us.debian.org/debian/ squeeze main non-free deb-src http://http.us.debian.org/debian/ squeeze main non-free deb http://security.debian.org/ squeeze/updates main non-free deb-src http://security.debian.org/ squeeze/updates main non-free # squeeze-updates, previously known as 'volatile' deb http://http.us.debian.org/debian/ squeeze-updates main non-free deb-src http://http.us.debian.org/debian/ squeeze-updates main non-free
Then, you should be able to install the "sun-java6-jdk" package with APT (as root):
sudo apt-get update sudo apt-get install sun-java6-jdk
During the installation process, you will need to accept the Java licensing terms (DLJ). Not accepting this agreement will cause the installation process to fail, as OpenNMS needs a Java Environment to run.
Hint
In the latest Debian and Ubuntu releases the Oracle Java package isn't available anymore. There are two ways to install vanilla Java from Oracle in Debian/Ubuntu.
The first one is using a privately maintained repository you can install with
sudo add-apt-repository ppa:ferramroberto/java
and install Oracle Java from there. The other one is the manual way. Download and install the binaries from Oracle. The steps to setup are here or here
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 APT 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 APT 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.
You can do so by running (as root):
sudo apt-get install opennms
You may see an error about IPLIKE. This is normal, it will attempt to install itself into the OpenNMS database, but on a new install the database has not been configured yet. We will re-attempt the install later.
Try It! Install OpenNMS
Install OpenNMS, using the "apt-get install opennms" command (as root):
sudo apt-get -y install opennms
You should see something like this:
Reading package lists... Done Building dependency tree Reading state information... Done The following extra packages will be installed: ... opennms-server opennms-webapp-jetty The following NEW packages will be installed: ... opennms opennms-server opennms-webapp-jetty 0 upgraded, 13 newly installed, 0 to remove and 51 not upgraded. Need to get 146 MB of archives. After this operation, 251 MB of additional disk space will be used. ... Get:13 debian.opennms.org stable/main opennms all 1.8.17-1 [6,874 B] Fetched 146 MB in 2s (55.7 MB/s) Preconfiguring packages ... Selecting previously deselected package iplike-pgsql84. Unpacking iplike-pgsql84 (from .../iplike-pgsql84_2.0.2-1_amd64.deb) ... Selecting previously deselected package opennms-db. Unpacking opennms-db (from .../opennms-db_1.8.17-1_all.deb) ... Selecting previously deselected package opennms-common. Unpacking opennms-common (from .../opennms-common_1.8.17-1_all.deb) ... ...
Post-Install Configuration
Disable APT Updates
Some distributions that use APT 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/apt/sources.list.d/opennms*" file and commenting out each "deb" 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/lib/jvm/java-6-sun:
sudo $OPENNMS_HOME/bin/runjava -S /usr/lib/jvm/java-6-sun/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):
sudo $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!
Java Network unreachable
If you try to install OpenNMS on Debian 6.0 Squeeze you may get a PostgreSQL error Network unreachable. In Debian 6.0 Squeeze Java applications are not allowed to connect to 127.0.0.1. It is only possible to connect to ::1 by default. The bug is described in http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=560044
(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 configure the iplike package from APT for performance reasons.
The appropriate IPLIKE package (eg, iplike-pgsql84, iplike-pgsql90, etc.) for your database should already have installed when you installed the main "opennms" package. All you should need to do is re-run the "install_iplike" shell script (as root):
sudo /usr/sbin/install_iplike.sh
Start OpenNMS and Connect to the Web UI
You can now start OpenNMS using the "service" command (as root).
Try It! Connect to the Web UI
Try starting OpenNMS, and connecting to the web UI.
sudo /usr/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.
