ESM Server Installation Guide - Windows

Note

It is recommended that you review the document titled Functional Overview of ESM before continuing with the tasks outlined here.*

System requirements

Hardware Requirements

Boemska recommend a dedicated (virtual or physical) machine on which to run the ESM Server. The ESM database can run on the same host, or if preferred on a dedicated database server. Communication between the ESM Server and the database is via JDBC which is configured as part of the installation process

  • Minimum 1 x Quad Core CPU
  • 8GB RAM
  • Approximately 1.5GB Diskspace for the ESM Server installation
  • 50 – 100GB Storage Space for the underlying ESM Database

Note: Large deployments with a high number of end users may require a higher specification and increased disk space. Contact Boemska for further details on sizing.

Supported Versions of Windows

  • Windows Server 2008 32bit (Service Pack 1 minimum)
  • Windows Server 2008 R2 64bit (Any Service Pack)
  • Windows Server 2012 64bit (Any Service Pack)

The following platforms are also known to work with ESM:

  • Windows XP Professional SP3 32bit
  • Windows 7 64bit
  • Windows 8
  • Windows 10

Supported Databases

PostgreSQL 9.6.5

MySQL 5.6 or newer

The following settings for MySQL are recommended:

  • the installed server type is 'Server Machine'
  • to be used as a 'Multifunctional Database'
  • with 20 concurrent connections to the database
  • configured to Run as a Windows Service.

Oracle 11g or newer

Installation Requirements

  • Approximately 1.5GB disk space for the ESM Server installation files

    • ESM Server Installer compressed (318MB)
    • ESM Server Installer unpacked (390MB)
    • ESM Server Installed (775MB)

  • 50GB – 100GB disk space/tablespace for selected database storage

    • Storage requirements vary depending on the number of nodes and sessions/jobs monitored
    • ESM data collection intervals and metric resolutions are configurable, both of which affect the storage required
    • ESM has a configurable automated maintenance schedule to manage and maintain storage
    • Where possible, Boemska recommends dynamically sized disk space/tablespace which can be adjusted according to demand.
    • For a more detailed break down of storage requirements, or if you have a complex/large environment please contact Boemska for further information

  • Ports – If a firewall is configured, the following ports will need to be opened for communication between the ESM Agent(s) and the ESM Server. The default ports are listed below, custom ports can be specified during installation if required

    • 18080 – default HTTP port for ESM communication
    • 18181 – default HTTPS port for ESM communication
    • 14848 – default ESM administration port

  • If the ESM Server instance is running on a different host to the database, one of the following ports (Database vendor selection dependant) will need to be opened for communication between the ESM Server and the Database over the configured JDBC connection. The default ports are listed below, change as appropriate if configured differently

    • MySQL- default port 3306
    • Oracle- default port 1521
    • PostgreSQL- default port 15432

  • A service account under which to run the ESM Server Windows service. ESM requires an account with the following:

    • Administrator rights.
    • A centrally managed or non-expiring (recommended) password
    • Run as service capability
    • Read/Write access to the target installation directory and sub directories

  • Access to a web browser


Third-party Components

Java

The ESM Server is supplied with its own Java Runtime Environment (JRE) and is automatically configured to use the bundled version.

To configure ESM to use a different JRE, please consult our online knowledge base or contact support@boemskats.com

Database Object Creation

Note: Complete the following object creation steps if followed as part of a pre-requisite installation phase which is to be carried out separately to the ESM Server installation. This is often required for sites with dedicated DBA resources. The main ESM Server Installation Wizard can automatically generate the following SQL code, given the correct inputs. If the same person is performing both the installation of the database and of the ESM Server application, you may postpone this step until the ESM Server Installation and copy and paste the generated SQL from the Installation Wizard.

Important: Make a note of, and keep safe, the username and password for the newly created database user as it will be required for installation and access to the ESM Server Database.

MySQL

  1. Log in to your instance of the MySQL database as an administrative user, either by running the 'MySQL Command Line Client' from the Start Menu, or by running this from the bin directory of your installation via the Command Prompt, for example:

    E:\mysql\bin> mysql -uroot -p
    Enter password:
    Welcome to the MySQL monitor.
    
  2. Create the user that the ESM Server application will use:

    create user 'esm'@'hostname' identified by 'esmPass';
    

    Where:

    esm is the name of the user you'd like the ESM Server application to use.

    hostname is the name of the host where you will be installing the ESM Server.

Note

If the ESM Server is being installed on the same host as the Database, it is safe to use 'localhost' as the hostname variable here. However, this will only function correctly if 'localhost' is also used as the target hostname in the JDBC connection string configured as part of the ESM Installation Wizard._

esmPass is the password you want to set for the ESM Server user.

  1. Create the database that the ESM Server application will use:

    create database esm CHARACTER SET utf8 COLLATE utf8_unicode_ci;
    
  2. Grant the new database user permissions on the newly created database:

    grant all on esm.* to 'esm'@'hostname';
    

    Where:

    esm is the name of the user you'd like the ESM Server application to use.

    hostname is the name of the host where you will be installing the ESM Server.

