Updated to agent 1.5.1
SphereShield Agent is a Windows Service to monitor other AGAT service and restart it if needed.
Monitored service can be:
Sip Filter (AgatSipFilter)
Bastion (for LAC, Teams Protector, Webex Protector filters)
Authentication Extender
Casb Adapter (AgatSphereShieldCasbAdapter)
Content Manager (AgatContentManagerService)
Monitoring operation consists of three main parts:
...
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:
Checking if monitored service is running and start it if not
Checking in DB if monitored service is alive using Service Management mechanism
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.
Info |
---|
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:
[DB mode] Write agent alive time in service management table for monitored service row
Check if the monitored service is running and start it if not
...
[DB mode] Check if monitored service is alive
...
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.
Service name: AgatSphereShieldServiceAgent[CustomerName]
Service display name: AGAT SphereShield Service Agent [Customer Name]
The agent is installed and configured by the installer.
To install the service manually (run as administrator):
Code Block |
---|
> AgatSphereShieldServiceAgent.exe install
|
To uninstall the service (run as administrator):
Code Block |
---|
> AgatSphereShieldServiceAgent.exe remove |
Configuration
There is an AgatSphereShieldServiceAgent.config file with configuration for the agent. The agent writes to a log file (default at C:\Agat\Logs\ServiceAgent\[CustomerName]) and to Event Log with source "AGAT SphereShield Service Agent".
Example of the configuration file:
...
language | xml |
---|
...
in the service management table
[Bastion] Check if Bastion and filters are OK:
Bastion health check procedure:
Forwarding proxy:
Request https://[BastionHealthcheckHost]/healthcheck with proxy BastionIP
for example https://test.skypeshield.com/teams_protection/healthcheck with proxy 127.0.0.1
Reverse proxy:
Request https://[BastionIp]/skypeshieldhealth with host header BastionHealthcheckHost
for example https://127.0.0.1/skypeshieldhealth with host header test.skypeshield.comIf received HTTP 200 status code (during response time of BastionMaxHealthcheckLatencyMilliseconds if set not to 0) - Bastion and filters are OK (no restart is done)
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.
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
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
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.
If alive check or bastion healthcheck not passed - restart the monitored service
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: /wiki/spaces/SKYP/pages/1126367233
Installation
The agent is installed and configured by the installer.
To install the service manually (run as administrator):
Code Block |
---|
> 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:
Code Block |
---|
> 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.
|
Info |
---|
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 |
---|---|---|
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 |
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. |
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. |
Example of the configuration file:
Expand | |||||
---|---|---|---|---|---|
| |||||
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
Logging
CustomerName - Can install multiple agents for different customers on the same machine and customer name should be different for each one.
LogFileFullName - The path to the agent logs. Need to replace AGAT with customer name. If installed with installer it does the work.
LogFileMaxSize - Defines the maximum size of the log file before the agent will clear out and create a new log.
LogFileLevel - The severity level of the logs generated by the agent. Possible values: off, fatal, error, warn, debug, info, all, alert, critical
EventLogLevel - The severity of the logs sent to the event viewer.
DB Connection
DBRequired - Agent can work without DB. This mode does not support portal UI operation - service management operation for remote restart and is designed mainly for Authentication Extender monitoring. To work without DB set DBRequired to false.
ConnectionString - Is needed when DBRequired is set to true. Need to replace values of SQLSERVER, DataBaseName, username, password.
Key/IV - AES encryption keys needed when DBRequired is set to true.
Monitored service
ServiceName - name of the service that agent will monitor. Possible values: AgatSipFilter, Bastion, AgatSphereShieldCasbAdapter[CustomerName], AgatContentManagerService
ServiceRestartTimeoutSeconds - How long should agent wait for restart to complete. If does not manage to start, agent will create event in the event log for manual operation to be done.
ServiceMonitorFrequencySeconds - Define how often will the monitoring happens (in seconds).
Note: Restart will occur only after ServiceMonitorNumberOfAttemptsBeforeRestart consecutive failures. Therefore cycle time should be configured accordingly.
If ConnectionString is set, this setting will be ignored as the relevant value will be read from DB.ServiceMonitorNumberOfAttemptsBeforeRestart - Number of checks before service restart.
If ConnectionString is set, this setting will be ignored as the relevant value will be read from DB.
Ethical Wall load - SIP Filter only
MonitorEthicalWallLoad - Ethical Wall load monitoring - relevant for SIP Filter only
MonitorEthicalWallLoadFrequencyMinutes - Define how often will the Ethical Wall load monitoring happen
Bastion healthcheck - Bastion only
BastionForwardProxy - Set to true if Bastion is running as Forward proxy, false if Bastion is running as Reverse proxy.
BastionIp - Bastion IP for the healthcheck request. If the Agent is installed on the Bastion use localhost address. Make sure to use a port which the Bastion listens to (and is used by the required channel).
Note: Default port is 443 for Reverse Proxy and 80 for Forward Proxy.
If a port other than the default is used, please add :<portnumber> to the end of the IP.BastionHealthcheckHost - The host to whom the health check request will be sent to.
BastionMaxHealthcheckLatencyMilliseconds - maximum latency for the health check response. Set 0 to disable latency check.
Bastion & LAC Filter troubleshooting
TroubleshootingOutputFolder - Folder for output of troubleshooting procedure, will include archive of log files.
TroubleshootingSplitIntoVolumes - Set to true to split troubleshooting archive into volumes, useful for email attachments
TroubleshootingSplitVolumeSize - Size of troubleshooting archive split volume in MB.
TroubleshootingDaysRange - Number of last days to include in troubleshooting archive.
Email notifications to admin
Settings for admin notification when the agent detects an issue.
EmailIssues - for which type of issues should an email be sent. you can set the following values: all, dbConnectionFailure, bastionDbConnectionFailure, restartFailure, restartSuccess.
Multiple values may be configured by comma, may be left empty to disable emailing at all.
Note that for any value except empty - SMTP should be configured in DB for DB mode or in the following settings.
If ConnectionString is set, no need to set the following SMTP configuration settings as they are read from DB.
SMTP Hostname: SMTP server Address.
SMTP Port: the port the SMTP server is listening on.
SMTP Account Name: Sender Address for the Agent.
SMTP Account Password: If SMTP requires authentication, this is the password for the sender account.
SMTP Requires SSL: Change to True if the SMTP server requires TLS/SSL.
SMTP Requires Authentication: Change to True if the SMTP server requires authentication
SMTP Mail Recipient: Administrator e-mail to receive notifications from the agent, can be multiple emails separated by , or ;
SMTP_Sending_Frequency - The frequency in which a mail notification will be sent.
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 notifications to support
Settings for support notification when the agent detects an issue.
SupportEmailIssues - for which type of issues should an email be sent. you can set the following values: all, dbConnectionFailure, bastionDbConnectionFailure, restartFailure, restartSuccess.
Multiple values may be configured by comma, may be left empty to disable emailing at all.
Note that for any value except empty - SMTP should be configured in the following settings.
SMTP settings for support team notification are the same as SMTP settings for admin, starting with Support prefix. Note that these settings are set only in config file and not in DB.
Monitoring Processing
The agent runs the monitoring each defined number of seconds (default 60) and does the following:
[DB mode] write agent alive time in service management table for monitored service row
check if monitored service is running and start it if not
[DB mode] check if monitored service is alive in service management table
[Bastion] check if Bastion and filters are OK:
Bastion healthcheck procedure:
for forward proxy:
request https://[BastionHealthcheckHost]/healthcheck with proxy BastionIP
for example https://test.skypeshield.com/teams_protection/healthcheck with proxy 127.0.0.1for reverse proxy:
request https://[BastionIp]/skypeshieldhealth with host header BastionHealthcheckHost
for example https://127.0.0.1/skypeshieldhealth with host header test.skypeshield.comif received HTTP 200 status code (during response time of BastionMaxHealthcheckLatencyMilliseconds if set not to 0) - Bastion and filters are OK (no restart is done)
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.
if healthcheck result not OK and the agent is in production mode (received 5 sequence OK results) - consider healthcheck as not passed
otherwise if healthcheck result is OK or the agent not in production mode (not received 5 sequence OK results) - consider healthcheck as passed
the agent will go into production mode (restart on error) only after receiving good result for 5 times indicating the correct operation to avoid misconfiguration in install.
If alive check or bastion healthcheck not passed - restart the monitored service
If failed to start the service X (X = ServiceMonitorNumberOfAttemptsBeforeRestart) times - kill the monitored service
Service Management Processing
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 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
...
|