Installation Guide

OneDDI - 3.1.6

Contents

  1. Introduction
  2. OneDDI Application
    1. Requirements
    2. Installation
    3. Upgrade
    4. Uninstallation
  3. OneDDI Sensor
    1. Requirements
    2. Installation
    3. Upgrade
    4. Uninstallation
  4. OneDDI Agent
    1. Requirements
    2. Installation
    3. Upgrade
    4. Uninstallation

Introduction

Welcome to the VendorN OneDDI product (OneDDI)!

This document details the necessary steps to install, upgrade and uninstall the OneDDI application. This document is aimed at product administrators.

OneDDI consists of the following installable componenents:

  • Application - Main OneDDI application, required for all modules
  • Agent - Windows agent used to forward DNS activity, collected from the DNS diagnostic logging feature of the Windows DNS server, to a OneDDI sensor, required for the Vision module when collecting data for Windows DNS servers
  • Sensor - Componenent used by Vision to collect, aggregate and alert on DNS activity from various supported sources, at least one sensor is required by the Vision module

One section in this document identifies the installation, upgrade and uninstallation steps for each of the above components.

When upgrading OneDDI, components should be upgraded in the following order:

  1. The main OneDDI application
  2. All OneDDI sensors
  3. All OneDDI agents

OneDDI Application

Requirements

OneDDI requires a product license to operate. An evaluation license can be requested by sending an email to VendorN, quoting the company name. Two product licenses exist, an “enterprise” and a “sme” license. The enterprise license is unrestricted. The sme license does not permit management of the real-time replication feature and only permits management of one OneDDI sensor. Once a license has been obtained, following installation the license is applied via the OneDDI user interface.

The OneDDI application is currently tested on 64bit Red Hat/CentOS 7, 8 and 9 systems. All OneDDI application components ship with all dependent software and do not require any software that would not otherwise be installed on a typical system.

OneDDI integrates with both the BlueCat Address Manager and Infoblox NIOS DNS, DHCP and IP address management (DDI) platforms. For Infoblox, OneDDI utilises the Infoblox API which is versioned e.g. /wapi/<version>/.... OneDDI is tested with an Infoblox API version of at least 2.0. For BlueCat, OneDDI utilises the RESTful V2 API available in Address Manager 9.5 and onwards.

When using the Vision module, the following is a recommended minimum hardware configuration:

  • At least 8 CPU cores
  • 8GB RAM
  • 2TB disk space

When NOT using the Vision module, the following is a recommended minimum hardware configuration:

  • At least 4 CPU cores
  • 4GB RAM
  • 20GB disk space

Either physical or virtual hardware can be used for production deployments in both cases.

Installation

The OneDDI application installer is named oneddi-<version>-1.x86_64.rpm - where <version> is the version being installed. This program should be transferred to a temporary location on the target server. The following steps can then be used to install the OneDDI application:

  1. Create the oneddi user - the OneDDI application will run as this user once started:

    sudo useradd oneddi

  2. Use the following command to install the OneDDI application:

    sudo yum install oneddi-<version>-1.x86_64.rpm

  3. Following installation, the OneDDI application will be installed as a system service and started, and will listen on TCP port 443. If a local firewall is running it may require an update to permit TCP port 443 connections to the application. For example, when using firewalld commands similar to the following may be used:

    sudo firewall-cmd --add-port=443/tcp --permanent
sudo firewall-cmd --reload

  4. Verify the web user interface can be accessed using the following URL:

    https://<ip-address-or-hostname>

  5. If a OneDDI license has been obtained it can now be applied via the OneDDI user interface.

Following the installation the default user admin will exist with the default password of OneDDI!. This user will have full permissions associated to manage all features of OneDDI and can be used for initial setup of the system.

Upgrade

Unless otherwise specified all versions of OneDDI are backwards compatible with all previous versions. That is, any newer version can be installed over the top of any older version. No version is forwards compatible though, and an older version cannot be installed over the top of a newer version.

The main OneDDI application is compatible with older OneDDI sensors. Currently no constraints are made on which sensor versions OneDDI applications support.

During an upgrade when replication is configured the active and standby peer databases can have different and incompatible schemas. Therefore, to upgrade a replication pair the replication relationship must be broken, i.e. replication must be deconfigured before the upgrade is performed. Once the upgrade is complete on both the active and standby peers replication can then be reconfigured.

Before an upgrade a backup of the application database should be taken by following the steps in the Redundancy / Backup & Restore section in the Admin Guide.

The OneDDI installer is named oneddi-<version>-1.x86_64.rpm - where <version> is the version of OneDDI being installed. This program should be transferred to a temporary location on the target server. The following steps can then be used to upgrade OneDDI:

  1. If replication is configured deconfigure replication.

  2. Use the following command to uninstall the existing OneDDI version - note that all data and configuration will NOT be removed by this command and it will remain under the /opt/oneddi directory once removed, this will then be used by the new version once installed:

    sudo yum remove oneddi

  3. Use the following command to install the OneDDI application:

    sudo yum install oneddi-<version>-1.x86_64.rpm

  4. Verify the web user interface can be accessed using the following URL:

    https://<ip-address-or-hostname>

