ESM Administration Guide for Windows

ESM Server

System Requirements

Hardware Requirements

Provisioning a standalone host to run the ESM Server component is advisable. The following host specifications are recommended:

• Minimum 4 CPUs or vCPUs
• 10GB RAM
• 2GB System Storage for the ESM Server binaries and logs
• 50 – 100GB Storage for the underlying ESM Database tablespace

Larger deployments with an increased number of end users, jobs or nodes may require more resource. If in doubt, contact Boemska Support for assistance when sizing the ESM Server host.

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 Server (for testing purposes):

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

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 breakdown 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
    
    

.NET Framework 3.5 (Including .NET 2.0 and 3.0)

The .NET Framework packages are required by the ESM Server Installation Wizard. On later versions of Windows Server (2012 onwards), they can be enabled using the Add Roles and Features Wizard.

Microsoft Visual C++ Redistributable Packages

The Microsoft Visual C++ Redistributable Packages are required by the ESM Embedded Database (PostgreSQL 9.5). A version is included with the ESM Server packages, under third_party/vcredist_x64.exe. Alternatively, it can be downloaded directly from the Microsoft website.

Ports

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

Port	Description	Mandatory	Notes
18080	Default HTTP port for ESM communication		Required for 2020.3.x and earlier.
18082	Default gRPC port for ESM communication		Required for ESM 2020.4.x
14848	Default Glassfish administration port		For debug purposes
15432	Default Database JDBC connection port		When configuring DB replication

In addition, the following ports should be opened for communication between the ESM Server and user(s) web browsers. The default port(s) are listed below but custom ports can be specified during the installation if required:

Port	Description	Mandatory	Notes
18080	Default HTTP port for ESM communication		Default user interface port for 2020.3.x and 2020.4.x
18181	Default HTTPS port for ESM communication		For embedded HTTPS

Note that correct functioning of embedded HTTPS requires manual post-installation configuration of certificates. Configuration with a standalone reverse proxy is also supported. For details contact Boemska Support.

For larger deployments where the ESM Embedded Database is clustered across multiple hosts, more detailed firewall configuration may be required.

User Accounts

An Operating System account is required to run ESM Server. ESM requires an account with the following properties:

• Administrator rights

• A centrally managed or non-expiring password (recommended)

• Run as service capability

• Read and Write access to the target installation directory and sub directories

Server Installation

Unpacking the ESM Server Installation package

1. Log on to the server using the nominated account with the required installation privileges (see installation requirements for more details)

2. Download the appropriate ESM Server installation package for your Windows operating system. Installation packages can be obtained by signing in to the Boemska Downloads site at https://downloads.boemskats.com/esm or by contacting your Boemska representative.

3. Unpack the archive to a suitable temporary location. This guide assumes a target location of

   C:\esm-server-installer
   

Running the Installation Wizard

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 agree to the terms set out in the license agreement in order to continue with the installation, by clicking the I Agree button.

3. Next, you will be presented with a choice of database. Unless otherwise instructed by your Boemska representative, select the Embedded option.
   Enter the username and password to set the credentials for the embedded database. In most cases, it is sufficient to change the password if required and otherwise using the default values provided.

4. The default Embedded database port is 15432. Unless this port is taken by another application running on the local machine, click Next.

5. 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 there is a conflict with another application running on the local machine. As per the note above, only the HTTP and optionally the HTTPS port (shown as the default 18080 and 18181 here) need to be externally accessible.
   Click Next.

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

7. 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.
   Click Next

8. 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 subfolder within the selected destination folder (e.g. c:\esm\esm-server)
   Click Next

9. Specify the target install location for the embedded database binaries, if it differs from the ESM server.
   Click Next

10. Specify the target location for the embedded database tablespace, if it differs from the ESM server. If you have provisioned a separate location for storage of ESM data, enter it here.
    Click Next

11. Specify the target location for the embedded database logs. In most cases the default value will suffice here.
    Click Install

