![[LWN Logo]](/images/lcorner.png) |
|
![[LWN.net]](/images/Included.png) |
From: announce-admin@opennms.org
To: "Announce List" <announce@opennms.org>
Subject: [OpenNMS-Announce] OpenNMS Install Guide (DRAFT)
Date: Fri, 24 Aug 2001 12:26:58 -0000
Shane O.
========
Shane O'Donnell
OpenNMS.org
shaneo@opennms.org
==================
OpenNMS Installation Guide
OpenNMS.org
Published in 2001.
Revision: 2.0.
Copyright (c) 1999, 2000, 2001, PlatformWorks, Inc .
www.opennms.org
_________________________________________________________________
Introduction
Table of Contents
P Acknowledgments, Copyrights and Introduction
P.1 Introduction
1 Minimum Requirements
1.1 Minimum Requirements
2 Configuring Dependencies
2.1 Linux Kernel
2.2 PostgreSQL Configuration
2.3 TomCat
2.4 RRDTool
2.5 CPAN
2.6 JAVA
2.7 OpenJMS
3 Installation
3.1 Directory Structure
3.2 Installing OpenNMS from install.opennms.org
3.3 Installing OpenNMS from RPM
3.4 Installing OpenNMS binaries from Tar ball
3.5 Installing OpenNMS from source
4 Configuring OpenNMS
4.1 Configuring a package and poller
4.1.1 Adding addresses
4.1.2 Specifying services
4.1.3 Adding packages to a poller
4.2 Configuring the view
4.3 Configuring services
4.4 Configuring schedulers
5 Viewing the Network
5.1 Starting OpenNMS
5.2 Viewing the Network
_________________________________________________________________
P Preface
Acknowledgments, Copyrights and Introduction
Copyrights
Copyright (C) 1999-2001 PlatformWorks, Inc. All rights
reserved.
Copyright (c) 1996-2001 PostgresSQL, Inc.
Copyright (c) 1994 Regents of California, Inc.
Copyright (c) 1994-2001 Sun Microsystems, Inc
Copyright (c) 1994-2001 IBM Corporation
Copyright (c) 2001 Microsoft Corporation
Copyright (c) 2001 Netscape
Copyright (c) 2001 Red Hat, Inc.
Copyright (c) 1999-2001 ExoLab Group
Copyright (c) 1999-2001 Apache Software Foundation
Copyright (c) 1998-2001 The Mozilla Organization
Useful links for information
XSLFO Spec, Oct 2000
XSLFO Bible
XSL Info Site
XML Organization
Docbook Organization
O'Reilly's DocBook: The Definitive Guide
OpenNMS.org - OpenNMS web site
apache.org - home of Xerces, XML4J etc
Sun - home of JAVA
W3C Organization - home of XSLFO and XML
PostgreSQL - home of PostgreSQL
P.1 Introduction
The Install guide is used by more experienced administrators
and network managers to install, configure and run the OpenNMS
system. Administrators looking for a less detailed guide for
installation may refer to the Quick Start Guide.
_________________________________________________________________
1 Chapter 1
Minimum Requirements
1.1 Minimum Requirements
Prior to installation, take a moment to familiarize yourself
with the following requirements. Configuring dependency
software will be further discussed in the following chapter.
Resource Minimum Requirement Available Resources
OpenNMS Installation Media/File Version 8.1 or greater www.OpenNMS.org
Linux Op System SUSE 7.1, Redhat 7.0, probably others www.linux.org
PostgreSQL* Version 7.12 or greater www.postgresql.org
TomCat** Version 4.0b1 jakarta.apache.org
RRDTool*** Version 1.0.28 or greater rrdtool.eu.org
CPAN Libraries DBI + DBD:Pg www.cpan.org
JAVA Virtual Machine (JVM) Version 1.3 or greater
www6.software.ibm.com/dl/dklx130/dklx130-p
OpenJMS Version 0.6.2 or greater openjms.exolab.org
Free Disk Space 25Mb (+8Mb/SNMP Device) in /opt, 25Mb in /tmp
Free Memory 256 MB available
_________________________________________________________________
2 Chapter 2
Configuring Dependencies
If you are planning to use the web installer to install the RPMs for
OpenNMS and it's dependencies, you can skip to Chapter 3. If you have
any of the dependencies already installed, you will need to make sure
to read this chapter. Most newer kernels will meet the requirements,
and the installer script should take care of upgrading everything else
that you will need to run OpenNMS on your system.
2.1 Linux Kernel
Due to the large number of JAVA threads used to control
OpenNMS, you may need to recompile the linux kernel to handle
more tasks. In the header file include/linux/tasks.h in the
source directory set NR_Tasks to 4000. This should be plenty.
Most kernels will not need to be modified and can already
handle this many tasks. The following reflects the change that
should be made to the task.h header before recompiling.
#define NR_TASKS 4000
More information about compiling a new kernel can be found in
the Kernel-HOWTO
2.2 PostgreSQL Configuration
Postgres must be run with the '-i -p 5432' mode in order for
OpenNMS to make network connections to it on localhost port
5432. In additions the number of buffers needs to be modified.
Depending on your version of postgres, there may be
configuration files that you can modify to reflect these
changes. The configuration files are commonly found in
/var/pgsql/data and may or may not actually be read, again
depending on your version of postgres. In order to make sure
that this happens each time the system is reloaded, you can
modify the init script that should found in /etc/rc.d/init.d/
and should be called either postgres or postgresql. The line
that actually starts the postmaster process in this script
should start with the su command with a -c and a call to either
pg_ctl or postmaster, and look similar to one of the following
exapmles
su -l postgres -c "/usr/bin/pg_ctl -D $PGDATA -p /usr/bin/postmaster st
art"
or
su -l postgres -c "/usr/bin/postmaster -D /home/postgres/data"
and should be modified to reflect the '-i -p 5432 -B 256 -N
128' and look similar to one of the following lines
su -l postgres -c "/usr/bin/pg_ctl -o '-i -p 5432 -B 256 -N 128' -D $P
GDATA -p /usr/bin/postmaster start"
or
su -l postgres -c "/usr/bin/postmaster -i -p 5432 -B 256 -N 128 -D /hom
e/postgres/data"
While it is recognized that it is likely that noone will have a
line that looks EXACTLY like one of the preceeding, it should
be similar. You only need add the options mentioned above. DO
NOT rewrite the entire line.
2.3 TomCat
The OpenNMS install.pl script expects that tomcat is installed
in /var/tomcat4 and the environment variable TOMCAT_HOME should
be set to point to this directory
In order for the Tomcat server 4.0b1 to function properly with
OpenNMS you must replace 2 files in the $TOMCAT_HOME/server
directory. The files are crimson.jar and jaxp.jar and you can
find them on the OpenNMS website at
www.opennms.org/fom-serve/cache/55.html
Once you have copied these files you should stop and restart
the tomcat server using the following commands
$TOMCAT_HOME/bin/shutdown.sh
$TOMCAT_HOME/bin/startup.sh
Startup and shutdown can also be done at boot by linking these
scripts to the appropriate run level or by using other init
scripts.
2.4 RRDTool
If you plan on building OpenNMS from source, you need to make
sure you install RRDTool with the shared libraries. There is
information about this in the README file in the source
directory of rrdtool. The process basically consists of the
following
sh configure --enable-shared
make
make install
You will also need to tell OpenNMS where to find these
libraries. This is done in ~/.bb-global.properties and
explained in more detail in the source install section of this
guide.
2.5 CPAN
The CPAN libraries DBI and DBD:Pg need to be installed in order
to do a source build. The following commands should install
these packages
perl -MCPAN -e shell
install DBI
install DBD::Pg
2.6 JAVA
The JDK package is necessary for building from source. If you
are installing a binary distribution of the OpenNMS software
you will only need the runtime environment.(JRE) In either case
the environment variable JAVA_HOME should be set to
/opt/IBMJava2-13 or the directory where it was installed.
2.7 OpenJMS
OpenJMS 0.2.6 or greater needs to be installed and running
prior to starting OpenNMS. As of the creation of this document
version 0.2.6-Beta is available from
ftp://ftp.opennms.org/pub/misc/openjms or CVS
_________________________________________________________________
3 Chapter 3
Installation
3.1 Directory Structure
When installed, OpenNMS defaults to the following directories:
Location Directory
OpenNMS Binaries /opt/OpenNMS/
OpenNMS Config Files /opt/OpenNMS/data/common/conf/
SQL Libraries /usr/lib/pgsql/opennms/
Boot script /etc/rc.d/init.d/opennms
Database Store /var/
3.2 Installing OpenNMS from install.opennms.org
To install or upgrade on a supported RPM platform, run, as
root:
lynx -source http://install.opennms.org | sh
3.3 Installing OpenNMS from RPM
The following is the proceedure for installing OpenNMS binaries
from the RPM.
1. Login as the "root" user.
2. Check to make sure the RPM package is not already installed:
rpm -qa | grep -i opennms
3. Acquire the install RPM file(s) either from
installation media (CD) or across the Internet. For internet
download, go to www.OpenNMS.org Get the most current set of
RPMs
4. install the RPMs
rpm -Uvh ./*.rpm
3.4 Installing OpenNMS binaries from Tar ball
Determine which binary package you need based on the libc
version. If you are not sure which version you have, try
ls /lib/libc-*.so
Once you determine weather you need 2.1 or 2.2 download the
appropriate package and unpack it to a temporary directory.
From that point jump to step 6 of the source install.
3.5 Installing OpenNMS from source
Installation for OpenNMS on Linux systems is via RPM packages
or tar.gz build. Information on installation procedures for
RPMs is included in the quickstart guide.
The following is for building from the source tar bundle
1. Login as the "root" user.
2. Unpack source code
3. Make sure the following environment variables are set to the
correct locations
export BB_HOME=/opt/OpenNMS
export JAVA_HOME=/opt/IBMJava2-13
export TOMCAT_HOME=/vat/tomcat4
4. In order to let OpenNMS know where libraries and
includes live, you will need to create
~/.bb-global.properties file. It should look something like
this.
compile.include=-I/usr/local/pgsql/include -I/usr/include -I. -I/usr/lo
cal/rrdtool-1.0.33/include
compile.lib=-L/usr/local/pgsql/lib -L/usr/local/rrdtool-1.0.33/lib
5. from the source directory run the following command
./build.sh install
6. copy src/dist to opt/OpenNMS
cp -r dist/ /opt/OpenNMS/
7. copy files necessary for tomcat interface and create
links to server files
cp -r $BB_HOME/webapps/opennms $TOMCAT_HOME/webapps/opennms/
ln -s /opt/OpenNMS/bin/opennms_common.jar /var/tomcat4/server/opennms_c
ommon.jar
ln -s /opt/OpenNMS/bin/opennms_web.jar /var/tomcat4/server/opennms_web.
jar
ln -s /opt/OpenNMS/bin/xerces.jar /var/tomcat4/server/xerces.jar
8. run the install script for OpenNMS to create database
$BB_HOME/bin/install.pl $BB_HOME/data/temp/create.sql
_________________________________________________________________
4 Chapter 4
Configuring OpenNMS
This section describes some of the configuration files, and how they
relate to capabilities, performance, and appearance of OpenNMS.
Certain tasks may require the modification of several files in order
to achieve the desired affect. It is recommended that you read this
section carefully if you plan to do anything more than specify
addresses to monitor. Configuration files referenced in this chapter
should be located in $BB_HOME/data/common/conf unless specifically
annotated. Some examples are provided in this text, but there are many
more in the default configuration files.
4.1 Configuring a package and poller
Each package defines address(es) to be polled and service(s) to
be monitored. Package(s) can then added to a poller.
4.1.1 Adding addresses
The first task is assigning address to be polled. This
can be done by adding an include range to the package.
Within the ranges section of the package "example1" add
the range of addresses to include. The following is a
snippet from packages.xml. In this example we include the
network 192.168.0.0/24 and override the default values
for retries and timeouts.
<irange>
<parms>
<parm>
<parmName>retries</parmName>
<value>1</value>
</parm>
<parm>
<parmName>end</parmName>
<value>192.168.0.254</value>
</parm>
<parm>
<parmName>begin</parmName>
<value>192.168.0.1</value>
</parm>
<parm>
<parmName>timeout</parmName>
<value>5s</value>
</parm>
</parms>
</irange>
Addresses can be added specifically in the packages.xml
file or as part of a flat text file or "URL" file that
contains one address per line with no comments or blank
lines. The following are examples of the xml
configuration used to specify each.
<specific>
<parms>
<parm>
<parmName>IP Address</parmName>
<value>12.0.0.1</value>
</parm>
</parms>
</specific>
<url>
<parms>
<parm>
<parmName>URL</parmName>
<value>file:/opt/OpenNMS/data/common/webservers
</value>
</parm>
</parms>
</url>
The URL in the example1 package by default
(/opt/OpenNMS/data/common/include) is written by OpenNMS
when devices are managed or unmanaged.
4.1.2 Specifying services
Once you've decided on the addresses you wish to monitor,
you may be concerned with the types of services you wish
to be monitored within that package. Where one package
may contain only colocated web servers, and not be
concerned with database servers running on those
machines. Another package may have a much broader range
of concerns. Services included in the package must exist
in services.xml and should also have associated
schedulers set up as well. There are serveral services
set up already in the default package "example1". You may
override some of the default settings when specifying
them in packages. In the following example we have
included the UFO Detection Protocol on TCP port 4 with
our own timeout, retry, and polling interval.
<service>
<serviceName>UFODP</serviceName>
<parms>
<parm>
<parmName>banner</parmName>
<value>*</value>
</parm>
<parm>
<parmName>retry</parmName>
<value>3</value>
</parm>
<parm>
<parmName>port</parmName>
<value>4</value>
</parm>
<parm>
<parmName>interval</parmName>
<value>5m</value>
</parm>
<parm>
<parmName>timeout</parmName>
<value>3s</value>
</parm>
</parms>
</service>
4.1.3 Adding packages to a poller
Once your packages are created they must be attatched to
a poller. This is done in the pollersXML.xml file. Aside
from creating a poller and assigning packages to it, in
this file you can specify the "discovery limit" which
controls the number of pinger threads that are used
during the discovery process. Increasing this can speed
up the discovery process but will also require more
resources. The only caveat to this is that the number is
the result of a formula long since lost. It is my
understanding that it would be as easy to replace this
with a number that makes more sense, than it would to try
to recover the formula that was originaly based on
bandwith. This unfotunately is rather low on the priority
list. The best I can offer is to play with the number and
count discovery threads. You should be able to watch the
log file /var/opennms/log/discovery.log and see how many
threads are running.
<poller>
<pollerID>localhost</pollerID>
<pollerName>local host</pollerName>
<pollerIP>127.0.0.1</pollerIP>
<discLimit>.00005</discLimit>
<package>example1</package>
</poller>
4.2 Configuring the view
Views can be configured by modifying views.xml and
viewsdisplay.xml. Within views.xml you can define the
catagories of specific services, as well as define thresholds
for the outage information that is displayed on the web page.
In this example we have created a catagory for UFO Detectors
and specified the remote end of our internet connection.
<category>
<label><![CDATA[Database Servers]]></label>
<normal>99</normal>
<warning>97</warning>
<service>UFO Detectors</service>
<rule><![CDATA[isUFODP]]></rule>
</category>
<category>
<label><![CDATA[Internet Connectivity]]></label>
<normal>99</normal>
<warning>97</warning>
<service>ICMP</service>
<rule><![CDATA[ipaddr IPLIKE 12.0.0.1]]></rule>
</category>
While in viewsdisplay.xml you can organize the layout of the
main console web view. In many instances the default views will
need not need to be changed.
<view>
<view-name>WebConsoleView</view-name>
<section>
<section-name><![CDATA[Category]]></section-name>
<category><![CDATA[UFO Detectors]]></category>
<category><![CDATA[Internet Connectivity]]></category>
</section>
</view>
4.3 Configuring services
The file services.xml holds the default definitions for all
services that OpenNMS recognizes. You can; add or remove
services, specify a service name, port, and dialog as well as
default timeouts and polling intervals. In the following
example we have setup the UFO detection protocol as a service
on TCP port 4.
<service>
<name>UFODP</name>
<dbCapability>isUFODP</dbCapability>
<capsdPluginClass>org.opennms.bb.dp.capsd.plugin.TestForTcpServ
er</capsdPluginClass>
<parms>
<parm>
<parmName>interval</parmName>
<value>5m</value>
</parm>
<parm>
<parmName>port</parmName>
<value>4</value>
</parm>
<parm>
<parmName>retry</parmName>
<value>3</value>
</parm>
<parm>
<parmName>timeout</parmName>
<value>3s</value>
</parm>
<parm>
<parmName>banner</parmName>
<value>*</value>
</parm>
</parms>
</service>
4.4 Configuring schedulers
Once a service is configured in services.xml and added to a
package, we will need to create a scheduler in order to poll
for the specified service at regular intervals. Pollers need to
be created in scmconfig.xml so they can be started by the
service control manager each time OpenNMS is started. In the
following example we have created a scheduler for UFO detection
protocol.
<service startup="automatic">
<svcid>OpenNMS.scheduler.UFODP</svcid>
<svcname>Scheduler</svcname>
<description>OpenNMS Scheduler Daemon</description>
<exec>
<jproc jvmid="schedVM">
<class>org.opennms.bb.dp.poller.scheduler.Polle
rScheduler</class>
<classpath>${jar.onms.common}</classpath>
<classpath>${jar.onms.distpoller}</classpath>
<classpath>${jar.apache.xerces}</classpath>
<classpath>${jar.jdbc.postgresql}</classpath>
<parameter>127.0.0.1</parameter>
<parameter>UFODP</parameter>
<parameter>org.opennms.bb.dp.poller.plugins.Ser
viceMonitorUFODP</parameter>
<property id="org.opennms.bluebird.propertyFile
">data/common/properties/bluebird</property>
</jproc>
</exec>
</service>
_________________________________________________________________
5 Chapter 5
Viewing the Network
5.1 Starting OpenNMS
Make sure the necessary dependencies have been started.
/sbin/service portmap start
/sbin/service postgresql start
/sbin/service openjms start
After those dependencies are started, you can start OpenNMS
/sbin/service opennms start
or
/opt/OpenNMS/opennms.sh all start
OpenNMS should start the tomcat server as well. At this point
you can grab a cup of coffee. Once everything is started, the
web ui should be available. However the discovery process is on
a 5 minute delay. You can check the status of OpenNMS and
"service control manager" using the following command.
# /opt/OpenNMS/opennms.sh scm status
-----------------------------------------------------------------------
-------
OpenNMS Command (Revision: functions.sh,v 1.15 2001/07/06 19:30:25 ben
Exp $)
-----------------------------------------------------------------------
-------
OpenNMS.eventd : RUNNING
OpenNMS.trapd : RUNNING
OpenNMS.actiond : RUNNING
OpenNMS.dhcpd : RUNNING
OpenNMS.icmpd : RUNNING
OpenNMS.capsd : RUNNING
OpenNMS.OutageManager : RUNNING
OpenNMS.RTCViewCategoryManager : RUNNING
OpenNMS.discovery : RUNNING
OpenNMS.scheduler.ICMP : RUNNING
OpenNMS.scheduler.SNMP : RUNNING
OpenNMS.scheduler.HTTP : RUNNING
OpenNMS.scheduler.FTP : RUNNING
OpenNMS.scheduler.SMTP : RUNNING
OpenNMS.scheduler.DNS : RUNNING
OpenNMS.scheduler.OpenSSH : RUNNING
OpenNMS.scheduler.Postgres : RUNNING
OpenNMS.scheduler.MySQL : RUNNING
OpenNMS.scheduler.SQLServer : RUNNING
OpenNMS.scheduler.Informix : RUNNING
OpenNMS.scheduler.Sybase : RUNNING
OpenNMS.scheduler.Oracle : RUNNING
OpenNMS.scheduler.DHCP : RUNNING
OpenNMS.scheduler.IMAP : RUNNING
OpenNMS.scheduler.POP3 : RUNNING
OpenNMS.scheduler.UFODP : RUNNING
If there are any problems or services are not starting
correctly, you can check the logs for more information. The log
files are located in /var/log/opennms/
5.2 Viewing the Network
Once tomcat is started, you can, in your web browser go to the
following address.
http://127.0.0.1:8080/opennms/
login: admin/admin
After logging in you will be directed to the main OpenNMS view
of your network. Although most browsers will work, only the
following are officially supported... for Linux: Netscape 4.7+,
Netscape 6+, Mozilla 0.8+ and for Windows: Netscape 4.7+,
Netscape 6+, IE 5.5+