Difference between revisions of "Installation:Yum"

From OpenNMS
Jump to navigation Jump to search
m (fix typo)
(Remove outdated content.)
(Tag: Replaced)
 
Line 2: Line 2:
 
{{Page Filter}}
 
{{Page Filter}}
  
{{warning|Official Install Guide|With OpenNMS Horizon we have now a version controlled official install guide which can be found here: http://docs.opennms.org/opennms/index.html. This wiki is going to be deprecated.}}
+
{{warning|Official Install Guide|With OpenNMS Horizon we have now a version-controlled official install guide which can be found here: http://docs.opennms.org/opennms/releases/latest/guide-install/guide-install.html. This wiki is going to be deprecated.}}
 
 
This tutorial covers installation for Linux distributions that make use of the YUM packaging system, including [http://fedoraproject.org/ Fedora®] , [http://www.redhat.com/rhel/ Red Hat Enterprise Linux®] and [http://www.centos.org/ CentOS].
 
 
 
== Select Your Release and Distribution ==
 
 
 
In order to tailor this tutorial to your distribution, please specify the release you decided upon previously, as well as your distribution version:
 
 
 
Hint: Please make sure you've Java Script activated to have a more convenient wiki page for your linux distribution.
 
Release in OpenNMS means, for example, "stable" or "snapshot".
 
 
 
<span class="page-filter-form-release"></span> <span class="page-filter-form-rpm-distribution"></span>
 
 
 
== Installing the Repository RPM ==
 
 
 
The first step is to install the "opennms-repo" RPM appropriate for your distribution.  This contains the information YUM needs to get OpenNMS package information for installing.
 
 
 
To do so, find the appropriate release RPM from https://yum.opennms.org/.
 
 
 
Then all you should need to do is install that repo package (as root):
 
 
 
  rpm -Uvh <nowiki>https://yum.opennms.org/repofiles/</nowiki>opennms-repo-{{Tutorial:Release}}-<span class="page-filter-rpm-distribution">'''''DISTRIBUTION'''''</span>.noarch.rpm
 
 
 
{{Try-It|title=Check for OpenNMS Packages|contents=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 -]$ rpm -Uvh \
 
    <nowiki>https://yum.opennms.org/repofiles/</nowiki>opennms-repo-{{Tutorial:Release}}-<span class="page-filter-rpm-distribution">'''''DISTRIBUTION'''''</span>.noarch.rpm
 
  Preparing...                ####################################### [100%]
 
  1:opennms-repo-{{Tutorial:Release}}-<span class="page-filter-rpm-distribution">'''''DISTRIBUTION'''''</span> ####################################### [100%]
 
  [user@opennms ~]$ yum search opennms
 
  Loaded plugins: fastestmirror
 
  <nowiki>====================== Matched: opennms =================================</nowiki>
 
  mib2opennms.i386: Generate OpenNMS Events from MIB Traps
 
  mib2opennms.x86_64: Generate OpenNMS Events from MIB Traps
 
  opennms.noarch: Enterprise-grade Network Management Platform
 
  opennms-core.noarch: The core OpenNMS backend.
 
  ...
 
}}
 
 
 
== Preparing the Database for OpenNMS ==
 
 
 
Before installing OpenNMS itself, you will want to install PostgreSQL, and do a few things to make sure PostgreSQL is working properly.
 
 
 
=== Installing PostgreSQL ===
 
 
 
First, you'll want to install PostgreSQL.  It is included in all of the major YUM-based distributions.  To install, just run the "<code>yum install</code>" command (as root):
 
 
 
  yum install postgresql postgresql-server
 
 
 
Note: The CentOS repository contains an older PostgreSQL v8.4.  Newer versions of PostgreSQL are generally very safe and add a lot of great features and performance enhancements. To install a newer version, such as v9.3, follow the instructions on the [http://www.postgresql.org/download/linux/redhat/ PostgreSQL RedHat family installation page].
 
 
 
=== Startup ===
 
 
 
Onec PostgreSQL is installed, the first thing you'll need to do is making sure PostgreSQL starts up properly.  On most distributions, you can just run (as root):
 
 
 
  /sbin/service postgresql start
 
 
 
Some distributions will require you to first initialize the database. If you see an error when running that command, try initdb first, and then start again:
 
 
 
  /sbin/service postgresql initdb
 
  /sbin/service postgresql start
 
 
 
Then, to ensure that PostgreSQL will start after a reboot, use the "<code>chkconfig</code>" command to enable start on bootup:
 
 
 
  /sbin/chkconfig postgresql on
 
 
 
NOTE: Redhat/CentOS 7 and variants use a different method of starting services.  The procedure to initialize and start the database are (installs may differ here):
 
 
 
  /usr/pgsql-9.4/bin/postgresql94-setup initdb
 
  /bin/systemctl start postgresql-9.4.service
 
  /bin/systemctl enable postgresql-9.4.service
 
 
 
=== Allowing User Access to the Database ===
 
 
 
By default, PostgreSQL only allows you to connect if you are logged in to the local account name that matches the PostgreSQL user.  Since OpenNMS runs as root, it cannot connect as a "postgres" or "opennms" user by default, so we have to change the configuration to allow that.
 
 
 
To do so, you will need to edit your database's '''pg_hba.conf''' file. On many default installations it can be found in the directory '''/var/lib/pgsql/data/''', however you may need to consult your distribution's PostgreSQL documentation for the location of this file if this is not the case.
 
 
 
By default '''pg_hba.conf''' should have entries similar to the following at the bottom of the file:
 
 
 
<pre>
 
local  all        all                              ident sameuser
 
host    all        all        127.0.0.1/32          ident sameuser
 
host    all        all        ::1/128              ident sameuser
 
</pre>
 
 
 
You will need to change these entries to resemble the following:
 
 
 
<pre>
 
local  all        all                              trust
 
host    all        all        127.0.0.1/32          trust
 
host    all        all        ::1/128              trust
 
</pre>
 
 
 
Once you have finished making changes, restart the database (as root):
 
 
 
  /sbin/service postgresql restart
 
 
 
Additionally, while it's beyond the scope of this beginning tutorial, you may want to check the [[Performance_tuning#Database_PostgreSQL_2|PostgreSQL section]] of the Performance Tuning page to get the most out of your database installation.
 
 
 
{{warning|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 consult the PostgreSQL documentation for setting a more restrictive environment.}}
 
 
 
== Installing the JDK ==
 
 
 
While we provide a JDK in our YUM repository as a fallback, it is very much recommended that you install the latest stable '''Java 7''' JDK from Oracle for the best performance.
 
 
 
{{warning|Java 8 is required beginning with OpenNMS 16|Starting with release 16, OpenNMS requires Java 8. Previous releases are ''not'' supported on Java 8. Please use Java 7 for OpenNMS 15.x and below.}}
 
 
 
To do so, go to [http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html the Oracle Java 8 SE JDK download page] or [http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html the Oracle Java 7 SE JDK download page], accept the license if you agree, choose the platform and architecture that's appropriate to your distribution (Linux x86 or Linux x64), and then download the jdk-*-rpm.bin file.
 
 
 
Once it has finished downloading, execute it from the command-line (it is a shell archive), and then install the resulting JDK rpm.
 
 
 
{{Try-It|title=Install the JDK|contents=After downloading the appropriate JDK file from Oracle, run the shell archive and install the RPM that gets unpacked.
 
 
 
<pre><nowiki>
 
[root@test ~]# rpm -ivh jdk-7u45-linux-i586.rpm
 
Preparing...                ########################################### [100%]
 
  1:jdk                    ########################################### [100%]
 
Unpacking JAR files...
 
        rt.jar...
 
        jsse.jar...
 
        charsets.jar...
 
        tools.jar...
 
        localedata.jar...
 
        jfxrt.jar...
 
        plugin.jar...
 
        javaws.jar...
 
        deploy.jar...
 
[root@test ~]#
 
</nowiki></pre>}}
 
 
 
== Installing OpenNMS ==
 
 
 
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, if they are not already installed on your system.
 
 
 
There are many packages available in the OpenNMS YUM repository, but the easiest way to get started is to install the "<code>opennms</code>" package. This will pull in everything you need to have a working OpenNMS, including the OpenNMS core, web UI, and a set of common plugins.
 
 
 
{{Try-It|title=Install OpenNMS|contents=Install OpenNMS, using the "<code>yum install</code>" command (as root):
 
 
 
  yum -y install opennms
 
 
 
You should see something like this:
 
 
 
<pre>...
 
Resolving Dependencies
 
--&gt; Running transaction check
 
---&gt; Package opennms.noarch 0:{{StableVersion}}-1 will be installed
 
---&gt; Package jicmp.x86_64 0:1.2.1-1 will be installed
 
---&gt; Package jicmp6.x86_64 0:1.0.1-1 will be installed
 
--&gt; Finished Dependency Resolution
 
 
 
<nowiki>Dependencies Resolved
 
 
 
===========================================================================
 
Package          Arch  Version            Repository              Size
 
===========================================================================
 
Installing:
 
opennms          noarch {{StableVersion}}-1            opennms-stable-common  2.2 k
 
Installing for dependencies:
 
jicmp            x86_64 1.2.1-1            opennms-stable-rhel6    44 k
 
jicmp6          x86_64 1.0.1-1            opennms-stable-rhel6    27 k
 
opennms-core    noarch {{StableVersion}}-1            opennms-stable-common  230 M
 
Transaction Summary
 
===========================================================================
 
Install      9 Package(s)
 
 
 
Total download size: 378 M
 
Installed size: 693 M
 
Downloading Packages:
 
...
 
(8/9): opennms-core-{{StableVersion}}-1.noarch.rpm            | 230 MB    07:23   
 
(9/9): opennms-webapp-jetty-{{StableVersion}}-1.noarch.rpm    |  75 MB    02:16   
 
---------------------------------------------------------------------------
 
Total                                      528 kB/s | 378 MB    12:13   
 
Running rpm_check_debug
 
Running Transaction Test
 
Transaction Test Succeeded
 
Running Transaction
 
  Installing : jicmp6-1.0.1-1.x86_64                                  1/9
 
  Installing : jicmp-1.2.1-1.x86_64                                    2/9
 
...
 
  Installing : opennms-{{StableVersion}}-1.noarch                                9/9
 
 
 
Installed:
 
  opennms.noarch 0:{{StableVersion}}-1
 
 
 
Dependency Installed:
 
  jicmp.x86_64 0:1.2.1-1                                                 
 
  jicmp6.x86_64 0:1.0.1-1                                                 
 
  opennms-core.noarch 0:{{StableVersion}}-1
 
  opennms-webapp-jetty.noarch 0:{{StableVersion}}-1
 
 
 
Complete!</nowiki></pre>}}
 
 
 
== Post-Install Configuration ==
 
 
 
=== Disable YUM Updates ===
 
 
 
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, you may want to disable the OpenNMS repositories after a successful installation by editing the "<code>/etc/yum.repos.d/opennms*</code>" file and adding '''enabled=0''' inside each <nowiki>[opennms-*]</nowiki> section. This can just as easily be changed back when it's time to upgrade.
 
 
 
=== Configure Java ===
 
 
 
Next, you need to tell OpenNMS which Java you want it to use, using the "<code>{{Tutorial:OPENNMS_HOME}}/bin/runjava</code>" command.  If you installed the recommended Sun/Oracle JDK, all you should need to do is point it at /usr/java/latest:
 
 
 
  {{Tutorial:OPENNMS_HOME}}/bin/runjava -S /usr/java/latest/bin/java
 
 
 
=== Create/Update the OpenNMS Database ===
 
 
 
Whenever you install OpenNMS or upgrade it, you should run the "<code>{{Tutorial:OPENNMS_HOME}}/bin/install</code>" command, to create the OpenNMS database, or update it to the latest version.  The install command takes many options, but in most cases all you should need is:
 
 
 
* -d - to update the database
 
* -i - to insert any default data that belongs in the database
 
* -s - to create or update the stored procedures OpenNMS uses for certain kinds of data access
 
 
 
{{Try-It|title=Create the Database|contents=Now it's time to create and configure the OpenNMS database.  To do so, run the following command (as root):
 
 
 
  {{Tutorial:OPENNMS_HOME}}/bin/install -dis
 
 
 
You should get output something like this:
 
 
 
<pre><nowiki>=========================================================================
 
OpenNMS Installer
 
=========================================================================
 
 
 
Configures PostgreSQL tables, users, and other miscellaneous settings.
 
 
 
- searching for jicmp:
 
  - trying to load /usr/lib64/libjicmp.so: OK
 
- searching for jicmp6:
 
  - trying to load /usr/lib64/libjicmp6.so: OK
 
...
 
- Running migration for changelog: URL [...]
 
INFO 2/1/12 12:48 PM:liquibase: Successfully acquired change log lock
 
INFO 2/1/12 12:48 PM:liquibase: Creating database history table
 
INFO 2/1/12 12:48 PM:liquibase: Reading from databasechangelog
 
INFO 2/1/12 12:48 PM:liquibase: Reading from databasechangelog
 
INFO 2/1/12 12:48 PM:liquibase: ChangeSet ran successfully in 54ms
 
...
 
INFO 2/1/12 12:49 PM:liquibase: Successfully released change log lock
 
- inserting PL/pgSQL iplike function... OK
 
 
 
Installer completed successfully!</nowiki></pre>}}
 
 
 
=== (Optional) Configure IPLIKE ===
 
 
 
OpenNMS uses a PostgreSQL stored procedure called "IPLIKE" which provides an API for easily performing complicated IP address queries.  By default, OpenNMS installs a version of IPLIKE that is compatible with all versions of PostgreSQL, but there is a platform-specific version of IPLIKE with much better performance.  While it is optional, it is recommended that you install the "<code>iplike</code>" package from YUM for performance reasons.
 
 
 
{{Try-It|title=Install IPLIKE|contents=To do so, install the "<code>iplike</code>" package with yum, like so (as root):
 
 
 
  yum -y install iplike
 
 
 
You should see it finish with something like this:
 
 
 
<pre><nowiki>Installed size: 30 k
 
Downloading Packages:
 
iplike-2.0.2-1rhel6.x86_64.rpm                  |  16 kB    00:00   
 
Running rpm_check_debug
 
Running Transaction Test
 
Transaction Test Succeeded
 
Running Transaction
 
  Installing : iplike-2.0.2-1.el6.x86_64                          1/1
 
- installing iplike into the opennms db (if it exists)... OK
 
 
 
Installed:
 
  iplike.x86_64 0:2.0.2-1.el6                                         
 
 
 
Complete!</nowiki></pre>
 
 
 
If you don't see "OK" next to the "installing iplike into the opennms db" line, for example if you changed the default PostgreSQL authentication options for security reasons, then you may have to run the script manually.  For details on the options available to you when running manually, run:
 
 
 
  /usr/sbin/install_iplike.sh -h
 
 
 
}}
 
 
 
=== Configure Your Firewall ===
 
 
 
Depending on your installation, some distributions will disable connecting to unknown IP ports by default.
 
 
 
Assuming that the '''iptables''' service is enabled, in order to permit connections from IP address other than the '''localhost (127.0.0.1)''', it is necessary to add a rule to the configuration file to allow OpenNMS.
 
 
 
==== Add a Firewall Exception for OpenNMS ====
 
 
 
In the case of RHEL and CentOS, this file is: '''/etc/sysconfig/iptables'''.  If you edit this file, you should see 1 or more lines starting with "-A INPUT" and containing a destination port ("--dport").  You will want to make a copy of one of these lines, and changed the destination port to 8980, like so:
 
 
 
  ...
 
  -A INPUT -p icmp -j ACCEPT
 
  -A INPUT -i lo -j ACCEPT
 
  -A INPUT -m state --state NEW -m tcp -p tcp --dport 22 -j ACCEPT
 
  '''-A INPUT -m state --state NEW -m tcp -p tcp --dport 8980 -j ACCEPT'''
 
  -A INPUT -j REJECT --reject-with icmp-host-prohibited
 
  ...
 
 
 
Note that some versions of CentOS and RHEL, instead of "'''INPUT'''" you will see something like "'''RH-Firewall-1-INPUT'''".  These are equivalent.  For the technical details, see the man page for iptables.
 
 
 
==== Restricting Connections to a Specific Subnet ====
 
 
 
It is common, however to restrict such connections only from a trusted range of IP addresses, and the addition to '''iptables''' of an optional '''-s address/mask''' is probably a better practice:
 
 
 
  ...
 
  -A INPUT -p icmp -j ACCEPT
 
  -A INPUT -i lo -j ACCEPT
 
  -A INPUT -m state --state NEW -m tcp -p tcp --dport 22 -j ACCEPT
 
  '''-A INPUT -m state --state NEW -m tcp -p tcp ''-s 12.34.56.00/24'' --dport 8980 -j ACCEPT'''
 
  -A INPUT -j REJECT --reject-with icmp-host-prohibited
 
  ...
 
 
 
This example would add permitted access from the C-class network at: 12.34.56.00 through 12.34.56.255, being specified using CIDR notation.
 
 
 
==== Restart the Firewall ====
 
 
 
Once you have made your edits, you can restart the firewall by running the service command (as root):
 
 
 
  /sbin/service iptables restart
 
 
 
''Before logging out, try connecting to your server again to confirm connectivity.''
 
 
 
== Start OpenNMS and Connect to the Web UI ==
 
 
 
You can now start OpenNMS using the "service" command (as root):
 
 
 
  /sbin/service opennms start
 
 
 
{{Try-It|title=Connect to the Web UI|contents=Try starting OpenNMS, and connecting to the web UI.
 
 
 
  /sbin/service opennms start
 
 
 
You should be able to go to http://YOUR-OPENNMS-IP:8980/opennms/ in your browser and see the web UI.  The default username and password are both "admin" so enter them in when you see the login prompt.}}
 
 
 
== Change the Administrator Password ==
 
 
 
As mentioned above, the default username is "admin" and the default password is "admin" as well.  It is recommended that you change the administrator user's password, for security reasons.  To do so, log in to the web UI and then click on the username (admin) in the upper-right corner, and then click "Change Password."  Enter the old and new passwords in the prompt, and click "OK."
 
 
 
{{Try-It|title=Change the Default Password|contents=To change the default password, browse to http://YOUR-OPENNMS-IP:8980/opennms/ and log in as administrator:
 
 
 
[[File:Login-admin.png|Log In as Admin]]
 
 
 
...then click the admin username in the upper-right corner:
 
 
 
[[File:Edit-admin-user.png|Edit Admin User]]
 
 
 
...and finally, click "Change Password," then fill out the form.}}
 
  
 
{{Tutorial:Next|Scan Your First Device|Capability Scanning|Now that OpenNMS is installed, it's time to scan your first device!  Let's move on to [[Tutorial Capability Scanning|the Capability Scanning tutorial]].}}
 
{{Tutorial:Next|Scan Your First Device|Capability Scanning|Now that OpenNMS is installed, it's time to scan your first device!  Let's move on to [[Tutorial Capability Scanning|the Capability Scanning tutorial]].}}
  
 
{{Tutorial:Footer}}
 
{{Tutorial:Footer}}

Latest revision as of 09:15, 4 November 2019


Warning.png Official Install Guide

With OpenNMS Horizon we have now a version-controlled official install guide which can be found here: http://docs.opennms.org/opennms/releases/latest/guide-install/guide-install.html. This wiki is going to be deprecated.



Next-arrow.png Next Step: Scan Your First Device

Now that OpenNMS is installed, it's time to scan your first device! Let's move on to the Capability Scanning tutorial.