Install Guide

dns-logger - 2.2.3

Contents

  1. Introduction
  2. System Requirements
  3. Upgrades & Upgrade Paths
  4. Installation
    1. Linux
    2. Windows
  5. Verify an Installation
  6. Uninstallation
    1. Linux
    2. Windows

Introduction

Welcome to the NoSpaceships Ltd dns-logger!

This document details the necessary steps to install, upgrade and uninstall the NoSpaceships Ltd dns-logger.

This document is aimed at all users of the dns-logger.

System Requirements

The dns-logger is currently tested on 64bit Red Hat/CentOS 6 and 7 systems, and 64bit Windows 2008 R2 and 2012 R2. While the dns-logger is currently tested on these platforms, it is supported to run on other Linux variants that use System V or Systemd service management, and any Windows platform following the release of Windows 2008.

All dns-logger components ship with all dependent software and do not require any software that would not otherwise be installed on a typical system with one exception. To install the dns-logger on Linux platforms Perl is required to run the installer. Most systems will provide this by default, but for Linux systems where a basic installation has been performed Perl must be installed before the installer can be successfully run.

DNS logging via packet capture on Windows platforms historically required some form of packet capture library. The dns-logger does NOT require any third party drivers, such as WinPCAP or npcap, which is typically required on Windows platforms to perform network packet capture. It simply installs and runs a single service which uses the operating systems existing functionality.

The dns-logger will be installed on existing infrastructure, therefore it does not impose any hardware requirements. Once installed, the dns-logger uses minimal CPU in comparison to the DNS server process, no disk I/O (only for simple logging), and by default approximately 50mb of memory.

The dns-logger will send Syslog or JSON formatted messages to one or more target servers using a configurable port. This connection is always initiated by the dns-logger. Therefore, the dns-logger should be permitted to connect to all configured target servers on their configured ports.

Upgrades & Upgrade Paths

Unless otherwise specified all versions of dns-logger 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 dns-logger installer is upgrade aware. No specific steps need be taken to perform an upgrade, and when the dns-logger installer finds an existing installation it will simply install over the top and upgrade it.

Installation

Linux

The dns-logger installer is named dns-logger-<version>-linux.bin for Linux platforms - where <version> is the version of dns-logger being installed. This program should be transferred to a temporary location on the target server.

Once transferred the file permissions of the program must be updated so that it can be executed, e.g.:

chmod 544 dns-logger-<version>-linux.bin

A command line switch will be specified to the dns-logger installer to indicate acceptance of the dns-logger End User License Agreement (EULA). The dns-logger EULA must be read before it can be accepted. The following command will display the dns-logger EULA on Linux platforms:

./dns-logger-<version>-linux.bin --show-eula

Once the dns-logger EULA has been read the following command can be executed as the root user to install the dns-logger:

./dns-logger-<version>-linux.bin --accept-eula --install <destination>

The dns-logger operating system service will be installed and started during installation.

For first time installations configuration should be reviewed. Edit the <install>/config/dns-logger.config file and review available options. The dns-logger service should then be restarted using one of the following commands depending on which service framework is being used:

systemctl restart dns-logger
service dns-logger restart

Windows

The dns-logger installer is named dns-logger-<version>-windows.exe for Windows platforms - where <version> is the version of dns-logger being installed. This program should be transferred to a temporary location on the target server.

For the Windows installer, the dns-logger EULA will be displayed when the installer is run, and will require acceptance of the EULA before it can complete successfully.

When the Windows installer is executed in silent/unattended mode, the EULA is NOT displayed and instead silently accepted. In this case initiating installation in this way indicates acceptance of the EULA.

The dns-logger can be installed simply by executing the dns-logger installation program and following the installation wizard.

The dns-logger operating system service will be installed and started during installation.

The dns-logger can be installed using a silent/unattended mode on Windows platforms using the following command (the start /wait prefix is used to ensure the command blocks until the installation has fully completed, also note that no quotes can exist in the command line anywhere):

start /wait dns-logger-x.x.x-windows.exe /S /D=c:\Program Files\dns-logger

NOTE The /D switch is used to control the directory in which to install the dns-logger. This can be omitted, in which case the default path c:\Program Files\dns-logger will be used, e.g.:

start /wait dns-logger-x.x.x-windows.exe /S

For first time installations configuration should be reviewed. Edit the <install>/config/dns-logger.config file and review available options. The dns-logger service can then be restarted using the following commands:

net stop dns-logger
net start dns-logger

Verify an Installation

Once installation is complete the installation can be verified using the dns-logger program that provides the dns-logger background service.

Refer to the Using the dns-logger / Standard Output Logging section in the dns-logger User Guide for more detail.

Uninstallation

Linux

Use the following command to uninstall dns-logger (this assumes an installation path of /opt/dns-logger):

NOTE This will delete all application code and all application data.

/opt/dns-logger/uninstall.sh --confirm

The dns-logger operating system service will be stopped and uninstalled during uninstallation.

Windows

For Windows platforms, execute the uninstall.exe program found under the dns-logger installation directory.

NOTE This will delete all application code and all application data.

The dns-logger can be uninstalled using a silent/unattended mode on Windows platforms using the following command (the start /wait prefix is used to ensure the command blocks until the uninstallation has fully completed, this assumes an installation path of c:\Program Files\dns-logger):

cd c:\Program Files
start /wait dns-logger\uninstall.exe /S

The dns-logger operating system service will be stopped and uninstalled during uninstallation.