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® 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.
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 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:
installer.properties
file 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.
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
‘.
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.
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.
esm-agent.service
service in the system.
ansible 'all' \ -b \ -m 'systemd' \ -a 'daemon_reload=true'
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 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)
sas-cas-mon
(SAS® Viya 3.5 – Unix only)
sas-lasr-mon
(SAS® 9.4 – Unix only)
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:
vars.yaml
file on the required host.
Let’s illustrate this process with the sas-proc-mon
SAS ESM Agent Module.
sas-proc-mon
SAS ESM Agent Module package on the required Linux hostsansible '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'
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.
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.
esm-sas-proc-mon.service
service in the system.ansible 'computehosts' \ -b \ -m 'systemd' \ -a 'daemon_reload=true'
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.
Registration is open! SAS is returning to Vegas for an AI and analytics experience like no other! Whether you're an executive, manager, end user or SAS partner, SAS Innovate is designed for everyone on your team. Register for just $495 by 12/31/2023.
If you are interested in speaking, there is still time to submit a session idea. More details are posted on the website.
Data Literacy is for all, even absolute beginners. Jump on board with this free e-learning and boost your career prospects.