Dashboard

From OpenNMS
Jump to: navigation, search

Summary

The OpenNMS Dashboard is built with the Google Web Toolkit (GWT). This is the first AJAX based OpenNMS component to be introduced to the OpenNMS WebUI.

Dashboard is designed to focus, and therefore also restrict, a user's view to devices of their interest. To do this, a new role was added that can be assigned to a user that restricts them to viewing only the dashboard if that is intended.

Configuration

There are 3 basics steps to setting up Dashboards in OpenNMS:

  1. Define Surveillance Views
  2. Categorize Nodes
  3. Assigning Dashboards to Users

Defining Surveillance Views

Dashboard is based on the Surveillance View feature introduced in 1.3.2. Even though this feature was available in 1.3.2, it was a bit obstructed from the user by the fact that it wasn't visible until configured correctly for there was no default configuration. In version 1.3.3, the feature became more visible with the addition of the Dashboard since it depends on this configuration. To support this requirement and to make the release target, we added a default view configuration (shown below) as well as enhancements to the installer that allowed us to pre-populate some generic categories.

Warning.png Obsolete XML Attributes

Between OpenNMS 1.6 and 1.8, the col attribute on the <column-def> element and the row attribute on the <row-def> element were removed from the XML schema for the surveillance-views.xml file. If these attributes are present in your version of this file, OpenNMS will fail to start up.

The Default Surveillance View Configuration

<?xml version="1.0" encoding="UTF-8"?>
<surveillance-view-configuration 
  xmlns:this="http://www.opennms.org/xsd/config/surveillance-views" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="http://www.opennms.org/xsd/config/surveillance-views http://www.opennms.org/xsd/config/surveillance-views.xsd"
  default-view="default" >
  <views >
    <view name="default" refresh-seconds="300" >
      <rows>
        <row-def label="Routers" >
          <category name="Routers"/>
        </row-def>
        <row-def label="Switches" >
          <category name="Switches" />
        </row-def>
        <row-def label="Servers" >
          <category name="Servers" />
        </row-def>
      </rows>
      <columns>
        <column-def label="PROD" >
          <category name="Production" />
        </column-def>
        <column-def label="TEST" >
          <category name="Test" />
        </column-def>
        <column-def label="DEV" >
          <category name="Development" />
        </column-def>
      </columns>
    </view>
  </views>
</surveillance-view-configuration>

Categorizing Nodes

In order to categorize nodes in the Surveillance View, choose a node and click Edit beside Surveillance Category Memberships. Recalling from your Surveillance View, choose two categories that represent a column and a row, for example, 'Severs' and 'Test', then click Add >>. For more, see categorizing nodes in the Surveillance View documentation.

If you have numerous nodes to categorize you can go to Admin -> Manage Surveillance Categories, Edit relevant category and select numerous nodes to be added to this category.

Assigning users a Dashboard

Users are assigned a Dashboard in the OpenNMS WebUI using a simple algorithm that determines which surveillance view is to be associated with their Dashboard session. The following criteria selects the proper Surveillance View for their Dashboard. The first matching item wins:

  1. Surveillance View name equal to the user name they used when logging into OpenNMS.
  2. Surveillance View name equal to the user's assigned OpenNMS group name
  3. Surveillance View name equal to the 'default-view' attribute in the surveillance-views.xml configuration file.

Example Configuration

The following example assigns a Dashboard to the user "drv4doe" (a router and switch jockey) and restricts the user for navigation to any other link in the OpenNMS WebUI.

1: Create the User

Using the OpenNMS WebUI create a user with ID: drv4doe

Adduser.jpg

2: Change magic-users.properties

Edit the magic-users.properties file in the /opt/opennms/etc directory and set drv4doe as a dashboard user.

role.dashboard.name=OpenNMS Dashboard User
role.dashboard.users=drv4doe
role.dashboard.notInDefaultGroup=true

3: Define Surveillance View

Edit $OPENNMS_HOME/etc/surveilliance-view.xml to add a definition for the user 'drv4doe', which you created in step 1.

