This document is written for system administrators, and it aims to provide both an in-depth view of the product architecture to simplify troubleshooting and the knowledge necessary for solid customizations.
Zimbra Chat is included in Zimbra starting in version 8.7.6 as Beta software and version 8.8.0 as Stable. Zimbra Chat provides simple and direct text-only chat between Zimbra accounts. It is composed of a Zimlet and a Zimbra extension.
The Zimbra extension exposes an XMPP client so users can chat from a standard XMPP client instead of using the Zimlet through the {product-short} {web-client}. Users can use both methods simultaneously.
Zimbra Chat is designed for Zimbra. It runs as a Zimbra Server Extension that implements an XMPP server and handles all the events shared between the clients. The Zimbra Chat Server Extension uses both XMPP and a custom protocol to communicate with the Chat Zimlet.
The server extension can handle multiple sessions for a single user, without limits. Each session has its own delivery queue to ensure that each session has exactly all of the events as any other session of the user.
Sessions are not limited by type (XMPP or Chat Zimlet). A user can use both the {product-short} {web-client} and an XMPP client at the same time, without worrying about interferences between the sessions.
Zimbra Chat is compose of two parts:
-
Chat Zimlet
-
Chat Extension
The Zimbra Chat Extension does not require the Chat Zimlet to work properly. The Chat Zimlet is designed and built to work only with the Zimbra Chat Extension.
The Chat Zimlet is the client component of Chat. It runs on the {product-short} {web-client} and is managed like any other Zimlet. It is fully integrated in the {product-short} {web-client} and uses the same graphics libraries. The Zimlet can work only with the Chat Extension because the Zimlet and Extension use a specific protocol to send and receive events. The Chat Zimlet is supported on all browsers and versions supported for the {product-short} {web-client}.
Features:
-
{product-short} {web-client} integration.
-
Manage the buddy list. Users can add, edit and remove buddies from the buddy list.
-
Open each `chat room' in a separate panel.
-
Manage personal status.
-
Send/Receive plain messages from users in the buddy list.
-
Send presence status to users in the buddy list.
-
View presence status of users in the buddy list.
-
Support for Emojis (emoticons) on conversations. Emojis are provided free by EmojiOne http://emojione.com/.
-
Send an entire conversation as email.
-
Search conversations in the chat history (if enabled in the Extension options, see Configuration Keys).
-
Get desktop notifications for any incoming message.
The Zimbra Chat Extension is the core of Zimbra Chat. It is a complete chat server that manages the events between connected clients.
It uses the ZAL to integrate into the mailboxd service of Zimbra.
The Extension can handle two types of connections:
-
SOAP connections incoming from the Chat Zimlet, using Zimbra’s SOAP infrastructure.
-
XMPP connections from compatible clients.
Features:
-
Handle events from multiple sessions.
-
Handle SOAP connections for Chat Zimlet clients.
-
Handle XMPP (plain and SSL) connections for compatible clients through a public port (see Configuration Keys)
-
Store the chat history for each conversation in a dedicated `chat' folder in the user’s mailbox (if enabled, see Configuration Keys).
-
Store the relationships between users in the Zimbra database.
Zimbra Chat comes bundled with all Zimbra packages for version 8.8.0 and higher as a Zimbra package.
No dedicated installation steps are required.
|
Warning
|
In case the Zimbra Chat package was not installed during the system’s installation or upgrade, please refer to the general documentation about package installation to install it. |
Zimbra Chat is upgraded with the rest of the Zimbra platform.
No dedicated upgrade steps are needed.
This chapter helps the administrator find and solve any issues. If no solution is found, the administrator is guided through the process to report the issue.
This process is fundamental to locating the source of an issue and to find a solution or to correctly report it.
To locate errors in the source code of the Chat Zimlet, enable developer
mode on the {product-short} {web-client} by modifying the URL of the
Zimbra installation, appending ?dev=1 into the browser URL. Adding the
dev=1 parameter to the URL forces Zimbra to load the entire Web
Client with all not minified sources, included the Zimlets. A longer
load time should be expected.
During the loading of the {product-short} {web-client}, open the browser developer tools.
In the browser developer tools console you will see logs from the Chat Zimlet. If an error occurs, it will be printed into the console.
If no errors are printed, but you see an unwanted behavior, enable the
break on exception option in the developer tools. With that option
enabled, if an error occurs, the execution of the software will be paused on the
line where the error is generated.
If an error occurs, please escalate the issue by sending the file, the row and any details about the error through the appropriate channels.
If no errors are detected, please see the "Chat Extension Error" section.
Any exception thrown by the Chat Extension is written into the
mailbox.log. To check if there are any exceptions, please refer to
the appropriate section of this guide.
If you can’t find a solution for the exception in the FAQ, please report the issue through the appropriate channels, including the complete exception information.
If the user is experiencing unexpected Zimlet behavior in the {product-short} {web-client}, use Google Chrome Developer Tools to figure out the source of the issue.
To open the Google Chrome Developer Tools:
* Open the main menu.
* Find the Other tools menu option.
* Select Developer Tools.
A new panel with many tabs should appear. These tabs are:
-
Console:: Like the server console, this tab will display some log information and allow you to interact with the JS Runtime.
-
Network:: This tab will show any network activity, and it can be used to identify the requests to the mailbox and the responses from it.
To open the Firefox Developer Tools, open the
main menu and click the Developer Tools button.
A new panel with many tabs should appear. These tabs are:
-
Console:: Like the server console, this tab will display some log information and you allow to interact with the JS Runtime.
-
Network:: This tab will show any network activity, and it can be used to identify the requests to the mailbox and the responses from it.
Gathering System information is a vital part of the troubleshooting process. This section helps the administrator collect useful system information required to correctly report an issue (as described in the "How to escalate and issue" section).
To see the version of the Extension and the Zimlet, type this command:
# As zimbra java -cp /opt/zimbra/lib/ext/openchat/openchat.jar com.zextras.lib.OpenChat
To see the list of deployed Zimlets, type this command:
# As zimbra zmzimletctl listZimlets
To see the list of Zimlets enabled for a user, type this command:
# As zimbra zmprov getAccount [email protected] zimbraZimletAvailableZimlets
To see the list of the preferences for the Zimlets enabled for a user, type this command:
# As zimbra zmprov getAccount [email protected] zimbraZimletUserProperties
The Chat Zimlet is not working after the user login, and I see some JavaScript Errors. What can I do?
This is most commonly caused by caching issues. Refresh all the caches with these commands:
# As zimbra zmprov flushCache -a zimlet com_zextras_chat_open
If the problem persists, escalate the issue.
The Chat Zimlet doesn’t start at login, and a popup appears informing the user that the server is not available. What can I do?
|
Tip
|
Remember that the Chat Zimlet will not start if the logged user is using the delegated access feature (e.g. View Mail button from the admin console) to protect the privacy of the user. |
Check to see if the Chat Extension is loaded correctly in the mailbox.log
(see the appropriate section of this guide about how to read the mailbox.log).
Loading of the Zimbra Extension is granted by the following lines at the mailbox startup:
xxxx-xx-xx xx:xx:xx,xxx INFO [main] [] mailbox - OpenChat starting ... xxxx-xx-xx xx:xx:xx,xxx INFO [main] [] extensions - OpenChat started
If the problem persists, report the issue, including the exception in the report.
Another Zimlet is using the sidebar, and a user cannot see the Chat buddy list. What can I do?
The Chat Zimlet uses a container that can be used by other Zimlets. To avoid collisions, try to detect if that container is used or not.
The Chat Zimlet uses an internal black list to detect incompatible
Zimlets and disable the sidebar mode, switching to the docked mode.
The detection may fail if the Zimlet using the sidebar container is not indexed in the internal blacklist.
If the problem persists, report the issue, mentioning the name of the conflicting Zimlet.
If a user is stuck in the sidebar mode and another Zimlet has taken control of the sidebar, you can reset the Zimlet user setting to use the docked mode with these commands:
# As zimbra # Reset the involved zimlet user preference: zmprov modifyAccount [email protected] \ -zimbraZimletUserProperties "com_zextras_chat_open:zxchat_pref_dockmode:FALSE" zmprov modifyAccount [email protected] \ -zimbraZimletUserProperties "com_zextras_chat_open:zxchat_pref_dockmode:TRUE" # Set the zimlet user preference to dock mode: zmprov modifyAccount [email protected] \ +zimbraZimletUserProperties "com_zextras_chat_open:zxchat_pref_dockmode:TRUE"
Then reload the {product-short} {web-client} to apply the modifications.
If the problem persists, report the issue.
Server to server messages are not delivered between the two servers. What can I do?
This issue can be caused by connection issues between two mailboxes.
Verify that the port 5269 is opened on each server and that the servers can
connect to each other.
To verify if the port is opened on the server, a simple check
can be done by trying to connect to port 5269 using a telnet client.
If everything seems to work properly, open the mailbox.log on both servers and
try to send an event (e.g. a text message). If an
exception appears, see if it provides a hint on the error. If there is no
meaningful exception, report the issue and include the exception in the report.
If you found an issue and are not able to fix it, the following information is vital to report:
-
A detailed description of the issue: What you are expecting and what is really happening?
-
A detailed description of the steps to reproduce the issue.
-
A detailed description of the installation and the environment: (see "Gathering System Information" section of this guide)
-
Server information: CPU, RAM, number of servers and for each server:
-
Zimbra Version
-
Chat Version
-
List of the installed Zimlets
-
-
Client information:
-
Browser name and version
-
Connectivity used between the servers and the client
-
Client Skin (theme)
-
Client Language
-
List of the Zimlets enabled for the user
-
-
-
Any log involved for the issue:
-
mailbox.logYou can remove any personal information to protect users' privacy.
-
Stress tests are being performed on Zimbra Chat.
We have noticed an increment of the workload stimabe at most 7% in an Zimbra installation with 20000 users.
The history feature of the Zimbra Chat Extension has the most impact. When a message is sent, a mime message is either created or updated, meaning few kilobytes are read or written and some database queries are performed.
|
Tip
|
We suggest disabling history in very large deployments. To edit the configuration see Configuration Keys. |
The Chat Extension is easily configurable through the Zimbra CLI. All of
the configurations are stored in LDAP.
To edit an account configuration, run these commands:
# As zimbra zmprov modifyAccount [email protected] {propertyName} {value}
- zimbraChatServiceEnabled
-
[boolean], Default value:true.Enable the Chat Service.
Can be applied to: * Global * Server
- zimbraChatHistoryEnabled
-
[boolean], Default value:true, requires a mailbox restart to be applied.Enable the chat history writing inside the chat folder.
Can be applied to: * Cos * Account
- zimbraChatConversationAuditEnabled
-
[boolean], Default value:false.Enable the dedicated log for the chat conversations.
Can be applied to: * Global * Domain
- zimbraChatXmppSslPortEnabled
-
[boolean], Default value:false, requires a mailbox restart to be applied.Enable the XMPP legacy SSL port.
Can be applied to: * Global * Server
- zimbraChatAllowUnencryptedPassword
-
[boolean], Default value:false.Allow unencrypted password login via XMPP.
Can be applied to: * Global * Server
- zimbraChatXmppPort
-
[port], Default value:5222, requires a mailbox restart to be applied.The XMPP standard port, usually used with StartTLS.
Can be applied to: * Global * Server
- zimbraChatXmppSslPort
-
[port], Default value:5223, requires a mailbox restart to be applied.The XMPP legacy SSL port.
Can be applied to: * Global * Server
- zimbraChatAllowDlMemberAddAsFriend
-
[boolean], optional.Add every member of the distribution list as buddies to each other.
Can be applied to: * Distribution list
Mailbox log is a standard Log4j log. Here are some sample rows of
a mailbox.log:
xxxx-xx-xx xx:xx:xx,xxx INFO [qtp1912962767-310:https://123.123.123.123:8443/service/soap/ModifyPropertiesRequest] [[email protected];mid=6;ip=172.17.0.2;ua=ZimbraWebClient - GC58 (Linux)/8.6.0_GA_1153;] soap - ModifyPropertiesRequest elapsed=4 xxxx-xx-xx xx:xx:xx,xxx INFO [qtp1912962767-310:https://123.123.123.123:8443/service/soap/ZxChatRequest] [] extensions - [email protected] changed status to AVAILABLE xxxx-xx-xx xx:xx:xx,xxx INFO [qtp1912962767-310:https://123.123.123.123:8443/service/soap/ZxChatRequest] [] soap - ZxChatRequest elapsed=24
Each row is composed of these elements:
- xxxx-xx-xx xx:xx:xx,xxx
-
Timestamp of the log row.
- INFO
-
The type of the log row.
- qtp…ModifyPropertiesRequest
-
Information on the threads that requested to write the log row, which is usually the handler that triggered the log row.
- name=…
-
Information on the user session.
- soap -
-
Source of the log row.
- ModifyPropertiesRequest elapsed=4
-
The content of the log row.
Mailbox log is a standard Log4j log. Here are some sample rows of
a zmmailboxd.out:
xxxx-xx-xx xx:xx:xx.xxx:INFO:oejs.SetUIDListener:main: Opened ServerConnector@397fbdb{HTTP/1.1}{0.0.0.0:8080}
xxxx-xx-xx xx:xx:xx.xxx:INFO:oejs.SetUIDListener:main: Opened ServerConnector@36ebc363{SSL-http/1.1}{0.0.0.0:8443}
xxxx-xx-xx xx:xx:xx.xxx:INFO:oejs.SetUIDListener:main: Opened ServerConnector@54d9d12d{SSL-http/1.1}{0.0.0.0:7071}