From OpenNMS

Contents 1 Overview 2 APT Repository Based Install 2.1 Choosing an APT Source 2.2 Adding a Repository 2.3 Adding the OpenNMS PGP Key to APT 3 Installing the OpenNMS Packages 3.1 Debian 4.0 (Etch) and Ubuntu 7.10 (Gutsy) or Newer 3.2 Systems Older than Debian 4.0 and Ubuntu 7.10 4 Configuring PostgreSQL for OpenNMS 4.1 System and Daemon Configuration 4.2 Preparing the OpenNMS Database 4.3 Installing IPLIKE 5 Installing OpenNMS 5.1 Setting Java Environment 5.2 Running the OpenNMS Installer 6 Starting OpenNMS 6.1 Discover Your Network 6.2 Get Notifications When Problems Occur

Overview

These instructions cover installation of OpenNMS and its requisites on Debian and Debian derived systems like Ubuntu.

While it is possible to obtain and install the OpenNMS packages without the help of this document, following some of the guidelines within may simplify the process and provide some assistance on what to do post-installation.

APT Repository Based Install

Debian-based distributions make use of the Advanced Package Manager, also known as APT, to manage the retrieval, configuration, and installation of software packages. While it is possible to just install the .deb packages and have the system still resolve many of the dependencies of the OpenNMS system, it is recommended to permanently add the OpenNMS repositories to your list of software sources to best resolve dependencies and allow for an easier upgrade options in the future.

Choosing an APT Source

Users of Debian-based systems can choose to install either the stable or unstable builds of OpenNMS.

The stable build is the latest officially released stable version of OpenNMS. If you are putting OpenNMS into a production environment for daily use, this is the recommended version install.

The unstable build is the latest officially released development version of OpenNMS. This may have more features than the stable version, but it may also contain bugs that have yet to be discovered or triaged.

Adding a Repository

To setup the OpenNMS stable repository on your system, you'll need to create a file called opennms.list within the /etc/apt/sources.list.d directory of your system with the following contents:

deb http://debian.opennms.org stable main
deb-src http://debian.opennms.org stable main

Likewise, if you've chosen to use the unstable branch of OpenNMS, you'll need enter the following information into opennms.list:

deb http://debian.opennms.org unstable main
deb-src http://debian.opennms.org unstable main

Adding the OpenNMS PGP Key to APT

Packages within the APT system are cryptographically signed to ensure their integrity. This step ensures the intregreity 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 -

Now that the keys and repositories are added, you can refresh your system package inventory as such:

sudo apt-get update

Installing the OpenNMS Packages

Debian 4.0 (Etch) and Ubuntu 7.10 (Gutsy) or Newer

OpenNMS and its dependencies can be installed on Etch and Gutsy with apt-get install opennms.

If any of the dependencies require configuration, you will be asked to provide configuration data for them. On an Ubuntu 10.04 system, you may need to be prepared to setup the Postfix MTA as well as other dependencies. OpenNMS will run and send mail when the application is configured to do so with any of the configured mail options, but if you wish for the system to send mail outside of the scope of OpenNMS, you may need to put thought into this configuration.

During the installation process, you will also need to accept the Sun Java licensing terms (DLJ). Not accepting this agreement will cause the installation process to fail, as OpenNMS needs a Java Environment to run.

If PostgreSQL was not pre-installed, and installed as a dependency of OpenNMS during the apt-get install operation, you may see a notice that IPLIKE installation failed. Installing IPLIKE successfully will be covered later in this document.

Systems Older than Debian 4.0 and Ubuntu 7.10

Installing OpenNMS on systems older than Etch and Gutsy requires additional steps to procure and install a suitable JDK for operation that must be completed prior to running the apt-get install opennms command. If you are comfortable doing this, there shouldn't be any reason you can't install and use OpenNMS, however you may find it easier to use a distribution that includes a working JDK.

Configuring PostgreSQL for OpenNMS

System and Daemon Configuration

By default, OpenNMS needs to be able to connect to a PostgreSQL server as the postgres user over a TCP/IP connection during the installation process. It is easier to run the installer in a configuration where the postgres user is not required to have password credentials, but it is certainly not required, and not encouraged on systems with multiple users.

To allow the postgres user to authenticate without a password, you first must change options in the pg_hba.conf file. On many systems, this will be located in /etc/postgresql/VERSIONNUMBER/main, where VERSIONNUMBER is your version of the PostgreSQL database.

The default pg_hba.conf file should have some configuration values near the bottom of the file that are similar those below:

# TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD

# "local" is for Unix domain socket connections only
local   all         all                               ident
# IPv4 local connections:
host    all         all         127.0.0.1/32          md5
# IPv6 local connections:
host    all         all         ::1/128               md5

To enable a password-less login, you will need to change those lines to reflect the following:

# TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD

# "local" is for Unix domain socket connections only
local   all         all                               trust
# IPv4 local connections:
host    all         all         127.0.0.1/32          trust
# IPv6 local connections:
host    all         all         ::1/128               trust

