This process includes all the currently known caveats associated
with the ONMS 1.1.2 packages. All the installation operations should
be performed as the root user. The vi editor is used by the author
of this document. It is recommended to install
vim in order to use the
:syn on command to enable syntax highlighting and reduce the chance
of an error. Additionally
sshd should be installed for remote administration.
Please do not use telnet.
/etc/apt/sources.list to include the OpenNMS apt server.
A typical sources.list file with the OpenNMS source as the last line
might look similar to this:
deb http://debian.yorku.ca/debian/ stable main non-free contrib deb http://non-us.debian.org/debian-non-US stable/non-US main contrib non-free deb http://security.debian.org/ stable/updates main contrib non-free deb http://debian.opennms.org/ debian/opennms stable
This particular /etc/apt/sources.list contains no deb-src lines
(for downloading package source files) or deb cdrom: lines (for downloading
packages from a distribution cdrom). These lines are often part of
the default apt configuration, and are unnecessary when using the
Internet as the package installation source (recommended) and are
not planning on modifying and recompiling packages (development).
The deb cdrom: lines can cause particular annoyance when they prompt
to insert specific cds into the drive when attempting package installations.
Details on obtaining the package source for OpenNMS can be found
in the
OpenNMS apt sources section.
bash#apt-get update
Look for output lines similar to the following to indicate a successful update of the OpenNMS sources:
Get:1 http://debian.opennms.org debian/opennms/stable Packages [4706B] Get:2 http://debian.opennms.org debian/opennms/stable Release [92B]
If this action has already been performed, a re-execution of the command will indicate a successful match to the previously downloaded OpenNMS source list:
Hit http://debian.opennms.org debian/opennms/stable Packages Hit http://debian.opennms.org debian/opennms/stable Release
A successful package list update will be followed by two lines of output with no error or warning messages:
Reading Package Lists... Done Building Dependency Tree... Done
Any error output here must be dealt with before proceeding. Often
this related to unavailable sources, or typos in the /etc/apt/sources.list
file. Feel free to simply cut and past the above
list if problems occur
here.
bash#apt-get upgrade
Next is a prompt to accept packages upgrades. Generally speaking, hit enter a few times here to bring a system up to the latest versions. For more information on the Debian apt package management system refer to the official Debian apt HOWTO.
bash#apt-get install java-common xlibs gcc bzip2 lynx make libstdc++2.9-glibc2.1 sun-jdk1.4-installer
Some of these packages may exist already, and several additional packages will be added to support dependencies.
bash#lynx http://java.sun.com/webapps/download/Display?BundleId=7016
The BundleId in the above URL is for J2SDK 1.4.0_02. Follow these
instructions on this page.
Y), and navigate
down the page using the pgdown and downarrow keys to the ACCEPT link
at the bottom of the page and select the link using the Enter key.Download j2sdk-1_4_0_02-linux-i586.bin
link and select it using the Enter key.D to download the binary file as an octet-stream. Once
the download is complete, press Enter twice to save the binary file
to disk with the default file name. Use q to exit.
/usr/src.
bash#cp j2sdk-1_4_0_02-linux-i586.bin /usr/src
[]are fine including the remove all files
cleanup).
bash#build-sun-jdk14
Without installing the xlibs packages, the Sun JDK will build with the following error messages, and maps will not work. Ensure that the xlibs dependency is met. Details on installing xlibs and reinstalling the Sun JDK are in the troubleshooting section.
dpkg-shlibdeps: warning: could not find path for libXp.so.6 dpkg-shlibdeps: warning: could not find path for libXt.so.6 dpkg-shlibdeps: warning: could not find path for libXext.so.6 dpkg-shlibdeps: warning: could not find path for libXtst.so.6 dpkg-shlibdeps: warning: could not find path for libX11.so.6
bash#apt-get install opennms libgetopt-mixed-perl
The PostgreSQL installation will prompt for a default encoding.
Accepting the default SQL_ASCII is fine. The OpenNMS databases are
automatically created with UNICODE encoding. The getopt-mixed-perl
package is optional and will allows a person to manually add interfaces
to OpenNMS without modifying the configuration files, a.k.a Generating
a new suspect event. A transcript of the typical installation process
is included in
Appendix D.
In certain circumstances the opennms-db package is unable to connect to the database. When this problem occurs there will be the output shown below.
- reading table definitions... OK DBI->connect(dbname=template1) failed: could not connect to server: No such file or directory at /usr/share/opennms-db/install.pl line 250 *** Unable to connect to the database!! *** Be sure PostgreSQL is started and running correctly before running this install script! could not connect to server: No such file or directory dpkg: error processing opennms-db (--configure): subprocess post-installation script returned error exit status 255
In this situation, simply re-run the installation.
bash#apt-get install opennms
Note: This step completes the package installation process to
satisfy apt, however it accomplishes proper execution of the installation
script and is equivalent to running the following command to create
the database structures and add the OpenNMS context to the server.xml
file.
bash#/usr/share/opennms/bin/install.pl /etc/opennms/create.sql
The transcript of this installation process that includes the error output is included in Appendix E.
These minor post-install modifications have been addressed in the discussion mailing list and should no longer be required in future releases of OpenNMS.
In certain circumstances the polling for SMB connections will
cause a timeout of the pollers and disable the OpenNMS server. To
avoid this problem the /etc/opennms/capsd-configuration.xml must
have a valid username, password and domain for all polled devices.
If this cannot be completed reliably, disable this poller to avoid
problems. If delays in rescanning occur with OpenNMS starting its
pollers this could be the cause. More information is available
here.
The SSH poller is a modified version of the TCP poller that reduces
the amount of logging on the polled sshd service. Unfortunately prolonged
use of this plugin, which submits a version number, can cause the
sshd service to spawn to its maximum processes, effectively causing
a temporary DoS. The problem is resolved by stopping OpenNMS. To
eliminate this problem completely modify the /etc/opennms/capsd-configuration.xml
line
<protocol-plugin protocol="SSH" class-name="org.opennms.netmgt.capsd.SshPlugin" scan="on" user-defined="false">
to use the TcpPlugin by replacing the word SshPlugin as follows:
<protocol-plugin protocol="SSH" class-name="org.opennms.netmgt.capsd.TcpPlugin" scan="on" user-defined="false">
The server.xml file is not properly modified by the Debian postinst scripts. As such the following OpenNMS context must be added to the server.xml file in order to log into OpenNMS. This can be accomplished by executing the following command:
bash#/usr/share/opennms/bin/install.pl -i /usr/share/opennms/etc/create.sql
This script is identical to the script executed during the package installation, except it is now invoked without the -t option allowing for modification of the Tomcat configuration. The following two lines of output indicate the change has occurred,
- checking Tomcat 4 for OpenNMS web UI... UPDATING: - adding OpenNMS web UI context to server.xml... DONE
/etc/postgresql/postgresql.confEnsure the following parameters are set
tcpip_socket = true max_connections = 256 shared_buffers = 1024
With 256MB of RAM the JAVA_HEAP_SIZE in /usr/share/opennms/bin/opennms.sh
should be modified from 256 to 128 (megabytes).
Currently OpenNMS has file permissions that require it to run itself and the tomcat4 service as root. To modify the tomcat4 configuration to do this, first stop the tomcat4 service.
bash#/etc/init.d/tomcat4 stop
To make the change edit the /etc/default/tomcat4 file to include
TOMCAT4_USER="root".
If /etc/default/tomcat4 is modified before the tomcat4 service
is stopped first or there may be
problems loggin into the OpenNMS console.
Once the above modifications have been committed, the Tomcat4 server will need to be restarted.
bash#/etc/init.d/tomcat4 start
The OpenNMS configuration HOWTOs written by Tarus Balog are the bread and butter of understanding how to configure OpenNMS. Reading these documents is a must for anybody new to OpenNMS or revisiting their configuration. Of course Part 1 can be skipped, as it does not apply to Debian users. Please read these HOWTOs prior to using OpenNMS, and additionally review the online FAQ headings to gain familiarity with the interface and types of information available there. Please read these documents before submitting questions to the mailing lists. The following summaries list some of the questions answered by each of Tarus' HOWTOs. IF THE ANSWERS TO THESE QUESTIONS ARE NOT KNOWN, please read these HOWTOs. They are available online at the OpenNMS.org Documentation page. Just read them, it does not take very long (i.e. they are a lot more concise than this HOWTO).
Please read the OpenNMS 1.1.2 Release Notes
Part 2 describes the configuration files /etc/opennms/discovery-configuration.xml,
/etc/opennms/capsd-configuration.xml and /etc/opennms/snmp-config.xml
. It answers the following questions and much more:
What interfaces and/or networks do I want to monitor?
How aggressively do I want to discover these interfaces?
When do I probe for new interfaces and services on my network?
How do I discover a new node without restarting OpenNMS?
What services do I discover on each interface, and how often do I rediscover them?
What interfaces have which SNMP community strings and support what SNMP version?
Part 3 describes the configuration file /etc/opennms/poller-configuration.xml.
It answers the following questions and much more:
Which interfaces do I poll to determine what services are up or down?
How frequently do I poll each service and interface?
When do I ignore events due to maintenance windows?
How does the polling frequency change when a service is down?
Part 4 describes the configuration files /etc/opennms/snmp-config.xml,
/etc/opennms/collectd-configuration.xml and /etc/opennms/datacollection-config.xml
. It answers the following questions and much more:
What interfaces have which SNMP community strings and support what SNMP version?
How many concurrent collection threads will occur?
Which interfaces belong to what collection package?
Which collection packages collect what service data (i.e. SNMP)?
What maximum size SNMP PDU will be collected?
Where will RRD files be stored?
What is the RRD file structure going to be?
What SNMP OIDs are in which collection groups?
Which collection groups are associated with which systems?
What SNMP system OID associates systems with actual interfaces?
How does OpenNMS know what data to collect from which SNMP agent?
Part 5 describes the configuration files /etc/opennms/eventconf.xml,
/etc/opennms/collectd-configuration.xml and /etc/opennms/datacollection-config.xml
. It answers the following questions and much more:
Where does OpenNMS listen for events?
How do I customize event messages?
How do I control what happens when an event arrives?
How do I suppress certain events, or keep them from entering the database?
What severity does each event have?
How are events like the movie Spinal Tap?
How do I customize event notification messages?
How do I extract SNMP Trap varbinds?
How do I browse the event database using psql?
A correction to Part 5 on how the dest attribute works should be included soon.
There is a document on KSC Reports that answers the following questions:
What is a KSC Performance Report?
What is a Node Report?
How do I make my own KSC report?
How do I add a graph to a report?
How do I modify a graph?
How do I view a report?