SphereShield Agent Service

Owned by Agat Support
Last updated: Apr 05, 2022 by Avi J. Levin (Unlicensed)
9 min read

Updated to agent 1.5.1

General

SphereShield Service Agent is a Windows Service used to monitor other AGAT service health and to enable remote service management from the Admin Portal.

The Agent can monitor the following services:

  • Sip Filter (AgatSipFilter)

  • Bastion (for LAC, Teams Protector, Webex Protector filters)

  • Authentication Extender

  • Casb Adapter (AgatSphereShieldCasbAdapter)

  • Content Manager (AgatContentManagerService)

Operation

Monitoring operation consists of three main parts:

  1. Checking if monitored service is running and start it if not

  2. Checking in DB if monitored service is alive using Service Management mechanism

  3. Sending a health check request to the Bastion and its filters. If the Bastion and filters are not healthy, the agent will try to restart the Bastion service.

The Service Agent will not verify service functionality for the Authentication Extender

Process Monitoring for Bastion

The agent runs the monitoring each defined number of seconds (default 60) and does the following:

  1. [DB mode] Write agent alive time in service management table for monitored service row

  2. Check if the monitored service is running and start it if not

  3. [DB mode] Check if monitored service is alive in the service management table

  4. [Bastion] Check if Bastion and filters are OK:

    1. Bastion health check procedure:

      1. Forwarding proxy:

        1. Request https://[BastionHealthcheckHost]/healthcheck with proxy BastionIP
          for example https://test.skypeshield.com/teams_protection/healthcheck with proxy 127.0.0.1

      2. Reverse proxy:

        1. Request https://[BastionIp]/skypeshieldhealth with host header BastionHealthcheckHost
          for example https://127.0.0.1/skypeshieldhealth with host header test.skypeshield.com

          1. If received HTTP 200 status code (during response time of BastionMaxHealthcheckLatencyMilliseconds if set not to 0) - Bastion and filters are OK (no restart is done)

          2. If received other HTTP status or error/exception - except statuses 404 (Not Found), 403 (Forbidden) and 401 (Unauthorized) - will try to restart Bastion service after 3 consecutive failures every 10 seconds - only if already in production mode.

          3. If the health check result is not OK and the agent is in production mode (received 5 sequence OK results) - consider the health check as not passed

          4. otherwise, if the health check result is OK or the agent is not in production mode (not received 5 sequence OK results) - consider the health check as passed

        2. the agent will go into production mode (restart on the error) only after receiving good result for 5 times indicating the correct operation to avoid misconfiguration in install.

        3. If alive check or bastion healthcheck not passed - restart the monitored service

        4. If failed to start the service X (X = ServiceMonitorNumberOfAttemptsBeforeRestart) times - kill the monitored service

Service Management Process

The agent receives commands through database table Service_Management and performing the required command on the monitored service. The commands are sent by Admin Portal from the Service Management page, or troubleshooting commands are sent from Troubleshooting wizard. The agent listens to the table and starts to perform the command when the Operation field is changed in the table.

Available commands are:

  • RESTART - restart the monitored service

  • START- start the monitored service

  • STOP - stop the monitored service

  • RESTART_AGENT - restart the agent itself

  • START_TRBL - start troubleshooting process

  • FINISH_TRBL- finish the troubleshooting process

Troubleshooting Processing

Troubleshooting is available only for Bastion with LAC filter.
More details here: https://agatsoftware.atlassian.net/wiki/spaces/SKYP/pages/1126367233

Installation

The agent is installed and configured by the installer.

To install the service manually (run as administrator):

> AgatSphereShieldServiceAgent.exe install

You will see service with the following details

Service name

AgatSphereShieldServiceAgent[CustomerName]

Service display name

AGAT SphereShield Service Agent [Customer Name]

Removal

To uninstall the service go to the folder with the Service Agent binaries in cmd and run as administrator:

> AgatSphereShieldServiceAgent.exe remove

Configuration

There is an AgatSphereShieldServiceAgent.config file with configuration for the agent. The agent writes to a log file (default at D:\Agat\Logs\ServiceAgent\[CustomerName]) and to Event Log with source "AGAT SphereShield Service Agent".

XML Configuration

Configuring the database connection string for the Agent

The database connection string is a must configuration in order for the Service Agent to work.

<add key="ConnectionString" value="Data Source=[SQLSERVER];Initial Catalog=[DataBaseName];Persist Security Info=True;User ID=[username];Password=[password]" />

Change the values in the square brackets to match the environment where the Access Portal database is located.

Logging configuration

Logging is configured in the AgatSphereShieldServiceAgent.config file in the Agent.

Key

Value

Details

Key

Value

Details

Logging

CustomerName

Company name

