Community/Welcome Guide

From OpenNMS
Jump to: navigation, search

Hello World

Welcome to the OpenNMS community- the place of the world's first enterprise grade network management platform developed under the open source model. This document is meant for anyone interested in learning about the OpenNMS project and the surrounding eco system. It is intended for people who are new to the project and give information you are looking for to get oriented.

In this document you will learn the following topics:

  • What is OpenNMS
  • Where can you find documentation
  • How can you get in contact with users, developers in the community
  • Which organizational groups are involved and how is it governed
  • How to get involved and how to contribute in the project
  • How are issues and incidents managed and the development process

We hope this guide will help and welcome you in our community with good looking and smart people.

What is OpenNMS

OpenNMS is a free and open network management platform to give you the ability to solve problems in the domain of FCAPS footnote:[ISO Telecommunications Management Network model and framework for Fault, Configuration, Accounting, Performance and Security categories] developed under the GNU Affero General Public License Version 3. The OpenNMS project is a collaboration of developers and network management specialists around the world, aiming to produce an open standard for a network management platform. Main focus of OpenNMS is fault- and performance management. The application provides access to the management data through a web interface and open a ReST API.

The project aims to deliver a solution for all types of network management issues, massively scalable and feature-rich. The technology consists of a series of interrelated programs delivering various components for network management solution.

OpenNMS high level components

Service Assurance
Detecting faults for services is an essential.
With Service Assurance we mean in OpenNMS everything related to the availability of a service.
OpenNMS measures response times, availability and detect outages.
The results are forwarded as Events through an OpenNMS internal messaging system and can be used for further incident workflows.
Performance Data Collection
Applications and network systems provide valuable performance metrics through management protocols or specific interfaces.
OpenNMS provides access to management protocols like SNMP, JDBC, JMX, WMI, WSMAN, NSClient or NRPE without coding just through configuration.
To be able to integrate application specific performance data it is possible to use a generic HTTP collector and XML/JSON collector.
Provisioning
Large networks build workflows to define a life cycle of devices and applications in a network.
The Provisioning system provides entry points in the UI, on the command line, and via programming interfaces to allow you to add, modify, and remove nodes and services.
In addition to specifying what to manage up front, services and nodes can also be automatically detected and the system allows a flexible mixture of both types of provisioning.
Notifications
Monitoring services is not enough and it is often necessary to establish workflows to get peoples attention to deal with outages.
With an extensible Notification system you can notify and build escalation plans for users and groups.
Notifications can be send via several media types like Mail, Jabber or SMS.
The basis for Notifications in OpenNMS are Events.
Alarms and Event Correlation
Alarms are generated from Events and are on a higher level.
To correlate Events to Alarms there is a build in Event deduplication and allows the usage of Drools.
Alarms can be integrated into service desk or incident management systems, i.e. OTRS, RT.
ReST API
To allow integration in complex environments OpenNMS provides a variety of ReST programming interfaces.
It is possible to get node assets, outages, alarms, notifications, events and collected performance data through a unified ReST API.
Event driven messaging
Generated or received events are forwarded and processed internally by a event messaging system.
The main function is to provide a communication bus for all components of OpenNMS.
Logging
Beside OpenNMS self generated events or detected service outages it is possible to use OpenNMS as a central logging application.
It supports supports external log messages like SNMP traps/informs and Syslog.
By providing a extensible connector also 3rd party application can be used to generate monitoring events.
Management Protocols
To provide access to management and monitoring information OpenNMS natively implements the most common network management protocols like JMX, WMI and SNMP.
Getting information from other application it is possible to gather information from 3rd party agents like NSClient++ or NRPE.
API and Scripts for Extensions
Sometimes there is no possibility to monitor a service by existing agents.
To give flexibility the service monitoring can be extended by scripts supported by the JSR 223.
With an open Java API for service monitoring and performance data collection there are also possibilities to extend OpenNMS in an efficient and scalable way.

Documentation

In OpenNMS you can find two types of documentation. The first type is a MediaWiki based documentation. It is the place where you can find tutorials from users how to integrate with 3rd party applications or devices and how are workflows around the project are defined. This documentation can be easily edited and changed by any person with a registered account on the MediaWiki and the change policy is not very strict. The Wiki based documentation can be found in http://wiki.opennms.org/wiki/Main_Page and is structured by categories.

