OpenNMS?? Installation Guide
|
Preface |
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 Blast Internet Services, which also owns the OpenNMS trademark.
The OpenNMS Project strives to remain independent, and includes contributions from people outside of Blast. Please visit the OpenNMS website for more information.
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-2004 Blast Internet Services, Inc.
Original code base for OpenNMS version 1.0.0 ?? 1999-2001 Oculan Corporation.
Mapping code Copyright ?? 2003 Networked Knowledge Systems, Inc.
ScriptD code Copyright ?? 2003 Tavve Software Company.
Installing OpenNMS - An Overview |
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
Distribution Specific Installation Instructions
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 Linux (many distributions), Solaris and Mac OSX.
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.
Minimum Requirements
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.
Processor: 1 GHz Pentium III class or better. OpenNMS will benefit from more processors.
Memory: 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.
Disk Space: 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.
Download
OpenNMS is available for download from Sourceforge on the OpenNMS download page. Install the dependent packages per this document, and read the release notes to insure that your installation goes smoothly.
Prerequisite Applications for OpenNMS |
This section will discuss the applications needed to support OpenNMS. They include:
Java (most of OpenNMS is written in Java)
Tomcat4 (this is used as the servlet container for our web-based user interface)
RRDtool (used for storing time series data and for generating performance graphs)
PostgreSQL (our back end database for storing events and device information)
Perl-DBD-Pg and Perl-DBI (for the initial setup of the database)
Metamail (to assist with mailing PDF attachments for availability reports)
The actual packages needed will differ depending on your operating system and version, but the required configuration will be the same.
If you are having trouble finding particular packages, check out the OpenNMS FTP site at ftp.opennms.org.
Java
OpenNMS is written mainly in Java (there are a few JNI calls to some C code in order to implement things such as ICMP, as well as some small Perl scripts to assist with the install), and so it follows that Java would need to be installed.
As the current code has a small dependency on a Sun-only library ("com.sun.net.ssl.internal.www.protocol" in the HTTPS Monitor), it is recommended that Sun's SDK is used. It should be possible to use IBM's SDK, but you'll get an error in the logs when the poller starts.
Note that I said "SDK". It is important to install the SDK instead of the JRE, as Tomcat will need to compile Java code (which requires "javac" in the SDK).
If you are attempting to install version 1.1.3 or later, you will need to use Java version 1.4.2 or later. You can get it from Sun's website. Step through the licensing process and then download the proper version of Java for your operating system.
Note: If you are using Linux, unless it is Debian you'll want to download the RPM (see my comments about package management earlier). For Debian you'll need the ".bin" file, and you'll need to follow the instructions for Debian in the next chapter.
If you are attempting to install version 1.1.2 or earlier, you cannot use 1.4.2 (it will cause memory leaks). You will need to use something earlier, and from experience the proper version is 1.4.0, release 2.
Tomcat4
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.
The latest version of Tomcat is Tomcat5, but we have not been tested against that yet. For version 1.1.0 of OpenNMS and later, we require at least Tomcat 4.1.18. For version 1.0, you must use Tomcat 4.0 in order to get the navigation links to work properly. This is due to a change that the Tomcat team made between 4.0 and 4.1.
If you have 4.0 installed and want to install 4.1, you may need to remove 4.0 first.
We need to make a few changes to Tomcat. Most of these should be done via the installer, but you will need to make two changes manually.
You'll need to find the tomcat4.conf
file (it's
in /etc/tomcat4/
on the Red Hat/Fedora series of
Linux distributions). It looks like this:
# tomcat /etc/rc.d script example configuration file # Use with version 1.07 of the scripts or later # Use Jpackage utils if present if [ -x /usr/bin/java-functions ]; then . /usr/bin/java-functions set_jvm fi # Source Java system configuration if exist if [ -r /etc/java/java.conf ]; then . /etc/java/java.conf fi # you could also override JAVA_HOME here # Where your java installation lives # JAVA_HOME="/usr/java/jdk" # JAVA_HOME="/opt/IBMJava2-131" # You can pass some parameters to java # here if you wish to #JAVACMD="$JAVA_HOME/bin/java -Xminf0.1 -Xmaxf0.3" # Where your tomcat installation lives # That change from previous RPM where TOMCAT_HOME # used to be /var/tomcat. # Now /var/tomcat will be the base for webapps only CATALINA_HOME="/var/tomcat4" JASPER_HOME="/var/tomcat4" CATALINA_TMPDIR="/var/tomcat4/temp" # What user should run tomcat TOMCAT_USER="tomcat" # You can change your tomcat locale here #LANG=en_US # If you wish to further customize your tomcat environment, # put your own definitions here # (i.e. LD_LIBRARY_PATH for some jdbc drivers) # Just do not forget to export them
The two changes we need to make involve JAVA_HOME
and TOMCAT_USER
.
Add a line for JAVA_HOME
that points to your
installation of JAVA. For example:
JAVA_HOME="/usr/java/j2sdk1.4.2_04/"
Now the second thing you need to do involves the Tomcat user. You have two choices:
The Easier Way: Just set the Tomcat user to "root":
TOMCAT_USER="root"
Note that this does open a potential security risk, although a minor one.
The Harder Way: You add the "tomcat" and "root" users to the "tomcat4" group, and then change permissions so that the "tomcat4" 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 -
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:
tomcat4: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
command:
chgrp -R [opennms_etc_dir]
chmod -R g+w [opennms_etc_dir]
where [opennms_etc_dir]
is the OpenNMS
"etc" directory.
Locate the OpenNMS "logs" directory. This is usually
/var/log/opennms
, and can be found by looking
in the log4j.properties file in the OpenNMS "etc" directory (find
an instance of "File"). Run the command:
chgrp -R [opennms_logs_dir]
chmod -R g+w [opennms_logs_dir]
where [opennms_logs_dir]
is the OpenNMS
"logs" 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.
Once OpenNMS is installed, it will need to make some changes. These should happen automatically, but I'll list them here for completeness.
First, in the CATALINA_HOME
directory (usually
/var/tomcat4
), you should see a subdirectory called
"webapps". The OpenNMS webapp directory will need to either be a
sub-directory in webapps or linked from there. The OpenNMS installer
should do this.
Second, also in the CATALINA_HOME
directory
should be a sub-directory called conf
. In that
directory is a file called server.xml
. We need to add
a "context" to that file in order for Tomcat to know where OpenNMS lives.
The installer should also do this update, but for reference it looks
like:
<!-- Example Server Configuration File --> <Server ... ... ... <Host ... > .... <Context path="/opennms" docBase="opennms" debug="0" reloadable="true"> <Logger className="org.opennms.web.log.Log4JLogger" homeDir="/opt/OpenNMS"/> <Realm className="org.opennms.web.authenticate.OpenNMSTomcatRealm" homeDir="/opt/OpenNMS"/> </Context > </Host > ... </Service >
Finally, Tomcat will also need to be aware of various opennms JARs
and libraries which provide the java classes which make these directives
work. To give tomcat access to these resources, links are created in
$CATALINA_HOME/server/lib
pointing to the locations
of the following OpenNMS JARs:
castor-0.9.3.9.jar ->
/opt/OpenNMS/lib/castor-0.9.3.9.jar
log4j.jar ->
/opt/OpenNMS/lib/log4j.jar
opennms_common.jar ->
/opt/OpenNMS/lib/opennms_common.jar
opennms_core.jar
-> /opt/OpenNMS/lib/opennms_core.jar
opennms_services.jar ->
/opt/OpenNMS/lib/opennms_services.jar
opennms_web.jar
-> /opt/OpenNMS/lib/opennms_web.jar
Note that the OpenNMS installer should make all of these changes, but if you are having problems accessing the web UI or logging on, these are things to check.
RRDtool
RRDtool is the genesis of probably the first widely used open-source network management tool, MRTG.
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.
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. We are known to work with any "1.0" version of RRDtool since 1.0.33.
PostgreSQL
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 of Postgres. Version 1.1 of OpenNMS requires a version of at least 7.2.
The minimum packages you will need to install should be:
postgresql
postgresql-server
postgresql-libs
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.
The postgresql.conf file
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:
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
Starting with Postgres 7.2 the "host-based authentication" file was added. This 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:
# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD local all all trust host all all 127.0.0.1 255.255.255.255 trust
Make sure that no other lines are uncommented in this file.
You will need to stop and restart Postgres after making these changes.
The Perl modules perl-DBI and perl-DBD-Pg
While OpenNMS is moving toward being as completely Java as possible, we still use a bit of Perl in the installation as well as in mailing availability reports.
Prior to 1.1.3, the install.pl script was used to create the initial OpenNMS database. If you are using a version of OpenNMS prior to 1.1.3, you'll need to have these two Perl modules installed.
As I have mentioned earlier, the easiest way for OpenNMS to know
that these modules are installed is if they are installed via packages.
The OpenNMS FTP site, ftp.opennms.org has compiled these
packages on a number of platforms (in the
/pub/dependencies
directory). Also, the application
cpan2rpm
can create these packages for you.
If you are installing a version prior to 1.1.3, please insure that these packages are installed.
The metamail Application
Since OpenNMS uses Perl to mail availability reports, with some
mailers it is necessary to add the metamail
application in order for the PDF files created by OpenNMS to be mailed
properly.
Like the Perl modules in the above section,
metamail
can be found on the OpenNMS FTP site (which
includes and SRPM) if metamail is not directly available for your
distribution.
Platform-Specific OpenNMS Installation Notes |
Debian
OpenNMS is supported on Debian, and can be installed using apt. However, due to licensing issues, we cannot distribute a version of Sun's Java SDK, so some extra steps are required.
Woody
Add the following to /etc/apt/sources.list and update, (i.e. "apt-get update"):
deb http://debian.opennms.org/ debian/opennms stable
Then obtain and install a suitable version of java.
Because of licensing issues, a suitable java sdk cannot be distributed with OpenNMS so you will have to obtain and install one yourself prior to installing OpenNMS. You have several options here:
Use the sun-jdk1.4-installer package and build script to download the j2sdk from Sun and build your own j2sdk1.4 package, (recommended).
Building and installing a j2sdk1.4 package:
The java-common package is a dependency for the j2sdk1.4 package you will be creating, and since it will be installed by dpkg, APT will not be there to pull it in so install it first.
[root@host /root]# apt-get install java-common
Next, install the sun-jdk1.4-installer package
[root@host /root]# apt-get install sun-jdk1.4-installer
Download the 1.4.2 SDK from Sun, get the non-RPM binary package
Then run the following command:
[root@host /root]# build-sun-jdk14 ./j2sdk-1_4_2_05-linux-i586.bin
where j2sdk-1_4_2_05-linux-i586.bin
is the binary file you downloaded from Sun.
Obtain and install and your own version and meet the OpenNMS packages dependencies by installing the java-virtual-machine meta package.
[root@host /root]# apt-get install java-virtual-machine
Then, install OpenNMS:
[root@host /root]# apt-get install opennms
Optionally install the documentation and/or contrib packages
[root@host /root]# apt-get install opennms-doc opennms-contrib
Sid
Add the following to /etc/apt/sources.list and update, (i.e. "apt-get update"):
deb http://debian.opennms.org/ debian/opennms unstable
Then obtain and install a suitable version of java.
Because of licensing issues, a suitable java sdk cannot be distributed with OpenNMS so you will have to obtain and install one yourself prior to installing OpenNMS. You have several options here:
Use the sun-jdk1.4-installer package and build script to download the j2sdk from Sun and build your own j2sdk1.4 package, (recommended).
Building and installing a j2sdk1.4 package:
The java-common package is a dependency for the j2sdk1.4 package you will be creating, and since it will be installed by dpkg, APT will not be there to pull it in so install it first.
[root@host /root]# apt-get install java-common
Next, install the sun-jdk1.4-installer package
[root@host /root]# apt-get install sun-jdk1.4-installer
Download the 1.4.2 SDK from Sun, get the non-RPM binary package
Then run the following command:
[root@host /root]# build-sun-jdk14 ./j2sdk-1_4_2_05-linux-i586.bin
where j2sdk-1_4_2_05-linux-i586.bin
is the binary file you downloaded from Sun.
Obtain and install and your own version and meet the OpenNMS packages dependencies by installing the java-virtual-machine meta package.
[root@host /root]# apt-get install java-virtual-machine
Then, install OpenNMS:
[root@host /root]# apt-get install opennms Optionally install the documentation and/or contrib packages
[root@host /root]# apt-get install opennms-doc opennms-contrib
Note: Recent versions of the Tomcat package in Sid, (unstable),
use jikes as the compiler instead of the javac from your toolkit. Open
up /etc/tomcat4/web.xml
in your favorite editor and
comment out the compiler init param
section.
Fedora
OpenNMS is supported on Fedora. Note that yum
and apt
for RPM repositories will be available
soon.
Fedora Core 1
There are no special requirements for OpenNMS on this distribution of Linux, except for those configuration issues mentioned in the previous section.
Fedora Core 2
There are no special requirements for OpenNMS on this distribution of Linux, except for those configuration issues mentioned in the previous section.
Mandrake
OpenNMS is supported on Mandrake. Note that
urpmi
repositories will be available soon.
Mandrake 8
There are no special requirements for OpenNMS on this distribution of Linux, except for those configuration issues mentioned in the previous section.
Mandrake 9
There are no special requirements for OpenNMS on this distribution of Linux, except for those configuration issues mentioned in the previous section.
Mandrake 10
There are no special requirements for OpenNMS on this distribution of Linux, except for those configuration issues mentioned in the previous section.
Red Hat
The following section refer to the supported versions of Red Hat
Linux. Note that yum
and apt
for
RPM repositories will be available soon.
Red Hat Linux 7
There are no special requirements for OpenNMS on this distribution of Linux, except for those configuration issues mentioned in the previous section. To use version 1.1. or later, you will need to install version 7.2 of Postgres (which was available in Red Hat Linux 7.3).
Red Hat Linux 8
OpenNMS is currently supported on Red Hat Linux 8, but version 1.2.0 will be the last version to support this operating system.
Red Hat Linux 9
There are no special requirements for OpenNMS on this distribution of Linux, except for those configuration issues mentioned in the previous section. Note that there was an issue with the RPM database "hanging" that might affect OpenNMS installation on a new system.
Red Hat Enterprise Linux 3
There are no special requirements for OpenNMS on this distribution of Linux, except for those configuration issues mentioned in the previous section.
SuSE
OpenNMS is now supported on SuSE.
SuSE Linux Enterprise Server 8
There are no special requirements for OpenNMS on this distribution of Linux, except for those configuration issues mentioned in the previous section.
SuSE Linux Pro 9
There are no special requirements for OpenNMS on this distribution of Linux, except for those configuration issues mentioned in the previous section.
Troubleshooting an OpenNMS Installation |
Common Installation Issues
The following section contains advice for overcoming common installation issues.
Dependency Problems
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,
like metamail
, 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.
The OpenNMS Application Won't Start
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 Web Application Will Not Start, or You Can't Log In
There are actually two main applications in the OpenNMS product: the application itself and the web-based User Interface (webUI). The webUI is implemented via Tomcat, and it is possible for Tomcat to be running and the OpenNMS application to be stopped and vice versa.
If you can't get to the OpenNMS interface
(http://[opennms server]:8080/opennms
or
http://[opennms server]:8180/opennms
on Debian -
where [opennms server] is the name of the OpenNMS machine) make sure
that Tomcat is running, and if necessary restart it. You should also be
able to access the main Tomcat page by leaving of the
"/opennms
".
Where to Get Help
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).
The OpenNMS Web Site
The main OpenNMS site is a Wiki. As a community project, there is a lot of good advice and information available there.
The OpenNMS Mailing Lists
OpenNMS maintains a number of active mailing lists on Sourceforge:
opennms-announce: A low traffic, moderated mailing list for OpenNMS announcements. All posts to this list are duplicated on the opennms-discuss list.
opennms-cvs: 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).
opennms-devel: This list is for code development discussion.
opennms-discuss: This is the main OpenNMS discuss list. Pretty much anything goes here. It's pretty friendly.
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.
opennms-maps: 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.
opennms-ug-tokyo: We have a small users group in Tokyo, Japan. This list is for meeting announcements or help in Japanese.
Commercial Support
If you are using OpenNMS in a production environment, or are considering it, you might be interested in commercial support. Blast Internet Services maintains the OpenNMS project, and we also offer support, training, consulting services and custom development.