Installing

Prelert Behavioral Analytics for the Elastic Stack / Engine API is installed with its own instance of Elasticsearch which is used to store analysis results and Kibana which is used to visualize the results.

If installing on a system that already has an existing instance of Elasticsearch, separate ports must be configured for the Elasticsearch API, transport client and Kibana. For this reason, we would encourage the use of a dedicated server/VM instance for deployments. The picture below depicts this approach alongside an existing Elastic Stack cluster environment.

Customer Elastic Stack with Prelert deployed as separate install

Note

When uninstalling Prelert, the Elasticsearch results store (installed by Prelert) will be removed as part of the product.

System Requirements

Operating System

The Prelert Behavioral Analytics for the Elastic Stack / Engine API must be installed on 64-bit Linux, Windows or Mac OS X.

The following Linux distributions are supported:

  • Red Hat Enterprise Linux (RHEL) 6.x or 7.x
  • CentOS 6.x or 7.x
  • SuSE Linux Enterprise Server (SLES) 11 or 12
  • Fedora 10+
  • Ubuntu 12+
  • Amazon Linux (latest)

The following Windows versions are supported:

  • Windows 10 (evals only)
  • Windows Server 2012
  • Windows Server 2012r2

The following Mac OS X versions are supported:

  • 10.10 “Yosemite” (evals only)
  • 10.11 “El Capitan” (evals only)

Please get in touch with support@prelert.com if you have a specific requirement to run on a currently unsupported operating system.

Hardware

For evaluation purposes, the recommended minimum hardware requirements are:

System:Dual core 2GHz
Memory:4GB RAM or higher
Disk space:5GB

Kibana

The Kibana plug-in is developed for Kibana 4.6.1. This version is required and is provided as part of the Engine API install.

Elasticsearch Results Store

The Engine API anomaly results, model state and configuration are stored in Elasticsearch 2.4.0 This version is required and is provided as part of the Engine API install.

It is possible to use an alternate Elasticsearch instance as the results store, however this must be running version 2.4.x in order for the Kibana User Interface to work. Please contact support@prelert.com if this is a requirement.

Scheduler for Elasticsearch

The Scheduler requests data using the Search and Scroll APIs from any Elasticsearch instance or cluster. The Scheduler is supported for use with the following versions of Elasticsearch:

  • Elasticsearch 1.7
  • Elasticsearch 2.0, 2.1, 2.2, 2.3, 2.4, 5.0

Installing on Linux or Mac OS X

On Linux and Mac OS X the software must be installed by a non-root user. The same non-root user that installs the software must subsequently run it. This non-root user should have their hard limit on file descriptors set to at least 30000 (because Apache Lucene can use a lot of file descriptors). The default hard limit on file descriptors is 1024 in many Linux distributions, which is only adequate for a small proof-of-concept.

To increase the limit on Linux the root user must edit the file /etc/security/limits.conf and add a line as follows, where myuser is the username of the non-root user who will install and run the Engine API.

myuser             hard    nofile            30000
  1. Download from here.

  2. If the installer has lost its execute permission during the download process, reinstate it using:

    > chmod +x prelert_engine_linux_64bit.bin
    
  3. On the command line run the executable and follow the instructions. This will allow you to select the installation directory and configure the port required.

./prelert_engine_linux_64bit.bin

A successful install will display the following to stdout:

Copyright (c) Prelert Ltd 2006-2016
====================================
License installed correctly

Starting datastore ....
The datastore has started
Starting the Engine API server ....
The Engine API server has started

Install complete
  1. You are now ready to use the Engine API
The Prelert Engine REST API is available at http://localhost:8080/engine/v2
The Prelert Engine Dashboard is available at http://localhost:5601

For Engine API users, we recommend the Tutorial: Flight Comparison Website using cURL.

Unattended installation on Linux or Mac OS X

On Linux and Mac OS X the software must be installed by a non-root user. The same non-root user that installs the software must subsequently run it. This non-root user should have their hard limit on file descriptors set to at least 30000 (because Apache Lucene can use a lot of file descriptors). The default hard limit on file descriptors is 1024 in many Linux distributions, which is only adequate for a small proof-of-concept.

Step 1. If the installer has lost its execute permission during the download process, reinstate it using:

chmod +x prelert_engine_linux_64bit.bin