An example of these steps is shown below:

MySQL Command Line Results

Oracle

  1. Log in to your instance of Oracle as an administrative user, or a user with tablespace and user creation rights.
  2. Create the TS_ESM tablespace, minimum 50 GB in size (or as instructed by Boemska for large environments)
  3. Create the user that the ESM Server application will use:

    CREATE USER esm IDENTIFIED BY esmPass DEFAULT TABLESPACE TS_ESM;
    

    Where:

    esm is the name of the user you'd like the ESM Server application to use.

    esmPass is the password you want to set for the ESM Server user.

  4. Grant the required privileges to the newly created user:

    GRANT CONNECT, RESOURCE, CREATE VIEW TO esm;
    

    Where:

    esm is the username of the database user created for the ESM Server application to use.


ESM Server Installation

Unpacking the ESM Server Installation package

  1. Download the appropriate ESM Server installation package for your 32-bit or 64-bit Windows operating system. Installation packages can be obtained by signing in to the Boemska Customer Area at https://boemskats.com or by contacting your Boemska representative. For help please email support@boemskats.com

  2. Unpack the archive to your desired location. This guide assumes a target location of

    C:\esm-server-installer
    

Installing the ESM Server

Double-clicking on the esm-server-setup.exe executable will start the ESM Server Installation Wizard.

Note: You may be prompted to grant the ESM Installation Wizard elevated privileges. This is required in order to deploy the ESM Server application as a Windows Service.

  1. You will be presented with a Welcome Screen.

    Click Next.

  2. You will now be presented with a License Agreement. You must click agree to the terms set out in the license agreement in order to continue with the installation, by clicking the I Agree button.

  3. If you chose MySQL follow this:

You will now be asked to enter the connection parameters for the database:

Database information

Select the required database from the drop-down menu

MySQL
Update the jdbc connection string: jdbc:mysql:localhost:<port>/esm?rewriteBatchedStatements=true as follows:

  • Change localhost to the hostname where the database is installed (if different).

  • <port> will be set to the default port for MySQL (3306). If required change to the port the database was configured with.

Oracle
Update the jdbc connection string: jdbc:oracle:thin:@localhost:<port>:<service_name> as follows:

  • Change localhost to the hostname where the database is installed (if different).

  • <port> will be set to the default port for Oracle (1521). If different change to the port the database was configured with.

  • <service_name> is the service name identifier for the Oracle database.

  • Enter the username and password of the database user you would like ESM Server to use when connecting to the database.

    If the creation of the database objects has already been completed, enter the username and password chosen at that time and skip the rest of this step by clicking Next.

    If the database object creation has not been completed, then do the following:

    Log into a command line (or similar client) of your database as an administrative user or a user with the required privileges to create:

    • Tablespaces (Oracle only)
    • Databases
    • Users

Click the '?' button next to the 'Create Tables' option on the ESM Installation Wizard screen.

Database configuration

The wizard uses the hostname, username and password provided to automatically generate the SQL code needed to complete the Database Object Creation steps.

Copy and paste and execute each step of the suggested code into the database client prompt

Note: Refer to the Database Object Creation section for more detail, and the expected outputs of this operation.

When each step has successfully completed, click Next

  • If you chose Embedded (PostgreSQL) follow this:

You will now be asked to enter the connection parameters for the database:

Database information

Select the required database from the drop-down menu

Embedded
Update the Database url: jdbc:postgresql://localhost:15432/esm

Enter the username and password of the database user you would like ESM Server to use when connecting to the database.

If the creation of the database objects has already been completed, enter the username and password chosen at that time and skip the rest of this step by clicking Next.

If the database object creation has not been completed, then do the following:

  1. Log into a command line (or similar client) of your database as an administrative user or a user with the required privileges to create:

    • Databases
    • Users

  2. Click the '?' button next to the 'Create Tables' option on the ESM Installation Wizard screen.

Database configuration

You have selected embedded (internal) database to be used with esm.

  1. The default Embedded database port is 15432. Click on the Next.

  2. The ESM Installation Wizard will now test the connection to the database. If the connection test is successful, you will see the following screen:

    ESM Port Settings

    Configure the ports you would like the ESM Server Web Application to use when accepting incoming connections. The default ports are recommended, but may be changed if they clash with another application running on the ESM Server machine. Note: You must ensure that your firewall is appropriately configured to accept connections on these ports.

Click Next.

  1. You are now presented with the ESM Admin Settings screen:

    ESM Admin Settings

    Choose a Username and Password for the ESM Web Application Administrative User. This is used to access the admin functionality of ESM via the web browser. Keep these details safe.

    Click Next.

  2. You are now prompted to create a Windows service for the ESM Server and start it after installation. Service creation is recommended, however this option can be unchecked if you wish to start the ESM Server manually or via another scripted method.

    ESM Service settings

