Copyright © 2004-2006 The OpenNMS Group, Inc.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts and with no Back-Cover Texts. A copy of the license is available at http://www.gnu.org/copyleft/fdl.html
Table of Contents
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.
The current corporate sponsor of OpenNMS is The OpenNMS Group, which also owns the OpenNMS trademark.
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:
Copyright © 2002-2005 The OpenNMS Group, Inc..
Original code base for OpenNMS version 1.0.0 Copyright © 1999-2001 Oculan Corporation.
Mapping code Copyright © 2003 Networked Knowledge Systems, Inc.
ScriptD code Copyright © 2003 Tavve Software Company.
Please send any omissions or corrections to this document to Tarus Balog
Table of Contents
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.
So, how should you use this document? It is arranged in the following sections:
This overview
The programs on which OpenNMS depends, and how they need to be modified
Installation and upgrade instructions, including details for spectific operating systems and distributions
Getting started with OpenNMS, including initial configuration and logging into the web interface
Building OpenNMS from source
Troubleshooting and Where to Get Help
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.).
Please see the latest release notes to see if your operating system is supported. Currently OpenNMS runs on many Linux distributions, Solaris and Mac OS X.
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.
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.
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.
A 1 GHz Pentium III (or equivalent processor) or better. OpenNMS can also take advantage of multiple processors.
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. Given a budget choice between more RAM and a faster CPU, choose more RAM.
OpenNMS requires about 25 MB of disk space for the program
files. In addition, each data variable collected requires, by
default, 283 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. Edit the
log4j.properties
file in the OpenNMS
configuration directory (usually
/opt/OpenNMS/etc
or
/etc/opennms
) to change those settings. For a
minimum system, 800 MB to 1 GB should be sufficient.
Note: Unless it is a very small system, do not use RAID-5 with OpenNMS. RAID-1 or RAID-1+0 is recommended if using RAID.
Table of Contents
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.
It is recommended that the JDK from Sun is used with OpenNMS, version 1.5 or higher. If OpenNMS is to be run on a 64-bit system, be sure to install the 64-bit JDK.
Sun's Java can now be installed using "apt" on etch, lenny or sid.
apt-get install sun-java5-jdk
This should also work on Ubuntu 6.10 (edgy) or 7.04 (fiesty). It is also acceptable to install sun-java6-jdk.
It is important to install the JDK instead of the JRE, as Tomcat will need to compile Java code (which requires "javac" in the JDK).
You will need to use Sun's Java 2 Platform, Standard Edition,
version 5 (1.5) or later. You can download
it from Sun's Java
website. Step through the licensing process and then download the proper
version of Java for your operating system. If you will be using an
RPM-based Linux package of OpenNMS, you will need to download the RPM
package of Java, otherwise, you will want the ".bin
" file.
Install Java according to the instructions from Sun. Note that all
64-bit versions of OpenNMS RPMs have been built against the 64-bit
version of Java (available toward the bottom of that page).
Tomcat is part of the Jakarta project in Apache, and it is a Java servlet engine. What that means is that Tomcat is a web server that serves up HTML that is built from small Java programs called "servlets". Note that this is much different than Java "applets"--servlets are run on the server, not downloaded to the browser. Once a servlet is compiled, Tomcat will cache it, which means that the first visit to a particular page may be slow, but subsequent visits should be rather fast.
Some distributions are able to use the JPackage project to download Tomcat5, but easy to install RPMs are hard to find. Usually, just downloading the tarball and placing it on the OpenNMS server is enough. There is no longer a requirement for a Tomcat RPM in OpenNMS.
It is recommended that you run Tomcat as "root" so that it has access to the files in the OpenNMS configuration and log directories. Usually, just setting JAVA_HOME to point to your Java 5 directory and running the startup scripts in the Tomcat bin directory is enough to get Tomcat running.
If you choose not to set the user that runs Tomcat to
root
, you will need to make the following changes so that
the Tomcat user can read and write the OpenNMS configuration files. This
process adds the "tomcat
" and "root
" users to
the "tomcat5
" group, and then changes permissions so that
the "tomcat5
" group can write to the OpenNMS
"etc
" and "logs
" directory.
You have to do this after the OpenNMS
software is installed.
The "tomcat
" user should have been created on
installation of Tomcat--verify this by looking in
/etc/passwd
.
Edit /etc/group
and add
"tomcat
" and "root
" as members of the
"tomcat4
" group. It should look something like:
tomcat5:x:91:tomcat,root
Locate the OpenNMS "etc
" directory. It is
usually in /opt/OpenNMS/etc
or
/etc/opennms
. It will have a number of files
with an ".xml
" extension, such as
capsd-configuration.xml
. Run the
commands:
#
chgrp -R tomcat5 $OPENNMS_HOME/etc#
chmod -R g+w $OPENNMS_HOME/etc
where $OPENNMS_HOME/etc
is the OpenNMS
"etc
" directory.
Locate the OpenNMS webapp logs directory. This is usually
/var/log/opennms/webapp
or in
logs/webapp
under the OpenNMS home directory.
Run the commands:
#
chgrp -R tomcat5 /var/log/opennms/webapp#
chmod -R g+w /var/log/opennms/webapp
where /var/log/opennms/webapp
is the
OpenNMS webapp logs directory.
Locate the OpenNMS reports directory. This is usually
share/reports
under the OpenNMS home directory.
Run the commands:
#
chgrp -R tomcat5 $OPENNMS_HOME/share/reports#
chmod -R g+w $OPENNMS_HOME/share/reports/
where $OPENNMS_HOME/share/reports
is the
OpenNMS reports directory.
Tomcat will start with just the first change, but without the second change you'll start seeing errors in the OpenNMS logs, and administration commands run in the web UI will fail because Tomcat cannot change the configuration files.
One more change that needs to be made is to allow Tomcat to access
more memory than the default. The easiest way to do this is via the
CATALINA_OPTS
environment variable. If the Tomcat
software being used has a configuration file as above, it can be added
to that file. Otherwise it is best just to add it to
catalina.sh
.
CATALINA_OPTS="-Xmx1024m"
The -Xmx option allows Tomcat to access up to 1GB of memory. Of course, the assumes that there is 1GB of available memory on the system. It will need to be tuned to the particular server in use.
RRDtool is the genesis of probably the first widely used open-source network management tool, MRTG. OpenNMS was originally built to use RRDtool for data storage, but the current default is to use JRobin (a java port of RRDtool). JRobin is included with OpenNMS.
RRDtool provides a "round robin" database that stores time-series data quickly and in a small amount of space. OpenNMS stores its performance-related data in RRD files created using RRDtool.
However, since JRobin is the default and RRDtool requires that some JNI code is compiled against the current operating system's libraries, RRDtool is now completely optional.
So if you don't care about using RRDtool, you don't have to do
anything. If you do want to use RRDtool, be sure to install the jrrd
package. Then edit the rrd-configuration.properties
file in the OpenNMS "etc
" directory and
uncomment:
# To switch to the JNI implementation uncomment the following lines: #org.opennms.rrd.strategyClass=org.opennms.netmgt.rrd.rrdtool.JniRrdStrategy #org.opennms.rrd.interfaceJar=/usr/share/java/jrrd.jar #opennms.library.jrrd=/usr/lib/libjrrd.jnilib
We require no special configuration for using RRDtool. As long as it was installed as a package, the OpenNMS package should be able to find it and configure itself to use the proper commands.
Note: If you install RRDtool in a location other than /usr/bin, you
should edit the
$OPENNMS_HOME/webapps/opennms/WEB-INF/configuration.properties
file and set the correct path.
PostgreSQL (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.
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.
OpenNMS requires version 7.4 or later of PostgreSQL, although 8.1 is recommended.
The minimum packages you will need to install should be:
postgresql-server
Note that Red Hat Enterprise Linux 3 and CentOS 3 call their PostgreSQL packages "rhdb" for the "Red Hat DataBase" and older releases of SuSE call their packages "postgres".
Once you have installed Postgres, you will need to make two changes
to Postgres configuration files: postgresql.conf
and
pg_hba.conf
. These files are only created once
Postgres 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 /etc/init.d
.
Locate the Postgres "data" directory. Often this is /var/lib/pgsql/data. You should then find the two files we need to modify in that directory.
This file controls some basic parameters of Postgres. We need to change three of these parameters.
Find the line in the file that contains
tcpip_socket
. It needs to read (this can be
ignored on PostgreSQL 8.0 and later as this is the default):
tcpip_socket = true
Make sure that there is no comment character ("#") in front of that line (or the other two that you change). This will enable OpenNMS to talk to the database.
Find the line in the file that contains
max_connections
. It needs to read:
max_connections = 256
Find the line that contains shared_buffers
.
It needs to read:
shared_buffers = 1024
The pg_hba.conf
file controls which machines
and users can access the database on a given machine via TCP/IP.
Since that is how OpenNMS accesses the database (via
localhost
) 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):
# 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
Make sure that no other lines are uncommented in this file.
You will need to stop and restart Postgres after making these changes.
You will need to create an opennms
database.
As the postgres
user, go to the
/usr/local/pgsql/bin
directory, and run the
following command:
#
./initdb -D /usr/local/pgsql/data -E ""
This will create the database. Following the instructions in the
section above, modify the pg_hba.conf
and
postgresql.conf
files.
Then you'll need to start the database:
#
./pg_ctl -D /usr/local/pgsql/data start
Now you are finished as the postgres
user.
OpenNMS makes heavy use of a function called "iplike". Since it is written in C, it has been removed from the main OpenNMS code and placed in its own project.
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.
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 and do the usual "configure", "make", and "make install". Once installed it should not be required to update it again.
Table of Contents
You need to be root when you execute the commands in this chapter.
Follow the instructions in either the fresh install section or the upgrade section, and then continue to the section on running the installer. If you have any errors during the installation process, please see the troubleshooting section of this guide.
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).
With OpenNMS 1.3.6, this code has been moved to its 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.
However, now jicmp has to be installed. The goal is to provide packages for most distributions via our online repositories. If packages are not yet available for your distribution, you will need to build jicmp from source. For RPM-based Linux distributions, the source code tarball can be fetched from Sourceforge, and the command
rpmbuild -tb [source tarball filename]
executed to create an RPM. Otherwise the source tarball can be extracted and the usual "configure; make; make install" run to compile and install it. It should be installed before continuing.
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.
Download the appropriate packages for your Linux distribution from the OpenNMS Files section on SourceForge.
#
rpm -i opennms-@product.version@-@product.release@_<distribution>.<platform>.rpm#
rpm -i opennms-webapp-@product.version@-@product.release@_<distribution>.<platform>.rpm#
rpm -i opennms-docs-@product.version@-@product.release@_<distribution>.<platform>.rpm
Download the appropriate package for your Solaris version from the OpenNMS Files section on SourceForge.
#
cd /usr/local#
gzip -d opennms-@product.version@-@product.release@-sol<version>-sparc-local.gz#
pkgadd -d `pwd`/opennms-@product.version@-@product.release@-sol<version>-sparc-local
OpenNMS is supported on Mac OS X via the fink project.
Upgrades from a previous version of OpenNMS to a current one usually just involve installing a new package for your particular distribution.
For RPM-based distributions, this is pretty simple using the
"rpm -Uvh [package name]
" command.
In addition, the OpenNMS installer may attempt to make changes to the database. Follow the instructions later in this chapter for executing the installer. The changes should go smoothly, but as with the best laid plans things may go wrong. Make a backup of your PostgreSQL database per the details below before upgrading in case there are problems.
To upgrade from 1.2.x to 1.3.x check out the wiki page.
OpenNMS stores data in a number of locations:
$OPENNMS_HOME/etc/
OpenNMS configuration files. If the default structure of a
file in $OPENNMS_HOME/etc
has changed between
versions, RPM will create a
"
" version of
that file. You will need to look at the changes between your file
and the new one and merge them manually, at the moment. The
command ".rpmnew
diff -u <old file> <new file> |
less
" can assist you in seeing what has changed.
$OPENNMS_HOME/share/rrd/
RRD data files that store response time data and performance
data collected from SNMP. The installer should not touch the RRD
files in $OPENNMS_HOME/share/rrd.
Unless you
are moving from RRDTool to jRobin, you should not have to worry
about them.
$OPENNMS_HOME/webapps/opennms/
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.
$PGDATA/
Data about nodes, services, events, notifications, etc., are
stored in the opennms
table in PostgreSQL.
Things can go wrong on upgrades, so it is always a good idea to make a backup of important information before attempting the upgrade.
For OpenNMS, you should do a few things:
Copy the contents of the
$OPENNMS_HOME/etc
directory to a safe location.
Should an issue arise with any new files, you will want to be able
to recover your original.
Make a backup of the postgres database. Using the
pg_dumpall
command you can dump the entire
contents of the database to a file:
#
pg_dumpall > old_data
will copy all of the data to a file called
old_data
. You will want to run this as the
"postgres" user:
#
sudo -u postgres pg_dumpall > old_data
To restore, run the command:
#
sudo -u postgres psql -U postgres -f old_data template1
If you have made changes to the web application, you will want to save a copy of your changes, as well.
As mentioned earlier, there should be no need to backup the RRD files during an upgrade.
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 installer. This tool will setup the opennms
database
within PostgreSQL and also install the OpenNMS web application ("webapp"
or the "webUI") into Tomcat.
Before you execute the installer, OpenNMS needs to be configured
to use an appropriate Java Runtime Environment (JRE). The OpenNMS tool
runjava
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.
Execute runjava
with the "-s
"
option to search for a JRE:
#
$OPENNMS_HOME/bin/runjava -s
#
$OPENNMS_HOME/bin/install -l /usr/local/lib -dis
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.
Table of Contents
OpenNMS has a default host discovery configuration that probably
does not fit your organization. Edit
$OPENNMS_HOME/etc/discovery-configuration.xml
. You'll
see something like this:
<discovery-configuration threads="1" packets-per-second="1" initial-sleep-time="300000" restart-sleep-time="86400000" retries="3" timeout="800"> <include-range retries="2" timeout="3000"> <begin>192.168.0.1</begin> <end>192.168.0.254</end> </include-range> <include-url>file:/opt/OpenNMS/etc/include</include-url> </discovery-configuration>
You will most likely want to change the beginning and end ranges
(within the <begin>
and <end>
tags,
respectively). And you can add multiple <include-range>
entries to fit your needs. If you would rather list the individual hosts
that you want to have discovered, you can insert
<specific>
tags above the
<include-range>
tag or place them in the file referrred
to by <include-url>
, one IP address per line. Lastly,
if you prefer to use the web interface to add hosts for OpenNMS to
monitor, you can comment out the contents of this file completely (put
"<!--
" before the first line and "-->
"
after the last line).
Point your browser at
http://<host>:8080/opennms/
(port 8180 on
Debian Linux). The initial user name is "admin
" and the
password is "admin
".
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.
The OpenNMS packages add an init script in
/etc
(usually /etc/init.d
),
however you need to execute chkconfig
to enable the
service to start automatically:
#
chkconfig --add opennms
Table of Contents
OpenNMS is a complex software product, and it does not (yet) have a
simple "./configure && make && make install
"
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.
The best place to find out how to build OpenNMS is from the developer's page on the wiki. You will need to check out the code and then build it.
Table of Contents
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.
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 FTP
site and check in the /pub/dependencies
directory.
In addition, sites like Ibiblio and FreshRPMs are also good
sources.
This can happen for a a number of reasons. You can run
"opennms -v status
" 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:
OpenNMS takes a while to startup. This can happen on larger
installations and when this happens "opennms -v status
"
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
$OPENNMS_HOME/etc/opennms.conf
and adding a
line like "START_TIMEOUT=20
" to double the number of
times it tests. You can set the value to 0
to have the
startup script not wait for OpenNMS to start.
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 FATAL
errors in the log files. You'll see
something like "Error accessing database
" in the
logs.
Dhcpd doesn't start. See the item in the next section.
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.
Other. If the OpenNMS is installed, and the packages were not
forced in using options like "--nodeps
", the
application should run just fine. If not, OpenNMS has a robust
logging facility. Change to the logs directory (usually
/var/log/opennms
) and search the logs, using
grep
or your tool of choice, for words like
FATAL
and ERROR
(the two highest log
severities). Those events should give you clues as to why OpenNMS is
not working.
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 "opennms -v status
" and
seeing everything in the running
state, except for
Dhcpd
. The solution is to edit
$OPENNMS_HOME/etc/service-configuration.xml
and
comment-out the "<service>...</service>
" stanza
for Dhcpd
. For example, this is what the section would look
like after modification to disable Dhcpd
:
<!-- 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> -->
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.
The
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 runjava
runjava
cannot find, you
can use its "-f
" option to specify the JRE you want OpenNMS
to use.
You either need to set "lc_messages = 'C'
" in your
postgresql.conf file and restart PostgreSQL or upgrade to PostgreSQL 7.4
or later.
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).
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
'C
' 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.
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.
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.
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
node
are copied into
node_old_11033991291234
). 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.
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.
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
node
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.
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,
node_old_11033991291234
, no other
node_old_*
tables, and no node
table, you can simply rename the table:
# psql -h localhost -U opennms opennms
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=#
ALTER TABLE node_old_11033991291234 RENAME TO node;
You can use the "\d" command within psql
to
see what other tables exist in your database. You can use "SELECT
count(*) from table;
" (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.
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 must not point at a node that does not exist.
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:
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 "$OPENNMS_HOME/bin/install -C <constraint>
-X
" to delete the offending rows.
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 "$OPENNMS_HOME/bin/install -C
<constraint>
" to mark the key column to NULL in the
offending rows.
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.
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.
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.
The latter part of the error could be something like
"<path>/iplike.so: cannot open shared object file: No such
file or directory
" or "ld.so.1: postgres: fatal:
<path>/iplike.so: wrong ELF class: ELFCLASS32
".
The PostgreSQL server cannot load the iplike.so
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 iplike.so
shared object is
compiled for a 32-bit instruction set, although the opposite is
possible, as well. You can use the "file
" command on
iplike.so
and the postmaster
binary with
PostgreSQL to check their instruction sets.
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
iplike.so
file was compiled for. For advanced users, you
can compile OpenNMS yourself to fit the processor set that you need. See
this
post to the discuss list for some pointers.
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.
To get around this, run the following commands:
stop postgres
rm -rf /var/lib/pgsql/data
/usr/sbin/setenforce 0
start postgres
Note that step 2 will delete any changes you made to the postgresql configuration files and you'll need to redo them.
An exact example of this error is:
"java.io.FileNotFoundException: /opt/opennms/etc/users.xml
(Permission denied)
".
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.
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).
Check the release notes for this release. They are in the Documentation section of the OpenNMS project page at SourceForge.
The main OpenNMS site 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 FAQ, the bug database and Google before posting to a mailing list. You might also find useful information in the old FAQ, but please realize that this information may be out of date.
OpenNMS maintains a number of active mailing lists on SourceForge:
A low traffic, moderated mailing list for OpenNMS announcements. All posts to this list are duplicated on the opennms-discuss list.
This is a fairly high traffic list of all updates to the CVS repositories on SourceForge. Moderated. Only CVS updates are posted here (no discussion).
This list is for code development discussion.
This is the main OpenNMS discuss list. It's pretty friendly. Pretty much anything goes here, however it is suggested that installation-related issues to go opennms-install.
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.
Whether or not to use maps in network management is as divisive an issue as abortion or gun control (grin). OpenNMS does have a small contributed map system, which still needs a lot of work. We can talk about it here.
We have a small users group in Tokyo, Japan. This list is for meeting announcements or help in Japanese.
The OpenNMS mailing lists are also archived at gmane.org.
If you are using OpenNMS in a production environment, or are considering it, you might be interested in commercial support. The OpenNMS Group maintains the OpenNMS project, and we also offer support, training, consulting services and custom development.