Homepage Installation Administrator Tips Developer Tips Download Buy

1. IMAP versus POP3

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

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

Table with the default mail server ports:

Protocol TLS Secured Default Port
IMAPS Yes 993
IMAP No 143
POP3S Yes 995
POP3 No 110

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

4. TLS Support

Secure connections are supported by using the TLS variant of the IMAP and POP3 protocol (IMAPS and POP3S). The JVM of the IBM Domino server is using the keystore file domino/jvm/lib/security/cacert to validate the TLS certificates. If the root certificate is not in the keystore file, you need to add the root (and intermediate) certificates from the connecting mail server into this cacert file.

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

To import the missing root and/or intermediate certificates:

  1. Open a command prompt windows with administrator privileges on the IBM 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 IBM Domino server.

6. IBM 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 = 15
  Squirrel.Config.Subscriptions.Limit = 50
  Squirrel.Config.Subscriptions.Used = 41
  Squirrel.Domino.Platform = 6.2 (Windows 8)
  Squirrel.Domino.Version = Release 10.0.1|November 29, 2018 (Windows/64)
  Squirrel.JAddin.StartedTime = 2019-02-10T07:04:36Z
  Squirrel.JAddin.VersionDate = 2019-02-03
  Squirrel.JAddin.VersionNumber = 2.1.0
  Squirrel.JVM.GCCount = 0
  Squirrel.JVM.HeapLimitKB = 131'072
  Squirrel.JVM.Version = 1.8.0_181 (IBM Corporation)
  Squirrel.Messages.IMAP.Processed = 433
  Squirrel.Messages.POP3.Processed = 22
  Squirrel.VersionDate = 2019-02-10
  Squirrel.VersionNumber = 1.0.0

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

8. 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 IBM 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 IBM 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
...