
[[getting-started-core]]
= Installation and Configuration
:description: Install and configure OpenNMS instance including PostgreSQL setup on CentOS/RHEL 9, Debian/Ubuntu, and Docker.

This section explains how to install and configure a new {page-component-title} instance, including the following tasks:

* Install all required OpenNMS {page-component-title} components, including PostgreSQL, on a single node.
* Run {page-component-title} core and PostgreSQL with the default configuration.
+
NOTE: The default configuration is not optimized to run in a production environment or monitor large networks.

** By default, your time series database is RRDtool, which persists RRD files on the local file system.
* Sign in to the web UI and change the `admin` account's default password.

== DNS considerations

If you are planning a large deployment, you may need to review your DNS configuration to ensure name lookups can be processed quickly.
DNS lookups may be performed by different processes, including while provisioning new nodes and when receiving syslog messages.
It is vital that DNS lookups can be performed quickly to prevent them from becoming a bottleneck, which can happen if your deployment covers thousands of nodes.
One way to mitigate DNS performance is to set up your {page-component-title} as a secondary DNS server so that it is able to self-host DNS records for your network.

ifeval::["{page-component-title}" == "Horizon"]
== Quick installation

If you want to get started quickly with OpenNMS Horizon on a bare metal system or a virtual machine, you can check out our https://github.com/opennms-forge/opennms-install[quick installation scripts].
This convenient script installs Horizon on Debian or Red Hat compatible systems, running the steps documented in this section of the deployment guide.
Use this quick starting point to evaluate and explore how to configure Horizon before moving to more complex distributed environments.

=== Scope

* Bootstrap a single-node Horizon system on RPM or DEB-based systems quickly, with the latest stable release.
* Installation follows the best practices from our official docs.
* Script is only for new installations and does not deal with existing installations or upgrades.
* Script does not configure or install Minions, Sentinels, or distributed time series storage like Newts or Cortex.

endif::[]

[[requirements]]
== Requirements

The following components and settings are required to set up a new {page-component-title} instance:

ifeval::["{page-component-title}" == "Meridian"]
* Credentials to access the Meridian repositories.
endif::[]
* A Linux physical server, or a virtual machine running a <<./system-requirements.adoc#operating-systems-core, supported Linux operating system>>.
* Internet access to download the installation packages. xref:system-requirements.adoc
* A working DNS server, and a localhost and server name that resolve properly.
* A system user with administrative permissions (`sudo`) to perform installation.
* A SELinux policy that permits binding to the ICMP service, if necessary.
+
NOTE: If you do not include the appropriate SELinux policy, {page-component-title} may generate an ICMP permissions error when starting up (see xref:reference:configuration/selinux.adoc[]).

ifeval::["{page-component-title}" == "Horizon"]
* To run services in Docker, you need https://docs.docker.com/compose/install[Docker Compose] for the service stacks from our examples.
* On Debian, you must install and configure `sudo` yourself.
See the https://wiki.debian.org/sudo/[Debian Wiki] for more information.
endif::[]

include::../time-sync.adoc[]

[[setup-postgresql]]
== Set up PostgreSQL

TIP: PostgreSQL 14 and 15 use the `scram-sha-256` https://www.postgresql.org/docs/14/auth-password.html[password authentication] method by default.
If you use older versions of PostgreSQL, you should change the method to `md5` in the `pg_hba.conf` before installing the {page-component-title} core instance.

== Pool size and maximum database connections

You must configure the PostgreSQL https://www.postgresql.org/docs/15/runtime-config-connection.html[max_connections] setting to allow at least 70 connections.
The number of connections is defined by the `maxPool` setting for each datasource (opennms 50 + opennms-admin 10 + opennms-monitoring 10).
The `maxSize` is not used with the `HikariCPConnectionFactory`, which is deprecated and just here for backward compatibility.

If you change the max pool size, make sure you also update the `max_connections`.
You typically set this in `PG_HOME/data/postgresql.conf`, but you may also use the `ALTER SYSTEM` syntax.
You must restart the PostgreSQL server to take effect.

NOTE: You may find https://pgtune.leopard.in.ua/[PGTune] useful to calculate configuration parameters for PostgreSQL.
As with all third-party tools, we do not endorse or guarantee it.
Use it at your own discretion.

