Homepage Installation Administrator Tips Developer Tips Download Buy

Administrator Tips

1. IMAP versus POP3

Whenever possible, use the TLS-secured version of the IMAP protocol (IMAPS). IMAP is generally more modern and more reliable to access your emails on the remote mail servers. TLS encryption (used in IMAPS and POP3S) prevent that the user password and the message content is sent in clear text.

The POP3 protocol does not include a specification for message read or unread indicators. To overcome this limitation, any POP3 client must access all messages at every interval and select the messages to be processed based on a ‘last message processed’ indicator. This is done in Squirrel with a hidden time stamp field added to the mail account subscription document.

2. Test Mode

Squirrel will run in test mode, if the license key field in the squirrel configuration document is empty or invalid. In test mode, the use of this add-in is limited to one active mail account subscription and 3 messages processed.

3. Mail Migration Usage

To support customers migrating entire POP3 or IMAP mailboxes to Domino, the option “Mail Migration” may be used to read all messages once during the next interval. This option is then reset by the back-end at the next message fetch interval.

4. Security

The password field in the mail account subscription document is always encrypted.

By using the TLS-secured versions of the protocols (IMAPS, POP3S), the password is also sent encrypted between the HCL Domino server and the Internet mail server.

The administrator may set the database ACLs in a way that the user may only create and modify his own mail account subscription documents (see Installation).

5. TLS Support

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.

6. Internet Server Certificate

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
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

To import the missing root and/or intermediate certificates:

  1. Open a command prompt windows with administrator privileges on the HCL Domino server
  2. cd domino\jvm\bin to change to the directory
  3. ikeyman to start the IBM Key Management utility
  4. 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.
  5. Change to Signer Certificates
  6. Click Add and select the root (or intermediate) certificate you need to import. Click OK and enter any descriptive text for this certificate.
  7. Restart the HCL Domino server.

7. HCL Domino Statistics

During execution, the Squirrel add-in maintains statistics and status information. They can be displayed with the Show Stat command:

> show stat squirrel
 Squirrel.Config.IntervalMin = 3
 Squirrel.Config.Subscriptions.Limit = 10
 Squirrel.Config.Subscriptions.Used = 7
 Squirrel.Domino.Platform = 6.2 (Windows 8)
 Squirrel.Domino.Version = Release 11.0.1|March 21, 2020 (Windows/64)
 Squirrel.JAddin.StartedTime = 2020-10-18T07:34:58Z
 Squirrel.JAddin.VersionDate = 2019-03-07
 Squirrel.JAddin.VersionNumber = 2.1.1
 Squirrel.JVM.GCCount = 0
 Squirrel.JVM.HeapLimitKB = 262'144
 Squirrel.JVM.HeapUsedKB = 17'649
 Squirrel.JVM.Version = 1.8.0_242 (Eclipse OpenJ9)
 Squirrel.Messages.IMAP.Processed = 9
 Squirrel.Messages.POP3.Processed = 2
 Squirrel.VersionDate = 2020-10-18
 Squirrel.VersionNumber = 1.4.1

8. Error Handling

If Squirrel encounters any error while processing an mail account subscription, it will disable this document to prevent future error messages. The last error message is saved in the mail account subscription document and a HCL Notes email message is sent to the user to inform of the error. After the error has been corrected (e.g. wrong password), the mail account subscription document must be manually enabled again to resume the processing for this subscription. Other errors (e.g. connection timeouts) are reported on the console and the operation is retried at the next interval.

9. Debugging

For problem determination, you may enable the built-in debugging feature. 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.

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

The debug output is written to the HCL Domino console and includes the name of the Java method with the source line number issuing the message.

> 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