Skip to content

ESM Agent Installation Guide - Windows

Important note

It is recommended that you review the document titled Functional Overview of ESM before continuing with the tasks outlined here. Likewise, after completing the tasks here, further configuration of SAS will be required before session-level detail is reported. The further configuration steps required are covered in Configuring SAS for ESM.

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.

ESM Agent Installation

Installation Notes

Installation Location

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.

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.

For more information on the ESM Agent directory structure and event directory layout for clustered filesystems, refer to the document titled Functional Overview of ESM.

Agent Events directory

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 ESM Agent 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 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\

Installing the ESM Agent

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-1.0) 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-1.0) 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.

Troubleshooting

If you encounter any problems with the ESM Agent installation, please contact your Boemska representative or visit http://support.boemskats.com Email support is available by emailing support@boemskats.com.

Useful troubleshooting steps for common issues are detailed below.

Connection Failure

If during installation, the ESM agent fails to connect to the ESM server, please take the following steps.

  • Ensure the server settings in the installation wizard match those of the ESM server to which the agent is reporting in to, and that the target server is running.

  • To check the target server is running, use a web browser to connect to your ESM server web client (e.g. http://esmserver:18080/esm-1.0) or check the ESM Server Administration guide for further information. Also ensure that any firewall is configured to allow TCP traffic between the agent and server on the specified port number.

Service Fails to Start

If during installation, or at any other stage the ESM Agent service fails to start, this may be due to a permissions issue. The following message may be displayed when starting the ESM Agent service at a command prompt:

Hostname detected: WIN2008R2N1
wrapper  | Starting the ESM Agent service...
wrapper  | Unable to start the service – Access is denied. (0x5)
Press any key to continue . . .

Note

For further details on using the command line to control the ESM Agent service see Starting and Stopping the ESM Agent service

To resolve this issue, the appropriate account with the relevant level of access is required to be specified in the “Log on as” properties of the Windows Service configuration. To specify the correct account and password, complete the following steps:

  1. Click Start

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

  3. Right Click Services and click Run as Administrator

  4. In the services window which appears, scroll down the list to the “ESM Agent” entry and right click, selecting Properties from the context menu

  5. Click the Log On tab

  6. Select the This account radio button and specify the relevant account with the required privileges, together with the valid password. Specify the full account, with domain name, (e.g. DOMAIN\Account).

  7. Click Apply followed by OK

  8. The ESM Agent service can be started from the services menu by right clicking it and selecting Start from the context menu

  9. The ESM Agent service should now start and report in to the ESM Server.

  10. To check the target server is running, use a web browser to connect to your ESM server web client (e.g. http://esmserver:18080/esm-1.0)

If the service fails to start after following these steps, firstly verify you have the correct credentials in the 'This account' section of the 'Log On' tab. For further details on why the service may have failed to start, please inspect the agent log file (see the Agent Administration section of this guide. For further help please email support@boemskats.com or visit https://boemskats.com.

Disabling Windows Short Names to enable SASWORK Monitoring

If SASWORK is configured to point to a volume with short names enabled, and you wish to monitor SASWORK with ESM (recommended) you must change your SASWORK configuration to use a volume with short names disabled.

  1. Determine the new location for SASWORK. This guide assumes a drive letter of E:

  2. Query the short name status of drive E: by issuing the following command at a command prompt with elevated/Administrator privileges:

fsutil.exe 8dot3name query E:
This should produce the following output: 
C:\WINDOWS\system32>fsutil.exe 8dot3name query E:
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 E:. If the status returns 8dot3 name creation is enabled on E:, issue the following command to disable it: 
C:\WINDOWS\system32>fsutil 8dot3name set E: 1
Successfully disabled 8dot3name generation on E:

  1. Now create a saswork directory (e.g E:\saswork)

  2. Now change the SAS Server configuration to set SASWORK to point to this location. It is recommended to change this setting in the Application Server root sasv9_usermods.cfg file. For example: 

    C:\SAS\Lev1\SASApp\sasv9_usermods.cfg
    add the following entry to this file: 
    -WORK "E:\saswork"

  3. Restart the SAS Object Spawners to pick up the new configuration

  4. Start a new SAS Session and re-issue the saswork option query: %put %sysfunc(getoption(work)); If the change has taken effect, you should see output in the SAS log similar to the following: 

    E:\saswork\_TD1592_WIN2008R2N1_

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

Inspecting the Agent Log Files

If the ESM Agent fails to report in to the ESM Server, the ESM Agent log file can be inspected for further information. If required, increased logging can be enabled for further debugging. Boemska Support can assist in debugging and may request these log files to support investigation.

Location

Log files are located in the logs sub-directory of the agent installation directory (e.g. \\filesystem\esm\esm-agent\logs)

Log File name

Log files are prefixed with the hostname of the machine on which the agent is installed and running (e.g. node1_wrapper.log)

Uninstalling the 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.