The second type is an Asciidoc based documentation. This documentation is version controlled and will be shipped with OpenNMS as official documentation. It is intended to document the full feature set of a specific OpenNMS version and can be used as a reference. Any person with a registered GitHub account can provide changes as Pull Request and follows the Code Contribution Workflow. People with commit permissions, i.e. OGP's and The OpenNMS Group employees are allowed to review and merge such changes so they will be published with the next release of OpenNMS. With every OpenNMS release the version controlled documentation will be build and deployed. The latest documentation can be found online on https://docs.opennms.org

Helpful links as starting point

Get in Contact

Find people who have experience in network management and monitoring on several places. You can ask questions by using our topic driven mailing list. All this mailing lists can be found on the Mailing Lists page in the wiki. Talk with people in realtime using registering a nick on Mattermost or via IRC, connect the freenode network and join channel #opennms. With the Q&A platform you can find help or send your own questions.

Beside mail, chat and the Q&A forum it is also possible to get in contact in real lifefootnote:[Real Life: A place with awesome graphic and you can get hurt]. There are two conferences organized by the OpenNMS community:

  • DevJam: The 5th season of the year to hack, learn and work for one week with people on OpenNMS. The annual conference is held at the University of Minnesota in Minneapolis in June/July.
  • OpenNMS on YouTube
  • The OpenNMS User Conference Europe which is organized from the OpenNMS Foundation Europe e.V. (OFE).

Talks and workshops are given by people from the community and commercial background with OpenNMS. There are several places where you can get news and information around the OpenNMS project.

Social Media

Blogs and other content

Governance

The project is mainly driven by The OpenNMS Group, Inc. and an elected group of community contributors OGP. OGP and people from The OpenNMS Group, Inc. have commit access to the project where the software is released and distributed. Most decisions will be made using a lazy consensus model.

The OpenNMS Group, Inc.

The OpenNMS Group, Inc. is the biggest sponsor of the project and provides a commercial product OpenNMS MERIDIAN which is similar to Red Hats Enterprise Linux subscription. Beside that they also develop new features through OpenNMS HORIZON which is similar to Red Hats Fedora and free as in freedom. The build and packaging infrastructure is also maintained and provided by the commercial company.

OpenNMS Foundation Europe e.V.

Getting people independent from companies to the project, there is a non-profit foundation based in Germany. Organizations and individuals can apply to become new members. Details on membership can be found on http://www.opennms.eu/membership.

The OpenNMS Foundation Europe e.V. (OFE) was founded on July 31st, 2012. The objective of the organization is to promote, develop, educate and research around free software and network (management) technologies, especially OpenNMS. The OFE web site with links to material of the conference can be found at http://www.opennms.eu.

OFE promotes the development, usage and adoption of the network management platform OpenNMS. Getting people with different skill sets together is important and for this reason they run the annual OpenNMS User Conference Europe (OUCE). This conference is run by foundation members and volunteers. The OFE initiates software development and studies which are made available to the public under the GPL or a suitable successor.

The statutes of the foundation can be found at http://www.opennms.eu/statutes (in German). Members are expected to participate in the OpenNMS community through technical contributions or community building efforts.

Order of the Green Polo

The Order of the Green Polo (OGP) is the super secret brotherhood of developers of the OpenNMS Project. You can recognize and OGP member by their good looks as well as their super-flashy, very coveted OpenNMS Green Polo.

[quote, Tarus Balog, Founder of the OpenNMS Project] Back in fall of 2004, I wanted to find a way to recognize those people who make OpenNMS what it is, and to thank them in some fashion. Ever since the advent of "business casual" workplace attire, the "logo" polo shirt has become a fixture in IT departments around the world. We sell black and white polos with the OpenNMS logo on our web site. But this is much, much, much, different. These are "green" polos, very rare, and they will never be available for sale. Think of them as equivalent to winning The Masters golf tournament's green jacket - only harder to get. In order to get one, all one has to do is give up all hope of having a life outside of OpenNMS, work long hours for free, and basically become a closed superhero, squashing bugs (or uncovering existence) in a single bound.

