OpenNMS Patterns and Scripts

Most of the scripts on this site output HTML so it’s easier to run them from a web server than on the command line. The following configuration is needed to serve the scripts through an Apache 2 web server.

The configuration below does the following:

1. Proxies the OpenNMS web interface through Apache.
2. Provides a document root to add custom .html, .shtml, and .cgi files.
3. Provides single sign on for both the document root and the OpenNMS web interface.
4. An unauthenticated area is provided for public content.

This is not the only way to configure Apache. I’ve tried to provide the simplest configuration that works. It can probably be done with a different web server as well. This configuration assumes that OpenNMS, Apache, and everything else are on the same server. If should be possible to modify it for split environments.

Prerequisites

1. Setting up Scripts
2. Install the Apache 2 Web Server. The default test page should be working. The information below assumes you know how to administrate Apache. If you’re not familiar with Apache please search online before posting a question.
3. mod_proxy, mod_proxy_http, and mod_include need to be installed, loaded, and enabled in apache. Most distributions already have them installed.
4. Set up firewalls to allow access to the HTTP port you will use. Normally 80 for HTTP and 443 for HTTPS.
5. OpenNMS needs to be running so it’s web interface can be accessed at http://your-server:8980/opennms/

Create Web Directories

Everything in the this section (Create Web Directories) can be completed by the noc-install-upgrade.sh script. See the post Install/Upgrade Scripts for more information.

The following commands will add sub-directories to $NOCBASE for the web server document root, public folder, views, and include scripts.

/bin/bash
source /etc/noc.conf
mkdir $NOCBASE/http
mkdir $NOCBASE/http/views
mkdir $NOCBASE/http/public
mkdir $NOCBASE/include
mkdir $NOCBASE/view-template
mkdir $NOCBASE/view-bin
echo '<a href="/opennms/">OpenNMS</a>' > $NOCBASE/http/index.shtml
echo 'public' > $NOCBASE/http/public/index.html
chmod -R a+rX $NOCBASE/http $NOCBASE/include $NOCBASE/view-template $NOCBASE/view-bin

Configure Apache Web Server (httpd)

The following examples assume $NOCBASE is /opt/noc and /etc/http/ contains your http configuration files. Modify these for your environment. Some distributions will already have some of these directives.

Change the document root to point to the directory created above:

DocumentRoot "/opt/noc/http"

Enable server side includes (SSI) for files with the .shtml extension:

AddType text/html .shtml
AddOutputFilter INCLUDES .shtml

Enable CGIs and the .cgi file extension:

LoadModule cgi_module modules/mod_cgi.so
AddHandler cgi-script .cgi

The files index.cgi and index.shtml need to be recognized as directory indexes:

DirectoryIndex index.html index.shtml index.cgi

Set up directory options and basic authentication on the document root then remove the authentication for the public sub-directory:

<Directory "/opt/noc/http">
  Options Indexes FollowSymLinks ExecCGI +Includes
  AllowOverride None
  AuthType Basic
  AuthName "NOC"
  AuthUserFile /etc/httpd/htpasswd
  Require  valid-user
</Directory>

<Directory "/opt/noc/http/public">
  Satisfy Any
  Allow from all
</Directory>

The apache proxy needs to serve the opennms jetty server under /opennms/. Also, Auth entries need to be added to /opennms/ so they match /opt/noc/http:

<Location "/opennms/">
  ProxyPass http://localhost:8980/opennms/
  ProxyPassReverse http://localhost:8980/opennms/

  AuthType Basic
  AuthName "NOC"
  AuthUserFile /etc/httpd/htpasswd
  Require  valid-user
</Location>

If you choose, a  firewall rule can block external requests to port 8980 which will ensure that all traffic goes through the proxy.

User Accounts

Now that apache authentication is set up we need to add users. Unfortunately users need to be added to OpenNMS as well as the apache htpasswd file. The passwords must match. While not ideal, having duplicate user entries allows a single web page to access both a custom script and the OpenNMS interface. For example, a custom web page may want to include a graph from OpenNMS.

Add at least the admin user to the htpasswd file:

htpasswd /etc/httpd/htpasswd admin

If the /etc/httpd/htpasswd file does not exist, it will need to be created when the admin user is added by using the -c switch.

Since maintaining duplicate user accounts is hard, you may want a single account for “read-only” users. Add the user account to OpenNMS as read-only and then create the apache username:

htpasswd /etc/httpd/htpasswd read-only

Security

You should ensure the web server is secured to your organizations standards. Since basic auth is used, the password is sent across the network in clear text if you’re using HTTP. As a first step, you might want to use HTTPS rather than HTTP. There are several good online tutorials on how to set up HTTPS in apache so I will not repeat them. Once HTTPS is working, you can redirect all port 80 traffic to port 443 with the Apache directives:

RewriteEngine On
RewriteCond %{SERVER_PORT} !=443
RewriteRule ^(.*)$ https://your-server-name$1 [L,R]

The OpenNMS web interface needs to be made aware of the HTTPS configuration. A line in the $OPENNMSBASE/etc/opennms.properties file needs to be uncommented:

opennms.web.base-url = https://%x%c/

Testing

You should now be able to use a browser to hit your apache web server. Start by hitting the public directory (http://your-server/public/). It should return a page containing the word “public” without promoting for a password. Then try the root page (http://your-server/). You should be promoted to login and then see a link to the OpenNMS web interface. You should now be able to hit the OpenNMS web interface without logging in again (http://your-server/opennms/). If you don’t see anything then make sure OpenNMS is running and check the log files. If you see the normal OpenNMS login page then something above is incorrect. Carefully check the log files and configuration.

Done!

You can replace the index files created above with versions custom made for your environment. Future posts will add scripts that produce HTML that can be linked to. You can add your own files under $NOCBASE/http/ but leave $NOCBASE/http/views and the other view-* directories empty. They will have a specific use.

You can also add other proxy directives to Apache. I have other monitoring systems proxied the same way as OpenNMS. A user can login once and all the systems are available without further logins. My monitoring home page has been evolving over the last couple years (see below). Let me know if you’re interested, after I post all the scripts I could cover how I put together my home page and the logic behind it.