<?xml version="1.0" encoding="UTF-8"?>
<surveillance-view-configuration 
  xmlns:this="http://www.opennms.org/xsd/config/surveillance-views" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="http://www.opennms.org/xsd/config/surveillance-views http://www.opennms.org/xsd/config/surveillance-views.xsd"
  default-view="default" >
  <views >
    <view name="drv4doe" refresh-seconds="300" >
      <rows>
        <row-def label="Servers" >
          <category name="Servers"/>
        </row-def>
      </rows>
      <columns>
        <column-def label="PROD" >
          <category name="Production" />
        </column-def>
        <column-def label="TEST" >
          <category name="Test" />
        </column-def>
      </columns>
    </view>
   <!-- default view here -->
    <view name="default" refresh-seconds="300" >
      <rows>
        <row-def label="Routers" >
          <category name="Routers"/>
        </row-def>
        <row-def label="Switches" >
          <category name="Switches" />
        </row-def>
        <row-def label="Servers" >
          <category name="Servers" />
        </row-def>
      </rows>
      <columns>
        <column-def label="PROD" >
          <category name="Production" />
        </column-def>
        <column-def label="TEST" >
          <category name="Test" />
        </column-def>
        <column-def label="DEV" >
          <category name="Development" />
        </column-def>
      </columns>
    </view>
  </views>
</surveillance-view-configuration>

This configuration and proper assignment of node categories will produce a default Dashboard for all users, other than "drv4doe", as shown here:

Drv4doe-dashboard-example.jpg


However, when logging in as "drv4doe", the user is taking directly to the Dashboard page and is presented with a Dashboard based on the drv4doe surveillance view definition as shown here:

Drv4doe-dashboard-example2.jpg

If the "drv4doe" user attempts to navigate away from the dashboard.jsp URL, they will be presented with the following message:


Access-denied.jpg

Navigation

Navigation to the Dashboard is automatic for users in the dashboard user role, otherwise, currently, navigation to the dashboard requires typing the following relative URL: /opennms/dashboard.jsp.

Hiding the Top Nav

You can hide the Top Nav on any page by specifying ?quiet=true; adding it to the end of the OpenNMS URL.

This is very handy when using the dashboard on a large monitor or tv screen for office wide viewing.

Dashlets

The Dashboard shipped with OpenNMS 1.3.3 includes 5 views of information that gives a user quick access to heads up/real-time information that is available in OpenNMS. These views were implemented using GWT and the Dashboard API for which they were implemented were named "Dashlets" by the OpenNMS developers. The 5 Dashlets AJAXify (I just love making up new words) current OpenNMS WebUI features:

  1. Surveillance View
  2. Alarms
  3. Notifications
  4. Node Status/Availability
  5. Resource Graph Reporting

Navigation is possible within each of the Dashlets by clicking on the "<<" and ">>" controls within the Dashlet header. This causes the Dashlet to page through any additional data available.

Surveillance View Dashlet

The surveillance view dashlet mimics the visual representation of node status shown in the Surveillance View feature. However, it also is a special Dashlet in the fact that it controls the content of all other Dashlets on the page. When it is first displayed, it sets the a filtering criteria on all the other Dashlets that restricts the data they present to the set of nodes that can be found in the view. In the "drv4doe" example above, the view is restricted to only show the nodes that fit in the subset of nodes represented by the intersection of the Production category with the Servers category. When multiple rows and/or columns are shown, as in the default view, the other Dashlets can be further restricted by the clicking on one of the row or column headers or on one of the table cells itself. The example below shows how the selection is highlighted in blue:

Drv4doe-dashboard-example3.jpg


Alarms/Notifications/Node Status Dashlets

These Dashlets are almost identical except for the set of data that they present. Clicking the the scrolling controls "<<" and ">>", pages through 5 rows of data at a time without the need for refreshing the entire HTML page (AJAX is cool).

Resource Graph Dashlet

Clicking on the "<<" and ">>" causes the Dashlet to scroll through all RRD based resource graphs available for the nodes that are currently set by the Surveillance View Dashlet (as described above). This scrolling is a very unique RRD graph presentation feature!

Anonymous dashboards

You can modify the configuration files for the security framework to give you access to one or more dashboards without logging in. At the end you'll be able to point a browser at a special URL like http://.../opennms/dashboard1 or http://.../opennms/dashboard2 and see a dashboard without any authentication.

First, configure surveillance views and create dashboard users as above. For example, make two dashboards and two users called "dashboard1" and "dashboard2". Test that you can log in as each of the new users and see the correct dashboard.

Now create some aliases you can use to distinguish between dashboards. In /opt/opennms/jetty-webapps/opennms/WEB-INF, edit web.xml. Just before the first <servlet-mapping> tag, add the following servlet entries:

  <servlet>
       <servlet-name>dashboard1</servlet-name>
       <jsp-file>/dashboard.jsp</jsp-file>
  </servlet>

  <servlet>
       <servlet-name>dashboard2</servlet-name>
       <jsp-file>/dashboard.jsp</jsp-file>
  </servlet>