Contribution

Rather than just using software there are several possibilities to contribute in the community. Reporting a bug, make suggestions for enhancements, help improving documentation or write in a blog how you solved a special problem are ways to enrich the project. In most cases you start with using OpenNMS in your environment and with more experience you may find bugs in the software. OpenNMS uses JIRA as bug and issue tracking software. We use it not just for tracking bugs it is also the core component to release the software and plan new features and enhancements. To create issues it is required to create JIRA account.

If you are able fix open issues with code patches or you just want to provide source code contribution with patches, you have to sign the OpenNMS Contribution Agreement. This is a fundamental requirement to get your source code contribution merged to the main release of OpenNMS. Contributing documentation is a great possibility to learn new features or fill gapes and give you the possibility to share your learning experience. It is also a great way to figure out where are limitations and opens other possibilities to help improving the software.

In the OpenNMS community there are two main events, DevJam and OUCE. Both conferences are organized by volunteers and happy for help organising the event. From running call for papers, help organizing projects, giving talks, workshops or help preparing the infrastructure there are several tasks you can get involved.

OpenNMS is the work of a large number of people. In order to maintain some order with respect to the copyright to the code, every contributor is asked to sign a "Contributor Agreement". The OpenNMS Contributor Agreement is based directly on the Sun (now Oracle) Contributor Agreement. It implements the concept of a dual copyright. This allows the OpenNMS code copyright to be consolidated under one organization (The OpenNMS Group) while allowing the creator of the code to maintain all of their rights.

Oracle provides a rather comprehensive FAQ on this agreement.

To get your code contribution upstream it is required to download, sign and send us the OpenNMS Contributor Agreement (OCA).

Development

The OpenNMS software is developed on GitHub and is structured in several development branches. Different branches are the basis to develop new features and make a new release. The source code is maintained in a public GitHub repository.

Development branches

Master Branch

The master branch is used for stable releases. Changes are not committed directly to this branch, all changes go through the development. After a time period, described in section Release Management, features from development will be merged to master and are tagged as versions of OpenNMS. To ensure stable releases there will be release candidates defined and are public available as installation packages and can be tested.

Develop Branch

The function of the Develop Branch is used as integration branch for features, bug and hot fixes. Changes to this branch should only be driven from specific feature branches to the Develop Branch.

Feature Branch

This branches are originated from the Develop Branch and represent a specific enhancement or complete feature. The name of the this feature branches are described our issue tracking system link:http://issues.opennms.org[JIRA]. To identify features to the issue tracking system, the branches start with the JIRA issue number. This is important for the reason JIRA creates the Release Notes which tracks all changes between versions.

Foundation Branch

This special branch is used to get hot- or bug fixes back from the commercial OpenNMS MERDIAN. It is used by The OpenNMS Group, Inc. and gives a transparent way to see which fixes and features are back ported.

Code Contribution Workflow

With GitHub comes the possibility to fork the whole code base of OpenNMS and change code and documentation as you want. You want to contribute your changes back to the release of OpenNMS you can follow the link:https://help.github.com/articles/using-pull-requests/[GitHub Fork & Pull] development principle. Pull Requests solve a specific issue and require an entry in our JIRA issue tracking system. These Pull Requests have to be reviewed and has to pass tests before they can get merged from an OGP or OpenNMS Group member.

Workflow for code contribution

This workflow ensures code changes are tracked for release management driven by JIRA. The pull request review step is important to get a shared understanding about requested code changes and improve code stability and quality.

Release management

OpenNMS is released and distributed in two flavors HORIZON and MERIDIAN. Both distributions are released under the AGPLv3 license model. The HORIZON release follows a main release cycle of 3-4 month. All new features are developed in HORIZON and the repository is public. The OpenNMS Group, Inc. provides the MERIDIAN distribution with commercial support and a main release cycle of ~12 month and support is given for an extended lifetime. Security and bugfix patches are maintained by The OpenNMS Group, Inc. and back ported between the two distributions. To get patches and fixes, it is required to have a MERIDIAN subscription for the repository access.

Release relationship between HORIZON and MERIDIAN