Click Next

  1. Specify the target install location for the ESM Server using the file browser, ensuring that sufficient disk space is available. A new folder can be created from the browse window if necessary, for example: c:\esm The installer will automatically create an esm-server sub folder within the selected destination folder e.g. c:\esm\esm-server

    ESM Install Location

Note

The default installation path, if not specified is as follows: %APPDATA%\..\Local\esm-server

In the case of MySQL just click Install to start the installation.

In the case of PostgreSQL you have more steps to do:

Select the location for the database directory. Setup will install ESM Server in the following folder. To install in a different folder, click Browse and select another folder.

Note: The default installation path, if not specified is as follows: C:\esm\esm-server\pgsql

Database Directory

Select data directory for embedded database. Setup will install ESM Server in the following folder. To install in a different folder, click Browse and select another folder. Click Next to continue.

Note: The default installation path, if not specified is as follows: C:\esm\esm-server\data

Data directory for embedded database

Select directory for database logs. Setup will install ESM Server in the following folder. To install in different folder, click Browse and select another folder.

Note: The default installation path, if not specified is as follows: C:\esm\esm-server\pgsql\logs

Click Install to start the installation.

Database logs directory

  1. The ESM Server application will now be installed. This may take a few minutes.

It takes the Web Server two or three minutes to configure itself after initial deployment. It is recommended that you wait a couple of minutes for the application to finish the initial deployment before proceeding to the next step (updating the ESM License)

Updating the ESM License

  1. Using a web browser, navigate to http://localhost:18080/esm-1.0/ where 18080 is the port you configured ESM Server on. If accessing from a machine other than the server, you must specify the hostname or IP address of the ESM Server in place of localhost. You should be presented with a screen requesting a license file ESM Server First Launch
  2. Click Browse to navigate and select your ESM license file.
  3. Click Upload, then Renew License.
  4. The License Holder and Expiry Date should be updated with the new license details. ESM Licence Applied
  5. Click Refresh. You should see the main ESM Web Application screen.

Validating the Database Connection

  1. Click on Admin Settings button from the main ribbon (top right) ESM Admin Button

  2. Enter the ESM Administrator username and password you configured during installation

  3. Verify that the application is connecting to the database correctly, by checking the reported Database Size: ESM Database Size

This concludes the ESM Server Installation and Configuration steps.

Now proceed with the ESM Agent installation and configuration steps for each node you wish to monitor


Server Administration

Starting and Stopping the ESM Server Service

Using Windows Service status

If the ESM Server is installed as a service, the service status can be verified using the Windows Services manager. To check the service status, do the following:

  1. Log on to the server using the account with the required privileges

  2. Click Start

  3. In the search box type services to filter the list of applications

  4. Right click Services and click Run as Administrator

  5. In the services window which appears, scroll down the list to the “ESM Web Server" entry. This should have a status of Started

  6. The service can be started and stopped from this interface by right clicking and changing the status

Using the Command Line

Note: cmd.exe does not support UNC paths. Use Windows Powershell to issue the following commands when the ESM Server installation path is not mapped to a drive letter.

  1. Click Start

  2. In the search box type Powershell to filter the list of applications

  3. Right click the Windows Powershell program and click Run as Administrator

  4. At the command prompt, navigate to the location of the installed esm agent binaries. e.g. c:\esm\esm-server\bin

  5. If ESM Server is installed and running as a Windows Service, the service can be stopped by issuing the "stop-service" command:

    C:\esm\esm-server\bin> .\esm-server.bat stop-service
    Stopping ESM Server service...
    

Note

If not installed/running as a Windows Service, issue the "stop" command:_

C:\esm\esm-server\bin> .\esm-server.bat stop
Stopping ESM Server ...
Waiting for the domain to stop ..
Command stop-domain executed successfully.
  1. To start the ESM Server Windows Service from the command line:

    C:\esm\esm-server\bin> .\esm-server.bat start-service
    Starting ESM Server service...
    

    Note: To start ESM Server independently of the Windows Service manager, issue the "start" command:

    C:\esm\esm-server\bin> .\esm-server.bat start
    Starting ESM Server ...
    Waiting for domain1 to start .........................................
    Successfully started the domain : domain1
    domain  Location: C:\esm\esm-server\esm-core\glassfish\domains\domain1
    Log File: C:\esm\esm-server\esm-core\glassfish\domains\domain1\logs\server.log
    Admin Port: 14848
    Command start-domain executed successfully.
    

Inspecting the ESM Server Log files

The ESM Server log file is located under the logs path of the installation directory. E.g. C:\esm\esm-server\logs.

By default, minimal logging is enabled for ESM Server to ensure smooth running of production environments. More detailed logging can be enabled with the assistance of Boemska Support. For further details please email support@boemskats.com


Uninstalling ESM Server

  1. First ensure ESM Server by stopping the ESM Web Server service via the windows is not running by issuing the stop server command. See Stopping ESM Server for further details
  2. Navigate to the installation location ESM Server E.g. C:\esm\esm-server
  3. Run the Uninstall.exe executable to uninstall
  4. The ESM Server installation directory may be removed if required.