If replication was deconfigured to perform the upgrade replication can be reconfigured again if both the active and standby peer have been upgraded.

Uninstallation

The following steps can then be used to uninstall the OneDDI application:

  1. Use the following command to uninstall the OneDDI application:

    sudo yum remove oneddi

  2. During the initial installation of OneDDI the oneddi user will have been created for the OneDDI web server. If the oneddi user is no longer required remove the user using the following command:

    sudo userdel -r oneddi

  3. If a local firewall is running, and it was updated to permit TCP port 443 connections to the web server, it may require an update to no longer allow TCP port 443 connections. For example, when using firewalld commands similar to the following may be used:

    sudo firewall-cmd --remove-port=443/tcp --permanent
sudo firewall-cmd --reload

Following uninstallation all data and configuration files specific to the host will still be located under the /opt/oneddi directory. If the data and configuration files are no longer required they can be removed using the following command:

sudo rm -r /opt/oneddi

OneDDI Sensor

Requirements

The OneDDI sensor is currently tested on 64bit Red Hat/CentOS 7, 8 and 9 systems. All OneDDI sensor components ship with all dependent software and do not require any software that would not otherwise be installed on a typical system.

Hardware requirements will depend on DNS query and response volume processed by the sensor. The following table identifies the minimum recommend hardware based on total messages per second (MPS, i.e. both queries and responses combined) from all the DNS servers sending their activity to the sensor:

MPS CPU cores RAM Disk space
Up to 20,000 8 8GB 200GB
Over 20,000 8 16GB 500GB

NOTE Disk space is used to cache data in the case of an error communicating back to the main OneDDI application. The sensor does not store any data which needs to be backed up.

Either physical or virtual hardware can be used for production deployments in all cases.

Installation

The OneDDI sensor installer is named oneddi-sensor-<version>-1.x86_64.rpm - where <version> is the version being installed. This program should be transferred to a temporary location on the target server. The following steps can then be used to install the OneDDI sensor:

  1. Create the oneddi user - the OneDDI sensor will run as this user once started:

    sudo useradd oneddi

  2. Use the following command to install the OneDDI sensor:

    sudo yum install oneddi-sensor-<version>-1.x86_64.rpm

  3. Following installation, the OneDDI sensor will be installed as a system service and started, and will listen on TCP port 444. If a local firewall is running it may require an update to permit TCP port 444 connections to the sensor. For example, when using firewalld commands similar to the following may be used:

    sudo firewall-cmd --add-port=444/tcp --permanent
sudo firewall-cmd --reload

  4. Depending on the DNS actvity data collection methods which will be used to send data to the sensor, other firewall updates will also be required in the case a firewall is used. More examples are given below using firewalld for the supported methods:

    # Windows OneDDI agent:
sudo firewall-cmd --add-port=8100/tcp --permanent

# Opensource dnstap:
sudo firewall-cmd --add-port=6000/tcp --permanent

# BlueCat HTTP:
sudo firewall-cmd --add-port=8443/tcp --permanent

# Infoblox data connector:
sudo firewall-cmd --add-port=8022/tcp --permanent

# Infoblox and ISC BIND syslog:
sudo firewall-cmd --add-port=8514/tcp --permanent

# Final reload
sudo firewall-cmd --reload

Following initial installation a sensor will have generated a unique connection key which is used when adding the sensor to the OneDDI user interface. This key is stored in the /opt/oneddi-sensor/config/http-connection.key file. When the sensor is added to the OneDDI user interface this connection key will be changed automatically.

Upgrade

Unless otherwise specified all versions of OneDDI are backwards compatible with all previous versions. That is, any newer version can be installed over the top of any older version. No version is forwards compatible though, and an older version cannot be installed over the top of a newer version.

The main OneDDI application is compatible with older OneDDI sensors. Currently no constraints are made on which sensor versions OneDDI applications support.

Additionally, OneDDI sensors are compatible with older OneDDI agents. Currently no constraints are made on which agent versions OneDDI sensors support.

The OneDDI sensor installer is named oneddi-sensor-<version>-1.x86_64.rpm - where <version> is the version of the OneDDI sensor being installed. This program should be transferred to a temporary location on the target server. The following steps can then be used to upgrade the OneDDI sensor:

  1. Use the following command to uninstall the existing OneDDI sensor version - note that all data and configuration will NOT be removed by this command and it will remain under the /opt/oneddi-sensor directory once removed, this will then be used by the new version once installed:

    sudo yum remove oneddi-sensor

  2. Use the following command to install the OneDDI sensor:

    sudo yum install oneddi-sensor-<version>-1.x86_64.rpm

Uninstallation

The following steps can then be used to uninstall the OneDDI sensor:

  1. Use the following command to uninstall the OneDDI sensor:

    sudo yum remove oneddi-sensor

  2. During the initial installation of the OneDDI sensor the oneddi user will have been created for the OneDDI sensor. If the oneddi user is no longer required remove the user using the following command:

    sudo userdel -r oneddi

  3. If a local firewall is running, and it was updated to permit TCP port 444 connections to the sensor, it may require an update to no longer allow TCP port 444 connections. For example, when using firewalld commands similar to the following may be used:

    sudo firewall-cmd --remove-port=444/tcp --permanent