[{tabs}]
====
CentOS 9::
+
--
include::centos9/postgresql.adoc[]
--

CentOS/RHEL 10::
+
--
include::centos-rhel10/postgresql.adoc[]
--
ifeval::["{page-component-title}" == "Horizon"]

Debian/Ubuntu::
+
--
include::debian-ubuntu/postgresql.adoc[]
--

Docker::
+
--
include::docker/postgresql.adoc[]
--
endif::[]
====

[[install-core-instance]]
== Install the core instance

IMPORTANT: For security reasons, {page-component-title} is designed to run within an organization's protected intranet.
Do not expose the web console or sign-in pages directly to the Internet without appropriate isolation controls, (for example, a VPN with multi-factor authentication).

[{tabs}]
====
CentOS 9::
+
--
include::centos9/install-core.adoc[]
--

CentOS/RHEL 10::
+
--
include::centos-rhel10/install-core.adoc[]
--

ifeval::["{page-component-title}" == "Horizon"]

Ubuntu::
+
--
include::ubuntu/install-core.adoc[]
--

Debian::
+
--
include::debian/install-core.adoc[]
--

Docker::
+
--
include::docker/core.adoc[]
--
endif::[]
====

[[set-up-core-instance]]
== Set up the core instance

[{tabs}]
====
CentOS/RHEL::
+
--
include::centos/initialize-core.adoc[]
--

ifeval::["{page-component-title}" == "Horizon"]
Debian/Ubuntu::
+
--
include::debian-ubuntu/initialize-core.adoc[]
--

Docker::
+
--
include::docker/initialize.adoc[]
--
endif::[]
====

[[ga-data-choices]]
== First-time sign in

After you start the {page-component-title} core services, you can access the web application at `\http://core-instance-ip:8980/opennms`.
The default user credentials are as follows:

* *Username:* `admin`
* *Password:* `admin`

When you try to sign in with these credentials, {page-component-title} prompts you to change your password.
Although you can also skip this action and sign in with default the credentials, we strongly recommend that you change the `admin` account's password to a secure one.

. Type your current password.
. Type your new password and confirm it.
. Click *Change Password*.

== Change password after first sign in

To change your account's password after the first time you sign in, follow these steps:

. On the top menu bar, click menu:Admin[Change Password].
. Type your current password and new password in the appropriate fields.
. Confirm your new password and click *Submit*.

The password is updated.

We encourage you to use {page-component-title} with individual user accounts instead of using only the `admin` account.
If all users have individual accounts, you can see who is completing tasks, (for example, clearing or acknowledging alarms).
For information on how to create personalized user accounts, see xref:operation:quick-start/users.adoc#create-user[Create a new user] in the Quick Start guide.

[[usage-statistics]]
=== Usage statistics

The first time you sign in, {page-component-title} notifies you that it collects anonymized usage statistics and publishes them to https://stats.opennms.com.
Consent to share collected usage statistics is assumed by default.

The OpenNMS Group uses this information to help determine product use and to improve the {page-component-title} software.
We do not share it with third parties, and we will not use it for sales purposes.

Click *Learn More* to view the xref:operation:deep-dive/admin/configuration/usage-statistics.adoc[information that we collect and share].
This also hides the notification.

Click *Dismiss* to simply hide the notification.
You can view the usage statistics at any time on the admin page.

NOTE: Admin users can xref:operation:deep-dive/admin/configuration/usage-statistics.adoc#disable-data-collection[opt out of sharing the statistics] at any time.

== First monitored node

The default configuration will discover a single node with an interface `127.0.0.1` and detect services exposed on the loopback interface, including the `OpenNMS-JVM` service.
Nodes with this service have JMX-based data collection performed on Java JVM statistics such as heap memory and open file handles.

== Related topics

* xref:operation:deep-dive/admin/configuration/startup.adoc[]
* xref:reference:configuration/selinux.adoc[]
* xref:reference:configuration/receive-snmp-traps.adoc[]
* xref:core/installing-jdbc-driver.adoc[]

== Next steps

See the xref:operation:quick-start/introduction.adoc[Quick Start guide] for more information on setting up and configuring your {page-component-title} instance.