The pg_hba.conf file only controls the authentication methods during a connection and not the actual network configuration. The PostgreSQL listener defaults to localhost in the postgresql.conf file. If you get errors that you can't connect to your PostgreSQL database, you may need to set or uncomment the listen_addresses directive in this file to reflect 'localhost'. The postgresql.conf file should be located in the same directory as your pg_hba.conf file should you need to make this change.

Additionally you will want to be certain that that the max number of of simultaneous connections is configured to be greater than c3p0.maxPoolSize in $OPENNMS_HOME/etc/c3p0.properties (50 by default) +10.

max_connections = 60

When you're certain that all your PostgreSQL configuration changes have been made, you will need to restart the daemon to apply the changes.

First, find the name of the PostgreSQL service:

user@ubuntu-server:~$ service --status-all |grep postgres

The result on a Ubuntu 10.04 server shows the service name as postgresql-8.4.

Then, restart the PostgreSQL listener using the name of the service:

user@ubuntu-server:~$ sudo service postgresql-8.4 restart

Preparing the OpenNMS Database

The next step is to create the OpenNMS database:

user@ubuntu-server:~$ sudo -u postgres createdb -U postgres -E UNICODE opennms

At this point, you can check the network listener and authentication changes, as well as whether or not your DB creation worked properly:

user@ubuntu-server:~$ psql -U postgres --host=localhost opennms

If you are presented with a prompt that looks like opennms=#, you can type \q and quit the psql shell as your tests were successful. If this was not successful, you will need to review your PostgreSQL configuration.

Installing IPLIKE

IPLIKE is a PostgreSQL stored procedure for quickly processing expressions which describe IP addresses or address space.

To install IPLIKE, run:

user@ubuntu-server:~$ sudo install_iplike.sh

Installing OpenNMS

Setting Java Environment

OpenNMS will need to know which JDK to use. Run:

user@ubuntu-server:~$ sudo /usr/share/opennms/bin/runjava -s

To have OpenNMS detect and use the best JRE for the application. If you wish to specify a JRE you can run:

user@ubuntu-server:~$ sudo /usr/share/opennms/bin/runjava  -S /usr/java/jdk1.5.0_12/bin/java

Running the OpenNMS Installer

Next, you need to run the OpenNMS installer, which will initialize the OpenNMS database, and do some other basic setup. Upon upgrade, you should run this command again to make sure your database schema and other things required at startup are up-to-date.

To run the installer:

user@ubuntu-server:~$ sudo /usr/share/opennms/bin/install -dis

A set of migrations will be 'played' into the database which will prepare it for use. This can take some time depending on your machine configuration.

Starting OpenNMS

Now that OpenNMS is installed and configured, you can start the daemons and access your application. To start the service:

user@ubuntu-server:~$ sudo service opennms start

To access OpenNMS, open your web browser and connect to http://yourhost:8980/opennms/, where yourhost is the name or IP of the system where you just installed OpenNMS. The default username and password are the same, so when presented with a login window, type admin in the user box, and admin in the password box, then click the Login button.

Discover Your Network

First, OpenNMS needs to know which devices (or, "nodes") you want it to discover. To discover nodes, OpenNMS does a ping sweep on IP address ranges that you configure it to discover. If an IP address that OpenNMS is not already managing responds to a discovery ping, then OpenNMS will begin scanning that IP address for services, create a new node in its database, and begin monitoring the node's interfaces and services. A new install of OpenNMS will not perform any discovery until you add one or more address ranges to the discovery configuration. You do this by logging into the web UI as the admin user and navigating to the Admin menu and then clicking on 'Configure Discovery' under the Operations section.

In the Include Ranges section of the Home / Admin / Discovery / Modify Configuration page, click on the 'Add New' button. In the window that pops up, enter the beginning and ending IP addresses for the range that you wish to include for discovery. The default values for Retries and Timeout are usually appropriate. Click the 'Add' button, and the popup window will close and the new range will show up in the Include Ranges section. Click the 'Save and Restart Discovery' button to apply your changes. Discovery of the newly added range will begin within a few seconds; the ping requests and service scans are spread out over time to avoid flooding your network, so it will take some time for all nodes in your newly added range to be scanned and discovered.

For more detailed information on discovery configuration, including how to add IP addresses manually to the discovery configuration file, see Discovery.

Get Notifications When Problems Occur

To get started, we need to configure the main admin user to have a valid e-mail address.

1. Log in as admin to the web UI
2. Go to Admin in the menu bar
3. Under the Operations section, set the Notification Status radio button to On and click the Update button
4. Under the OpenNMS System section, go to Configure Users, Groups and Roles and then Configure Users
5. click the icon under "Modify" for the admin user
6. set the Email address, and click the Finish button

This should get OpenNMS configured to send the default notifications to the administrator e-mail address.

Notifications are extremely flexible and can be configured to do complex escalations, scheduled outages, and user management. Detailed instructions are available in the Notification Configuration How-To.