The name of the company(will be appended to the service upon installation

LogFileFullName

string

The file path to the logs

LogFileMaxSize

integer(MB)

Max size for each log file before creating a new log file.

LogFileLevel

Off/Fatal/Critical/Error/Alert/Warn/Info/Debug/All

The severity level of Service Agent logs.

EventLogLevel

Off/Fatal/Critical/Error/Alert/Warn/Info/Debug/All

The severity level of the Service Agent in the Windows Event Viewer.

DB Connection

DBRequired

true/false

Work in standalone mode without contacting the database

ConnectionString

Data Source=[SQLSERVER];Initial Catalog=[DataBaseName];Persist Security Info=True;User ID=[username];Password=[password]

The database connection string

(Note: Fill in the relevant details of the environment upon initial configuration)

Key

Key from the admin portal

Can be found in the Admin Portal server under the folder c:\inetpub\AccessPortal\Configuration\applicationSettings.xml

(Required if DBRequired set to true)

IV

IV for AES encryption

Can be found in the Admin Portal server under the folder c:\inetpub\AccessPortal\Configuration\applicationSettings.xml

(Required if DBRequired set to true)

Monitoring settings

ServiceName

The service name

the name of the service to monitor

(note: Make sure to fill in the internal Service name and not the display name)

ServiceRestartTimeoutSeconds

Time for wait after restart(sec)

 

ServiceMonitorFrequencySeconds

Time between each check(sec)

Will load from database if the connection string is filled in

ServiceMonitorNumberOfAttemptsBeforeRestart

The number of time of failure needed for a restart

Will load from database if the connection string is filled in

Ethical Wall

MonitorEthicalWallLoad

true/false

Enable monitoring Ethical Wall load (only relevant to the SIP Filter)

MonitorEthicalWallLoadFrequencyMinutes

Time(Min)

The time in minute between each check of ethical wall load

Bastion

BastionForwardProxy

false/true

Whether the Bastion is a forward proxy (relevant for Teams Protector deployment)

BastionIp

A valid IP address(default: 127.0.0.1)

The IP to which to send a request

BastionHealthcheckHost

The http Host address(default: BastionHealthcheckHost)

The Host address header to send in the heartbeat

BastionMaxHealthcheckLatencyMilliseconds

Maximum latency for getting healthcheck results(milliseconds)

0 will disable latency check

TroubleshootingOutputFolder

Path to Filter logs

Path to the Filter logs in order to inspect for issues

TroubleshootingSplitIntoVolumes

true/false

Split troubleshooting archive into volumes

(useful for email attachments)

TroubleshootingSplitVolumeSize

size in MB(default: 10)

troubleshooting archive split volume in MB.

TroubleshootingDaysRange

Number of days(default: 1)

Number of last days to include in troubleshooting archive

Email

EmailIssues

[Empty]/all/dbConnectionFailure/bastionDbConnectionFailure/restartFailure/restartSuccess

What issues will cause sending email

SMTP_HostName

Hostname

The SMTP server to send the SMTP request to.

SMTP_Port

Port number

The port to send the FTP request on.

SMTP_AccountUserName

Email address of the sender account

The Email address is used to send the email and authenticate against the SMTP server.

SMTP_AccountPassword

Password for the email account used for sending

The password of the Email Address.

SMTP_RequiresSsl

False/True

Sends the Email via SSL.

SMTP_RequireAuthentication

False/True

Whether to use signing in(depending on if the SMTP server requires authentication in order to send Emails through it.)

SMTP_MailSubject

The subject of the mail sent

The Subject of the Email to be sent.

SMTP_MailBody

Message content

The message content to be sent.

SMTP_MailRecipient

Email of the recipient

The Email Address of the recipient

SMTP_Sending_Frequency

Time before sending new mail

The frequency of sending mail notification.
This value depends on the "Service Monitoring Frequency (seconds)" value in Admin Portal (ServiceMonitorFrequencySeconds setting).
For example, if ServiceMonitorFrequencySeconds is set to 60 seconds and SMTP_Sending_Frequency is set to 10 ,
the agent will send mail when issue detected and than additional mail every 10 min ( 60X10 = 600 sec = 10 min )

Email for Support

SupportEmailIssues

[Empty]/all/dbConnectionFailure/bastionDbConnectionFailure/restartFailure/restartSuccess

What issues will cause sending email

SupportSMTP_HostName

Hostname

The SMTP server to send the SMTP request to.

SupportSMTP_Port

Port number

The port to send the FTP request on.

SupportSMTP_AccountUserName

Email address of the sender account

The Email address is used to send the email and authenticate against the SMTP server.

SupportSMTP_AccountPassword

Password for the email account used for sending

The password of the Email Address.

SupportSMTP_RequiresSsl

False/True

Sends the Email via SSL.

SupportSMTP_RequireAuthentication

False/True

Whether to use signing in(depending on if the SMTP server requires authentication in order to send Emails through it.)

SupportSMTP_MailSubject

The subject of the mail sent

The Subject of the Email to be sent.

SupportSMTP_MailBody

Message content

The message content to be sent.

SupportSMTP_MailRecipient

Email of the recipient

The Email Address of the recipient

SupportSMTP_Sending_Frequency

Time before sending new mail

The frequency of sending mail notification.
This value depends on the "Service Monitoring Frequency (seconds)" value in Admin Portal (ServiceMonitorFrequencySeconds setting).
For example, if ServiceMonitorFrequencySeconds is set to 60 seconds and SMTP_Sending_Frequency is set to 10 ,
the agent will send mail when issue detected and than additional mail every 10 min ( 60X10 = 600 sec = 10 min )

Example of the configuration file: