Debugging - RIT-ITS/CertifiCat-PS GitHub Wiki
The CertifiCat-PS module, by design, includes a large amount of console output as part of the execution of each function. The goal is that, if a failure or issue should occur, it will be obvious to the administrator as to which step resulted in an issue. Depending on how the module is implemented, this output can be captured via the standard PowerShell transcript functionality (as is the case for the sample scripts in this repository).
Additionally, each function returns an object with several properties that can be used both for troubleshooting, and for further automation.
Using the steps on this page, the contents of these objects can also be logged to a file, or the Windows event log.
Debug logging can be enabled in one of two ways:
Debug logging can be enabled on a per-function or just-in time basis by using the following parameters on the desired function:
This switch must be present to cause the function in question to output the contents of the object to a file or event log
Type: Switch
Position: Named
Required: False
Specifies where the CertifiCat-PS debug logs are written, when the debugMode option is EVT or Both.
Type: String
Position: Named
Required: False
Controls where the CertifiCat-PS debug informaiton is written: EVT (the windows event log), File (a text file on disk), or Both (a text file on disk and the Windows Event Log)
Type: String
Position: Named
Required: False
Default Value: EVT
ValidateSet: EVT, File, Both
In lieu of adding parameters to an individual function, an administrator can enable global logging for all CertifiCat-PS functions by creating an environment variable called CERTIFICAT_DEBUG_ALWAYS.
The value of the environment does not matter -- the code simply checks for the presence of the variable, not for a specific value. The variable can also be created as either a User variable, or a System variable, depending on whether you want global logging for all users on the machine, or just a particular user.
When CertifiCat-PS is configured to log to the Windows Event Log (via the debugMode parameter value EVT or Both), it does so by writing to the application log in a dedicate log source (by default) of CertifiCat-PS. Further, a specific Event ID is used to indicate (a) the function that was logged, and (b) whether that function ran successfully or unsuccessfully.
Refer to the table below for a list of each function and the event IDs for a successful and unsuccessful run:
| Function | Successful ID | Unsuccessful Event ID |
|---|---|---|
| Assert-SiteCertificate | 1001 | 2001 |
| Confirm-ACMERenewalReadiness | 1002 | 2002 |
| Disable-ACMEProxyRedirect | 1003 | 2003 |
| Enable-ACMEProxyRedirect | 1004 | 2004 |
| Initialize-ACMEEnvironment | 1005 | 2005 |
| Initialize-ACMEProxyRedirect | 1006 | 2006 |
| Initialize-CertifiCatVariables | 1007 | 2007 |
| Initialize-ExistingACMECertificate | 1008 | 2008 |
| Initialize-NewACMECertificate | 1009 | 2009 |
| Repair-NewACMEOrder | 1010 | 2010 |
| Set-ACMEHome | 1011 | 2011 |
| Copy-CertifiCatSamples | 1012 | 2012 |
The following output shows the difference between the information that is output to console from one of the CertifiCat-PS functions, versus that which is captured in the debug logs.
Note that the contents of the debug logs are the same, regardless of whether they are send to the Windows Event Log, or a flat file.
Assert-SiteCertificate -hostToTest myserver.example.com -portToTest 443
=========================================
[Assert-SiteCertificate]
Checking Site Certificate
=========================================
-> Attempting to make an SSL connection to 'myserver.example.com' on port 443...ok
=========================================
[Assert-SiteCertificate]
Completed successfully!
=========================================
FunctionName : Assert-SiteCertificate
RunningPSVersion : 7.5.0
PS5Command : powershell.exe {import-module -Force; Assert-SiteCertificate -hostToTest
"myserver.example.com" -portToTest "443" }
FunctionArguments : -hostToTest "myserver.example.com -portToTest "443"
FunctionSuccess : True
Errors : {}
Certificate : [Subject]
CN=myserver.example.com, O=My Org, S=New York, C=US
[Issuer]
CN=InCommon RSA Server CA 2, O=Internet2, C=US
[Serial Number]
1234567890ABCDEFG1234567890
[Not Before]
3/10/2025 8:00:00 PM
[Not After]
6/9/2025 7:59:59 PM
[Thumbprint]
98765432109876543210
CertificateIssueDate : 3/10/2025 8:00:00 PM
CertificateExpirationDate : 6/9/2025 7:59:59 PM
CertificateThumbprint : 98765432109876543210
CertificateSerialNumber : 1234567890ABCDEFG1234567890
CertificatePublicKeyType : RSA
CertificatePublicKeyBits : 2048
HostTested : myserver.example.com
PortTested : 443
debugEnabled : True
debugLogDirectory : c:\its\logs\certificat-ps\debug
debugMode : EVT
[ CertifiCat-ps Debug Message ]
Function: Assert-SiteCertificate
Completed: 03/25/2025 13:40:28
Function Return Object:
-> Property 'Certificate' is of type 'System.Security.Cryptography.X509Certificates.X509Certificate2' and has value: [Subject]
CN=myserver.example.com, O=My Org, S=New York, C=US
[Issuer]
CN=InCommon RSA Server CA 2, O=Internet2, C=US
[Serial Number]
1234567890ABCDEFG1234567890
[Not Before]
3/10/2025 8:00:00 PM
[Not After]
6/9/2025 7:59:59 PM
[Thumbprint]
98765432109876543210
-> Property 'CertificateExpirationDate' is of type 'datetime' and has value: 06/09/2025 19:59:59
-> Property 'CertificateIssueDate' is of type 'datetime' and has value: 03/10/2025 20:00:00
-> Property 'CertificatePublicKeyBits' is of type 'int' and has value: 2048
-> Property 'CertificatePublicKeyType' is of type 'string' and has value: RSA
-> Property 'CertificateSerialNumber' is of type 'string' and has value: 1234567890ABCDEFG1234567890
-> Property 'CertificateThumbprint' is of type 'string' and has value: 98765432109876543210
-> Property 'debugEnabled' is of type 'switch' and has value: True
-> Property 'debugLogDirectory' is of type 'string' and has value: c:\its\logs\certificat-ps\debug
-> Property 'debugMode' is of type 'string' and has value: EVT
-> Property 'Errors' is an object whose contents are null
-> Property 'FunctionArguments' is of type 'string' and has value: -hostToTest "myserver.example.com" -portToTest "443"
-> Property 'FunctionName' is of type 'FunctionInfo' and has value: Assert-SiteCertificate
-> Property 'FunctionSuccess' is of type 'bool' and has value: True
-> Property 'HostTested' is of type 'string' and has value: myserver.example.com
-> Property 'PortTested' is of type 'int' and has value: 443
-> Property 'PS5Command' is of type 'string' and has value: powershell.exe {import-module -Force; Assert-SiteCertificate -hostToTest "myserver.example.com" -portToTest "443" }
-> Property 'RunningPSVersion' is of type 'string' and has value: 7.5.0
--------------------------------------------------------------