Bugfixes and security patches are shared and new features will be moved from HORIZON to MERIDIAN. The decision to release new features in HORIZON is community driven and the for MERIDIAN it is driven by The OpenNMS Group, Inc. To release the software the community and The OpenNMS Group uses the public available JIRA issue tracking software.

HORIZON 4 month release phases

  • Development: Phase to develop new features, changes in architecture and major bug fixes. This state can be installed as OpenNMS Horizon SNAPSHOT release. Changes are merged from pull requests after reviewing and testing. Major releases can require configuration changes or data migration.
  • Feature Freeze: No features are pulled in develop branch. The code base get stabilized and get ready for a first release condidate.
  • Stabilize code: Getting problems solved, missing unit tests are added, outstanding review are done, fixes are made and get Continuous Integration green. Preparation for Release Candiate 1
  • Release Candidate 1 (RC1): Test phase driven by the OpenNMS community. Hotfixes can be made and applied to development branch during the test phase.
  • Release Candidate 2 (RC2): Test phase with applied hot fixes from RC1
  • Release: Release date for HORIZON which can be installed as stable release.

Phases for releases are announced on the OpenNMS Developers mailing list. Releases are announced on the OpenNMS announce mailing list and can also be found as entry on the OpenNMS Website and changes are published in Releases section of the project website.

Bug tracking

The OpenNMS community appreciates feedback from user and tester. Any bug in code, documentation or workflows can help us to improve the project and the software. If you find a bug please verify it is not already been reported by searching JIRAs bugs list: http://issues.opennms.org. In the top menu Issues, you can use Search for Issues in the project OpenNMS with Type: Bug.

If you found a new bug, fill out a bug report:

  • Give a clear, concise summary
  • Provide as much detail as possible in the description. Paste in your command output or stack traces, link to screenshots, etc.
  • Be sure to include which version of the software you are using. This is especially critical if you are using a development or unstable branch.
  • Add information about your Java environment which is used by OpenNMS. You can find it in the configuration java.conf in your OpenNMS configuration directory and by running java -version
  • Any deployment-specific info is helpful as well. Example: Ubuntu 14.04 LTS, which version of PostgreSQL, JRobin, RRDtool, store-by-group- or store-by-foreignsource settings.

To verify bugs you can use the mailing lists or the Q&A board.

Continuous Integration

For quality assurance we use Atlassian Bamboo as Continuous Integration (CI) system footnote:[Open Source Licensed, https://www.atlassian.com/software/bamboo]. It is publicly available on http://bamboo.internal.opennms.com:8085. It provides the following tasks:

  • Checks code for compile errors
  • Runs unit and integration test infrastructure
  • Runs final smoke tests
  • Build and generates Java API documentation
  • Build and generates version related documentation
  • Build and distribute RPM and DEB packages to public server

All branches in the OpenNMS GitHub repository will be processed by the CI system. Feature branches and results are distributed to the public available repository server as YUM and DEB package. If you are interested to get your branch of your forked OpenNMS processed through bamboo, please contact the OpenNMS Developer mailing list. There are also branches intended to fix bugs, which means that they do not introduce new features. These branches are named after the JIRA issue following the pattern NMS-{issue-number}. Builds are automatically triggered with changes in feature-, develop or master branches.

Pull Request Labels

Changes to the source code are made with Pull Requests and need to be reviewed for transparency and quality assurance. They can be merged from an elected OGP within the community or employees of The OpenNMS Group. The following labels are defined:

By Type
  • enhancement: Extend or improve an existing feature
  • docs: Changes to documentation
  • configuration: Changes to OpenNMS configuration for device and application monitoring support
  • backport: Changes which need to be back ported to older versions
  • bug: Fixes an existing bug in the code base
  • refactoring: Related just to code which does refactoring of same feature and functionality
By Workflow
  • duplicate: Changes are made already somewhere else
  • invalid: Changes can't be merged cause the code changes don't fit use cases
  • revert: This change reverts and previously merged Pull Request or Commit
  • review: This Pull Request is done and needs to be reviewed and merged to the code base
  • triage: This Pull Request can't be merged cause there are open questions or discussions which makes the PR incomplete to merge
  • wontfix: This Pull Request will not be merged for several reasons