<preface>
<title>Preface</title><para>
OpenNMS is the creation of numerous people and organizations,
operating under the umbrella of the OpenNMS project. The original code
base was developed and published under the GPL by the Oculan Corporation
until 2002, when the project administration was passed on to Tarus
Balog.
</para><para>
The current corporate sponsor of OpenNMS is
<ulink>The OpenNMS Group</ulink>,
which also owns the OpenNMS trademark.
</para><para>
OpenNMS is a derivative work, containing both original code,
included code and modified code that was published under the GNU General
Public License. Please see the source for detailed copyright notices,
but some notable copyright owners are listed below:
</para><itemizedlist>
<listitem>
<para>
<trademark>Copyright </trademark> 2002-2009
<ulink>The OpenNMS Group, Inc.</ulink>
</para>
</listitem><listitem>
<para>
Original code base for OpenNMS version 1.0.0
<trademark>Copyright </trademark> 1999-2001
<ulink>Oculan Corporation</ulink>.
</para>
</listitem><listitem>
<para>
Mapping code <trademark>Copyright </trademark> 2003
<ulink>Networked Knowledge Systems, Inc.</ulink>
</para>
</listitem><listitem>
<para>
ScriptD code <trademark>Copyright </trademark> 2003
<ulink>Tavve Software Company</ulink>.
</para>
</listitem>
</itemizedlist><para>
Please send any omissions or corrections to this document
to <ulink>Tarus Balog</ulink>.
</para>
</preface><chapter>
<title>Overview</title><section>
<title>About OpenNMS</title><para>
OpenNMS is the world's first enterprise-grade network management
system developed under the open source model. As with any complex and
powerful system, getting it installed and configured can take a
little effort. It is the purpose of this document to explain what is
required to get OpenNMS installed.
</para>
</section><section>
<title>How to Use This Document</title><para>So, how should you use this document? It is arranged in the
following sections:</para><itemizedlist>
<listitem>
<para>This overview</para>
</listitem><listitem>
<para>
The programs on which OpenNMS depends, and how they need to
be modified
</para>
</listitem><listitem>
<para>
Installation and upgrade instructions, including details for
specific operating systems and distributions
</para>
</listitem><listitem>
<para>
Getting started with OpenNMS, including initial configuration
and logging into the web interface
</para>
</listitem><listitem>
<para>Building OpenNMS from source</para>
</listitem><listitem>
<para>Troubleshooting and Where to Get Help</para>
</listitem>
</itemizedlist><para>
This installation guide relies strongly on the idea of "packages."
Most modern operating systems and distributions have a system where
software can be installed and managed through the use of packages
that group the files belonging to a given application together (as well as
managing changes to those files, removal, upgrades, etc.).
</para><para>
Please see the latest
<ulink>release notes</ulink>
to see if your operating system is supported. Currently, OpenNMS runs
on many Linux distributions, Solaris, Mac OS X and Windows.
</para><para>
This guide assumes that if you use packages, you do so consistently.
This is because OpenNMS will attempt to determine if the software it
requires is installed by using the operating system's built in
package management system. If you've installed, say, Java, but not via packages,
OpenNMS will be unable to determine that Java is installed and it
will fail.
</para><para>
To get back to the original question of "how should you use this
document," first go through the second section to insure that you have all
of the prerequisite applications properly installed and configured. Use
the third section to help get those packages installed for your
particular operating system, as well as the OpenNMS software. Finally, use
the last section to help correct any errors your might encounter.
</para>
</section><section>
<title>Minimum Requirements</title><para>
While it is impossible to exactly size OpenNMS for a particular environment,
the following represents the minimum requirements for installation, assuming a
network of about 200 devices. Note that OpenNMS can monitor more than 100 times
that given the proper hardware.
</para><glosslist>
<glossentry>
<glossterm>Processor</glossterm><glossdef>
<para>A 1 GHz Pentium III (or equivalent processor) or better.
OpenNMS can also take advantage of multiple processors.</para>
</glossdef>
</glossentry><glossentry>
<glossterm>Memory</glossterm><glossdef>
<para>
A minimum of 256 MB of RAM, although 512 MB is strongly
recommended. The OpenNMS Java Virtual Machine benefits from large
amounts of memory, up to 2 GB, and more if using a 64-bit processor.
</para><para>
Given a budget choice between more RAM and a faster CPU, choose
more RAM.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm>Disk Space</glossterm><glossdef>
<para>
OpenNMS requires about 200 MB of disk space for the program
files. In addition, each data variable collected requires, by
default, a little under 300 KB of disk space. It is safe to assume
that each interface being managed will require around 2 MB of disk
space, so for 200 interfaces you are looking at 400 MB (conservatively).
Depending on the number of events stored, you can assume 100 MB to
200 MB are required for the database. Finally, the OpenNMS logs
can grow quite large, especially in debug mode.
</para><para>
Edit the <filename>log4j.properties</filename> file in the OpenNMS
configuration directory (usually <filename>/opt/opennms/etc</filename>
or <filename>/etc/opennms</filename>) to change those settings. By
default, the Log4J file rotation is configured to use 100MB per log
file, which ends up using a little under 2 GB.
</para><para>
<emphasis>Note</emphasis>: Due to the write-heavy nature of
time-series data and the database, it is recommended that you do not use
RAID-5 with OpenNMS. RAID-1 or RAID-1+0 is recommended if using RAID.
In addition, LVM adds a small but appreciable amount of overhead and it
is recommended that you do not use it.
</para>
</glossdef>
</glossentry>
</glosslist>
</section>
</chapter><chapter>
<title>Preparing for install</title><section>
<title>Before You Begin</title><section>
<title>Configure RPM-based Distributions with Yum</title><para>
Before you begin installing, you will want to set up Yum to install from
the OpenNMS repositories. This covers most RPM-based distributions, including
<ulink>Red Hat Enterprise Linux</ulink>,
<ulink>Fedora</ulink>, and
<ulink>CentOS</ulink>.
</para><section>
<title>Preparation: Yum Fastest Mirror Plugin</title><para>
Before you start, you may want to install the yum-fastestmirror RPM if your distro
supports it. This can often speed up downloads of large packages. See the
<ulink>CentOS Wiki</ulink>
for more details. This step is not strictly necessary, but can make your overall
yum experience better.
</para><para>
<programlisting>[user@localhost]$ sudo yum install yum-fastestmirror
Setting up Install Process
...
Running Transaction
Installing: yum-fastestmirror ######################### [1/1]
Installed: yum-fastestmirror.noarch 0:1.1.9-2.fc8
Complete!</programlisting>
</para>
</section><section>
<title>Preparation: Determine Which Release to Install</title><para>There are 4 types of releases available through yum.</para><itemizedlist>
<listitem>
<para>
<emphasis>stable:</emphasis>
the latest officially released stable version of OpenNMS
</para>
</listitem><listitem>
<para>
<emphasis>unstable:</emphasis>
the latest officially released development version of OpenNMS
</para>
</listitem><listitem>
<para>
<emphasis>testing:</emphasis>
a nightly build of the code that will be part of the next stable version of OpenNMS
</para>
</listitem><listitem>
<para>
<emphasis>snapshot:</emphasis>
a nightly build of the very latest development version of OpenNMS
</para>
</listitem>
</itemizedlist>
</section><section>
<title>Install the OpenNMS Repository RPM</title><para>
To simplify installation through Yum, we've created an RPM that contains the configuration
necessary for Yum to be able to find the other OpenNMS packages. Based on the release you
chose in the section above, choose the approprate RPM from the <ulink>OpenNMS Yum Repository</ulink>.
</para><para>
For example, to install the latest snapshot release on Fedora 7, you would run:
<programlisting>rpm -Uvh http://yum.opennms.org/repofiles/opennms-repo-snapshot-fc7.noarch.rpm</programlisting>
</para><para>
Or, to install the latest unstable release on CentOS or RHEL 5, you would run:
<programlisting>rpm -Uvh http://yum.opennms.org/repofiles/opennms-repo-unstable-rhel5.noarch.rpm</programlisting>
</para><para>
Now you should see OpenNMS packages available when you get a list of yum packages:
<programlisting> [user@localhost]$ sudo yum list opennms
...
Available Packages
opennms.noarch 1.5.96-1 opennms-unstable</programlisting>
</para><note>
<para>
If you are using older yum-based distributions (like CentOS 3, for example), you may
need to append the yum configuration to <filename>/etc/yum.conf</filename>. Older
versions of yum don't recognize <filename>/etc/yum.repos.d/</filename> as a valid
location for yum configuration. You can fix this by using <filename>cat</filename>
to append the repository configurations to <filename>/etc/yum.conf</filename>:
<programlisting>[root@localhost]# cat /etc/yum.repos.d/* >> /etc/yum.conf</programlisting>
</para>
</note>
</section>
</section><section>
<title>Configure RPM-based Distributions with URPMI (Mandriva)</title><section>
<title>Enable the Primary Mandriva Repositories</title><para>
First, you'll want to enable the primary Mandriva URPMI repositories. The
easiest way to do so is to follow the instructions at <ulink>EasyURPMI</ulink>. For example, on Mandriva
Linux 2007, you would end up running something like this:
<programlisting>urpmi.addmedia main ftp://mirrors.usc.edu/pub/linux/distributions/mandrakelinux/official/2007.1/i586/media/main/release with media_info/hdlist.cz
urpmi.addmedia --update main_updates ftp://mirrors.usc.edu/pub/linux/distributions/mandrakelinux/official/2007.1/i586/media/main/updates with media_info/hdlist.cz</programlisting>
</para>
</section><section>
<title>Enable the OpenNMS Mandriva Repositories</title><para>
Now, you'll need to enable the OpenNMS Mandriva repositories. First, add
the OpenNMS stable repository (replace mandriva2007 with your release):
<programlisting>urpmi.addmedia --probe-hdlist opennms-stable http://yum.opennms.org/stable/mandriva2007</programlisting>
</para><para>
If you want OpenNMS stable snapshots, add the testing repository next
(replace mandriva2007 with your release):
<programlisting>urpmi.addmedia --probe-hdlist opennms-testing http://yum.opennms.org/testing/mandriva2007</programlisting>
</para><para>
If you want the latest unstable version, add the unstable as well
(replace mandriva2007 with your release):
<programlisting>urpmi.addmedia --probe-hdlist opennms-unstable http://yum.opennms.org/unstable/mandriva2007</programlisting>
</para><para>
And if you want to install nightly snapshots, then add the snapshot one
(replace mandriva2007 with your release):
<programlisting>urpmi.addmedia --probe-hdlist opennms-snapshot http://yum.opennms.org/snapshot/mandriva2007</programlisting>
</para>
</section>
</section><section>
<title>Configure Debian-Based Distributions</title><section>
<title>Add the OpenNMS Repository to Your <filename>sources.list</filename></title><para>
First, you need to tell apt-get how to find OpenNMS. Add the following
contents to your <filename>/etc/apt/sources.lists</filename> file:
<programlisting>deb http://debian.opennms.org stable main
deb-src http://debian.opennms.org stable main</programlisting>
</para><para>
If you wish to use the latest development version of OpenNMS, add
unstable instead:
<programlisting>deb http://debian.opennms.org unstable main
deb-src http://debian.opennms.org unstable main</programlisting>
</para>
</section><section>
<title>Add the OpenNMS PGP Key to APT</title><para>
The OpenNMS Debian repository is signed with a PGP key (fingerprint
<code>22EE DDA6 8698 B02F B2EC 50B7 062B 8A68 4C4C BBD9</code>).
You will need to tell APT about the key:
<programlisting>wget -O - http://debian.opennms.org/OPENNMS-GPG-KEY | sudo apt-key add -</programlisting>
</para>
</section>
</section>
</section><section>
<title>Prerequisite Package: Java</title><para>
OpenNMS is written mainly in Java, although there are a few JNI
calls to some C code in order to implement things such as ICMP. and so it
follows that Java would need to be installed.
</para><para>
OpenNMS requires Java SE 5.0 or higher (JDK 1.5). It is recommended that the
JDK from Sun is used with OpenNMS. If OpenNMS is to be run on a 64-bit system,
be sure to install the 64-bit JDK.
</para><section>
<title>Installing Java on RPM-based Distributions Using Yum</title><para>
The Sun JDK is available in our Yum repository. If you have configured Yum
as specified above, you just need to run:
<programlisting>yum install jdk</programlisting>
</para><para>
Because of a bug in the 64-bit RPM signing, if you are on x86_64, you will
need to disable GPG checking. You can do so with the <code>--nogpgcheck</code>
option to yum:
<programlisting>yum --nogpgcheck install jdk</programlisting>
</para>
</section><section>
<title>Installing Java on RPM-based Distributions Using URPMI</title><para>
The Sun JDK is available in our URPMI repository. If you have configured
URPMI as specified above, you just need to run:
<programlisting>urpmi --auto jdk</programlisting>
</para>
</section><section>
<title>Installing Java on Debian or Ubuntu</title><para>Sun's Java can now be installed using "apt" on Debian Etch or higher.</para><para>
<programlisting>apt-get install sun-java5-jdk</programlisting>
</para><para>
This should also work on Ubuntu 6.10 (Edgy Eft) or higher. Alternatively,
you could install sun-java6-jdk, which has performance improvements over
the java5 version.
</para>
</section><section>
<title>Installing Java on Other Platforms</title><note>
<para>
It is important to install the JDK instead of the JRE, as the web UI
will need to compile JSPs into Java code.
</para>
</note><para>
You will need to use Sun's Java SE, version 5 (1.5) or later. You can
<ulink>download
it</ulink> from Sun's <ulink>Java</ulink>
website. Step through the licensing process and then download the
proper version of Java for your operating system.
</para>
</section>
</section><section>
<title>Prerequisite Package: PostgreSQL</title><para>
<ulink>PostgreSQL</ulink>
(or "Postgres") is a relational database that OpenNMS uses to store
information about devices on the network, as well as information about
events, notifications and outages.
</para><para>
When installing OpenNMS, two things must happen. First, OpenNMS has
to be able to contact the database over TCP/IP (even on localhost) and
second, the installation process must be able to create the
database.
</para><para>OpenNMS requires version 7.4 or later of PostgreSQL,
although 8.1 or higher is recommended for performance reasons.</para><section>
<title>Installing PostgreSQL on RPM-Based Distributions Using Yum</title><para>
On modern versions of Red Hat Enterprise Linux, CentOS, and Fedora,
you should just need to install the <filename>postgresql-server</filename>
RPM:
<programlisting>[user@localhost]$ sudo yum -y install postgresql-server
Setting up Install Process
...
Running Transaction
Installing: postgresql-server ######################### [1/1]
Installed: postgresql-server.x86_64 0:8.2.5-1.fc8
Complete!</programlisting>
</para><note>
<para>
Red Hat Enterprise Linux 3 and CentOS 3 call their PostgreSQL
packages "rhdb" for the "Red Hat DataBase" so if you are on one of
these older distributions, you will have to substitute "rhdb" for
"postgresql" when installing:
<programlisting>sudo yum -y install rhdb-server</programlisting>
</para>
</note>
</section><section>
<title>Installing PostgreSQL on RPM-Based Distributions Using URPMI</title><para>
On Mandriva, you use URPMI to install the PostgreSQL server:
<programlisting>sudo urpmi --auto postgresql-server</programlisting>
</para>
</section><section>
<title>Installing PostgreSQL on Debian-Based Distributions</title><para>
On Debian or Ubuntu, use apt to install the PostgreSQL server:
<programlisting>sudo apt-get update
sudo apt-get install postgresql-8.1</programlisting>
</para>
</section><section>
<title>Installing PostgreSQL on Windows</title><para>
On Windows, all you should need to do is get the latest Windows installer
from <ulink>PostgreSQL.org</ulink>.
</para><note>
<para>
If you are running on a FAT32 filesystem, see the <ulink>detailed
installation instructions on the wiki</ulink>.
</para>
</note><para>
First, unpack the installer. The installer does not run properly from
inside a zipped folder, so you will need to extract the ZIP file. You
should be able to just copy the postgresql-X.X.msi and
postgresql-X.X-int.msi files to your desktop and run them from there.
</para><para>
Then, run the postgresql-X.X.msi and follow the instructions. For the most
part, the defaults should be just fine, although if you're allowing the
installer to initialize your database, make sure the encoding is set
to "UTF-8".
</para>
</section><section>
<title>Configure PostgreSQL</title><para>
Once you have installed PostgreSQL, you will need to make two changes
to Postgres configuration files:
<filename>postgresql.conf</filename> and <filename>pg_hba.conf</filename>.
</para><para>
These files are only created once PostgreSQL has been started, so if
your installation method for Postgres did not start the database, do
so before continuing. Usually, startup scripts will be placed in
<filename>/etc/init.d</filename>.
</para><para>Locate the Postgres "data" directory. Often this is <filename>/var/lib/pgsql/data</filename>.
You should then find the two files we need to modify in that directory.</para><section>
<title>The <filename>postgresql.conf</filename> File</title><para>
This file controls some basic parameters of PostgreSQL. We need to
change three of these parameters.
</para><orderedlist>
<listitem>
<para>
First we need to make sure PostgreSQL is listening on an IP socket, and not
just a local unix socket.
</para><para>
For PostgreSQL 7.4 and 8.0, make sure the following
line is set and uncommented:
<programlisting>tcpip_socket = true</programlisting>
</para><para>
On PostgreSQL 8.1 and up, use this instead:
<programlisting>listen_addresses = 'localhost'</programlisting>
</para>
</listitem><listitem>
<para>
Next, find the line in the file that contains
<varname>max_connections</varname>. It needs to be at least:
</para><para>
<programlisting>max_connections = 256</programlisting>
</para>
</listitem><listitem>
<para>
Find the line that contains <varname>shared_buffers</varname>.
It needs to be at least:
<programlisting>shared_buffers = 1024</programlisting>
</para>
</listitem>
</orderedlist>
</section><section>
<title>Customizing the <filename>pg_hba.conf</filename> File</title><para>
The <filename>pg_hba.conf</filename> file controls which machines
and users can access the database on a given machine via TCP/IP.
</para><para>
Since that is how OpenNMS accesses the database (via <code>localhost</code>)
it is necessary to modify this file to allow OpenNMS to work. The easiest
thing to do is to just allow anyone from the localhost to access the database
(do not add the last line if your system does not support IPv6):
</para><para>
<programlisting># TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
local all all trust
host all all 127.0.0.1 255.255.255.255 trust
host all all ::1 ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff trust</programlisting>
</para><para>
Make sure that no other lines are uncommented in this file.
</para><para>
You will need to stop and restart Postgres after making these changes.
</para>
</section><section>
<title>Creating the PostgreSQL Database</title><para>
Most distributions will automatically initialize the default database
on first startup, but if yours doesn't (for example, on Solaris), you
will need to do so manually.
</para><para>
As the <code>postgres</code> user, go to the
<filename>/usr/local/pgsql/bin</filename> directory (or wherever your PostgreSQL
binaries are installed), and run:
<programlisting>./initdb -D /usr/local/pgsql/data -E "UNICODE"</programlisting>
</para><para>
Then you'll need to start the database:
<programlisting>./pg_ctl -D /usr/local/pgsql/data start</programlisting>
</para>
</section><section>
<title>Adding the iplike function</title><para>
OpenNMS makes heavy use of a stored procedure called "iplike". Since it is
written in C, it has been removed from the main OpenNMS code and placed
in its own project.
</para><para>
If a C-based iplike is not installed, the OpenNMS installer will
add a version written in the PostgreSQL command language. It will work,
but not as quickly as the compiled iplike will.
</para><para>
To install iplike, simply download the proper package for your
distribution. There should be a package for PostgreSQL versions 7.4-8.1,
and one for 8.2+. In addition, there will be separate 32-bit and 64-bit
versions. It is also possible to download a tarball from the <ulink>OpenNMS
SourceForge project page</ulink>, and do the usual "./configure", "make", and "make
install". Once installed it should not be required to update it on every
OpenNMS upgrade.
</para>
</section>
</section>
</section><section>
<title>Prerequisite Package: JICMP</title><para>
Java has never had a really good API for ICMP. Since ICMP is the basis for
the "ping" command, it is rather imperative that any Java-based network
management platform address the need for ICMP. OpenNMS does this by using
some code written in C, and accessing it using the Java Native Interface
(JNI).
</para><para>
As of OpenNMS 1.3.6, the ICMP code has been moved to it's own library
outside of OpenNMS. This makes the main OpenNMS application pure Java, and
as such it only has to be built once, instead of for each platform.
</para><para>
Packages for JICMP are available for most distributions. If your
distribution does not have packages available, you can download the
source from <ulink>the
SourceForge download page for JICMP</ulink>.
</para><section>
<title>Installing JICMP on RPM-Based Distributions Using Yum</title><para>
On most RPM-Based Distributions, all you should need to run is:
<programlisting>yum install jicmp</programlisting>
</para>
</section><section>
<title>Installing JICMP on RPM-Based Distributions Using URPMI</title><para>
On Mandriva, you can install JICMP with the command:
<programlisting>urpmi --auto jicmp</programlisting>
</para>
</section><section>
<title>Installing JICMP on RPM-Based Distributions from Source</title><para>
If JICMP has not already been compiled on your RPM-based platform, you
can build a native RPM from the <ulink>source
tarball</ulink> like so:
<programlisting>rpmbuild -tb <filename>jicmp-X.X.X.tar.gz</filename></programlisting>
</para><para>
If you are on a 64-bit platform, you can build a 64-bit RPM instead
like so:
<programlisting>rpmbuild --target=x86_64 <filename>jicmp-X.X.X.tar.gz</filename></programlisting>
</para>
</section><section>
<title>Installing JICMP on Debian-Based Distributions</title><para>
On Debian or Ubuntu, you can install JICMP through apt:
<programlisting>sudo apt-get install libicmp-jni</programlisting>
</para>
</section><section>
<title>Installing JICMP from Source</title><para>
To build from source, download the <ulink>latest
source tarball from SourceForge</ulink>, unpack it, and run the usual:
<programlisting>./configure
make
make install</programlisting>
</para>
</section>
</section>
</chapter><chapter>
<title>Installing OpenNMS</title><note>
<para>
You need to be root when running most of the commands in this chapter.
</para>
</note><section>
<title>Where to Find OpenNMS Data</title><para>OpenNMS stores data in a number of locations:</para><glosslist>
<glossentry>
<glossterm>
<filename>$OPENNMS_HOME/etc/</filename>
</glossterm><glossdef>
<para>OpenNMS configuration files.</para><para>
On some distributions, upstream changes in files in this directory
are detected and means are provided for migrating those changes to
the new release.
</para><para>
On RPM-based distributions, if an OpenNMS configuration file has changed,
RPM will create a "<filename>.rpmnew</filename>" file which contains the
version of that configuration file that shipped with the new version of
OpenNMS. You will need to look at the changes between your file
and the new one and merge them manually, at the moment. The command
"<code>diff -u <old file> <new file> | less</code>" can
assist you in seeing what has changed.
</para><para>
On Debian-based distributions, dpkg will automatically prompt you when
a configuration file has changed upstream between versions, and will offer
you a set of options to deal with it.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm><filename>$OPENNMS_HOME/share/rrd/</filename></glossterm><glossdef>
<para>
RRD data files that store response time data and performance data collected
from SNMP (and elsewhere). The installer should not touch the RRD files in
<filename>$OPENNMS_HOME/share/rrd</filename>. Unless you are migrating from
RRDTool to jRobin, you should not have to worry about them.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm>
<filename>$OPENNMS_HOME/webapps/opennms/</filename> and
<filename>$OPENNMS_HOME/jetty-webapps/opennms/</filename>
</glossterm><glossdef>
<para>
The OpenNMS web application. While data is not stored here, some users may
customize the web interface and these customizations should be saved before
upgrading OpenNMS.
</para>
</glossdef>
</glossentry><glossentry>
<glossterm><filename>$PGDATA/</filename></glossterm><glossdef>
<para>
Data about nodes, services, events, notifications, etc., are stored in the
<code>opennms</code> table in PostgreSQL.
</para>
</glossdef>
</glossentry>
</glosslist>
</section><section>
<title>Performing a Fresh Install</title><para>
Follow the instructions in this section appropriate for your operating
system if you are performing a fresh install. If you are upgrading an
existing installation of OpenNMS, see the next section.
</para><section>
<title>Installing on RPM-Based Distributions</title><section>
<title>Determine What to Install</title><para>
As of version 1.6, OpenNMS is packaged in a modular fashion. The
following packages are available for installation:
</para><itemizedlist>
<listitem>
<para>
<emphasis>opennms-core</emphasis>: The core OpenNMS code,
responsible for network discovery, polling, data collection,
notification, and more.
</para>
</listitem><listitem>
<para>
<emphasis>opennms-docs</emphasis>: Documentation.
</para>
</listitem><listitem>
<para>
<emphasis>opennms-webapp-jetty</emphasis>: The OpenNMS web
UI, designed to be started by the opennms-core engine.
</para>
</listitem><listitem>
<para>
<emphasis>opennms-webapp-standalone</emphasis>: The OpenNMS
web UI, designed to be run in Tomcat or another suitable
servlet container.
</para>
</listitem><listitem>
<para>
<emphasis>opennms</emphasis>: A convenience package which
installs everything you need for a functional OpenNMS
installation on a single system.
</para>
</listitem><listitem>
<para>
<emphasis>opennms-remote-poller</emphasis>: The standalone
remote poller, which can report back to an OpenNMS instance.
</para>
</listitem><listitem>
<para>
<emphasis>opennms-plugin-ticketer-centric</emphasis>: The
<ulink>CentricCRM/Concursive</ulink>
ticketer plugin.
</para>
</listitem>
</itemizedlist>
</section><section>
<title>Installing on RPM-Based Distributions Using Yum</title><para>
As long as Yum is configured to point at the OpenNMS repository,
all you should need to run is:
<programlisting>sudo yum install <varname>[packages]</varname></programlisting>
...where <varname>[packages]</varname> is the list of packages above
that you wish to install.
</para>
</section><section>
<title>Installing on RPM-Based Distributions Using URPMI</title><para>
If URPMI is configured to point at the OpenNMS repository, you can install
by running:
<programlisting>sudo urpmi --auto <varname>[packages]</varname></programlisting>
...where <varname>[packages]</varname> is the list of packages above
that you wish to install.
</para>
</section><section>
<title>Installing on RPM-Based Distributions Manually</title><para>
Download the packages you wish to install from the <ulink>SourceForge
download page for OpenNMS</ulink>.
</para><para>
Then, use <code>rpm -i</code> to install the packages:
<programlisting>rpm -ivh opennms*.rpm</programlisting>
</para><note>
<para>
As of OpenNMS 1.3.10, you can use the <code>--relocate</code> flag to RPM
if you wish to put the logs and collection data in an alternate location:
<programlisting>rpm -ivh --relocate /var/opennms=/mnt/netapp/opennms-data /var/log/opennms=/mnt/netapp/opennms-logs opennms*.rpm</programlisting>
</para>
</note>
</section>
</section><section>
<title>Installing on Solaris</title><para>
Download the appropriate package for your Solaris version from the <ulink>SourceForge
download page for OpenNMS</ulink>.
</para><para>
Then, install the package using <code>pkgadd</code>:
<programlisting><computeroutput># </computeroutput><command>cd /usr/local</command><computeroutput># </computeroutput><command>gzip -d opennms-*-local.gz</command><computeroutput># </computeroutput><command>pkgadd -d `pwd`/opennms-*-local</command></programlisting>
</para>
</section><section>
<title>Installing on Mac OS X</title><para>
OpenNMS is supported on Mac OS X via the <ulink>Fink</ulink> project.
</para><para>
Once you've installed Fink, you should be able to install OpenNMS by running:
<programlisting>fink install opennms</programlisting>
</para>
</section><section>
<title>Installing on Windows</title><para>
OpenNMS is supported on Windows as well, although the lack
of true package management makes it a bit more work to maintain.
</para><para>
To install on Windows, download the latest
<filename>standalone-opennms-installer-X.X.X.jar</filename>
file from <ulink>the
OpenNMS SourceForge download page</ulink>.
</para><para>
You should be able to then just double-click the jar file in
Explorer, and follow the instructions in the install wizard.
</para><para>
Once you're done, you may want to make a pristine copy of the
<filename><varname>$OPENNMS_HOME</varname>/etc</filename> directory
so it's easy to tell what's changed in later releases later.
</para>
</section>
</section><section>
<title>Upgrading an Existing Installation</title><section>
<title>Upgrading: Preparation</title><para>
There are a number of things you can do that can help ease the transition
when doing upgrades.
</para><section>
<title>Prune Unneeded Events</title><para>
Should you not be doing this already, either using vacuumd or
cron, prune away any unneeded events. The events table will most
probably be the largest, and there's no point backing up data that
you don't need.
</para><para>
For example, to delete any events older than 6 weeks that have no
associated outages, you can run, from the <filename>psql</filename>
command-line:
<programlisting>--# this deletes any events that are not associated with outages
DELETE FROM events WHERE NOT EXISTS
(SELECT svclosteventid FROM outages WHERE svclosteventid = events.eventid
UNION
SELECT svcregainedeventid FROM outages WHERE svcregainedeventid = events.eventid
UNION
SELECT eventid FROM notifications WHERE eventid = events.eventid)
AND eventtime < now() - interval '6 weeks';</programlisting>
</para>
</section><section>
<title>Back Up Your Database</title><para>
Depending on the version you are upgrading <emphasis>from</emphasis> and the
version you are upgrading <emphasis>to</emphasis>, you may run into issues with
the database upgrade. It is <emphasis>strongly recommended</emphasis> that
you back up the database.
<programlisting>pg_dump -U postgres -Fc -C -f opennms-database-backup.pg opennms</programlisting>
</para>
</section><section>
<title>Back Up Your OpenNMS <filename>etc</filename> Directory</title><para>
Back up your <filename>$OPENNMS_HOME/etc</filename> directory before doing any
upgrades, so you can go back to your previous version if something goes wrong, and
so you have a reference of your previous configuration when adapting config file
changes to the new version.
<programlisting>tar -C $OPENNMS_HOME -cvzf /tmp/opennms-etc-backup.tar.gz etc</programlisting>
</para>
</section><section>
<title>Assess the Events Table Size</title><para>
If you have a large number of events, you may need to increase the amount
of memory passed to the OpenNMS <filename>install</filename> tool. For example,
if you have 250k events, you will need almost 600MB of heap. When the time comes
to run the <filename>install</filename> tool, assuming you have enough available
memory, it's probably safe to just use a very large value to pass to
<filename>install</filename>, like:
<programlisting>install -Xms1024m -Xmx2048m -dis</programlisting>
</para>
</section>
</section><section>
<title>Upgrading RPM-Based Distributions Using Yum</title><para>
If you have the OpenNMS Yum repositories configured, all you should need
to do to get the new release is run:
<programlisting>sudo yum upgrade opennms</programlisting>
</para><para>
If you are comfortable letting your distribution give you OS updates along
with OpenNMS, you can just run:
<programlisting>sudo yum upgrade</programlisting>
</para>
</section><section>
<title>Upgrading RPM-Based Distributions Using URPMI</title><para>
If you have the OpenNMS URPMI repositories configured, you can upgrade by
running:
<programlisting>sudo urpmi --auto opennms</programlisting>
</para><para>
As with Yum, if you are comfortable letting URPMI give OS updates along with
OpenNMS, you can run:
<programlisting>sudo urpmi --auto --auto-select opennms</programlisting>
</para>
</section><section>
<title>Upgrading RPM-Based Distributions Manually</title><para>
You can upgrade RPM systems manually by downloading the <ulink>RPM
packages from SourceForge</ulink> and upgrade them by running:
<programlisting>sudo rpm -Uvh opennms*.rpm</programlisting>
</para>
</section><section>
<title>Upgrading Debian-Based Distributions</title><para>
If your Debian or Ubuntu system is configured with the OpenNMS Apt
repository, you should just need to run:
<programlisting>sudo apt-get update
sudo apt-get -u install opennms</programlisting>
</para>
</section><section>
<title>Upgrading Windows</title><para>
Since there is no automated installation/upgrade procedure for
Windows, you will have to do some preparation before installing
the latest version.
</para><itemizedlist>
<listitem>
<para>Back up and then remove <filename><varname>$OPENNMS_HOME</varname>/etc</filename>.</para>
</listitem><listitem>
<para>Remove <filename><varname>$OPENNMS_HOME</varname>/lib</filename>,
<filename><varname>$OPENNMS_HOME</varname>/webapps/opennms/WEB-INF/lib</filename>, and
<filename><varname>$OPENNMS_HOME</varname>/jetty-webapps/opennms/WEB-INF/lib</filename>.</para>
</listitem>
</itemizedlist><para>
Once you've cleaned up the etc and lib directories, the next
step is to download the latest <filename>standalone-opennms-installer-X.X.X.jar</filename> from <ulink>the
OpenNMS SourceForge download page</ulink>.
</para><para>
Next, run the installer jar, and install over your existing OpenNMS location.
</para><para>
If you backed up the pristine <code>etc</code> directory on your
previous installation, you can compare it to the current one to see
if there are any configuration changes you wish to integrate into
your new install.
</para><para>
Copy your backed up <code>etc</code> directory back into the
<filename><varname>$OPENNMS_HOME</varname>/etc</filename> directory.
</para><para>
You should now be able to run your upgraded OpenNMS.
</para>
</section>
</section><section>
<title>Configure Java for OpenNMS</title><para>
Before you can run the post-install, OpenNMS needs to be configured
to use an appropriate Java Runtime Environment (JRE). The OpenNMS tool
<filename>runjava</filename> is used to set this up, and it can either
search for a suitable JRE or you can tell it exactly which JRE to use.
</para><section>
<title>Search for a JRE (suggested)</title><para>
Execute <filename>runjava</filename> with the "<code>-s</code>"
option to search for a JRE:
</para><programlisting><computeroutput># </computeroutput><command>$OPENNMS_HOME/bin/runjava -s</command></programlisting>
</section><section>
<title>Configure a specific JRE</title><para>
Execute runjava with the "<code>-S <path to JRE></code>"
option to specify the exact JRE you want OpenNMS to use:
<programlisting><computeroutput># </computeroutput><command>$OPENNMS_HOME/bin/runjava -S <path to JRE's java executable></command></programlisting>
</para>
</section>
</section><section>
<title>Run the OpenNMS Installer Application</title><para>
No matter which installation method above you choose, and whether
you are performing a fresh install or an upgrade, you still need to run
the OpenNMS installer. This tool will setup the <code>opennms</code> database
within PostgreSQL among other things.
</para><programlisting><computeroutput># </computeroutput><command>$OPENNMS_HOME/bin/install -l /usr/local/lib -dis</command></programlisting><para>
The "-l" parameter will look for the jicmp and/or jrrd libraries
in the location specified. The "-dis" will initialize and check the
database. Note at the end of the output from the installer it will
indicate if iplike has been installed properly.
</para><para>
For a full list of options the installer accepts, run
"<code>$OPENNMS_HOME/bin/install -h</code>".
</para>
</section>
</chapter><chapter>
<title>Getting Started with OpenNMS</title><section>
<title>Configuring Discovery</title><para>
By default, OpenNMS will not discover hosts until you configure it to do
so, or explicitly add them in the Admin UI. You will most likely want to
tell OpenNMS where to look to discover hosts on your network.
</para><para>
Edit <filename>$OPENNMS_HOME/etc/discovery-configuration.xml</filename>. You
should see an example <include-range> tag with a <begin> and an
<end> which is commented out.
</para><para>
You will most likely want to uncomment it and change the beginning and end
ranges (within the <code><begin></code> and <code><end></code>
tags, respectively). Additionally, you can add as many
<code><include-range></code>es as you'd like.
</para><para>
If you would rather list the individual host that you want to have
discovered, you can insert <code><specific></code> tags above the
<code><include-range></code> tag.
</para><para>
Lastly, if you prefer to use the web interface to add individual hosts for
OpenNMS to monitor, you leave the contents of this file commented out.
</para>
</section><section>
<title>Login to the Web Application</title><para>
By default, OpenNMS's built-in web server listens on port 8980, so point
your browser at <filename>http://<host>:8980/opennms/</filename>
(where <host> is the host you're running OpenNMS on). The initial
user name is "<code>admin</code>" and the password is
"<code>admin</code>".
</para>
</section><section>
<title>Configure OpenNMS to Start Automatically at Boot Time</title><para>
If everything looks good, you can configure OpenNMS to start automatically
at boot time. By default on most platforms OpenNMS does not start
automatically until you configure it to do so.
</para><section>
<title>Configuring Automatic Startup on RPM-based Linux Distributions</title><para>
The OpenNMS packages add an init script in <filename>/etc</filename>
(usually <filename>/etc/init.d</filename>), however you need to execute
<filename>chkconfig</filename> to enable the service to start
automatically:
<programlisting><computeroutput># </computeroutput><command>/sbin/chkconfig --add opennms</command></programlisting>
</para>
</section><section>
<title>Configuring Automatic Startup on Solaris</title><programlisting><computeroutput># </computeroutput><command>ln -s $OPENNMS_HOME/bin/opennms /etc/init.d/opennms</command><computeroutput># </computeroutput><command>ln -s ../init.d/opennms /etc/rc3.d/S99opennms</command><computeroutput># </computeroutput><command>ln -s ../init.d/opennms /etc/rc3.d/K01opennms</command></programlisting>
</section>
</section>
</chapter><chapter>
<title>Performance Tuning</title><section>
<title>Performance "Do"s</title><section>
<title>Lots of RAM</title><para>
OpenNMS is not terribly heavy on CPU usage, but is <emphasis>extremely</emphasis>
I/O-bound, and will also take advantage of as much RAM as you can give it.
OpenNMS itself doesn't use a huge amount of RAM per-node, but allowing the OS to
cache filesystem interaction makes a very large performance difference.
</para>
</section><section>
<title>Battery-Backed Write Cache</title><para>
If you are running on hardware RAID, it is strongly recommended that you
have a battery-backed write cache. For example, one user reported that on
an HP DL380 G4, the I/O wait of the server dropped from 15% to essentially
nothing, using a 128MB battery-backed write cache.
</para>
</section><section>
<title>Multiple Spindles</title><para>
You will get the most out of OpenNMS if you spread your I/O out into multiple
spindles and/or separate disks/channels.
</para><section>
<title>PostgreSQL</title><para>
PostgreSQL writes primarly to 2 classes of files and directories.
</para><glosslist>
<glossentry>
<glossterm>the database</glossterm><glossdef>
<para>
The main PostgreSQL database is in <filename><varname>$PGDATA</varname>/base</filename>
(<varname>$PGDATA</varname> is usually something like
<filename>/var/lib/pgsql/data</filename>).
</para>
</glossdef>
</glossentry><glossentry>
<glossterm>the journal</glossterm><glossdef>
<para>
PostgreSQL keeps a journal of transactions, in
<filename><varname>$PGDATA</varname>/pg_xlog</filename>.
</para>
</glossdef>
</glossentry>
</glosslist><para>
If you can separate the pg_xlog directory onto another spindle or mount
point, you will increase your PostgreSQL performance considerably. To do
so, you should be able to just shut down PostgreSQL, move that directory,
symlink it to the old location, and start it back up.
<programlisting>sudo /etc/init.d/postgresql stop
sudo mv /var/lib/pgsql/data/pg_xlog /mnt/xlogspindle/pg_xlog
sudo ln -s /mnt/xlogspindle/pg_xlog /var/lib/pgsql/data/pg_xlog
sudo /etc/init.d/postgresql start</programlisting>
</para>
</section><section>
<title>Round-Robin (Collection and Performance) Data</title><para>
The RRD data is the single heaviest source of I/O in most OpenNMS
installations. Making sure that it is on a different spindle from
PostgreSQL makes a huge difference.
</para><itemizedlist>
<listitem>
<para>RRD data storage causes a large number of small random
disk writes, usually a few writes for each update.</para>
</listitem><listitem>
<para>By default, OpenNMS stores each collected variable in its
own file, unless the store by group feature is enabled.</para>
</listitem><listitem>
<para>Normally, there will be 2-3 writes for each update: one for
the file header, one for the previous RRA, one for the next RRA.</para>
</listitem><listitem>
<para>When multiple samples are consolidated into a single stored
data point in the RRA, there will be additional writes. By
default, such consolidations happen hourly and daily on the GMT
day boundary. This will cause higher than normal amount of
writes after the top of the hour and after the GMT day boundary.</para>
</listitem>
</itemizedlist><para>
The OpenNMS RRDs live, by default, in <filename><varname>$OPENNMS_HOME</varname>/share</filename>.
If you are using the RPMs, this will be <filename>/var/opennms</filename> instead.
<programlisting>sudo mv /var/opennms /mnt/rrdspindle/opennms
sudo rm -f /opt/opennms/share
sudo ln -s /mnt/rrdspindle/opennms /opt/opennms/share</programlisting>
</para>
</section>
</section><section>
<title>Use <varname>noatime</varname> on OpenNMS Data Spindles on Linux and Solaris</title><para>
If you are dedicating spindles or drives to OpenNMS, you can mount them
with the <varname>noatime</varname> option on Linux or Solaris for an
additional performance boost. This will keep the OS from updating the
file access time on individual RRD and database files every time they
are used.
</para><para>
On Linux, you do so by editing <filename>/etc/fstab</filename> and adding
<varname>noatime</varname> to the options section of the filesystem. For example:
<programlisting>LABEL=/ / ext3 defaults 1 1
LABEL=/var/opennms /var/opennms ext3 defaults,noatime 1 2
LABEL=/var/lib/pgsql /var/lib/pgsql ext3 defaults,noatime 1 2
LABEL=/var/lib/pgsql/data/pg_xlog /var/lib/pgsql/data/pg_xlog ext3 defaults,noatime 1 2</programlisting>
</para><para>
On Solaris, you edit <filename>/etc/vfstab</filename> and add
<varname>noatime</varname> as an option at the end of the mountpoint
information, like so:
<programlisting>/dev/dsk/c1d0s0 /dev/rdsk/c1d0s0 / ufs 1 no
/dev/dsk/c1d1s0 /dev/rdsk/c1d1s0 /opt/opennms/share ufs 2 no noatime
/dev/dsk/c1d2s0 /dev/rdsk/c1d2s0 /usr/local/pgsql/data ufs 2 no noatime
/dev/dsk/c1d3s0 /dev/rdsk/c1d3s0 /usr/local/pgsql/data/pg_xlog ufs 2 no noatime</programlisting>
</para>
</section><section>
<title>RAID Drives</title><para>
Use a mirrored stripe (RAID-10), with enough disks to handle the amount of data
you need to collect. A single disk, a pair of mirrored disks (RAID-1), or a
RAID-5 is only appropriate for an installation doing a small amount of data
collection.
</para>
</section><section>
<title>PostgreSQL Performance Tuning</title><para>
There are a number of other things you can do to tune PostgreSQL. For a good
writeup on PostgreSQL performance tuning, see <ulink>this page at revsys.com</ulink>.
</para><section>
<title>PostgreSQL 8.1-specific Recommendations</title><para>
If you have a reasonable amount of RAM (2GB+), the following settings should
give much better performance than the defaults that come with the PostgreSQL
configuration:
<programlisting>shared_buffers = 20000
work_mem = 16348
maintenance_work_mem = 65536
vacuum_cost_delay = 50
checkpoint_segments = 20
checkpoint_timeout = 900
wal_buffers = 64
stats_start_collector = on
stats_row_level = on
autovacuum = on</programlisting>
</para>
</section><section>
<title>PostgreSQL 8.2+ Recommendations</title><para>
On systems with 4GB or more of RAM, we've found that changing the
max_fsm_pages and max_fsm_releations, as well as work_mem and
maintenance_work_mem improves performance dramatically:
<programlisting>work_mem = 100MB
maintenance_work_mem = 128MB
#max_fsm_pages = 204800 # min max_fsm_relations*16, 6 bytes each
max_fsm_pages = 2048000
#max_fsm_relations = 1000 # min 100, ~70 bytes each
max_fsm_relations = 10000</programlisting>
</para>
</section><note>
<para>
If you increase memory settings for PostgreSQL, you will probably need
to increase the maximum shared-memory settings in your OS. On Linux,
you can do this by editing <filename>/etc/sysctl</filename> and adding
the line:
<code>kernel.shmmax=170639360</code>
</para><para>
Depending on how many shared memory segments you need, you may need to
adjust that value.
</para>
</note>
</section>
</section><section>
<title>Performance "Don't"s</title><para>
Because of OpenNMS's high-I/O profile, there are a number of things that will
cause performance issues on reasonably large installs.
</para><itemizedlist>
<listitem>
<para>Don't run in a VM (although some pseudo-VMs like <ulink>Xen</ulink> are not as hard on I/O as things like
<ulink>VMware</ulink>).
</para>
</listitem><listitem>
<para>Don't put the database or RRD data on file systems managed by LVM.</para>
</listitem><listitem>
<para>Don't put DB or RRD data on file systems on RAID-5.</para>
</listitem><listitem>
<para>Don't use older kernels. Linux 2.6 and Solaris 10 perform much
better than older releases.</para>
</listitem>
</itemizedlist>
</section>
</chapter><chapter>
<title>Building From Source</title><section>
<title>Are you sure you want to do this?</title><para>
OpenNMS is a complex software product, and it does not (yet) have a
simple "<code>./configure && make && make install</code>"
build process like many other tools. If there is a packaged release for
your operating system, we highly suggest you use that instead. If you have
problems with a packaged release, please see the troubleshooting section
for assistance.
</para><para>
The best place to find out how to build OpenNMS is from the <ulink>developer's</ulink>
page on the wiki. You will need to <ulink>check
out</ulink> the code and then <ulink>build</ulink> it.
</para>
</section>
</chapter><chapter>
<title>Troubleshooting an OpenNMS Installation</title><section>
<title>Common Installation Issues</title><para>The following section contains advice for overcoming common
installation issues. If your issue is not addressed below, please see the
section on where to get help.</para><section>
<title>Dependency Problems</title><para>To assist with code management, the easiest way to install OpenNMS
is via packages. Every effort has been made to insure that the packages
OpenNMS depends on are required before the OpenNMS package can be
installed. You should be able to find those packages on the distribution
CDs that came with your system. For some of the more obscure packages,
you can visit the OpenNMS <ulink>FTP</ulink>
site and check in the <filename>/pub/dependencies</filename> directory.
In addition, sites like <ulink>Ibiblio</ulink> and <ulink>FreshRPMs</ulink> are also good
sources.</para>
</section><section>
<title>Error: "Started OpenNMS, but it has not finished starting
up"</title><para>This can happen for a a number of reasons. You can run
"<code>opennms -v status</code>" a few times after getting this error to
see if OpenNMS eventually starts itself completely and if not, to see
which daemons never start up completely. Here are some of the likely
causes of this problem:</para><orderedlist>
<listitem>
<para>OpenNMS takes a while to startup. This can happen on larger
installations and when this happens "<code>opennms -v status</code>"
will eventually show that all services have started up. By default,
the startup script will try 10 times to see if OpenNMS has started
and will wait 5 seconds between each try. You can increase the
number of times by creating
<filename>$OPENNMS_HOME/etc/opennms.conf</filename> and adding a
line like "<code>START_TIMEOUT=20</code>" to double the number of
times it tests. You can set the value to <code>0</code> to have the
startup script not wait for OpenNMS to start.</para>
</listitem><listitem>
<para>Database is not running. If only about half or less of the
daemons are shown as running, you can check for this condition by
looking for <code>FATAL</code> errors in the log files. You'll see
something like "<code>Error accessing database</code>" in the
logs.</para>
</listitem><listitem>
<para>Dhcpd doesn't start. See the item in the next section.</para>
</listitem><listitem>
<para>JNI library problem. OpenNMS uses a few native C libraries
that are accessed using JNI (Java Native Interface). Normally they
just work, except users have started seeing problems when running
Linux in native AMD64 mode where they end up using a 32-bit (x86)
version of Java and a 64-bit (AMD64) version of the JNI libraries,
or vice-versa. If you have this problem, you might want to try
switching your version of Java from 32-bit to 64-bit or in the other
direction.</para>
</listitem><listitem>
<para>Other. If the OpenNMS is installed, and the packages were not
forced in using options like "<code>--nodeps</code>", the
application should run just fine. If not, OpenNMS has a robust
logging facility. Change to the logs directory (usually
<filename>/var/log/opennms</filename>) and search the logs, using
<filename>grep</filename> or your tool of choice, for words like
<code>FATAL</code> and <code>ERROR</code> (the two highest log
severities). Those events should give you clues as to why OpenNMS is
not working.</para>
</listitem>
</orderedlist>
</section><section>
<title>DHCP Poller Won't Start</title><para>The OpenNMS DHCP poller will fail to start most operating systems
(Linux, in particular) if you are running a DHCP client on the OpenNMS
server. You'll see this by running "<code>opennms -v status</code>" and
seeing everything in the <code>running</code> state, except for
<code>Dhcpd</code>. The solution is to edit
<filename>$OPENNMS_HOME/etc/service-configuration.xml</filename> and
comment-out the "<code><service>...</service></code>" stanza
for <code>Dhcpd</code>. For example, this is what the section would look
like after modification to disable <code>Dhcpd</code>:</para><programlisting> <!-- Commented out since we have a DHCP client on this server
<service>
<name>OpenNMS:Name=Dhcpd</name>
<class-name>org.opennms.netmgt.dhcpd.jmx.Dhcpd</class-name>
<invoke pass="1" method="start"/>
<invoke at="status" pass="0" method="status"/>
<invoke at="stop" pass="0" method="stop"/>
</service>
--></programlisting><para>We discourage the running of OpenNMS on a server that is a DHCP
client, both because OpenNMS may not be able to monitor DHCP servers on
the network, and it is important that the monitoring server have a
static IP address for receiving traps and to be reliant on as few
network services as possible.</para>
</section><section>
<title>Error: "runjava: Could not find an appropriate JRE"</title><para>The <code><filename>runjava</filename></code> program is used to
locate a suitable JRE for OpenNMS at install time that will be used for
the installer and also for running OpenNMS after installation. See the
section earlier in this manual on installing Java for OpenNMS. If you
installed Java in a location that <code>runjava</code> cannot find, you
can use its "<code>-f</code>" option to specify the JRE you want OpenNMS
to use.</para>
</section><section>
<title>Error: "The database server's error messages are not in English
..."</title><para>You either need to set "<code>lc_messages = 'C'</code>" in your
postgresql.conf file and restart PostgreSQL or upgrade to PostgreSQL 7.4
or later.</para><para>The installer does not always verify that an operation will
succeed before executing the operation (e.g.: dropping database
functions). In this case, it catches the exceptions returned from the
database and checks the exception to see if it is an "okay" exception
that should be ignored (e.g.: if the database function does not exist
when attempting to drop a function).</para><para>In PostgreSQL 7.4 and later, a new client/server protocol is used
(version 3, to be specific) that provides specific error codes intended
for programmatic evaluation and we use these error codes if the server
provides them. However for PostgreSQL versions before 7.4, we require
that the database server error language be in English (the
'<code>C</code>' locale) so that we can parse the text error messages.
If you are not running PostgreSQL 7.4 or newer, the installer executes a
bogus query against the database and checks for an expected result in
English.</para>
</section><section>
<title>Error: "Column X in new table has NOT NULL constraint
..."</title><para>This is a warning that the installer might not update tables
successfully. Make sure that your database is backed up, and run the
installer again with the "-N" option to ignore this check.</para><para>As an attempt to ensure that the install will complete
successfully, a check is done to see if there might be any rows with
NULL columns that might be inserted into a column in an upgrade table
with a NOT NULL constraint. This usually happens when a previous run of
the installer failed, or might be due to modifications to the database
schema or a really old version of the schema.</para>
</section><section>
<title>Error: "One or more backup tables from a previous install still
exists"</title><para>When the installer runs to upgrade the OpenNMS database from a
previous install, it often updates table schemas. When it does this, it
copies the data in a table to a temporary table (e.g.: the contents of
<filename>node</filename> are copied into
<filename>node_old_11033991291234</filename>). The original table is
deleted, the new version of the table is created, the data in the
temporary table is translated into the new table, and finally the
temporary table is deleted.</para><para>Unfortunately, the installer cannot check for all problems that
might break translation, so sometimes the translation step fails. In
this case, the installer "reverts" the table it was processing by
dropping the new table and moving the temporary table into its
place.</para><para>Reverting the table in case of a problem is all good and well, but
sometimes even it does not work properly, especially with older versions
of the Java installer. If this happens, the temporary table (the one
with "_old_" in it) is left with all of the old data. Until OpenNMS
1.1.5, this problem would not be caught the next time you ran the
installer. The installer would see that you did not have the
<filename>node</filename> table, for example, and happily continue to
create a new one for you. This is bad, especially since you probably
still have data that you care about that is now in the "old"
table.</para><para>If you get this error, you will want to get rid of the table(s)
containing "_old_", however you want to first check if they contain
data. For example, if you have a single table,
<filename>node_old_11033991291234</filename>, no other
<filename>node_old_*</filename> tables, and no <filename>node</filename>
table, you can simply rename the table:</para><programlisting># <command>psql -h localhost -U opennms opennms</command><computeroutput>Welcome to psql 7.4.6, the PostgreSQL interactive terminal.
Type: \copyright for distribution terms
\h for help with SQL commands
\? for help on internal slash commands
\g or terminate with semicolon to execute query
\q to quit
opennms=# </computeroutput><command>ALTER TABLE node_old_11033991291234 RENAME TO node;</command></programlisting><para>You can use the "\d" command within <filename>psql</filename> to
see what other tables exist in your database. You can use "<code>SELECT
count(*) from table;</code>" (fill in the table name for "table") to get
a count of rows in any table. If you have empty tables, you can just
drop them. If you have multiple tables with data, you will have to
decide which table of data you want to keep or merge them. This is left
as a (not so simple) exercise for the reader.</para>
</section><section>
<title>Error: "Table X contains N rows (out of M) that violate new
constraint Y"</title><para>Over time OpenNMS extends its database schema to improve
functionality. This error can happen because of the way certain
administrative functions in older versions of OpenNMS functioned or if
the database was modified outside of OpenNMS (the latter is common for
larger sites). Over time OpenNMS has introduced additional foreign key
constraints on its database. These are used to ensure internal database
consistency when data in two tables are tied together by a shared key.
For example, each event can have a pointer to the node that it is
related to; there is a foreign key constraint that requires that an
event <emphasis>must not</emphasis> point at a node that does not
exist.</para><para>Starting with 1.1.5, when we upgrade the database schema, we first
check for rows that violate any new foreign key constraints that might
be added. There are three options to to fix these errors:</para><orderedlist>
<listitem>
<para>Remove the offending rows. This is suggested if the number of
rows that violate the constraint is small in comparison to the total
number of rows in the affected table and if you don't need the data.
Use "<code>$OPENNMS_HOME/bin/install -C <constraint>
-X</code>" to delete the offending rows.</para>
</listitem><listitem>
<para>Mark the key in the offending rows to NULL. This is suggested
if you need to keep the data around or are not yet sure about what
to do with it. Use "<code>$OPENNMS_HOME/bin/install -C
<constraint></code>" to mark the key column to NULL in the
offending rows.</para>
</listitem><listitem>
<para>Fix the key in the offending rows. This is for advanced users
and requires a good amount of effort. This is left as an exercise
for the reader.</para>
</listitem>
</orderedlist>
</section><section>
<title>Error: "- adding iplike database function... <snip>
org.postgresql.util.PSQLException: ERROR: could not access file
'<snip>/lib/iplike.so': Permission denied"</title><para>The PostgreSQL server cannot access the iplike.so file. This could
be due to the file itself not having appropriate permissions for the
user that PostgreSQL runs as and/or one or more of the parent
directories of the iplike.so not having appropriate permissions.</para><para>This error is seen even when running the installer as root because
it is not OpenNMS nor the installer that cannot access the iplike.so
file, but the PostgreSQL database. The installer instructs the
PostgreSQL database to load the iplike.so and the PostgreSQL database
server usually runs as a non-root user, so it is subject to filesystem
access control checks like any other normal user. This is commonly seen
when people install OpenNMS into a home directory for root or another
user and the permissions on that home directory do not allow users other
than the owner of the directory access.</para>
</section><section>
<title>Error: "- adding iplike database function... <snip>
org.postgresql.util.PSQLException: ERROR: could not load library
..."</title><para>The latter part of the error could be something like
"<code><path>/iplike.so: cannot open shared object file: No such
file or directory</code>" or "<code>ld.so.1: postgres: fatal:
<path>/iplike.so: wrong ELF class: ELFCLASS32</code>".</para><para>The PostgreSQL server cannot load the <code>iplike.so</code> file.
This is almost always caused by the PostgreSQL server and the iplike.so
file being compiled for different processor instruction sets. This is
commonly seen when the PostgreSQL server is compiled to use a 64-bit
instruction set but the OpenNMS <code>iplike.so</code> shared object is
compiled for a 32-bit instruction set, although the opposite is
possible, as well. You can use the "<code>file</code>" command on
<code>iplike.so</code> and the <code>postmaster</code> binary with
PostgreSQL to check their instruction sets.</para><para>The easiest solution is to see if there is a packaged version of
OpenNMS compiled for the same instruction set (32- or 64-bit) as your
PostgreSQL server. The next easiest method for most users is to switch
the PostgreSQL server to match the instruction set that the
<code>iplike.so</code> file was compiled for. For advanced users, you
can compile OpenNMS yourself to fit the processor set that you need. See
<ulink>this
post to the discuss list</ulink> for some pointers.</para>
</section><section>
<title>Error: "Exception in thread "main"
org.postgresql.util.PSQLException: ERROR: relation "pg_user" does not
exist" when running installer.</title><para>This error means the database was not created properly. Since the
installer script is supposed to create the database, one might assume it
is a problem with OpenNMS, but instead it is an issue with the SELinux
portions of Red Hat 4 (and CentOS 4). Basically, the postgres init_db
command is not able to write to /dev/null, and it fails without a useful
error message.</para><para>To get around this, run the following commands:</para><orderedlist>
<listitem>
<para>stop postgres</para>
</listitem><listitem>
<para>rm -rf /var/lib/pgsql/data</para>
</listitem><listitem>
<para>/usr/sbin/setenforce 0</para>
</listitem><listitem>
<para>start postgres</para>
</listitem>
</orderedlist><para>Note that step 2 will delete any changes you made to the
postgresql configuration files and you'll need to redo them.</para>
</section><section>
<title>Error: java.io.FileNotFoundException: ... (Permission
denied)</title><para>An exact example of this error is:
"<code>java.io.FileNotFoundException: /opt/opennms/etc/users.xml
(Permission denied)</code>".</para><para>If the above error happens when using admin functions through
the web interface, such as managing users, notifications, and adding
nodes, then the Tomcat web server is running as a non-root user but
you haven't changed the permissions on the configuration files so
the Tomcat user can access them. Go back and follow the instructions
earlier in the install guide on setting up Tomcat to run as a non-root
user.</para>
</section>
</section><section>
<title>Where to Get Help</title><para>OpenNMS is a community supported project. Please keep that in mind
when seeking help on the program, as no one gets paid to work on the
project (unless it is through a commercial support contract).</para><section>
<title>The Release Notes</title><para>Check the release notes for this release. They are in the <ulink>Documentation</ulink>
section of the OpenNMS project page at SourceForge.</para>
</section><section>
<title>The OpenNMS Web Site</title><para>The main OpenNMS <ulink>site</ulink>
is a Wiki. As a community project, there is a lot of good advice and
information available there. In particular, we suggest checking the
above-mentioned release notes, the <ulink>FAQ entries on the wiki</ulink>,
the <ulink>bug database</ulink> and,
of course, <ulink>Google</ulink>,
before posting to a mailing list.</para>
</section><section>
<title>The OpenNMS Mailing Lists</title><para>OpenNMS maintains a number of active mailing lists <ulink>on SourceForge</ulink>:</para><glosslist>
<glossentry>
<glossterm><ulink>opennms-announce</ulink></glossterm><glossdef>
<para>A low traffic, moderated mailing list for OpenNMS
announcements. All posts to this list are duplicated on the
<glossterm>opennms-discuss</glossterm> list.</para>
</glossdef>
</glossentry><glossentry>
<glossterm><ulink>opennms-cvs</ulink></glossterm><glossdef>
<para>This is a fairly high traffic list of all updates to the Subversion
repositories on SourceForge. Moderated. Only SVN updates are posted here
(no discussion).</para>
</glossdef>
</glossentry><glossentry>
<glossterm><ulink>opennms-devel</ulink></glossterm><glossdef>
<para>This list is for discussion of development of the OpenNMS codebase.</para>
</glossdef>
</glossentry><glossentry>
<glossterm><ulink>opennms-discuss</ulink></glossterm><glossdef>
<para>This is the main OpenNMS discuss list. It's pretty friendly, and
reasonably high-volume. It tends to focus on configuration issues and
general discussion of network management, but pretty much anything goes
here. However, it is suggested that installation-related issues go to
the <glossterm>opennms-install</glossterm> list instead.</para>
</glossdef>
</glossentry><glossentry>
<glossterm><ulink>opennms-install</ulink></glossterm><glossdef>
<para>This is a great list for new users to OpenNMS. The main
focus is installation issues (cleared up by this great documentation,
right?) but most "newbie" questions are welcome here.</para>
</glossdef>
</glossentry><glossentry>
<glossterm><ulink>opennms-maps</ulink></glossterm><glossdef>
<para>OpenNMS has a network map feature, which includes code for
automatically determining relationships between hosts (Linkd). This
is the appropriate list for discussion of maps and the underlying
Linkd code.</para>
</glossdef>
</glossentry><glossentry>
<glossterm><ulink>opennms-windows</ulink></glossterm><glossdef>
<para>A discussion list for people running OpenNMS on Windows.</para>
</glossdef>
</glossentry><glossentry>
<glossterm><ulink>opennms-francais</ulink></glossterm><glossdef>
<para>A list for discussion of OpenNMS in French.</para>
</glossdef>
</glossentry><glossentry>
<glossterm><ulink>opennms-italia</ulink></glossterm><glossdef>
<para>A list for discussion of OpenNMS in Italian.</para>
</glossdef>
</glossentry><glossentry>
<glossterm><ulink>opennms-ug-tokyo</ulink></glossterm><glossdef>
<para>A list for discussion of OpenNMS in Japanese, as well as
general discussion among the Tokyo OpenNMS Users Group.</para>
</glossdef>
</glossentry><glossentry>
<glossterm><ulink>opennms-ug-uk</ulink></glossterm><glossdef>
<para>A list for discussion of OpenNMS in UK English for those
who don't speak American English (OK, just kidding). Actually,
a discussion list for the UK OpenNMS Users Group. ;)</para>
</glossdef>
</glossentry>
</glosslist><para>The OpenNMS mailing lists are also archived at <ulink>gmane.org</ulink>.</para>
</section><section>
<title>Commercial Support</title><para>If you are using OpenNMS in a production environment, or are
considering it, you might be interested in commercial support. The
<ulink>OpenNMS Group</ulink>
maintains the OpenNMS project, and we also offer support, training,
consulting services and custom development.</para>
</section>
</section>
</chapter>