cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 
BookmarkSubscribeRSS Feed

SAS Enterprise Session Monitor – Deployment Using Ansible

Started ‎05-18-2023 by
Modified ‎05-18-2023 by
Views 1,220

SAS® Enterprise Session Monitor (SAS ESM) is an observability tool provided by SAS that will allow you to monitor your SAS® 9.4, SAS® Viya® 3.5, or SAS® Viya® Platform deployments.

 

In this post, I will show you how Ansible® could help you to deploy and configure SAS Enterprise Session Monitor in your environment. Later, in another post, I will show you how Ansible could be used to integrate SAS ESM with your SAS deployments.



Ansible to help us to deploy and configure SAS Enterprise Session Monitor

 

Ansible® is an open-source, command-line IT automation software application written in Python. It can configure systems, deploy software, and orchestrate advanced workflows to support application deployment, system updates, and more. (source: ansible.com )

 

In the SAS Enterprise Session Monitor context, Ansible is extremely useful to automate the deployment and configuration of SAS ESM Agents and SAS ESM Agent Modules across multiple hosts in parallel.

 

A few assumptions before stating…

 

We assume that you have licensed SAS ESM which provides you with access to the SAS ESM download repository. We are starting from the point after which you have downloaded the SAS ESM installation assets and have made them available to your SAS deployments.

 

Ansible is deployed and configured on one of your hosts: the Ansible Controller host. Note that Ansible is a requirement for all SAS Viya 3.x environments.

 

SAS Enterprise Session Monitor Server is already deployed in your environment

 

Since you typically install only a single instance of the SAS ESM Server, I do not find that Ansible needs to be used. Just refer to the SAS Enterprise Session Monitor Server Installation documentation.

 

SAS Enterprise Session Monitor Agent

 

SAS ESM Agents must be deployed and configured on each SAS deployment host that you want to monitor in your environment. Because of that, you must repeat the deployment and configuration task several times. You could, of course, manually install SAS ESM Agents on every host. Alternatively, Ansible becomes a great tool since it can be used to automate tasks that could be executed in parallel against several hosts at a time.

 

The workflow you will follow to deploy the SAS ESM Agents using Ansible is:

  1. Copy and extract the SAS ESM Agent install packages on each host.
  2. Create the SAS ESM Agent installer.properties file on each host.
  3. Install the SAS ESM Agent on each host.
  4. Create a service to automatically start the SAS ESM Agent on each host.

 

Copy and extract the SAS ESM Agent install packages on each host

 

The SAS ESM Agent package must be copied on each SAS deployments hosts that need to be monitored in your environment.

 

1. Create a directory to store the SAS ESM Agent package on all hosts

 

Because the SAS ESM Agent must be managed by a user that is not root and not the user that is used to manage the ESM Server embedded database, I decided to use the sas user that already exists in my environment.

 

ansible 'all' \
        -b \
        -m 'file' \
        -a 'path=/opt/sas/esm/installers
            state=directory
            owner=sas
            group=sas
            mode=0774'

 

This creates the /opt/sas/esm/ installers directory on every host in the deployment inventory, sets the ownership to my sas user, and opens permissions on the directory as needed.

 

 2. Now it is possible to copy the SAS ESM Agent package on all hosts using the Ansible copy module.

 

# Copy the SAS ESM Agent package into the installer directory
export _ESM_AGENT_PACKAGE_LINUX=$(grep "esm-agent-linux" /download/sasesmpackages/checksums.md5 | awk -F "/" '{print $2}')
ansible 'all' \
        -b \
        -e "_ESM_AGENT_PACKAGE_LINUX=${_ESM_AGENT_PACKAGE_LINUX}" \
        -m 'copy' \
        -a 'src=/download/sasesmpackages/{{ _ESM_AGENT_PACKAGE_LINUX }}
            dest=/opt/sas/esm/installers
            owner=sas
            group=sas
            mode=0664'

 

In these commands:

 

The checksums.md5 file is used to extract the SAS ESM Agent package name into the _ESM_AGENT_PACKAGE_LINUX environment variable. This is convenient since the SAS ESM packages name contains its version that is subject to change with each update. 

 

checksums.md5 file content example.

 

[...]
ef7a36b48eaf7fedb3203b4b5591b6a2  ./esm-agent-linux-2022.4.7.tar.gz
[...]

 

The SAS ESM Agent package is copied on all hosts in the /opt/sas/esm/installers directory and the ownership and permission are automatically set as expected.

 

We now have the SAS ESM Agent package on each host, but we need to extract the individual files from the tar file before we can install it.

 

