ESM Agent Installation Guide - Unix

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 Linux/Unix¶

64 bit Linux (RHEL4 or later recommended)
AIX v5.2 to 7.2
HPUX 11i
Solaris v8 or later

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 750 MB disk space (including logs)
A user account with sudoer privilege, or suitable privileges to run the ESM Agent sufficiently. The following should be considered when choosing or configuring a system user account for ESM:
- The user account will need Read/Write access to the target installation directory and sub directories
- To use ESM to measure the size of SASWORK and SASUTIL directories of user-owned SAS sessions, the account under which the ESM Agent process is executing must have the privileges necessary to read those directories.
- To use ESM to tail logfiles generated by system services, userspace sessions or batch jobs, the agent process must have the privileges necessary to read the logfiles written by those processes.
- To use ESM to terminate SAS sessions from the ESM interface, the account under which the agent service is executing must have the privileges necessary to do so at the operating system level.
A running ESM Server. During installation the agent will validate connectivity to the target server. Please install, configure and start an ESM Server instance before installing the agent
The hostname or IP address and port number of the ESM Server
A modern Web Browser. Although ESM loads and works under IE8, usable performance is not guaranteed.
If a firewall is configured, the default TCP port 18080 (or the custom configured port selected during server installation) will need to be opened for communication to the target ESM server

ESM Agent Installation¶

General Information¶

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 generate the agent installation directory. The ESM Agent is then started from each subsequent grid node from the generated installation directory.

For single node or non-clustered file systems, the ESM Agent can be installed to a local file system.

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.

Getting the ESM Agent Installation package¶

Download the appropriate ESM agent installation package for your Linux/Unix 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. If you have not received your logon details or require further help, plese contact Boemska Support on support@boemskats.com.

Installing the ESM Agent¶

Note

For Grid or multi-node installations where the ESM Agent is to be installed to a clustered file system, it is only necessary to execute the full Installation Wizard once, as outlined for the First/Primary node installation below. For subsequent nodes, the ESM Agent can be started from the shared installation directory. The initial startup will generate a node specific events directory, using the node hostname for the unique path.

For single node or non clustered file systems, follow the installation steps and run the Installation wizard on each node.

First/Primary node installation¶

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

Unpack the installation package and navigate to its contents, which will be a subdirectory called esm-agent-installer:

esminstaller at node1 in /home/esminstaller
$  tar xf /pub/esm/esm-agent-x64-linux-v1.0-branch_build.tar.gz -C /pub/esm
esminstaller at node1 in /home/esminstaller
$ cd /pub/esm/esm-agent-installer
esminstaller at node1 in /pub/esm/esm-agent-installer
$

Execute ./setup.sh to start the ESM Agent Installation Wizard. You should be greeted with the Terms of License, which you can accept by typing 'y':

$ ./setup.sh 

 Terms of License and User Agreement 

Please review the following Terms of License before installing the ESM Agent.

     By typing 'y' you confirm that:

i)   there is a valid license agreement in place which duly authorises you to use this
ii)  you have read the Software License Agreement and you understand its terms and
iii) you agree to be bound by the terms and conditions of the Software License
     software and describes your rights and obligations as a licensee of this software

     You should not proceed and select 'n' if you cannot confirm any of the
     statements above.

If you accept the Terms of License above please type 'y' to continue.  y

Specify the Agent installation path:

=============================================================================
 ESM Agent Installer Started.
 Current time:  Mon  2 Jul 16:47:57 BST 2018
=============================================================================

Please, insert agent install path: [default: /home/nik]

/pub/esm

The installer will automatically create an esm-agent sub folder within the selected destination folder named esm-agent, which in this example will be /pub/esm/esm-agent

Enter the hostname or IP address of the ESM Server into which this Agent will report, and the port which the server is listening on. You may hit enter to accept the defaults:

What is the hostname or IP address of the ESM server: [default: localhost]
apps.boemskats.com
What port is the ESM server configured to communicate on: [default: 18080]
18080

For the next step the format in which SAS Foundation reports the hostname for each node is needed. This can be sourced by either running the following command from a shell:

echo 'data _null_; file STDOUT; put "&syshostname."; run;' | \
     /pub/sas/SASFoundation/9.4/sas -stdio 2>/dev/null

or running the following code from an existing SAS session:

%put &syshostname.;

The Installer will prompt for the format which matches the output from either of the above.

How is the value of the &syshostname macro variable formatted within the target environment?
1) node1.boemskats.com
2) node1
3) Set hostname manually
Chosen format: 2
You have chosen node1 as your hostname format.

Configure the block devices which ESM will monitor. The script will attempt to detect available block devices using the lsblk command, but this does not always detect all devices for which metrics are available. If a device is not shown in the list of defaults, but is visible under /proc/diskstats or by running iostat -x, the agent should generally be able to report on it. Ensure all devices are punctuated by a trailing semicolon, including the last device in the list.
```
Please specify the storage devices you would like to be monitored.
When adding more than one, ensure they are separated by a semicolon ';'.
To disable disk monitoring, type 'none'.

You can also type 'auto' or 'autodiscover' if you want ESM to try to automatically
find eligible disk devices, but this is not always reliable.

Recommended disks to monitor, according to lsblk -l: [default: sda;vda; ]
sda;
Selected disks: "sda;"
```

The ESM Agent will now install. On completion, a message similar to the following will be displayed:

Extracting ESM Agent
Moving ESM Agent to /pub/esm
Configuring ESM Agent...
Configuring ESM Agent default events folder...

Checking connection between ESM Agent and ESM Server...
Connection to apps.boemskats.com:18080 succeeded!

-----------------------------------------------------------------------------
   ESM Agent installation complete: 
   Successfully installed to: /pub/esm/esm-agent
