Contents 1 You probably don't want to build from source 2 Applicable versions 3 Getting the source 4 Maven 2 4.1 Maven dependencies 5 Modules 6 Preparation 7 Install jicmp 8 Building 8.1 Inline 8.2 Inline with an alternate distribution directory 8.3 Attached with an alternate distribution directory 8.4 Don't forget to clean if you've changed build options 8.5 Building tools 9 Running OpenNMS 9.1 Fix the Permissions 9.2 Set the JVM 9.3 Set up the database 9.4 Customizing the pg_hba.conf file 9.5 Start opennms 9.6 Setting up the OpenNMS webapp 9.6.1 View the webapp!!! 10 Troubleshooting

You probably don't want to build from source

For most users, it is recommended that you follow the QuickStart guide relevant to your platform, and install pre-built binaries.

These instructions are recommended for developers interested in building from source.

Applicable versions

This document applies to building the code in "master" (trunk) in Git and OpenNMS 1.3.2 and later releases. For 1.2 releases, see section 5 of the install guide.

Getting the source

Checking out the Source Code

Maven 2

A copy of Maven 2 (a.k.a. mvn or m2) is now included in the OpenNMS source tree and the old build.sh script now calls Maven rather than Ant. If you run into problems with builds ensure that this is being used (the build script honours the MVN environment variable). Older versions of maven have been know to have problems downloading dependencies and following redirects.

That is about all the similarity between the new build system and the old one. To get an overview of Maven 2, read Gettting Started and Better Builds with Maven.

Maven dependencies

Maven downloads the dependencies for building OpenNMS from Maven repositories on the Internet.

If you are not connected to the Internet, run mvn with the -o flag to work offline. However, to do that, your local repository (~/.m2/repository) will need to contain all required dependencies, which you will then have to obtain in some other way (typically from some other internet connected host). See the <repository> tags in the top level pom.xml for the places that maven would have looked to find the dependencies.

Modules

The OpenNMS source code has been broken up into sub-modules. Modules can be simple modules that represent the code for a single "artifact" like a jar file. They can also be "aggregate" modules with are container modules made up of sub-modules of their own. Here are some points to help you find things:

• Each jar module contains a src/main/java directory which contains all of its Java sources. A war or webapp module has its web pages stored at its src/main/web sub-directory.
• Tests and related code are under src/test/java.
• Maven also supports "resources" or other files that should be included in jar files such as *.properties and other things. These are stored in src/main/resources (or src/main/filtered if property filters should be run on them first) and src/test/resources (similarly src/test/filtered for filtered test resources).

Preparation

To make sure that you don't run into bug #1873, verify that the "javah" executable is in your path and that it is version 1.5 or later by running "javah -version". E.g.:

$ javah -version
javah version "1.5.0_07"

Make sure you have postgresql-devel and rrdtool-devel installed.

Install jicmp

To build jicmp from source, you'll also need automake, autoconf, and libtool.

 cd jicmp
 m4/autogen.sh
 ./configure
 make
 sudo make install

This should put jicmp into /usr/local/lib (or /usr/local/lib64 on some 64-bit systems).

Building

Inline

The simplest way to build OpenNMS is by issuing the following command:

./build.sh install assembly:directory-inline

This will compile and build all the code and assemble a distribution under target/opennms-${version} and can be run from that location.

Inline with an alternate distribution directory

If you want OpenNMS to be staged to a different directory, you can use this command:

./build.sh -Ddist.dir=$PWD -Ddist.name=dist install assembly:directory-inline

This will install it in the $PWD/dist directory (i.e. the directory "dist" as a subdirectory of where you are running this command). And will only successfully run from that location.

Attached with an alternate distribution directory

To build a distribution so as to run it from a different location, say /opt/opennms, use this:

./build.sh -Dopennms.home=/opt/opennms install assembly:attached

This will build a distribution in target/opennms-${version}.tar.gz containing a distribution intended by untarred inside the /opt/opennms directory:

 cd target
 cp -p opennms-*.tar.gz /opt/opennms
 cd /opt/opennms
 tar zxf opennms*.tar.gz
 chmod +x bin/*

Don't forget to clean if you've changed build options

If you've built OpenNMS previously and have changed build options (such as the "opennms.home" property) or performed an update from the source code repository, you'll want to do a clean build, first:

./build.sh clean

Building tools

If you want to build one of the OpenNMS tools in the opennms-tools directory, you can go to the directory, opennms-rrd-stresser for example, and run

mvn $target

from there. It will then get and build the necessary dependencies for you. If you ran "mvn install", you will find the compiled tool in the target/ subdirectory.

Running OpenNMS

Now that you have OpenNMS built you can run it.

Fix the Permissions

There is a bug in the dist creation that fails to properly set the execute permissions for scripts. Fix this as follows:

chmod +x <opennms.home>/bin/*
chmod +x <opennms.home>/contrib/*
chmod -x <opennms.home>/contrib/*.README
chmod -x <opennms.home>/contrib/opennms.mib

Set the JVM

Before you can do anything else with OpenNMS you'll need to tell which JVM to use. To do this enter the following command:

<opennms.home>/bin/runjava -s

If that does not find a suitable JVM for OpenNMS, or if you want to force a specific JVM, you can use this:

<opennms.home>/bin/runjava -S <the directory in which your JVM is installed>/bin/java

This will create a file called java.conf in <opennms.home>/etc that contains the java command that will run whenever opennms is started

Set up the database

The next step is to set up the OpenNMS database. Do this using the following command:

 <opennms.home>/bin/install -disU

This will set up the database for OpenNMS, preserving any existing data. To completely clear the database and start over use the following:

 <opennms.home>/bin/install -discU

For more information on the flags available to the installer, for example to specify a different name for the database, run

 <opennms.home>/bin/install -h

If this step fails, please check the following:

Customizing the pg_hba.conf file

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.

Start opennms

At this point you should be able to start the opennms 'daemon'. As root run this command:

 <opennms.home>/bin/opennms start

Setting up the OpenNMS webapp

OpenNMS versions later than 1.3.7 have a built in web application server. Once you have opennms started you can simply browse to http://localhost:8980/opennms and see the webapp front end.

You can also install the webapp in a Tomcat 5.5 server. See the install instructions for Tomcat installation.

View the webapp!!!

Now you may start Tomcat and visit http://localhost:8980/opennms/ to view the webapp! Login as "admin" with the password "admin".

Troubleshooting

See Building FAQ.