export _ESM_AGENT_PACKAGE_LINUX=$(grep "esm-agent-linux" /download/sasesmpackages/checksums.md5 | awk -F "/" '{print $2}')
ansible 'all' \
        -b --become-user=sas \
        -e "_ESM_AGENT_PACKAGE_LINUX=${_ESM_AGENT_PACKAGE_LINUX}" \
        -m 'unarchive' \
        -a 'src=/opt/sas/esm/installers/{{ _ESM_AGENT_PACKAGE_LINUX }}
            dest=/opt/sas/esm/installers
            remote_src=yes'

 

This command extracts the agent package on each host, making sure the files are owned by my sas user

 

Now the environment is ready to deploy and configure the SAS ESM Agent.

 

Create the SAS ESM Agent installer.properties file on each host

 

The installer.properties file is used to set the required configuration parameters to be able to install the SAS ESM Agent.

 

export _ESM_SERVER_HOST=my.esm.server.fqdn
export _ESM_AGENT_INSTALL_DIR="\/opt\/sas\/esm"
export _ESM_SERVER_PORT=18082
ansible 'all' \
        -b --become-user=sas \
        -e "_ESM_AGENT_INSTALL_DIR=${_ESM_AGENT_INSTALL_DIR} _ESM_SERVER_PORT=${_ESM_SERVER_PORT} _ESM_SERVER_HOST=${_ESM_SERVER_HOST}" \
        -m 'shell' \
        -a 'cd /opt/sas/esm/installers/esm-agent-installer;
            cp -p conf/installer.propertiesOPTIONAL conf/installer.properties;
            sed -i "s/AGENT_INSTALL_DIR=\$HOME/AGENT_INSTALL_DIR={{ _ESM_AGENT_INSTALL_DIR }}/g" conf/installer.properties;
            sed -i "s/SERVER_PORT=18080/SERVER_PORT={{ _ESM_SERVER_PORT }/g" conf/installer.properties;
            sed -i "s/ESMCUSTOMHOSTNAME=/ESMCUSTOMHOSTNAME=$(hostname -f)/g" conf/installer.properties;
            sed -i "s/THIS_HOSTNAME=s/THIS_HOSTNAME=f/g" conf/installer.properties;
            if [ ! -z {{ _ESM_SERVER_HOST }} ];
            then
               sed -i "s/SERVER_HOST=localhost/SERVER_HOST={{ _ESM_SERVER_HOST }}/g" conf/installer.properties;
            fi'

 

After copying the provided installer.propertiesOPTIONAL template as the required installer.properties file, several sed commands are used on the remote hosts through the Ansible command to customize the installer.properties file specifically for each host.

 

In this Ansible command, the shell module is used to execute a series of bash commands on the remote hosts.

 

Some variables are set and passed to the Ansible command to provide required configuration parameters common to all SAS ESM Agent configuration:

 

  • _ESM_SERVER_HOST: The SAS ESM Server FQDN. Used to set the SERVER_HOST parameter in the installer.properties file.
  • _ESM_AGENT_INSTALL_DIR: The path of the directory on which the SAS ESM Agent must be deployed on each host. Used to set the AGENT_INSTALL_DIR parameter in the installer.properties file.
  • _ESM_SERVER_PORT: The port on which the SAS ESM Server listens for SAS ESM Agents. Used to set the SERVER_PORT parameter in the installer.properties file.

 

Some SAS ESM Agent configuration parameters are set or calculated on each host:

 

  • ESMCUSTOMHOSTNAME: To define a hostname that will be used to qualify the SAS ESM data for this SAS ESM agent. The script above set it using the $(hostname -f) bash command to get the name specific to each host.
  • THIS_HOSTNAME: The parameter that the SAS ESM Agent must pass to the hostname command. It can be either ‘s‘ (for short) or ‘f‘ (for full). The script above set it as ‘f‘.

 

Install the SAS ESM Agent on each host

 

The SAS ESM Agent installer.properties file is now ready on each host. It is time to invoke the SAS ESM Agent installer script.

 

# Install the SAS ESM Agent
ansible 'all' \
        -b --become-user=sas \
        -m 'shell' \
        -a 'cd /opt/sas/esm/installers/esm-agent-installer;
            ./setup.sh;'

 

As result, the SAS ESM Agent will be deployed and configured on each host.

 

Create a service to automatically start the SAS ESM Agent on each host

 

In a production environment, you do not want to manage (start/stop/restart) the ESM Agent manually using the provided scripts. It is better to create systemd daemons (services) to manage the SAS ESM Agent on each host.

 

