How To: Enable or Disable Debug Logging on an On-Premises Appliance

Version Affected: All

 

Overview

This article explains how to enable or disable debug logging on an on-premises appliance, to assist with troubleshooting.

There are two methods, depending on what needs debug logging:

• Enabling or disabling audit, debug, error, or Syslog logging on one or more realms.
• Configuring Filebeat logging, including enabling debug logging.
   

In this article

• Method 1: Enable Logging on Realms Using Set-SALogging
• Method 2: Configure Filebeat Logging

Method 1: Enable Logging on Realms Using Set-SALogging

Use this method to enable or disable audit, debug, error, or Syslog logging on one realm, several realms, or all realms at once, without changing any other settings.

1. Download the Set-SALogging script from this link, to any folder on the IdP where you have write permission.
2. After downloading, right-click the script, click Properties, then Unblock (if present).
3. The script can be run from any folder on the IdP. For help on usage and examples, run:
   

   Set-SALogging -help

The tool can be run in two modes:

• Interactive: run without supplying parameters, and the tool asks which realms to update — all realms, or a list of realms separated by commas or spaces. It then offers Enabling, Disabling, or No Change for text Audit, Debug, and Error logs, as well as Syslog. Only valid existing realms are processed, and only those requiring a change are modified.
• Non-interactive: does the same, taking input from command-line parameters without prompting for additional input. Non-interactive mode is triggered by supplying any of:

  -Silent
  -BeatsLoggingEnabled
  -AuditLoggingEnabled
  -DebugLoggingEnabled
  -ErrorLoggingEnabled
  -SysLogEnabled
  -SysLogHost
  -SysLogPort
  -SysLogRFC
  -SysLogPEN
  -RealmNumbers

In both modes, the tool logs to the same folder as the executable, and creates a RollBack folder there containing batch files that revert the web.configs to their prior state. If needed, run these batch files elevated as Administrator to bypass UAC.

Syntax:

Set-SALogging [-Silent] [-SkipDecryption] [-IgnoreEncryption] [-WebconfigFolder <String>]
[-BeatsLoggingEnabled] [-AuditLoggingEnabled] [-DebugLoggingEnabled]
[-ErrorLoggingEnabled] [-SysLogEnabled] [-SysLogHost <String>] [-SysLogPort <UInt16>]
[-SysLogRFC <Object>] [-SysLogPEN <UInt16>] [-RealmNumbers <Int32[]>] [<CommonParameters>]

Examples:

# Run Set-SALogging fully interactively
Set-SALogging

# Enable audit text logging on all realms, suppressing prompts for input and any output
Set-SALogging -Silent -AuditLoggingEnabled $true

# Run interactively but skip the decryption and encryption phase (requires all web.configs to already be decrypted)
Set-SALogging -SkipDecryption

# Run non-interactively for the realms provided, skip decryption and encryption, and try to process web.config files that may still have encrypted sections
Set-SALogging -SkipDecryption -IgnoreEncryption -RealmNumbers 1,2,3,5,7,11,13,17

# Run non-interactively against all realms, enable Syslog and set Syslog options
Set-SALogging -SysLogEnabled $true -SysLogHost '10.10.10.10' -SysLogPort 1514 -SysLogRFC 'RFC5424' -SysLogPEN 46952

Method 2: Configure Filebeat Logging

Use this method to troubleshoot issues with the SecureAuth Filebeat service specifically.

1. Stop the SecureAuth Filebeat service in the services.msc console.
2. In the Filebeat configuration file, uncomment the line starting logging.level: debug:
   

   C:\Program Files\SecureAuth Corporation\FileBeat\filebeat.yml

When removing the "#" character, do not leave a leading space on the line — a leading space prevents the Filebeat service from starting.

3. Start the Filebeat service.

Filebeat logging is enabled by default and writes to %ProgramData%\SecureAuth Corporation\Filebeat\Logs. Log files are named filebeat with no file extension, and can be opened in any text editor.

Log files rotate whenever the Filebeat service restarts, or whenever the current log file reaches 10 MB. Up to 7 log files are kept on disk by default — once that limit is reached, the oldest log file is deleted each time a new one is created.

The following settings, placed in filebeat.yml under its ==== Logging ===== section, control this behavior:

• logging.to_eventlog — send Filebeat logs to the Windows Application Event Log (accepted values true/false, default false).
• logging.files.path — where to write log files (default %ProgramData%\SecureAuth Corporationilebeat\logs).
• logging.to_files — send Filebeat logs to file (accepted values true/false, default true).
• logging.level — sets the logging level (accepted values info/warning/error/debug, default info).
• logging.files.name — name for the log file (default filebeat).
• logging.files.rotateeverybytes — rotate the log based on file size (default 10 MB, or 10485760 bytes).
• logging.files.keepfiles — how many log files to keep on disk (accepted range 2–1024, default 7).
• logging.files.rotateonstartup — rotate log files whenever the service starts (accepted values true/false, default true).
• logging.selectors — at debug level, selectively enable logging only for specific components instead of all of them; use ["*"] to enable every selector.

Any setting left out of filebeat.yml uses its default value.

See Elastic's own Filebeat logging configuration reference for more detail — some settings may not apply to older Filebeat versions.

Special Considerations

Always back up filebeat.yml before changing any of these settings. If the file is edited incorrectly, the Filebeat service will not be able to read it and will fail to start.


 

SecureAuth Knowledge Base Articles provide information based on specific use cases and may not apply to all appliances or configurations. Be advised that these instructions could cause harm to the environment if not followed correctly or if they do not apply to the current use case.

Customers are responsible for their own due diligence prior to utilizing this information and agree that SecureAuth is not liable for any issues caused by misconfiguration directly or indirectly related to SecureAuth products.