sudo firewall-cmd --reload

  4. Additionally, any firewall rules added to permit specific DNS activity collection methods will also need to be removed. For example, when using firewalld:

    # Windows OneDDI agent:
sudo firewall-cmd --remove-port=8100/tcp --permanent

# Opensource dnstap:
sudo firewall-cmd --remove-port=6000/tcp --permanent

# BlueCat HTTP:
sudo firewall-cmd --remove-port=8443/tcp --permanent

# Infoblox data connector:
sudo firewall-cmd --remove-port=8022/tcp --permanent

# Infoblox and ISC BIND syslog:
sudo firewall-cmd --remove-port=8514/tcp --permanent

# Final reload
sudo firewall-cmd --reload

Following uninstallation all data and configuration files specific to the host will still be located under the /opt/oneddi-sensor directory. If the data and configuration files are no longer required they can be removed using the following command:

sudo rm -r /opt/oneddi-sensor

OneDDI Agent

Requirements

The OneDDI agent is currently tested on 64bit Windows 2016, 2019 and 2022 systems. All OneDDI agent components ship with all dependent software and do not require any software that would not otherwise be installed on a typical system.

Since the OneDDI agent will be installed on DNS servers it does not have any hardware requirements. The OneDDI agent:

  • Has a small footprint - It consumes less that 1MB for its installation and log files, it does not write any data to disk and operates purely out of memory.
  • Uses a fixed specified amount of memory - The agent operates an in memory circular queue of messages it sends to a OneDDI sensor. The size of this queue is configurable in the config\agent.config file in the installation directory and defaults to 100MB. For servers with higher throughput, or more available memory, this can be increased.
  • Does not require high privileges - It only needs to be able to read the DNS server Windows Event Logs.
  • Does not use an automated installer - Files are provided as a ZIP archive with an installation PowerShell script so that it can be deployed using software management solutions.

Either physical or virtual hardware can be used for production deployments.

Installation

The OneDDI agent installer is named oneddi-agent-<version>.zip - where <version> is the version being installed. The ZIP file, when unzipped, contains a directory named oneddi-agent.

This file should be transferred to a temporary location on the target server. The following steps can then be used to install the OneDDI agent:

  1. Unzip the oneddi-agent-<version>.zip file.
  2. Move the resulting oneddi-agent directory to the parent installation directory, i.e. c:\Program Files\.
  3. Open a command window and change to the installation directory, i.e. c:\Program Files\oneddi-agent.

  4. Use the following command to create the default configuration file and install and start the OneDDI agent Windows Service, following this the OneDDI agent Windows Service will be running:

    powershell scripts\Install.ps1

  5. Edit the config\agent.config file under the installation directory and specify the IP address of the OneDDI sensor the agent will forward DNS activity to, note that multiple OneDDI sensors can be specified for redundancy and the first connected sensor will be used:

    # Default queue size
queue-size 104857600

# Automtically failover to second sensor when first is lost
target 1.1.1.1:8100
target 2.2.2.2:8100
  6. If changes were made to the config\agent.config file under the installation directory, restart the OneDDI agent Windows Service.
  7. The DNS server can then be added to OneDDI within the OneDDI user interface.

Upgrade

Unless otherwise specified all versions of OneDDI are backwards compatible with all previous versions. That is, any newer version can be installed over the top of any older version. No version is forwards compatible though, and an older version cannot be installed over the top of a newer version.

OneDDI sensors are compatible with older OneDDI agents. Currently no constraints are made on which agent versions OneDDI sensors support.

The OneDDI agent installer is named oneddi-agent-<version>.zip - where <version> is the version being installed. The ZIP file, when unzipped, contains a directory named oneddi-agent.

This file should be transferred to a temporary location on the target server. The following steps can then be used to upgrade the OneDDI agent:

  1. Open a command window and change to the installation directory, i.e. c:\Program Files\oneddi-agent.

  2. Use the following command to stop and uninstall the OneDDI agent Windows Service - this will not remove any files or directories:

    powershell scripts\Uninstall.ps1
  3. Unzip the oneddi-agent-<version>.zip file.
  4. Move the resulting oneddi-agent directory to the parent installation directory, i.e. c:\Program Files\, over the top of the existing oneddi-agent directory, confirming when prompted to overwrite all the existing files.

  5. Use the following command to install and start the OneDDI agent Windows Service, following this the OneDDI agent Windows Service will be running:

    powershell scripts\Install.ps1

Uninstallation

The following steps can then be used to uninstall the OneDDI sensor:

  1. Open a command window and change to the installation directory, i.e. c:\Program Files\oneddi-agent.

  2. Use the following command to stop and uninstall the OneDDI agent Windows Service - this will not remove any files or directories:

    powershell scripts\Uninstall.ps1
  3. Close the command window.

Following uninstallation all data and configuration files specific to the host will still be located under the installation directory, i.e. c:\Program Files\oneddi-agent. If the data and configuration files are no longer required they can be removed.