1. Create a temporary esm-agent.service file on the Ansible Controller host.

 

To simplify the process, the main idea is to create a systemd esm-agent.service file on the Ansible Controller host and then copy it on each host to define the SAS ESM Agents systemd daemons (services) on them. The esm-agent.service file is the same for each host and does not require host-specific customizations.

 

cat > /tmp/esm-agent.service <<EOM
[Unit]
Description=ESM agent control
After=network.target

[Service]
ExecStart=/opt/sas/esm/esm-agent/bin/esm-agent-nonforking.sh start
Restart=on-failure
Type=simple
TimeoutStartSec=10
TimeoutStopSec=5
RestartSec=2
LimitNOFILE=500000
LimitNPROC=500000
ExecStop=/opt/sas/esm/esm-agent/bin/esm-agent-nonforking.sh stop
SuccessExitStatus=143
User=root

[Install]
WantedBy=multi-user.target
EOM

 

2. The SAS ESM Agents systemd esm-agent.service file must be copied on each host

 

Its ownership must be set as root:root, and the permission as rw-rw-r-- (0664).

 

ansible 'all' \
        -b \
        -m 'copy' \
        -a 'src=/tmp/esm-agent.service
            dest=/etc/systemd/system/esm-agent.service
            owner=root
            group=root
            mode=0664'

 

3. The SAS ESM Agent systemd esm-agent.service must be registered, enabled, and started on each host.

 

These Ansible commands are using the systemd module that allows us to control systemd units on remote hosts.

 

  •        Reload the systemd daemons to register the new esm-agent.service service in the system.

 

ansible 'all' \
        -b \
        -m 'systemd' \
        -a 'daemon_reload=true'

 

  •       Enable and start the new esm-agent.service service.

 

ansible 'all' \
        -b \
        -m 'systemd' \
        -a 'name=esm-agent
            state=restarted
            enabled=yes'

 

Hint: The state argument is set to restarted instead of started to ensure that service will be restarted in case it was already started.

 

 

4. For more security, it is recommended to delete the SAS ESM Agent systemd esm-agent.service temporary file on the Ansible Controller host.

 

rm -f /tmp/esm-agent.service

 

The SAS ESM Agent is now deployed and configured on all required hosts and its associated systemd service is created.

 

 

SAS Enterprise Session Monitor Agent Modules

 

SAS ESM Agent Module is a SAS ESM component that will enhance the ESM functionalities by finding information/events from logs files. They required significant changes to the default logging configuration of most SAS systems.

 

There are currently three SAS ESM Agent Modules available:

 

  • sas-proc-mon (SAS® 9.4, SAS® Viya 3.5 – Windows and Unix)
    Should be deployed only on the hosts where compute or SAS Programming Environment (SPRE) components are deployed.

 

  • sas-cas-mon (SAS® Viya 3.5 – Unix only)
    Should be deployed only on the hosts where SAS Cloud Analytic Services (CAS) components are deployed.

 

  • sas-lasr-mon (SAS® 9.4 – Unix only)
    Should be deployed only on the hosts where LASR components are deployed.

 

SAS ESM Agent Module must be deployed only on specific hosts. For this reason, it is recommended to have a specific host group defined into the Ansible inventory.ini file like: computehosts, cashosts, and lasrhosts.

The workflow you will follow to deploy the SAS ESM Agents using Ansible is:

  1. Copy and extract the SAS ESM Agent Module install packages on the required host.
  2. Customize the SAS ESM Agent Module vars.yaml file on the required host.
  3. Create a service to automatically start the SAS ESM Agent Module on the required host.


Let’s illustrate this process with the sas-proc-mon SAS ESM Agent Module.

Copy and extract the SAS ESM Agent Module install packages on the required host.

 

  • Copy the sas-proc-mon SAS ESM Agent Module package on the required Linux hosts
ansible 'computehosts' \
        -b \
        -m 'copy' \
        -a 'src=/download/sasesmpackages/sas-proc-mon_unix.zip
            dest=/opt/sas/esm/installers
            owner=sas
            group=sas
            mode=0664'
  • unzip the sas-proc-mon ESM Agent Module package on all required Linux hosts

 

ansible 'computehosts' \
        -b --become-user=sas \
        -m 'unarchive' \
        -a 'src=/opt/sas/esm/installers/sas-proc-mon_unix.zip
            dest=/opt/sas/esm/esm-agent/modules
            remote_src=yes'

 

Customize the SAS ESM Agent Module vars.yaml file on the required host.

 

