Get OpenNMS
Get Involved
Get to Know Us
From OpenNMS
Contents |
Installing on RedHat-Based Distributions
These instructions cover installation for Linux distributions that make use of the YUM packaging system. Some distributions that make use of this packaging system include Fedora® , Red Hat Enterprise Linux® and CentOS.
While it is possible to obtain and install the OpenNMS packages without the help of this document, following some of the guidelines within may simplify the process and provide some assistance on what to do post-installation.
Installing a YUM package puts a permanent repository reference into the system the package is installed on. This allows the administrator of the machine to have an upgrade path for future OpenNMS releases. You may choose to disable the repository after installation to disable this feature.
The YUM packaging system will also attempt to resolve any dependencies required by a package and install them as well. For instance, installing the opennms-plugins.noarch package will attempt to install opennms-plugin-provisioning-link.noarch, opennms-plugin-provisioning-map.noarch and other dependencies as well.
Installing on Red Hat Enterprise Linux 4
If you want to use YUM on Red Hat Enterprise Linux 4 instead of uptodate, see the Yum on RHEL4 page.
Preparation: YUM Fastest Mirror Plugin
Before you begin, you may want to install the install the YUM fastestmirror package if it is supported by your platform. This package will attempt to optimize your selection of download mirrors to provide the best speeds possible. Fully deploying and administering this package is outside the scope of this document, instead refer to the fastestmirror documentation on the CentOS wiki site.
Example fastestmirror install:
[user@opennms ~]$ su -c 'yum install yum-fastestmirror' Setting up Install Process ... Running Transaction Installing: yum-fastestmirror ######################### [1/1] Installed: yum-fastestmirror.noarch 0:1.1.9-2.fc8 Complete!
Choosing an OpenNMS Release
The OpenNMS Community makes four builds of the OpenNMS software platform available through YUM repositories. These builds vary in purpose, from deployment ready to developer specific to those who wish to live on the cutting edge. You'll need to pick from one of the following options:
- stable
- The latest officially released stable version of OpenNMS. Current stable version is 1.8.3. If you are putting OpenNMS into a production environment for daily use, this is the recommended version install.
- unstable
- The latest officially released development version of OpenNMS. This may have more features than the stable version, but it may also contain bugs that have yet to be discovered or triaged.
- testing
- a nightly build of the code that will be part of the next stable version of OpenNMS
- snapshot
- a nightly build of the very latest development version of OpenNMS
Installing the Repository RPMs
To allow your system to fetch the OpenNMS packages from the OpenNMS YUM repository, you must first install the appropriate package from the OpenNMS YUM Repository site. Choose the release you want to use and then install the distribution-specific RPM package appropriate for your platform.
To install this package, type: su -c 'rpm -Uvh package_url' at a shell prompt. If the package you wish to install is located at http://yum.opennms.org/repofiles/opennms-repo-stable-fc13.noarch.rpm, run:
[user@opennms ~]$ su -c 'rpm -Uvh http://yum.opennms.org/repofiles/opennms-repo-stable-fc13.noarch.rpm'
Once you've installed the distribution-specific RPM package of your choice, a query of the YUM database should show OpenNMS as an available install option when you run yum search opennms:
[user@opennms ~]$ yum search opennms Loaded plugins: fastestmirror Excluding Packages from CentOS-5 - Base Finished Excluding Packages from CentOS-5 - Updates Finished ============================ Matched: opennms ======================================= mib2opennms.i386 : Generate OpenNMS Events from MIB Traps mib2opennms.x86_64 : Generate OpenNMS Events from MIB Traps opennms.noarch : Enterprise-grade Network Management Platform (Easy Install) opennms-core.noarch : The core OpenNMS backend. opennms-docs.noarch : Documentation for the OpenNMS network management platform opennms-plugin-provisioning-dns.noarch : DNS Provisioning Adapter for OpenNMS opennms-plugin-provisioning-link.noarch : Link Provisioning Adapter for OpenNMS opennms-plugin-provisioning-map.noarch : Map Provisioning Adapter for OpenNMS opennms-plugin-provisioning-rancid.noarch : RANCID Provisioning Adapter for OpenNMS opennms-plugin-ticketer-centric.noarch : OpenNMS Trouble-Ticketer Plugin: CentricCRM opennms-plugins.noarch : All Plugins for OpenNMS opennms-remote-poller.noarch : Remote (Distributed) Poller for OpenNMS opennms-repo-stable.noarch : Yum repository files for stable/rhel5 OpenNMS opennms-webapp-jetty.noarch : Embedded web interface for OpenNMS opennms-webapp-standalone.noarch : Standalone web interface for OpenNMS
Systems With Older Versions of YUM
Some older versions of yum do not recognize /etc/yum.repos.d/ as a valid location for YUM repositories, which will make the command above not return any results. In this case you will need to append the OpenNMS repositories to the end of /etc/yum.conf by typing su -c 'cat /etc/yum.repos.d/* >> /etc/yum.conf' at a command prompt to ensure YUM is able to fetch the packages from the OpenNMS repository.
Installing the PostgreSQL Database Server
While YUM will install the PostgreSQL packages automatically, there are several reasons to install PostgreSQL prior to your OpenNMS installation:
- Installing PostgreSQL first will result in an optimized IPLIKE stored procedure for your OpenNMS database which greatly improves performance. IPLIKE can easily be installed later, but installing PostgreSQL first automates this task when the OpenNMS installer is run later.
- Your Linux distribution may ship with a version of PostgreSQL that may not have the optimizations and features of a later version of PostgreSQL. Later versions of PostgreSQL ship with maintenance features turned on by default, which greatly help with maintenance of the OpenNMS database after deployment. For more information on this topic, see the [Configuring YUM] section of the commandprompt.com wiki.
To install PostgreSQL from your distribution's official sources, type: su -c 'yum -y install postgresql-server' at the command prompt.
Example PostgreSQL server install using default distribution repositories:
[user@opennms ~]$ sudo yum -y install postgresql-server Setting up Install Process ... Running Transaction Installing: postgresql-server ######################### [1/1] Installed: postgresql-server.x86_64 0:8.2.5-1.fc8 Complete!
After successful installation of the PostgreSQL server you will need to initialize the database with su -c 'service postgresql initdb', then start the database with su -c 'service postgresql start'. To ensure this configuration is persistent upon a reboot of the server, type: su -c 'chkconfig postgresql on' at the command prompt.
Configuring PostgreSQL for OpenNMS
OpenNMS needs to be able to connect to PostgreSQL as the postgres user over a TCP/IP connection by default.
To allow OpenNMS to connect to the database, you will need to edit your database's pg_hba.conf file. On many default installations it can be found in /var/lib/pgsql/data, however you may need to consult your distribution's PostgreSQL documentation for the location of this file.
By default pg_hba.conf should have entries similar to the following at the bottom of the file:
local all all ident sameuser host all all 127.0.0.1/32 ident sameuser host all all ::1/128 ident sameuser
You will need to change these entries to resemble the following:
local all all trust host all all 127.0.0.1/32 trust host all all ::1/128 trust
Next, you will need to edit postgresql.conf to accept TCP/IP connections. As with pg_hba.conf, check the defaults or your distribution's PostgreSQL documentation for the location of this file. Both postgresql.conf and pg_hba.conf by default should be in the same location.
Depending on your version of PostgreSQL, the directive within the postgresql.conf file that must be changed may either be labeled tcpip_socket or listen_addresses. Configuration file comments will indicate whether you need to uncomment this to make the daemon listen or what you may need to change this parameter to. Make the appropriate changes, save your file, and quit your editor.
Example section from postgresql.conf with network listening enabled:
... # you can use "*" to listen on all addresses listen_addresses = 'localhost' ...
Security Implications
The above changes to the default PostgreSQL configuration will make it easy to install OpenNMS on your server, but it also allows for anyone with a local user account to have full access to said DB. As this guide is a quick start, the assumption is that the server is limited to users of the OpenNMS system. If this is not the case, you should probably consult the PostgreSQL documentation for setting a more restrictive environment.
Additionally you will want to be certain that that the max number of of simultaneous connections is configured to be greater than c3p0.maxPoolSize in $OPENNMS_HOME/etc/c3p0.properties (50 by default) +10.
max_connections = 60
Configuring PostgreSQL Beyond the Defaults
PostgreSQL will self-adjust many parameters, but some have to be hand-set to get performance beyond modest defaults. When increasing these values, you may find that PostgreSQL does not start because the desired PostgreSQL parameters require changes in your system's kernel parameters. The PostgreSQL section of the Performance Tuning portion of the wiki will help you set these and get the most out of your PostgreSQL server
To apply the changes you've made to the PostgreSQL configuration, you will need to restart it with su -c 'service postgresql restart'
Lastly, to create the database for OpenNMS enter the following at the command prompt :
[user@opennms ~]$ su - postgres -c 'createdb -U postgres -E UNICODE opennms'
Installing the OpenNMS packages
With all the prerequisites taken care of, you can now install OpenNMS. The OpenNMS software is not a single package, but a combination of many components. The YUM packaging system will download and install all of these components and their dependencies, such as the Java environment and others if they are not already configured on your system.
There are many packages available in the OpenNMS YUM repository, but as this is a quick start, we will install the one package that will provide everything you need to get started. To install this package type: su -c 'yum install opennms'. If you are on a fast connection and have setup the YUM fastestmirror plugin, this will take just a few moments to download the packages required and proceed to installing them.
{{important|Disabling the OpenNMS Repository|Some distributions that use YUM/RPM as a package management system will attempt an automatic update at regular intervals. A system administrator could potentially run a manual update and inadvertently upgrade OpenNMS resulting in a misconfiguration or complete failure. To avoid these scenarios, disable the OpenNMS repositories after a successful installation by adding enabled=0 to the files matching /etc/yum.repos.d/opennms*. This can just as easily be changed back when it's time to upgrade.
Example YUM Installation of the OpenNMS base packages:
[user@opennms ~]$ sudo yum install opennms ... Setting up repositories opennms-snapshot-rhel5 100% |=========================| 1.1 kB 00:00 opennms-unstable-common 100% |=========================| 1.1 kB 00:00 opennms-stable-common 100% |=========================| 1.1 kB 00:00 opennms-unstable-rhel5 100% |=========================| 1.1 kB 00:00 ... Resolving Dependencies --> Populating transaction set with selected packages. Please wait. ---> Downloading header for opennms to pack into transaction set. opennms-1.6.1-1.noar 100% |=========================| 5.4 kB 00:00 ---> Package opennms.noarch 0:1.6.1-1 set to be updated --> Running transaction check --> Processing Dependency: opennms-core = 1.6.1-1 for package: opennms .. Dependencies Resolved ============================================================================= Package Arch Version Repository Size ============================================================================= Installing: opennms noarch 1.6.1-1 opennms-stable-common 5.9 k Installing for dependencies: jicmp i386 1.0-1 opennms-stable-rhel5 31 k opennms-core noarch 1.6.1-1 opennms-stable-common 48 M opennms-webapp-jetty noarch 1.6.1-1 opennms-stable-common 27 M postgresql i386 8.1.9-1.el5 updates 2.8 M postgresql-server i386 8.1.9-1.el5 updates 4.0 M Transaction Summary ============================================================================= Install 6 Package(s) Update 0 Package(s) Remove 0 Package(s) Total download size: 82 M Is this ok [y/N]: y Downloading Packages: (1/6): opennms-core-1.6.1 100% |=========================| 48 MB 03:57 ... Running Transaction Installing: postgresql ######################### [1/6] Installing: postgresql-server ######################### [2/6] Installing: jicmp ######################### [3/6] Installing: opennms-core ######################### [4/6] Installing: opennms-webapp-jetty ######################### [5/6] Installing: opennms ######################### [6/6] - moving *.sql.rpmnew files (if any)... done - checking for old update files... done *** Installation complete. You must still run the installer and *** make a few other changes before you start OpenNMS. See the *** install guide and release notes for details. Installed: opennms.noarch 0:1.6.1-1 Dependency Installed: jicmp.i386 0:1.0-1 opennms-core.noarch 0:1.6.1-1 opennms-webapp-jetty.noarch 0:1.6.1-1 postgresql.i386 0:8.1.9-1.el5 postgresql-server.i386 0:8.1.9-1.el5 Complete!
Configuration
Running the OpenNMS Installer
Now that the OpenNMS distribution packages are installed on your system, there are a few tasks to complete before starting the service.
First, OpenNMS needs to which Java JDK it needs to take advantage of. To set this and persist the setting, run: su -c '/opt/opennms/bin/runjava -s'. Running this command will search through your system for possible Java environments and select the best one for OpenNMS to use.
Next, you will need to run the OpenNMS installer which will bootstrap your database and initialize the system to prepare for operation. Depending on your system's hardware, this could take anywhere from a few moments to a few minutes. If the installer cannot proceed for some reason, or there is a problem with the system configuration, the installer will do its best to tell you what is wrong and how to remedy it.
To run the OpenNMS installer on a machine installed from YUM sources, run
[user@opennms ~]$ su -c '/opt/opennms/bin/install -dis'
Once the installer is complete, you can start OpenNMS. To start OpenNMS on most systems that are Red Hat derived, type: su -c 'service opennms start'. If you wish to have OpenNMS started at boot-time, you will need to set this with chkconfig. On most systems, use su -c 'chkconfig opennms on' to have OpenNMS started at boot time. You can now login with the admin/admin login and password combination to your new OpenNMS instance at http://your-server-address:8980/opennms/.
Discover Your Network
OpenNMS needs to know which devices (or, "nodes") you want it to discover. To discover nodes, OpenNMS does a ping sweep on IP address ranges that you configure it to discover. If an IP address that OpenNMS is not already managing responds to a discovery ping, then OpenNMS will begin scanning that IP address for services, create a new node in its database, and begin monitoring the node's interfaces and services. A new install of OpenNMS will not perform any discovery until you add one or more address ranges to the discovery configuration. You do this by logging into the web UI as the admin user and navigating to the Admin menu and then clicking on 'Configure Discovery' under the Operations section.
In the Include Ranges section of the Home / Admin / Discovery / Modify Configuration page, click on the 'Add New' button. In the window that pops up, enter the beginning and ending IP addresses for the range that you wish to include for discovery. The default values for Retries and Timeout are usually appropriate. Click the 'Add' button, and the popup window will close and the new range will show up in the Include Ranges section. Click the 'Save and Restart Discovery' button to apply your changes. Discovery of the newly added range will begin within a few seconds; the ping requests and service scans are spread out over time to avoid flooding your network, so it will take some time for all nodes in your newly added range to be scanned and discovered.
For more detailed information on discovery configuration, including how to add IP addresses manually to the discovery configuration file, see Discovery.
