Enable CSAPI debug logging for Protection Engine on Windows Servers

Products

• Protection Engine for Cloud Services
• Protection for SharePoint Servers
• Protection Engine for NAS

Issue/Introduction

The following instructions provide steps for enabling or disabling CSAPI debug logging within a Windows and Linux environment for Symantec Protection Engine (SPE)

Resolution

Prior to SPE 9.0, to enable CSAPI debug logging, one has to set the CSAPI environment variables and restart SPE service so that the logging is enabled.

Process restart could be painful in certain cases based on the deployment scenario and complexity of the issue reproduction. Hence, In SPE 9.0 we have introduced a supportability feature to enable CSAPI debug logging at runtime without restart of the SPE service.

Following are the steps to enable it -

1. Create a file with name - logging.conf
2. Add the required parameters for enabling CSAPI logs in this file. All of these parameters have same name as is used for environment variable based logging.
3. Following is the format/syntax of the file - (I have attached sample logging.conf file to this article for reference)

[csapi-log-config]
CSAPI_DEBUG_LOG_ENABLE=<true/false>
CSAPI_DEBUG_LOG=<log file name>
CSAPI_DEBUG_LEVEL=<debug log level between 0-5>
CSAPI_DEBUG_SECTION=
CSAPI_DEBUG_FILE_SIZE_LIMIT=
CSAPI_DEBUG_MAX_LOG_FILES=

4. Copy this file to SPE installation directory. By default, "C:\Program Files\Symantec\Scan Engine" on Windows and "/opt/SYMCScan/bin" on Linux systems.

5. SPE looks for this file every 30 seconds and once the file is found the logging will be enabled if all settings are valid. On reading the file, SPE deletes the file, so make sure to have the backup file created for it.

Validations or pre-requisites -

CSAPI_DEBUG_LOG_ENABLE - Allowed values for this parameter is true or false. It is a mandatory parameter.
CSAPI_DEBUG_LOG - It should not be a empty value if the logging is enabled using above parameter. It is a mandatory parameter if logging is enabled. Make sure the directory path exists and SPE process has a write access on it.
CSAPI_DEBUG_LEVEL - Allowed values are 0 to 5, both inclusive. It is a mandatory parameter is logging is enabled. (0 - None, 1 - Fatal, 2 - Error, 3 - Warning, 4 - Notice, 5 - Verbose)
CSAPI_DEBUG_SECTION - Valid integer value. It is an optional parameter.
CSAPI_DEBUG_FILE_SIZE_LIMIT - Valid integer value. It is an optional parameter. Min is 0 and Max is 1GB, default is 1GB. This value is in bytes. (Eg. 500 MB will be given as 500x1024x1024 = 524288000)
CSAPI_DEBUG_MAX_LOG_FILES - Valid integer value. It is an optional parameter. Min is 3 files and Max is 20 files, default is 3 files.

All optional parameters are set to their respective default by CSAPI if not specified or specified outside of the allowed range.

Logging -
If something is wrong with any of above parameters like validation errors or error in loading/reading of the file, then SPE will log an error message accordingly in the logging destinations enabled.

What happens to existing environment variable based logging - If someone want to enable CSAPI debug logging using existing environment variable based way then, it is still supported and work fine. If someone does not want to use environment variable way then, there won't be any environment variables and logging can be enabled using above way of runtime enabling of the logs. In all cases run time logging would be having priority since it's set at run time.

 

For SPE below 9.0 versions:

Warning:  This process requires a reboot of the system for the changes to take effect.

NOTE: Due to the reboots required and the possible performance impact to SPE, CSAPI logging should only be enabled to trace through specific issues during a scheduled maintenance window. 

To Enable CSAPI Logging

1. To open the System Properties control panel, click Start > Run or Start > Search, or Windows key + R, or right click Windows Icon>Run then type: sysdm.cpl

2. On the Advanced tab, click the Environment Variables.button

3. On the Environment Variables page under System variables (and not User variables for Administrator), click on New... and add the following variables:

Variable Name	Value
CSAPI_DEBUG_LOG	C:\Program Files\Symantec\Scan Engine\log\csapi.log
CSAPI_DEBUG_LEVEL	5
CSAPI_DEBUG_FILE_SIZE_LIMIT	104857600
CSAPI_DEBUG_MAX_LOG_FILES	1

    
4.  Click OK to save changes and exit the Environment Variables page.

5. Click OK to exit the System Properties control panel

6. Restart/Reboot the server to make these Environment Variables effective.. 

 

 

To Disable CSAPI Logging

To disable CSAPI logging remove the created system variables specified in the Enable section then perform a restart/reboot of the server.

1. To open the System Properties control panel, click Start > Run or Start > Search, then type: sysdm.cpl

2. On the Advanced tab, click the Environment Variables.button

3. On the Environment Variables page under System variables, click CSAPI_DEBUG_LOG, then click Delete.

4. Click CSAPI_DEBUG_LEVEL, then click Delete.

5. Click CSAPI_DEBUG_FILE_SIZE_LIMIT, then click Delete.

6. Click OK to save changes and exit Environment Variables.

7. Click OK to exit System Properties control panel.

8. Restart the operating system to make Environment Variables effective.

 

NOTE: Due to the reboots required and the possible performance impact to SPE, CSAPI logging should only be enabled to trace through specific issues during a scheduled maintenance window. 

 

 

The steps below are only if you are doing it from a command prompt

To enable CSAPI logging from a command prompt:

Make a backup of the registry first.

From elevated command prompt.
setx CSAPI_DEBUG_LOG "C:\Program Files\Symantec\Scan Engine\log\csapi.log" -M
setx CSAPI_DEBUG_LEVEL "5" -M
setx CSAPI_DEBUG_FILE_SIZE_LIMIT "104857600" -M
setx CSAPI_DEBUG_MAX_LOG_FILES "1" -M

Restart the operating system.

 

To disable CSAPI logging from a command prompt:

From elevated command prompt.

REG delete “HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment” /F /V “CSAPI_DEBUG_LOG” 
REG delete “HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment” /F /V “CSAPI_DEBUG_LEVEL”
REG delete “HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment” /F /V “CSAPI_DEBUG_FILE_SIZE_LIMIT”
REG delete “HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment” /F /V “CSAPI_DEBUG_MAX_LOG_FILES”

Restart the operating system.

Note:  System variables are written to the following registry location:  HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment

Additional Information

CSAPI_DEBUG_LOG is an admin specified location.  Ensure the specified location has adequate diskspace to store the log file.

If CSAPI_DEBUG_FILE_SIZE_LIMIT variable is not specified, there is no upper limit to the log size. A Csapi.log of 100 MB (104857600 bytes) is created with the above settings. The Csapi.log will be overwritten when the maximum size is reached. The log size can be modified by changing the value of the CSAPI_DEBUG_FILE_SIZE_LIMIT.  It is not recommended to change the default log size of 100 MB unless requested by a Support Engineer.

If CSAPI_DEBUG_LOG is pointed at a location that does not exist or has no remaining free space, no log file will be created.

CSAPI_DEBUG_MAX_LOG_FILES can be increased up to 20 if necessary. This will cause CSAPI to create up to 20 log files of your specified size limit before rolling logs.