12. The ESM Server installation will now take place. This may take a few minutes. As the services are added they should have a return code of 0, as per the following screenshot. This is the desired result.
    Click Close

Note

It will take up to two minutes for the web interface to become accessible, as the ESM Web Application is deployed into its Application Server for the first time. During this deployment, a java process owned by the ESM installation user will consume a lot of CPU. Once this process has subsided, the application will be ready and accessible via the URL provided.

Validating the Database Connection

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

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: The size of the database should be reported, showing a good connection between the ESM Server and the ESM Database and normal operation of the ESM Server application.

Note

This concludes the ESM Server Installation and Configuration steps. Now proceed with the ESM Agent installation and configuration steps for each node to be monitored, as outlined in the ESM Agent Installation Guide for Windows.

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. Click Start

2. In the search box type services to locate the Windows Services manager application

3. Right click Services and click Run as Administrator

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

5. The service can be started and stopped from the Windows Services manager similarly to other services.

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 Windows drive letter.

1. Click Start

2. In the search box type powershell to locate the Powershell program

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. cd 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...
   

   If ESM is not installed or running as a Windows Service, it can be stopped by issuing 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.
   

6. 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...
   

   Similarly to the stop command above, ESM Server can be started independently of the Windows Service manager by issuing 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.
   

Uninstall ESM Server

1. First ensure ESM Server is not running by issuing the stop server command. See Starting and Stopping the ESM Server Service 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 the application.

4. Click Close.

ESM Agent

System Requirements

Supported versions of Windows

• Windows Server 2003
• Windows Server 2008 32bit (Service Pack 1 minimum)
• Windows Server 2008 R2 64bit (Any Service Pack)
• Windows Server 2012
• Windows XP Professional SP3 32bit
• Windows 7 64bit
• Windows 8 64bit
• Windows 10

Supported versions of SAS®

ESM is compatible with all recent versions of SAS. The minimum recommended version of SAS is SAS v9.1.3; however, as ESM Agents monitor sessions at the process level, ESM is able to monitor earlier versions of SAS where necessary. Some custom configuration may be required.

Installation Requirements

• Approximately 850 MB disk space (including logs)

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

  • Administrator or elevated rights. If you wish to use ESM to terminate SAS sessions from the ESM interface, ensure the account under which the agent service is running has the required permissions to control the SAS services

  • A centrally managed or non-expiring (recommended) password

  • Run as service capability

  • Read/Write access to the target installation directory and sub directories

• A running ESM Server. During installation the agent will validate the connection to the target server. Please install, configure and start the ESM Server first

• The hostname/IP address and port number of the ESM Server

• Access to a web browser

• If a firewall is configured, the ESM Server HTTP port, default 18080 (selected during ESM Server installation) will need to be opened for communication to the target ESM server.

Agent Installation

Information about multi node deployments

For Grid or multi-node deployments of ESM, it is recommended to install the ESM Agent to a clustered file system, accessible by all nodes in the grid. The installation procedure only needs to be run once on the first grid node to configure the agent installation directory. On each subsequent grid node, the Windows service and node events location can be registered by running a batch script.

Information about single node deployments

Alternatively for single node installations or installs where local agent installation is sufficient, the ESM Agent can be installed to file system local to the node being monitored.

ESM Events

The ESM Agent runs on each SAS Application Server node and is responsible for collecting process and server events and metrics, and submitting them to the ESM Server Application. Each node has a dedicated events sub directory which the agent monitors. In grid/multi-node installation, the event directories on a clustered file system may look like this:

\\filesystem\ESM\esm-agent\events\**node1**\
\\filesystem\ESM\esm-agent\events\**node2**\
\\filesystem\ESM\esm-agent\events\**node3**\

Windows Server short names and SASWORK monitoring

In order to utilise the SASWORK monitoring feature of ESM, please ensure that SASWORK is configured to point to a disk volume with short names disabled

To verify the location of SASWORK and determine short name status, run the following SAS code from an interactive or batch session: %put %sysfunc(getoption(work));