The sas-proc-mon ESM Agent Module must be configured. A vars.yaml file is provided but need to be customized.

 

ansible 'computehosts' \
        -b --become-user=sas \
        -m 'shell' \
        -a 'cp -p /opt/sas/esm/esm-agent/modules/sas-proc-mon/vars.yaml /opt/sas/esm/esm-agent/modules/sas-proc-mon/vars.yaml.bak;
            sed -i "s|sasType: \"v9\"|sasType: \"viya\"|g" /opt/sas/esm/esm-agent/modules/sas-proc-mon/vars.yaml;
            sed -i "s|ignore_work_tables: true|ignore_work_tables: false|g" /opt/sas/esm/esm-agent/modules/sas-proc-mon/vars.yaml;
            sed -i "/  CS:/,/      dataAccess:/s/^/#/" /opt/sas/esm/esm-agent/modules/sas-proc-mon/vars.yaml;'

 

Note that this configuration is documented only in the README.md file that is provided with each SAS ESM Agent Module package.

 

Create a service to automatically start the SAS ESM Agent Module on the required host

1. Create a temporary esm-sas-proc-mon.service file on the Ansible Controller host. 

 

cat > /tmp/esm-sas-proc-mon.service <<EOM
[Unit]
Description=ESM SAS PROC Monitoring Module
After=network.target
[Service]
Environment=ESMHOME=/opt/sas/esm/esm-agent ESMEVENTS=/opt/sas/esm/esm-agent/events/{ESMCUSTOMHOSTNAME} LOGLEVEL=INFO ESMNODENAME={ESMCUSTOMHOSTNAME}
PassEnvironment=ESMHOME ESMEVENTS LOGLEVEL ESMNODENAME
User=root
ExecStart=/opt/sas/esm/esm-agent/modules/sas-proc-mon/esm-module.sh -nonforking
Type=simple
TimeoutStartSec=10
TimeoutStopSec=5
RestartSec=2
[Install]
WantedBy=multi-user.target
EOM


Note that the {ESMCUSTOMHOSTNAME} variable is set in this default esm-sas-proc-mon.service file to be able to configure this value later in the process.

 

2. Copy the sas-proc-mon ESM Agent Module systemd daemon (service) on all required Linux hosts.

 

ansible 'computehosts' \
        -b \
        -m 'copy' \
        -a 'src=/tmp/esm-sas-proc-mon.service
            dest=/etc/systemd/system/esm-sas-proc-mon.service
            owner=root
            group=root
            mode=0664'

 

3. Customize the sas-proc-mon ESM Agent Module systemd daemon (service) on all required Linux hosts.

 

This step is required to customize the esm-sas-proc-mon.service file on each host by replacing the {ESMCUSTOMHOSTNAME} variable by each host FQDN.

 

ansible 'computehosts' \
        -b \
        -m 'shell' \
        -a 'sed -i "s|{ESMCUSTOMHOSTNAME}|$(hostname -f)|g" /etc/systemd/system/esm-sas-proc-mon.service;'

 

4. The SAS ESM Agent systemd esm-sas-proc-mon.service must be registered, enabled, and started on each host.

 

  • Reload the systemd daemons to register the new esm-sas-proc-mon.service service in the system.
ansible 'computehosts' \
        -b \
        -m 'systemd' \
        -a 'daemon_reload=true'

 

  • Enable and start the new esm-sas-proc-mon.service service.

ansible 'computehosts' \
        -b \
        -m 'systemd' \
        -a 'name=esm-sas-proc-mon
            state=restarted
            enabled=yes'

 

5. For more security, it is recommended to delete the esm-sas-proc-mon SAS ESM Agent Module systemd esm-sas-proc-mon.service temporary file on the Ansible Controller host.

 

rm -f /tmp/esm-sas-proc-mon.service

 

Now SAS Enterprise Session Monitor is fully deployed. The next steps will consist of integrating SAS deployments in SAS ESM which will be the topic of my next post.

0 Likes
Contributors
Version history
Last update:
‎05-18-2023 03:16 PM
Updated by:
SAS Employee

hackathon24-white-horiz.png

The 2025 SAS Hackathon has begun!

It's finally time to hack! Remember to visit the SAS Hacker's Hub regularly for news and updates.

Latest Updates

SAS AI and Machine Learning Courses

The rapid growth of AI technologies is driving an AI skills gap and demand for AI talent. Ready to grow your AI literacy? SAS offers free ways to get started for beginners, business leaders, and analytics professionals of all skill levels. Your future self will thank you.

Get started

Article Labels
Article Tags