Step 2. Create a settings file containing all the installer variables you want to customize. This settings file is interpreted as a Bourne shell script, so variables should be assigned and values should be quoted according to Bourne shell rules. The available settings are:

AGREE_LICENSE:

Do you agree to the Prelert end user license agreement? Must be set to Y. Any other value will cause the installation to fail.

Default: N

LICENSE_KEY:

Must be set to the electronic license key provided by Prelert.

Default: none

PRELERT_HOME:

The installation directory. If this directory does not exist the installer will attempt to create it, in which case the last directory in the path to this directory must be writable by the user running the installer. Alternatively this directory may already exist but must be empty and writable by the user running the installer.

Default: /opt/prelert/prelert_home

PRELERT_DATA_DIR:
 

The data directory. Can be set to any writable directory.

Default: $PRELERT_HOME/data

PRELERT_LOGS_DIR:
 

The root log file directory. Can be set to any writable directory.

Default: $PRELERT_HOME/logs

WEB_SERVICE_PORT:
 

TCP port used by the Engine API.

Default: 8080

ES_HTTP_PORT:

TCP port used by Elasticsearch’s HTTP REST API.

Default: 9200

ES_TRANSPORT_START_PORT:
 

One end of a range of TCP ports used by Elasticsearch’s transport protocol.

Default: 9300

ES_TRANSPORT_END_PORT:
 

The other end of a range of TCP ports used by Elasticsearch’s transport protocol.

Default: 9400

KIBANA_HTTP_PORT:
 

TCP port used by Kibana.

Default: 5601

INSTALL_DATASTORE:
 

Set to N to prevent the elasticsearch datastore from being installed. Any value other than N means it will be installed.

Default: Y

ES_HOST:

The host name used for communications with the elasticsearch cluster. Required for distributed analytics. (Alpha)

ES_CLUSTER_NAME:
 

The elasticsearch cluster name. Required for distributed analytics. (Alpha)

Default: Prelert

START_ENGINE:

Should the processes be started by the installer? Any value other than Y means no.

Default: Y

The AGREE_LICENSE and LICENSE_KEY settings must be specified, as their default values will not allow a successful installation. The other settings do not need to be specified if the default values are acceptable. For example, you might create a file called settings.txt containing the following:

AGREE_LICENSE=Y
LICENSE_KEY='user@company.com|1482288827|any|prelert|7b8ab436e6e0e2a918c72f42451b9eefd4609174'
PRELERT_HOME=/usr/local/prelert/engine
WEB_SERVICE_PORT=9080
START_ENGINE=Y

Step 3. On the command line run the installer executable specifying the silent option and the name of your settings file. It is best to also redirect the output of the script to a file in case any problems occur, for example:

./prelert_engine_linux_64bit.bin silent settings.txt > install.log 2>&1

A successful install will set an exit code of 0, which you can test programmatically, for example in a shell script you could put this immediately after the line that runs the Prelert installer:

test $? -ne 0 && echo Installation failed

Step 4. You are now ready to use the Engine API

The Prelert Engine REST API is available at http://localhost:8080/engine/v2
The Prelert Engine Dashboard is available at http://localhost:5601/app/prelert

Installing on Windows

On Windows the software must be installed by a user with administrative privileges. After installation the Engine API will run as two Windows services that will start automatically when the machine is rebooted. Any user with administrative privileges can stop and start both services using shortcuts in the Start Menu -> All Programs -> Prelert Engine or Start Screen -> Apps -> Prelert Engine.

  1. Download from here.
  2. Double click on the Windows installer msi file and follow the on-screen prompts.
  3. You will be asked to accept the terms of the license agreement.
  4. You will then be asked if you would like to select a Typical or Custom installation.
  1. By selecting Typical you will be asked to supply a valid license key and the install will proceed using default settings.

  2. By selecting Custom you will be asked to supply a valid license key and may then configure the following parameters:

    • Installation folder
    • Ports used by the Prelert Engine services
    • Whether to add firewall exceptions for the selected ports
  1. Click Next to proceed with the installation. Please make sure you accept the associated User Access Control messages should they appear.
  2. The final Windows Installer screen will display final status of the installation and provide a link to the Engine API Dashboard.
Browse to http://localhost:5601 on exit

