Table of Contents |
---|
Introduction
One of logs written by Ubisecure SSO is the diag log. Diag logs are divided into multiple types and contain diagnostic information about configuration, initialization or some runtime events. The logs are written to files that are usually named according to the convention uas_diag3.[data].log (where [date] is formatted as YYYY-MM-DD). Log file names may be altered by configuration settings.
General format
The log consists of fields separated by spaces. Each line represents one log entry and starts with a timestamp in ISO 8601 format. The next value represents the type of log entry. The last field is the message.
General log entry format:
...
There are currently thirteen possible log entry types: init, environment, protocol, login, method, mapper, acl, authz, ui, session, identity, inboundmapping and tech.
Each of these will be detailed with example content for each field in the listing below.
Init
An init entry entry is generated during system startup and initialization. Contains information about initialized components, crucial parameters, possible warnings and errors.
Logger: diag.init
Example:
...
Table of Contents |
---|
Introduction
All Ubisecure SSO applications deployed to SSO Tomcat print diagnostic information to the shared SSO diagnostic log. In the default installation the file is named sso_diag.YYYY-MM-DD.log
and it resides in the ubilogin/logs
folder.
See Understanding SSO logger configuration about the technical details.
General format
Each line in the diagnostic log file represents one log entry with a set of fields separated by a space.
General log entry format:
Timestamp | Context | Type | Level | Message |
---|---|---|---|---|
2022-09-19 10:15:45,398 | uas | init | INFO | TicketProtocolSAML2: started |
2022-09-19 10:15:24,255 | search | com.ubisecure.ubilogin.uwa.UbiloginFilter | INFO | Ubilogin Web Agent started (urn:uuid:7dfbab8e-aae0-4f64-b139-687400089ecd netmask=disabled) |
2022-09-30 06:42:00,086 | sso-api | com.globalsign.iam.sso.api.resource.node.directory.AbstractDirectoryObjectLeaf | INFO | 10.0.2.2 cn=Administrator,ou=System,cn=Ubilogin,dc=localhost PUT /site/testing-site |
Each log entry starts with a timestamp in the following format: YYYY-MM-DD hh:mm:ss,SSS.
The next field contains the name of the application printing the events the first field after the timestamp. The application name is the same as the webapp folder in the installation:
uas
ubilogin
logviewer
search
sso-api
totp
password
password-reset
cdc
otpserver
The type of log entry is either one of the predefined Entry type or a fully qualified class name.The predefined Entry types are especially in use by the SSO Authentication server (uas
) and are explained later in this document.
Log level is one of the well-known logging levels: TRACE
, DEBUG
, INFO
, WARN
, or ERROR
. The default levels to log are: INFO
, WARN
and ERROR
. You may configure the desired level to log based on the type of the log entry. How to modify the log levels is described in the end of this document.
The last field is the log message. In case of SSO API (sso-api
) the log message is preceded by two additional fields: IP address and the authenticated user name (sub).
In case of an exception the log entry is followed by the exception stack trace only if DEBUG
level is set for the type of this log entry. This rule applies only to the Ubisecure developed code and is meant for preserving disk space.
Entry types
There are currently thirteen possible log entry types: init
, environment
, protocol
, login
, method
, mapper
, acl
, authz
, ui
, session
, identity
, inboundmapping
and tech
.
Each of these will be detailed with example content for each field in the listing below.
Init
An init entry is generated during system startup, initialization, and stopping. Contains information about initialized components, crucial parameters, possible warnings and errors.
Logger: diag.init
Examples:
2022-10-03 07:05:48,929 ubilogin init INFO Ubilogin Server Management 9.1.0 started |
Environment
This type of entry is also generated on startup and contains information related to the runtime environment and configuration. Data may be written in many rows and the structure of the data is indicated by the row indentation.
Logger: diag.init.environment
Example:
20212022-0810-0306 1607:3829:5219,241097 uas environment INFO Java Cryptography Extension (JCE) Unlimited Strength Providerinstalled: SunJGSSYes |
Protocol
Protocol entries are generated for diagnostics of protocols, usually connected with runtime errors.
For some exceptions of type TicketProtocolException
and its subtypes, such as TicketProtocolOAuth2Exception
and TicketProtocolSAML2Exception
, the issuer of the request (which is the client_id or entityId of the application) is shown in square brackets.
Logger: diag.protocol
Example:
2021 |
Login
The login entry is generated at runtime to diagnose ubilogin SSO authentication mapping issues. Happy-case entries are seen only if DEBUG level is specified for this type.
Logger: diag.login
Example:
20212022-0810-0306 1607:3829:5319,619097 uas login DEBUG Locator.findUbiloginAuthMapping(testlogin): (&(objectClass=ubiloginAuthMethod)(cn={0})(ubiloginAuthMapping={1})): names.size()=1 |
...
This type of entry is used for runtime diagnostic of runtime errors of authentication authentication methods.
Logger: diag.method
Example:
20212022-0610-1607 0108:4304:2628,253694 uas method com.ubisecure.ubilogin.sso. INFO ubilogin.authorizer.MethodMenuFilterMethodPolicyFilter:UbiloginAgent[cnCN=CustomerID APIUbilogin,ouOU=eIDM ServicesSystem,cnCN=Ubilogin,dcDC=examplelocalhost]:[MethodStatus[password.21,true]] |
Mapper
Mapper entries are used when mapping users to groups. They are created for runtime diagnostic.
Logger: diag.mapper
Example:
20212022-0610-1607 0108:4304:2635,258467 uas mapper INFO ubilogin.mapper.RegisteredMapper:Identity[UBILOGIN&password.21&<saml:NameID xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName" NameQualifier="ldap:///cn=Ubilogin,dc=examplelocalhost">cn=d3857c0f-bf12-4de8-80cd-60ab2abaeeb3,ou=Users,ou=eIDM Users,cn=Ubilogin,dc=example<>CN=Administrator,OU=System,CN=Ubilogin,DC=localhost</saml:NameID>]:[UbiloginGroup[cnCN=eIDMUserAccounting Users,ouOU=eIDMAccounting,ouOU=eIDM UsersSystem,cnCN=Ubilogin,dcDC=examplelocalhost], UbiloginGroup[cn=PasswordAuthenticated Users,ou=Password,ou=System,cn=Ubilogin,dc=examplelocalhost], UbiloginGroup[cnCN=CustomerID APIPassword Users,ouOU=eIDM Services,cn=Ubilogin,dc=example], UbiloginGroup[cn=Authenticated Users,ou=System,cnPassword,OU=System,CN=Ubilogin,dcDC=examplelocalhost], UbiloginGroup[cnCN=eIDMUserAdministrators,ouOU=eIDM GroupsSystem,cnCN=Ubilogin,dcDC=examplelocalhost]] |
Acl
Another type of runtime diagnostic entry is access control, named acl.
Logger: diag.acl
Example:
20212022-0610-1607 0108:4304:3135,799471 uas acl INFO ubilogin.authorizer.saml2.SubjectAccessUbiloginAccessControl:Identity[UBILOGIN&password.21&<saml:NameID xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName" NameQualifier="ldap:///cn=Ubilogin,dc=examplelocalhost">cn=d3857c0f-bf12-4de8-80cd-60ab2abaeeb3,ou=Users,ou=eIDM Users,cn=Ubilogin,dc=example<>CN=Administrator,OU=System,CN=Ubilogin,DC=localhost</saml:NameID>]:true |
Authz
Auths entries are related to authorization diagnostic and are created at runtime.
Logger: diag.authz
Example:
20212022-0610-1607 0108:4304:3135,800471 uas authz INFO ubilogin.authorizer.UsernameAuthorizer:Identity[UBILOGIN&password.21&<saml:NameID xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName" NameQualifier="ldap:///cn=Ubilogin,dc=examplelocalhost">cn=d3857c0f-bf12-4de8-80cd-60ab2abaeeb3,ou=Users,ou=eIDM Users,cn=Ubilogin,dc=example<>CN=Administrator,OU=System,CN=Ubilogin,DC=localhost</saml:NameID>]:urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName:password.21.grant_typedn=passwordCN%3DAdministrator%2COU%3DSystem%2CCN%3DUbilogin%2CDC%3Dlocalhost&password.2.dn=cn%3Dd3857c0f-bf12-4de8-80cd-60ab2abaeeb3%2Cou%3DUsers%2Cou%3DeIDM+Users%2Ccn%3DUbilogin%2Cdc%3Dexample&password.2.ldap=ldap%3A%2F%2F%2Fcn%3DUbilogin%2Cdc%3Dexample |
UI
...
1.ldap=ldap%3A%2F%2F%2Fcn%3DUbilogin%2Cdc%3Dlocalhost&username=CN%3DAdministrator%2COU%3DSystem%2CCN%3DUbilogin%2CDC%3Dlocalhost |
UI
These entries are used for runtime diagnostic of user interface issues. Created at runtime. Happy-case entries are seen only if DEBUG level is specified for this type.
Logger: diag.ui
20212022-0610-1607 0308:1204:3335,876471 uas ui WARN unmarshalJSON: protocol.oauth2.TicketProtocolOAuth2Exception: The requested application is invalid: javax.json.stream.JsonParsingException: Unexpected char 60 at (line no=1, column no=1, offset=0) |
...
Session entries are generated for diagnostics of session handling, usually connected with runtime errors. Happy-case entries are seen only if DEBUG level is specified for this type.
Logger: diag.session
Example:
20212022-0810-0507 1108:04:2835,021589 uas session DEBUG SessionStoreGC.gc(1628168668021) |
...
This type of entry is used for runtime diagnostic of runtime errors on identity creation and encoding.
Logger: diag.identity
Example:
20212022-0610-1603 0314:1922:3632,992913 uas identity INFO X509IdentityFactory.createIdentities(): Identity[UBILOGIN&password.2&<saml:NameID xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Format="urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName" NameQualifier="ldap:///cn=Ubilogin,dc=examplelocalhost">cn>CN=d3857c0f1445dd95-bf12d685-4de84d9b-80cda7ce-60ab2abaeeb382f111545810,ouOU=Users,ouOU=eIDM Users,cnCN=Ubilogin,dcDC=example<localhost</saml:NameID>] |
Inboundmapping
Separate This specific type of entries is inboundmapping. It's used for diagnostics of attributes mapping.
Logger: diag.inboundmapping
Example:
20212022-0810-07 09 14:2804:0835,340232 uas inboundmapping WARN InboundMappingTable: ubiloginAttributeName: cn=1,cn=imt.soso.1,cn=Server,ou=System,cn=Ubilogin,dc=test |
...
Tech entries are used for miscellaneous diagnostics messages.
Logger: tech
Example:
20212022-06-16 00:27:12,111 tech ping: the system is alive 2021-06-16 00:27:17,718 tech JLDAP: 10-03 07:05:57,023 uas tech INFO JLDAP: url=ldap://ubilogin-directory localhost/cn=Ubilogin,dc=example localhost,servers=[ldap://ubilogin-directory localhost/cn=Ubilogin,dc=example localhost],tls=false,confConnectTimeout=15000,confReadTimeout=15000,confMaxAge=120000,confAuthPool=8,failoverType=multi-master |
Configuration
The Diag log may be configured either via configuration file (logback.xml replacing log4j.properties since SSO 9.1) or via SSO UI.
Configuring via logback.xml file (SSO >= 9.1)
The logback.xml file is located in ubilogin customization directory (ubilogin-sso/ubilogin/custom/logging/logback.xml) and contains the configuration of all SSO logging. Learn about Logback configuration file syntax.
The defaults for diag log entry type based logging is configured in these lines:
Code Block |
---|
<turboFilter class="com.ubisecure.common.logging.MarkerBasedLogFilter">
<DefaultLevels>audit=info;tech=info;diag.*=info</DefaultLevels>
</turboFilter> |
The syntax for DefaultLevels
is the following:
- the delimiter for individual entry type settings is semicolon (;)
- the entry type key is one among these listed in section Entry Types in lowercase (
diag.init
,diag.init.environment
,tech
, etc.);diag.*
can be used to specify all entry types starting withdiag
- the case.insensitive default level is one of these:
trace
,debug
,info
,warn
,error
,off
and is specified after equal sign (=), e.g.tech=info
- the default level if not specified is
off
There are custom patterns that have been defined for diag console and file logging:
Code Block |
---|
<conversionRule conversionWord="diagex" converterClass="com.ubisecure.common.logging.LogExceptionConverter" />
<conversionRule conversionWord="diagmarker" converterClass="com.ubisecure.common.logging.MarkerConverter" />
<property name="CONSOLE_LOG_PATTERN"
value="%d{'yyyy-MM-dd HH:mm:ss,SSS'} %diagmarker %level %msg %diagex%nopex%n" />
<property name="FILE_LOG_PATTERN"
value="%d{'yyyy-MM-dd HH:mm:ss,SSS'} %diagmarker %msg %diagex%nopex%n" /> |
LogExceptionConverte
r (diagex
) controls when stack trace is printed to the log and MarkerConverter
(diagmarker
) prints either the entry type or the Java class name based logger category.
The diag log file name and the rotation of it is defined by this block:
Code Block |
---|
<property name="LOG_FOLDER" value="@logs.dir.esc@" />
<property name="UAS_LOG_FILE" value="${LOG_FOLDER}/uas3" />
...
<appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
<filter class="ch.qos.logback.core.filter.EvaluatorFilter">
...
</filter>
<encoder>
<pattern>${FILE_LOG_PATTERN}</pattern>
</encoder>
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
<fileNamePattern>${UAS_LOG_FILE}_diag.%d{yyyy-MM-dd}.log</fileNamePattern>
...
</rollingPolicy>
</appender> |
You can also define the log level of any of the SSO or 3rd party libraries based on their category:
Code Block |
---|
<logger name="servlet.LogLevelUpdater" level="DEBUG" />
<logger name="org.apache.activemq" level="INFO" /> |
To change any of these settings you need to manually apply the same changes on all nodes. A restart of Tomcat may also be required. It depends if you define scan="true"
and scanPeriod
in your logback.xml file.
Configuring via log4j.properties file (SSO <= 9.0)
The log4j.properties file is located in web application directory for the UAS module (tomcat/webapps/uas/WEB-INF/log4j.properties) and contains the configuration of all logs for the UAS. By convention the lines responsible for the diag log are set as follows:
log4j.logger.ubilogin.tech = INFO, Diag, C
log4j.logger.ubilogin.diag = INFO, Diag
log4j.logger.ubilogin.diag.init = INFO, C
log4j.appender.Diag = com.ubisecure.log4j.DailyFileAppender
log4j.appender.Diag.File = @logs.dir.esc@/uas3_diag
log4j.appender.Diag.layout = org.apache.log4j.PatternLayout
log4j.appender.Diag.layout.ConversionPattern = %d{ISO8601} %c{1} %m%n
The upper lines are responsible for setting the logging level and assigning logger types to the Diag log. The lower lines define the naming and layout of the files.
These changes are stored locally on each node. To change these settings you need to manually apply the same changes on all nodes, a restart of Tomcat may also be required.
Configuring via UI
...
|
Logger configuration
The default logger configuration is detailly explained in Understanding SSO logger configuration.
We don't recommend modifications to the default Diagnostic log configuration except tuning the log levels especially when troubleshooting issues.
Configuring log levels for predefined Entry types
The Diagnostic log levels for predefined may be configured either via SSO Management UI or via the configuration file.
Configuring via SSO Management UI
Configuring via SSO Management UI Logging tab is the recommended way as no server restart is required and in a clustered environment the change applies to both nodes.
See Management UI logging configuration for guidelines.
Configuring with Logback configuration files
It is also possible to override the default levels for the Entry types in the logger configuration file which resides in the following location in the default installation:
Windows:
Code Block | ||
---|---|---|
| ||
C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\custom\logging\include-logback.xml |
Linux:
Code Block | ||
---|---|---|
| ||
/usr/local/ubisecure/ubilogin-sso/ubilogin/custom/logging/include-logback.xml |
To change the default levels please modify the DefaultLevels
value in this section:
Code Block |
---|
<!-- (1) Default levels for Diagnostic logs entry types -->
<turboFilter class="com.ubisecure.common.logging.MarkerBasedLogFilter">
<DefaultLevels>audit=info;tech=debug;diag.*=info;diag.init.environment=warn</DefaultLevels>
</turboFilter> |
The syntax for DefaultLevels
is the following:
- the delimiter for individual entry type settings is semicolon (;)
- the entry type key is one among these listed in section Entry Types in lowercase (
diag.init
,diag.init.environment
,tech
, etc.);diag.*
can be used to specify all entry types starting withdiag
- the case.insensitive default level is one of these:
trace
,debug
,info
,warn
,error
,off
and is specified after equal sign (=), e.g.tech=info
- the default level if not specified is
off
Configuring log levels for arbitrary classes
The log levels for arbitrary classes may be configured only via configuration file include-logback.xml
.
You can specify package name, part of the package name, or a fully qualified class name. You can also define the log level of any of the SSO or 3rd party libraries.
Please add your definitions to the following section in the configuration file:
Code Block |
---|
<!-- (10) Customise log levels -->
<!-- Some examples -->
<logger name="com.ubisecure.saml2" level="DEBUG" />
<logger name="com.ubisecure.saml2.metadata.URLMetadataLocator" level="INFO" />
<logger name="org.apache.activemq" level="WARN" /> |