C:\Users\ADMINI~1\AppData\Local\Temp\2\SAS Temporary Files\_TD2692_WIN2008R2N1_

If the output contains the tilde ~ character similar to the output above, then SASWORK is configured to point to a disk volume with short names enabled.

To verify short name status at a system level, A system administrator can query short name status by doing the following:

At a command prompt with elevated/Administrator privileges, issue the following command to query the short name setting:

C:\WINDOWS\system32>fsutil.exe 8dot3name query
The registry state is: 2 (Per volume setting - the default).

Individual volumes can be queried by adding the volume drive letter at the end of the command

C:\WINDOWS\system32>fsutil.exe 8dot3name query C:
The volume state is: 0 (8dot3 name creation is enabled).
The registry state is: 2 (Per volume setting - the default).

Based on the above two settings, 8dot3 name creation is enabled on C:

For compatibility reasons, ESM requires SASWORK to be mounted on a disk volume with short names disabled. As SAS requires and recommends short names to be enabled for application of future maintenance releases and patches, SASWORK must be moved to a disk volume different to that of the SAS binaries, with short names disabled. See the following Microsoft Tech Net article for further details on the performance implications of having short names enabled: Disabling Short Names.

Unpacking the installation package

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

Unpack the archive to your desired location. For completeness, this guide assumes a target location of:

\\filesystem\esm-agent-installer\

First/Primary node installation

1. Log on to the server using the nominated account with the required privileges (see installation requirements for more details)

2. Open the destination folder of the unpacked installation package (\\filesystem\esm-agent-installer) and double click the esm-agent-setup.exe executable to start the ESM Agent Installation Wizard.

   Note

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

3. You will be presented with a Welcome Screen.

   Click Next to proceed

4. 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.

5. The ESM Agent Settings Information screen is now shown

   1. Enter the hostname or IP address of the ESM server in to which this agent will report

   2. Enter the port on the ESM server for the agent to use (18080 is default)

   3. The ESM Agent hostname value is auto detected from system settings. Leave this setting blank. Specify a hostname only if you wish to report node statistics using a different hostname value. Each agent hostname reporting into an ESM server instance must be unique.

   4. Leave the Disks to monitor blank to allow ESM to auto detect, or specify each disk drive letter separated by a semi colon. Important: drive letters must be specified in upper case, with no trailing slash. For example: E:;F:;

   5. Click Next to proceed

6. The ESM agent will now attempt to connect to the specified ESM server. If the connection is successful you will be prompted to select the installation path of the agent. If the connection attempt fails, the message Connection to <server>:<port> could not be established will be displayed. Please see Connection Failure in the Troubleshooting section for details on how to resolve this.

7. Specify the target install location for the ESM agent using the file browser. A new folder can be created from the browse window if necessary (e.g. \\filesystem\esm). The installer will automatically create an esm-agent sub folder within the selected destination folder (e.g. \\filesystem\esm\esm-agent)

8. Click Install. The installer will now unpack the required files to the specified directory and create and start the ESM Agent Windows service.

9. Verify the ESM Agent service installation and start up by checking the installer log window. The following lines should be present at the end of the log:

   Creating service...
   Creating service returned: 0
   Starting service...
   Starting service returned: 0
   

