Some hints and tips to help your problem determination
Common Error Messages
Error Message
Possible Reason
RunJava: Can't find class JAddIn
lotus/notes/addins/jaddin/Squirrel in the classpath. Class names are case-sensitive.
The RunJava task was unable to load the class. Make sure that it is written with exact upper and lower case characters and it can be found by the RunJava class loader
JAddin: Unable to load Java class Squirrel
The JAddin framework was unable to load Squirrel.jar. Make sure that it is written with exact upper and lower case characters.
RunJava: Can't find stopAddin method for class Squirrel.
The Squirrel class must be loaded thru the JAddin framework and not directly from RunJava. Use the command Load RunJava JAddin Squirrel to start Squirrel.
The user class name in the command and the internal name do not match. Most likely you have not typed the name with correct upper and lower case characters.
Out of memory
All Java add-ins execute in a single Java Virtual Machine (JVM) in RunJava. The Domino Notes.Ini parameter JavaMaxHeapSize=xxxxMB may be used to increase the heap space
User is authenticated but not connected
This is a know temporary error in Microsoft Exchange.
Connection Problems
Basic Connection Test
If Squirrel is unable to connect to the Internet mail server, check if a direct connection from the HCL Domino server to the specified Internet mail server is possible. This can be done with Telnet or NetCat (nc).
> nc -v imap.gmail.com 993
Connection to imap.gmail.com port 993 [tcp/imaps] succeeded!
Starting with version 1.6.5, Squirrel performs a basic connection test to the configured mail server before processing messages. Any error found during this test is written to the HCL Domino console (and in log.nsf). The correponding subscription document is not disabled as connection errors are often temporary.
TLS Connection Test
To check which TLS certificate the Internet mail server is using, you may issue the openssl command:
> openssl s_client -connect imap.gmail.com:993
CONNECTED(00000006)
depth=2 OU = GlobalSign Root CA - R2, O = GlobalSign, CN = GlobalSign
verify return:1
depth=1 C = US, O = Google Trust Services, CN = Google Internet Authority G3
verify return:1
depth=0 C = US, ST = California, L = Mountain View, O = Google LLC, CN = imap.gmail.com
verify return:1
---
Certificate chain
0 s:/C=US/ST=California/L=Mountain View/O=Google LLC/CN=imap.gmail.com
i:/C=US/O=Google Trust Services/CN=Google Internet Authority G3
1 s:/C=US/O=Google Trust Services/CN=Google Internet Authority G3
i:/OU=GlobalSign Root CA - R2/O=GlobalSign/CN=GlobalSign
...
Secure connections are supported by using the TLS variant of the IMAP and POP3 protocol (IMAPS and POP3S). The JVM of the HCL Domino server is using the keystore file domino/jvm/lib/security/cacert to validate the TLS certificates. If the root certificate is not found in the keystore file, you need to add the root (and intermediate) certificates from the connecting mail server into this cacert file.
Add Certificate to Keystore File
To import the missing root and/or intermediate certificates:
HCL Domino 11+:
Open command prompt window with administrator priviledge on the HCL Domino server
cd domino\jvm\bin to change to the directory
Add the certificate to the 'cacert' file, e.g.
keytool -import -trustcacerts -keystore jvm/lib/security/cacerts -storepass changeit -alias "New Root CA" -import -file NewRootCA.pem
Restart the HCL Domino server
HCL Domino 9 and 10:
Open command prompt window with administrator privilege on the HCL Domino server
cd domino\jvm\bin to change to the directory
Enter ikeyman to start the IBM Key Management utility
Click Key Database File and then Open. Select the file cacerts in the directory domino\jvm\lib\security. You need to have All files selected to see it. The password to open the file is changeit.
Change to Signer Certificates
Click Add and select the root (or intermediate) certificate you need to import. Click OK and enter any descriptive text for this certificate.
Restart the HCL Domino server.
Debugging
For a detailed problem determination, you may use the built-in debugging features.
Enable/Disable Debug
Domino Console Command
Description
Load RunJava JAddin Squirrel Debug!
Start Squirrel add-in in debug mode
Tell Squirrel Debug!
Start the debug mode while the add-in is running
Tell Squirrel NoDebug!
Stop the debug mode while the add-in is running
Squirrel Debug
When activated, the HCL Domino console shows debugging information from the Squirrel add-in and the underlying JAddin framework. The output includes the name of the Java method with the source line number issuing the message. This debuggin information is written to the HCL Domino Console.
While active debugging adds a significant amount of data to the console log and to the log.nsf database, it can be helpful in finding the root of a problem.
> Load RunJava JAddin Squirrel Debug!
05.02.2019 07:44:15 JVM: Java Virtual Machine initialized.
05.02.2019 07:44:15 RunJava: Started JAddin Java task.
05.02.2019 07:44:15 JAddin: Debug logging enabled - Enter 'Tell Squirrel NoDebug!' to disable
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(144) JAddin framework version 2.1.0
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(145) Squirrel will be called with parameters null
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(148) Creating the Domino message queue
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(166) Opening the Domino message queue
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(184) Loading the user Java class Squirrel
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(196) User Java class Squirrel successfully loaded
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(208) => Squirrel.addinInitialize()
05.02.2019 07:44:15 DEBUG: Squirrel.addinInitialize(80) -- addinInitialize()
05.02.2019 07:44:15 DEBUG: Squirrel.addinInitialize(94) Creating the Domino session
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(210) <= Squirrel.addinInitialize()
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(221) => Squirrel.start()
05.02.2019 07:44:15 DEBUG: JAddin.runNotes(223) <= Squirrel.start()
05.02.2019 07:44:15 DEBUG: Squirrel.runNotes(117) -- runNotes()
05.02.2019 07:44:15 DEBUG: Squirrel.runNotes(130) => Squirrel.addinStart()
05.02.2019 07:44:15 Squirrel: The Internet Mail Collector for HCL Domino - Version 1.0.0 2019-02-01
05.02.2019 07:44:15 Squirrel: Copyright iota systems GmbH 2019 / ABdata, Andy Brunner 2019. All Rights Reserved.
05.02.2019 07:44:15 DEBUG: Squirrel.addinStart(182) Configuration database Squirrel.nsf successfully opened
05.02.2019 07:44:15 DEBUG: Squirrel.readConfiguration(384) Reading configuration document
05.02.2019 07:44:15 DEBUG: Squirrel.checkServerLicense(461) License key: null
05.02.2019 07:44:15 Squirrel: No valid license key found - Running in test mode (1 active subscription, 3 messages)
05.02.2019 07:44:15 DEBUG: Squirrel.readConfiguration(417) Configuration document successfully processed
05.02.2019 07:44:15 DEBUG: Squirrel.newVersionCheck(311) -- newVersionCheck()
05.02.2019 07:44:16 DEBUG: Squirrel.newVersionCheck(321) Available version on website: 1.0.0
05.02.2019 07:44:16 DEBUG: Squirrel.readSubscriptions(431) Read all subscription documents
05.02.2019 07:44:16 DEBUG: Squirrel.dbGetAllDocuments(633) View Squirrel.nsf/($Accounts) entries: 1
05.02.2019 07:44:16 DEBUG: Squirrel.addinStart(196) Subscription documents: 1
05.02.2019 07:44:16 DEBUG: Squirrel.addinStart(239) Subscription jsmith@acme.com: POP3S pop.acme.com:995 => John Smith/ACME
05.02.2019 07:44:16 DEBUG: Squirrel.addinStart(242) Subscription jsmith@acme.com: Keep mail on server: 1
05.02.2019 07:44:16 DEBUG: Squirrel.readInbox(607) Subscription jsmith@acme.com: Last POP3 Time stamp: 2019-02-03T11:56:46Z
05.02.2019 07:44:17 DEBUG: Squirrel.readInbox(623) Subscription jsmith@acme.com: Login successful
05.02.2019 07:44:17 DEBUG: Squirrel.readInbox(675) Subscription jsmith@acme.com: Messages in inbox: 4
05.02.2019 07:44:17 DEBUG: Squirrel.readInbox(706) Subscription jsmith@acme.com: Unread POP3 messages: 4
05.02.2019 07:44:17 DEBUG: Squirrel.addinStart(256) Subscription jsmith@acme.com: Processing next message
05.02.2019 07:44:17 DEBUG: Squirrel.addinStart(270) Subscription jsmith@acme.com: Message object: com.sun.mail.pop3.POP3Message@c0923a6c
...
Eclipse Jakarta Mail Debug
In addition to the debugging information sent to the HCL Domino console, the Eclipse Jakarta Mail is instructed to create debugging output. Due to the amount of information, the data is written to a separate file with the name Squirrel-Debug-YYYY-MM-YY.log in the HCL Domino data directory.
Squirrel for Domino - Version 1.5.0 - Jakarta mail debug log started 2021-04-10 14:03:49
Mail property mail.imaps.port: 993
Mail property mail.store.protocol: imaps
Mail property mail.imaps.partialfetch: false
Mail property mail.mime.decodetext.strict: false
Mail property mail.imaps.peek: true
Mail property mail.mime.charset: UTF-8
DEBUG: setDebug: Jakarta Mail version 1.6.6-SNAPSHOT
DEBUG: getProvider() returning javax.mail.Provider[STORE,imaps,com.sun.mail.imap.IMAPSSLStore,Oracle]
DEBUG IMAPS: mail.imap.partialfetch: false
DEBUG IMAPS: mail.imap.ignorebodystructuresize: false
DEBUG IMAPS: mail.imap.statuscachetimeout: 1000
DEBUG IMAPS: mail.imap.appendbuffersize: -1
DEBUG IMAPS: mail.imap.minidletime: 10
DEBUG IMAPS: peek
DEBUG IMAPS: closeFoldersOnStoreFailure
DEBUG IMAPS: trying to connect to host "imap.servicehoster.ch", port 993, isSSL true
* OK [CAPABILITY IMAP4rev1 SASL-IR LOGIN-REFERRALS ID ENABLE IDLE LITERAL+ AUTH=PLAIN AUTH=LOGIN] Dovecot ready.
DEBUG IMAPS: AUTH: PLAIN
DEBUG IMAPS: AUTH: LOGIN
DEBUG IMAPS: protocolConnect login, host=imap.servicehoster.ch, user=xxx@abdata.ch, password=<non-null>
DEBUG IMAPS: AUTHENTICATE PLAIN command trace suppressed
DEBUG IMAPS: AUTHENTICATE PLAIN command result: A0 OK [CAPABILITY IMAP4rev1 SASL-IR LOGIN-REFERRALS ID ENABLE IDLE SORT SORT=DISPLAY THREAD=REFERENCES THREAD=REFS THREAD=ORDEREDSUBJECT MULTIAPPEND URL-PARTIAL CATENATE UNSELECT CHILDREN NAMESPACE UIDPLUS LIST-EXTENDED I18NLEVEL=1 CONDSTORE QRESYNC ESEARCH ESORT SEARCHRES WITHIN CONTEXT=SEARCH LIST-STATUS BINARY MOVE SNIPPET=FUZZY PREVIEW=FUZZY LITERAL+ NOTIFY SPECIAL-USE QUOTA] Logged in
DEBUG IMAPS: connection available -- size: 1
A1 SELECT INBOX
* FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
* OK [PERMANENTFLAGS (\Answered \Flagged \Deleted \Seen \Draft \*)] Flags permitted.
* 0 EXISTS
* 0 RECENT
* OK [UIDVALIDITY 1614859984] UIDs valid
* OK [UIDNEXT 2] Predicted next UID
A1 OK [READ-WRITE] Select completed (0.001 + 0.000 + 0.001 secs).
A2 SEARCH UNSEEN ALL
* SEARCH
A2 OK Search completed (0.001 + 0.000 secs).
A3 CLOSE
Don't forget to manually delete these debug files after use.
Debugging OAuth 2.0
Starting with version 1.6.0, Squirrel is using the freeware SOFA for OAuth 2.0 authentication. This framework writes his own detailed logging, which can be configured in the file SOFA-Logging.properties located in the HCP Domino program directory. The resulting log files Squirrel-Debug-OAuth-{n}.log are created in the HCL Domino program directory.
Use the sample file in the distribution package to configure and activate the SOFA debug log.
2022-08-20T11:44:23.071 FEIN SOFA (Simple OAuth 2.0 Framework for Authentication) Version 0.8.1 (2022-03-03) initialization called
2022-08-20T11:44:23.102 FEIN SOFA running on OS platform <Windows 8 6.2/amd64>
2022-08-20T11:44:23.102 FEIN SOFA running on JVM version <International Business Machines Corporation openj9-0.29.0>
2022-08-20T11:44:23.258 FEIN SOFA AES-256 cipher initialized
2022-08-20T11:44:23.258 FEIN SOFA authenticate() called
2022-08-20T11:44:23.305 FEIN OAuth grant type <client_credentials>
2022-08-20T11:44:23.305 FEIN OAuth scope <https://graph.microsoft.com/.default>
2022-08-20T11:44:23.305 FEIN OAuth client ID <aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa>
2022-08-20T11:44:23.305 FEIN SOFA executeHttpTransaction() called
2022-08-20T11:44:23.305 FEIN HTTP connecting to URL <https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx/oauth2/v2.0/token>
2022-08-20T11:44:23.524 FEIN HTTP method <POST>
2022-08-20T11:44:23.540 FEIN HTTP header sent <Date: Sat, 20 Aug 2022 09:44:23 GMT>
2022-08-20T11:44:23.540 FEIN HTTP header sent <User-Agent: SOFA/0.8.1 (Simple OAuth 2.0 Framework for Authentication)>
2022-08-20T11:44:23.540 FEIN HTTP header sent <Accept: application/json>
2022-08-20T11:44:23.540 FEIN HTTP header sent <Content-Type: application/x-www-form-urlencoded>
2022-08-20T11:44:23.540 FEIN HTTP header sent <Content-Length: 178>
2022-08-20T11:44:23.852 FEIN HTTP data size sent <178 bytes>
2022-08-20T11:44:23.852 FEIN HTTP connection established with cipher <TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384>
2022-08-20T11:44:23.915 FEIN HTTP header received <HTTP/1.1 400 Bad Request>
2022-08-20T11:44:23.915 FEIN HTTP header received <x-ms-ests-server: 2.1.13481.11 - NEULR1 ProdSlices>
2022-08-20T11:44:23.915 FEIN HTTP header received <X-Content-Type-Options: nosniff>
2022-08-20T11:44:23.915 FEIN HTTP header received <Pragma: no-cache>
2022-08-20T11:44:23.915 FEIN HTTP header received <P3P: CP="DSP CUR OTPi IND OTRi ONL FIN">
2022-08-20T11:44:23.915 FEIN HTTP header received <Date: Sat, 20 Aug 2022 09:44:23 GMT>
2022-08-20T11:44:23.915 FEIN HTTP header received <Strict-Transport-Security: max-age=31536000; includeSubDomains>
2022-08-20T11:44:23.915 FEIN HTTP header received <Cache-Control: no-store, no-cache>
2022-08-20T11:44:23.915 FEIN HTTP header received <Set-Cookie: stsservicecookie=estsfd; path=/; secure; samesite=none; httponly>
2022-08-20T11:44:23.915 FEIN HTTP header received <Expires: -1>
2022-08-20T11:44:23.915 FEIN HTTP header received <Content-Length: 554>
2022-08-20T11:44:23.915 FEIN HTTP header received <X-XSS-Protection: 0>
2022-08-20T11:44:23.915 FEIN HTTP header received <x-ms-request-id: 572b6d8d-f54d-42a2-a12d-66c527c50b00>
2022-08-20T11:44:23.915 FEIN HTTP header received <Content-Type: application/json; charset=utf-8>
2022-08-20T11:44:23.915 FEIN HTTP response code <400>
2022-08-20T11:44:23.915 FEIN HTTP data size received <554 bytes>
2022-08-20T11:44:23.915 FEIN SOFA executeHttpTransaction() elapsed time <610 ms>