Just before the first <error-page> tag, add the following servlet-mapping entries:

  <servlet-mapping>
       <servlet-name>dashboard1</servlet-name>
       <url-pattern>/dashboard1</url-pattern>
  </servlet-mapping>

  <servlet-mapping>
       <servlet-name>dashboard2</servlet-name>
       <url-pattern>/dashboard2</url-pattern>
  </servlet-mapping>

After the last <filter-mapping> tag, add the following filter-mapping entries:

  <filter-mapping>
    <filter-name>AddRefreshHeader-120</filter-name>
    <url-pattern>/dashboard.jsp</url-pattern>
  </filter-mapping>
  <filter-mapping>
    <filter-name>AddRefreshHeader-120</filter-name>
    <url-pattern>/dashboard1</url-pattern>
  </filter-mapping>
  <filter-mapping>
    <filter-name>AddRefreshHeader-120</filter-name>
    <url-pattern>/dashboard2</url-pattern>
  </filter-mapping>

Next edit applicationContext-acegi-security.xml to enable anonymous authentication for the /dashboard1 and /dashboard2 aliases. Near the top of the file, find <bean id="filterChainProxy" ...>. Below the entry for "/rss.jsp*", add an entry for each of the dashboard aliases:

  <bean id="filterChainProxy" class="org.acegisecurity.util.FilterChainProxy">
    <property name="filterInvocationDefinitionSource">
      <value>
        CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
        PATTERN_TYPE_APACHE_ANT
        /rss.jsp*=httpSessionContextIntegrationFilter,logoutFilter,authenticationProcessingFilter,basicProcessingFilter,securityContextHolderAwareRequestFilter,anonymousProcessingFilter,basicExceptionTranslationFilter,filterInvocationInterceptor
        /dashboard1*=httpSessionContextIntegrationFilter,logoutFilter,securityContextHolderAwareRequestFilter,dash1AnonymousProcessingFilter,filterInvocationInterceptor
        /dashboard2*=httpSessionContextIntegrationFilter,logoutFilter,securityContextHolderAwareRequestFilter,dash2AnonymousProcessingFilter,filterInvocationInterceptor
        /**=httpSessionContextIntegrationFilter,logoutFilter,authenticationProcessingFilter,basicProcessingFilter,securityContextHolderAwareRequestFilter,anonymousProcessingFilter,exceptionTranslationFilter,filterInvocationInterceptor

...

About halfway through the file, look for <bean id="filterInvocationInterceptor" ...>. Below the entry for "/dashboard.jsp", add an entry for each of the aliases:

  <bean id="filterInvocationInterceptor" class="org.acegisecurity.intercept.web.FilterSecurityInterceptor">

...

        /frontpage.htm=ROLE_USER,ROLE_DASHBOARD
        /dashboard.jsp=ROLE_USER,ROLE_DASHBOARD
        /dashboard1=ROLE_USER,ROLE_DASHBOARD
        /dashboard2=ROLE_USER,ROLE_DASHBOARD
        /gwt.js=ROLE_USER,ROLE_DASHBOARD

...

Finally, near the bottom of the page, add a new instance of AnonymousProcessingFilter for each alias.

  <!-- Set the anonymous username to dashboard1 so the dashboard page
       can match it to a surveillance view of the same name. -->
  <bean id="dash1AnonymousProcessingFilter" class="org.acegisecurity.providers.anonymous.AnonymousProcessingFilter">
    <property name="key"><value>foobar</value></property>
    <property name="userAttribute"><value>dashboard1,ROLE_DASHBOARD</value></property>
  </bean>

  <bean id="dash2AnonymousProcessingFilter" class="org.acegisecurity.providers.anonymous.AnonymousProcessingFilter">
    <property name="key"><value>foobar</value></property>
    <property name="userAttribute"><value>dashboard2,ROLE_DASHBOARD</value></property>
  </bean>

Restart OpenNMS and you should bring up a dashboard at http://.../opennms/dashboard1 without logging in.

Some problems with this hack:

  • There's no way to switch dashboards without closing the browser (or deleting the JSESSIONID session cookie).
  • If you accidentally click a link that requires full user privileges (e.g. Node List), you'll be given a login form. Once you get to the login form, there's no going back to the dashboard without restarting the browser. Something gets stuck in the session that prevents the AnonymousProcessingFilter from doing its magic.

If the second problem bothers you, you can set ROLE_USER in addition to ROLE_DASHBOARD in your userAttribute property. However this will give full user access to anonymous browsers.

Tested with OpenNMS 1.5.91 and Jetty.