From OpenNMS
(Redirected from Building from Source)
Jump to navigation Jump to search

Warning.png Outdated OpenNMS Wiki!

Our wiki has been used for about 20 years now, so with a smile in one eye and a tear in the other, we finally decided to grant its retirement. Please use the [official documentation page] and the [Discourse forum]. The migration process from MediaWiki to Discourse is still ongoing and everybody is welcome to join the clean-up [project]. If you want to provide new articles, please use the [knowledge base] section whose articles are per default editable for all of us.

Current page count is 3,231

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.

These are not upgrade instructions!

Attempting to build a newer version of OpenNMS from source on top of an existing install is not supported. If you are upgrading, back up your data and configs and do a fresh install.

Applicable versions

This document applies to building the code in "master" (trunk) in Git and OpenNMS 1.8.3 and later releases. For older releases, see Building OpenNMS (Old).

Getting the source

Follow the instructions in the referenced wiki page to install needed files and to download a local copy of the OpenNMS source code.

Checking out the Source Code


A copy of Maven is now included in the OpenNMS source tree.

To get an overview of Maven in general, read Getting 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.


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).

Install development prerequisites

A Java Development Kit is required.

For Debian/Ubuntu systems, run

sudo apt-get install openjdk-8-jdk

To verify, confirm that javah is installed

$ javah -version
javah version "1.8.0_252"

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

For Debian/Ubuntu systems, run

sudo apt-get install postgresql-server-dev-11
sudo apt-get install librrd-dev

Also, make sure your git version is 2.x or higher. 1.x can cause dependency issues with the web/javascript portion of the build.

Install jicmp

jicmp is a separate project from OpenNMS itself. A compiled version of jicmp is required to build OpenNMS.

Install a pre-built jicmp package

See Jicmp for how to install the current jicmp package from the OpenNMS package YUM or APT repositories.

For Debian/Ubuntu systems, follow the tutorial instructions to add the OpenNMS repositories and then run

sudo apt-get install jicmp jicmp6    (maybe package "libicmp-jni" is also needed? TODO)

Build jicmp from source

To build jicmp from source, in addition to the Jicmp tarball you'll also need automake, autoconf, and libtool.

 cd jicmp
 autoreconf -fvi
 sudo make install

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

Note: As of version 1.10 it seems that jicmp6 is also mandatory. You can find a jicmp6 tarball here.

If you'd rather build jicmp from the latest git source, follow the instructions for cloning and building in the


There are two scripts associated with building. 
compiles all of the platform-agnostic, non-system-specific OpenNMS jars; this is essentially a smart wrapper around the 'mvn' command. Use this where you would normally use the 'mvn' command. 
assembles packages of the OpenNMS release, including configuration files, webapps, etc.

Both scripts can be passed a number of options for overriding behavior and environment settings. Run "./ --help" or "./ --help" for details.

Note: If the command stops with an error about a missing dependency, try just running it again. Sometimes maven is unable to download needed files the first time it tries but it succeeds on the second try.

Since not all Tests might be executable on ones local Machine, it might also be helpful to use the -DskipTests Argument to prevent their execution.

Using a HTTP Proxy during build

If you are building on a host that doesn't have a direct internet connection, you will need to edit maven/conf/settings.xml to set your web proxy. I needs to look something like this:


Note: Change to the address of your proxy.


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

./ -p fulldir

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:

./ -Ddist.dir=$PWD -p fulldir

This will install it in the $PWD/dist directory (i.e. the directory "dist" as a subdirectory of where you are running this command). Note that because it translates the configuration files, it 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:

./ -Dopennms.home=/opt/opennms

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 clean the assembly, first:


If there are pom updates or files getting renamed from one sub-module to another in the source code it's generally a good idea to clean after updating before attempting to rebuild.

Building tools (opennms-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. In lieu of the 'mvn' command, you can also run



RPM Packages

You should only have to run:

 ./ build a snapshot RPM with your latest code.

Debian Packages

First, edit debian/changelog and create a log entry for your nightly/snapshot build. Then, just run:


A full set of .deb package files will be created in the directory above the "opennms" top-level source code directory.

Solaris Packages

There is a makefile to generate Solaris packages. Just run:

 cd solaris

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:

cd <opennms.home>

chmod +x bin/*
chmod +x contrib/*
chmod -x contrib/*.README
chmod -x 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:

./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:

./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:

./bin/install -dis

This will set up the database for OpenNMS, preserving any existing data. To completely clear the database and start over, DROP your existing database first.

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

 ./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):

local all all trust
host all all 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:

cd <opennms.home>
./bin/opennms start

After OpenNMS has started you enter the webUI at http://localhost:8980/opennms/ with "admin" as user and password.


See Building FAQ.