10. Use a web browser to connect to your ESM server web client (e.g. http://esmserver:18080/esm) to verify the agent has started, connected and is reporting data. You should see a node with the specified agent hostname listed in the Live view. Clicking the node will load the live graph.

If required, now follow the service installation for subsequent grid nodes, or repeat the installation steps for non-clustered file systems on those nodes.

Reminder of a previous Note

Once the ESM Agent installation is complete for all nodes, further configuration of SAS is required for full integration. This is detailed in the document titled Configuring SAS for ESM.

If the ESM Agent failed to install, or the service fails to start, please check the Troubleshooting section for further information.

Windows Service installation for subsequent nodes on shared filesystems

Note

Skip this step if the ESM Agent is installed on a local file system

Following the successful installation and validation of the ESM Agent on the first shared (e.g. SAS GRID) node, subsequent nodes only require the Windows service and Event directory to be registered.

1. Log on to the server using the nominated account with the required privileges (see installation requirements for more details)

2. Navigate to the location of the installed ESM Agent binaries. e.g.
   //filesystem/esm/esm-agent/bin

3. Right click the esm-agent.bat file and select Run as Administrator

4. The interactive batch file will prompt you for a command. Type install and hit Enter. The installer will auto detect the node hostname and install the windows service

   Enter The Command (start : stop : restart : install : remove : reinstall : query) : install
   Hostname detected: WIN2008R2N1
   wrapper  | ESM Agent installed.
   Press any key to continue . . .
   

5. Press any key to close the command prompt window

6. To start the service, right click the esm-agent.bat file and select Run as Administrator

7. At the prompt type start to start the ESM Agent service

8. The ESM Agent service will now start

9. Use a web browser to connect to your ESM server web client (e.g. http://esmserver:18080/esm) to verify the agent has started and is reporting in. You should see a node with the specified agent hostname listed in the Live view. Clicking the node will load the live graph.

Repeat the Windows Service Installation steps for each node as required, verifying each node is displayed in the ESM server web client.

The same note on configuration, again

Once the ESM Agent installation is complete for all nodes, further configuration of SAS is required for full integration. This is covered in the document titled Configuring SAS for ESM.

If the ESM Agent failed to install, or the service fails to start, check the Troubleshooting section for further information.

Agent Administration

Starting and Stopping the ESM Agent service

Using Windows Service status

The ESM Agent 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 Agent 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 Agent 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. \\filesystem\esm\esm-agent\bin

5. Run the esm-agent.bat file by issuing the following command:
   .\\esm-agent.bat

6. The interactive batch file will prompt you to enter a command. Type query and hit Enter.

PS>cd \\filesystem\esm\esm-agent\bin
\\filesystem\esm\esm-agent\bin>esm-agent.bat
Enter The Command (start : stop : restart : install : remove : reinstall : query) : query
Hostname detected: WIN2008R2N1
wrapper  | The ESM Agent Service is installed.
wrapper  |   Start Type: Automatic
wrapper  |   Interactive: No
wrapper  |   Running: Yes
Press any key to continue . . .

1. The appropriate commands can also be specified when invoking the script as follows:

2. The agent can be stopped with the following command:
   

   .\esm-agent.bat stop
   

3. Start the agent with the following command:
   

   .\esm-agent.bat start
   

4. The agent can be restarted with the following command:
   

   .\esm-agent.bat restart
   

Uninstall ESM Agent

Grid/Multi-node installations

The ESM Agent service must be uninstalled from each node. For shared filesystem installations (i.e. SAS GRID), this must be performed using the command line.

The same note from earlier on cmd.exe and UNC paths

cmd.exe does not support UNC paths. Use Windows Powershell to issue the following commands when the ESM Agent 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. \\filesystem\esm\esm-agent\bin

5. Remove the ESM Agent Windows service by issuing the following command:
   esm-agent.bat remove

6. Repeat steps 1 to 5 for each node until all ESM Agent Windows services have been removed

7. If required, the original installation folder and its contents can now be deleted

Using the Uninstall Wizard

For single node or non-clustered file system installations, the uninstall wizard can be used to remove the ESM Agent installation as follows:

1. Access the original installation folder (e.g. C:\esm\esm-agent).

2. Right click the Uninstall.exe executable and select Run as Administrator.

3. This will stop the ESM Agent and remove the “ESM Agent” Windows service.

4. If required, the original installation folder and its contents can now be deleted.

This concludes the removal of the ESM Agent.

Warning

Where removing ESM permanently, remember to remove any ESM specific configuration from your SAS Configuration scripts. For more details, refer to document titled Configuring SAS for ESM.