-----------------------------------------------------------------------------

Following installation, you will be prompted to start the ESM Agent. Before doing so, consider the user account requirements specified in the Installation Requirements section of this document. If the current user meets those requirements, proceed as instructed:

You can start ESM Agent by running this command:
   /pub/esm/esm-agent/bin/esm-agent.sh start

Do you want to start it now? (y/n):  y

The ESM Agent should now start:

Checking connection between ESM Agent and ESM Server...
Connection to apps.boemskats.com:18080 succeeded!
Starting ESM Agent...

Log file: '/pub/esm/esm-agent/logs/localhost_wrapper.log'

Agent started. (pid 12968)

Use a web browser to connect to the ESM Server web client 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, and clicking the node should load the live graph.

If the ESM Agent failed to install or start, please refer to the Troubleshooting section of this document for further information.

Installation on subsequent nodes¶

To monitor subsequent GRID nodes, simply starting the ESM Agent from the shared filesystem on each node should be sufficient.

/filesystem/esm/esm-agent/bin/esm-agent.sh start

To monitor nodes that do not share an identically mounted filesystem, repeat the installation steps for each node to be monitored.

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.

ESM Agent Operation¶

Starting and Stopping the ESM Agent Service¶

The ESM Agent can be started with the following command:

Note

The ESM agent should be run under an account with sufficient permissions to inspect and manage the processes being monitored. On a typical multi-user system, the ESM Agent is therefore started and stopped by prefixing the sudo command to the start and stop commands below.

/filesystem/esm/esm-agent/bin/esm-agent.sh start

Checking connection between ESM Agent and ESM Server...
Connection to apps.boemskats.com:18080 succeeded!
Starting ESM Agent...
Log file: '/pub/esm/esm-agent/logs/node1_wrapper.log'
Agent started. (pid 3327)

The ESM Agent can be stopped with the following command:

/filesystem/esm/esm-agent/bin/esm-agent.sh stop

Stopping ESM Agent...
Stopped ESM Agent.

The status of the ESM Agent can be checked with the following command:

/filesystem/esm/esm-agent/bin/esm-agent.sh status
ESM Agent is not running.

Inspecting the Agent Log Files¶

If the ESM Agent fails to connect 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 will assist in debugging and may request these log files when providing support.

Log files are located in the logs subdirectory of the agent installation directory, and the logfiles are prefixed with the hostname of the machine on which the agent is installed. The logfile for a given instance of the agent is also output as part of a successful startup:

/filesystem/esm/esm-agent/bin/esm-agent.sh start

Checking connection between ESM Agent and ESM Server...
Connection to apps.boemskats.com:18080 succeeded!
Starting ESM Agent...
Log file: '/pub/esm/esm-agent/logs/node1_wrapper.log'
Agent started. (pid 3327)

By default, the Agent will keep a rotation of 5 logfiles, up to a maximum size of 100mb per logfile. This, alongside other logging parameters, can be configured by modifying esm-agent\conf\wrapper.conf. Further information on the logging parameters specified within this file can be found by referring to the official Tanuki Java Service Wrapper documentation, or by contacting Boemska Support.

Troubleshooting¶

Agent fails to start¶

If on starting the agent the following message is displayed:

[user@node1 bin]$ ./esm-agent.sh start

Checking connection between ESM Agent and ESM Server...
Checking connection between ESM Agent and ESM Server(2)...
Checking connection between ESM Agent and ESM Server(3)...
Checking connection between ESM Agent and ESM Server(4)...
Checking connection between ESM Agent and ESM Server(5)...
Could NOT connect to ESMServer:18080.
Did you forgot to open port 18080 on ESMServer or your ESM server was not started?
Check if server and port are correct in /filsesystem/esm/esm-agent/conf/esmconfig.sh
----------------------------------------------------
NOTE: Check if your server is started and try again!

This may be caused by a number of issues:

ESM Server not started
Please ensure the ESM Server is started before bringing up your Agent
Communications port (default 18080) not accessible
Please ensure any firewalls between your Server and Agent(s) have been configured to allow communication on the configured ESM port
Incorrect ESM Server hostname specified in Agent configuration
Please ensure the correct ESM Server hostname/IP address is specified in the Agent configuration. If this is incorrect, either restart the Agent installation process, or ensure that the correct hostname or IP address is set as the ESMSERVER variable in esm-agent/conf/esmconfig.sh.

Agent fails to pick up Events sent by SAS¶

When an ESM Agent for a given host first connects to the ESM Server, the Server registry stores the initial configured value for the events directory in the database. Every subsequent time that the Agent connects, any events location already stored by the ESM Server overrides the ESMEVENTS parameter specified in esmconfig.sh.

If an ESM Agent running on the same hostname has previously connected to the ESM server, but the install location has changed from the initial install, the Events Directory setting from the previous installation may override the location configured as part of the most recent installation. If this is suspected, it is important to verify that the ESM Events directory specified for that host in the ESM Admin screen is correct. If it is not, the previous configuration can be removed by clicking on the icon in the list of configured agents on the ESM Admin Screen.

For more information about the ESM Admin Screen, review the ESM Administration Guide.

Uninstalling the ESM Agent¶

First, ensure the ESM Agent is stopped with the following command

/filesystem/esm/esm-agent/bin/esm-agent.sh stop

You may now delete the ESM Agent installation directory if required. If the ESM Agent was configured to start using something like init.d, systemd or upstart, you may need to update your startup configuration. Otherwise no further action is required.

Warning

If removing ESM permanently, remember to remove any ESM specific configuration from your SAS Configuration scripts. Depending on the version of ESM you have installed, the integration routines may not fail gracefully if the ESM agent is deleted before your SAS environment is deconfigured.