For Engine API users, we recommend the Tutorial: Flight Comparison Website using cURL.

If anything goes wrong with an installation on Windows and you cannot determine what the problem is, please obtain a log file using the procedure detailed Getting a Windows installer log.

Unattended installation on Windows

On Windows the software must be installed by a user with administrative privileges. After installation the Engine API will run as two Windows services that will start automatically when the machine is rebooted. Any user with administrative privileges can stop and start both services using shortcuts in the Start Menu -> All Programs -> Prelert Engine or Start Screen -> Apps -> Prelert Engine.

Installing the Engine API without user interaction on Windows is achieved by running the msiexec program that is part of Windows. You must elevate privileges before running msiexec. (On modern versions of Windows, even administrators do not have administrative rights all the time: they can elevate their privileges when they need to perform a task that requires administrative rights.) If running msiexec from a command prompt, you must start the command prompt by right-clicking and choosing “Run as administrator”. If you want to invoke the Engine API installer from another program then either that other program must have been started using “Run as administrator” or it must programmatically elevate privileges before invoking the Engine API installer.

Step 1. Decide which installer properties you want to change the values of. The available properties are as follows:

LICENSEKEY:

Must be set to the electronic license key provided by Prelert.

Default: None

INSTALLDIR:

The installation directory.

Default: C:\Program Files\Prelert\Engine API\

WEB_SERVICE_PORT:
 

TCP port used by the Engine API.

Default: 8080

ES_HTTP_PORT:

TCP port used by Elasticsearch’s HTTP REST API.

Default: 9200

ES_TRANSPORT_START_PORT:
 

One end of a range of TCP ports used by Elasticsearch’s transport protocol.

Default: 9300

ES_TRANSPORT_END_PORT:
 

The other end of a range of TCP ports used by Elasticsearch’s transport protocol.

Default: 9400

KIBANA_HTTP_PORT:
 

TCP port used by Kibana.

Default: 5601

DATA_DIR:

The Elasticsearch data directory.

Default: [INSTALLDIR]cots\elasticsearch\data\

LOGS_DIR:

The root Engine API and job logs directory.

Default: [INSTALLDIR]logs\

CONFIGUREFIREWALL:
 

If non-empty, the installer will open the Engine API TCP port in Windows Firewall. Set this property to “” on the msiexec command line if you do not want the firewall to be opened.

Default: 1

CONFIGUREFIREWALL2:
 

If non-empty, the installer will open the Elasticsearch TCP port in Windows Firewall. Set this property to “” on the msiexec command line if you do not want the firewall to be opened.

Default: 1

CONFIGUREFIREWALL3:
 

If non-empty, the installer will open the Kibana TCP port in Windows Firewall. Set this property to “” on the msiexec command line if you do not want the firewall to be opened.

Default: 1

It is only necessary to specify a property on the command line if its value is to be different from the default value. However, it does not hurt to specify properties with values that are the same as the defaults.

Step 2. Run msiexec with elevated privileges specifying the properties you want to change at the end of the command line, for example

msiexec /quiet /i prelert_engine_windows_64bit.msi /log "%TEMP%\\install.log" LICENSEKEY="user@company.com|1482288827|any|prelert|7b8ab436e6e0e2a918c72f42451b9eefd4609174" WEB_SERVICE_PORT=9080 CONFIGUREFIREWALL2=""

The /quiet option will result in an installation that is completely silent, which might be useful if the Engine API installer is being controlled by a wrapper installer that manages several products. One problem with running msiexec from a script is that it returns immediately, leaving the script unable to check whether the installation succeeded. In a batch file the solution is to use the /wait option on the start command, for example:

start /wait msiexec /quiet /i prelert_engine_windows_64bit.msi /log "%TEMP%\\install.log" LICENSEKEY="user@company.com|1482288827|any|prelert|7b8ab436e6e0e2a918c72f42451b9eefd4609174" WEB_SERVICE_PORT=9080 CONFIGUREFIREWALL2="" INSTALLDIR="%ProgramFiles%\\MyProductSuite\\Prelert Engine API\\"

if errorlevel 1 echo Installation failed

Step 3. You are now ready to use the Engine API

The Prelert Engine REST API is available at http://localhost:8080/engine/v2
The Prelert Engine Dashboard is available at http://localhost:5601/app/prelert