Zimbra Docs is based on a customized LibreOffice online (LOOL) package that allows collaborative editing of documents, spreadsheets and presentations from within the Zimbra WebClient.
The Zimbra Docs server is the heart of the service. The service hosts each document opened through a LibreOffice engine and responds to the client with every keystroke and change.
|
Important
|
Install this component on one or more dedicated nodes running Ubuntu 16.04 LTS, Ubuntu 18.04 LTS, or Red Hat CentOS 7. |
The extension is the component that coordinates everything. Its main tasks are:
-
Select which Docs server upon which to open the next document.
-
Redirect the client when it needs to open a document.
-
Read and write documents to and from system storage on behalf of the Docs server.
-
Connect to each Docs server via an administrative WebSocket. Keep track of the availability and the resource usage of each.
-
Orchestrate concurrent user connections to the same document in the same server. (document sharing)
The NG Modules package contains the Zimbra Docs Extension together with the NG Core.
A Zimbra Docs Zimlet handles the integration with Briefcase and with email attachments. It is a thin web client that connects to a native server instance via WebSocket, renders a document, and only sends changes to the client to keep the fidelity of the document on par with a desktop client while limiting network bandwidth consumption to the bare minimum.
Documents in preview and attachments are shown in read-only mode with a simplified interface, while edit mode has a full interface.
Its main tasks are:
-
Change the btn:[Create] button in the {either-web-client} to the related Docs feature.
-
Change the {web-client} preview feature to use Docs.
-
Allow the preview of documents.
Zimbra Docs features are available on all browsers officially supported by the {product-short} {web-client}, with some client-side limitations:
| Browser | Version | OS | Supported |
|---|---|---|---|
Microsoft Edge (Chromium) |
Latest |
Windows |
[check circle] Yes |
Microsoft Edge (Chromium) |
Others |
Windows |
[check circle] Limited |
Microsoft Edge (EdgeHTML) |
Any |
Windows |
[times circle] No |
Internet Explorer |
Any |
Windows |
[times circle] No |
Mozilla Firefox |
Latest |
Windows/Linux/OSX |
[check circle] Yes |
Mozilla Firefox |
ESR |
Windows/Linux/OSX |
[check circle] Yes |
Mozilla Firefox |
Others |
Windows/Linux/OSX |
[check circle] Limited |
Google Chrome |
Latest |
Windows/Linux/OSX |
[check circle] Yes |
Google Chrome |
Others |
Windows/Linux/OSX |
[check circle] Limited |
Safari |
Latest |
OSX |
[check circle] Yes |
Safari |
Others |
OSX |
[check circle] Limited |
While likely to work, items marked as "[check circle] Limited" are only supported on the browser’s two previous stable releases to the current one.
Here is what happens behind the scenes when a user creates a document:
-
The Zimlet prompts the Extension to create a new, empty document
-
The Extension creates the document and returns its ID to the client
-
The Zimlet opens a new Zimbra tab containing an iframe pointing towards
/service/extension/wopi-proxy -
The extension receives the request from the client, creates a unique token for the needed document, and replies with a new URL
-
The URL points toward
/docs/[docs-node-id]/[token], which will be proxied by nginx to the specific Docs Server node -
The Docs Server will respond with the web application in Javascript
-
The web application opens a WebSocket connection, going through nginx
-
Docs Server receives the WebSocket connection along with a token, sends a
read wopicommand towards the mailbox URL indicated in the parameters (after validating the URL against allowed nodes) -
The Extension validates the token and replies with information and content
-
The Docs Server node parses the document, renders it, and sends it back to the client.
-
The document is fully opened and editable.
Open document
redirect to docs
+------------------------+ +----------------------+
| Zimbra Proxy | | Mailbox |
| +-------------> |
| Nginx | | Zimbra Docs Extension|
+------------------------+ +----------------------+
| | ^
| | |
| | WOPI:
| Admin Web Read/Write
| Socket Documents
| | |
| | |
| | |
| +---v----------------+
| | |
+--------------------> Docs Server |
Load Client | |
Open client websocket +--------------------+
All mailbox servers will need to be able to directly communicate with the Docs Server over port 8443 (HTTPS Backend), which must be open on both ends.
The Docs Server communicates with the Extension through port 9980, so incoming traffic from all mailbox and proxy servers to that port must be allowed. The Docs Server component must also be able to directly communicate with the master LDAP server as well as with all Mailbox servers.
Download the zimbra-docs tgz standalone installer, extract it and as the root user execute the install.sh script contained in the package.
To obtain the information required for the initial Docs Server setup, run the following command on any mailbox server:
zimbra@mbx1:~$ zmlocalconfig -s ldap_master_url zimbra_ldap_user zimbra_ldap_userdn zimbra_ldap_passwordThis will return the info you need in the following format:
ldap_master_url = ldap://ldap01.cfd6a9e5.test.domain.com:389
zimbra_ldap_user = zimbra
zimbra_ldap_userdn = uid=zimbra,cn=admins,cn=zimbra
zimbra_ldap_password = Deyked4ofMarjThe script will install the Zimbra Docs package and then ask for information about the master LDAP, URL, username, and password, all needed to add a new server in the LDAP with just the 'docs' service installed/enabled.
Every Docs Server will be visible by every node, and will read the LDAP to write the configuration in /opt/zimbra/conf/docs/loolwsd.xml.
After completing the setup, you need no other configuration.
Adding Custom Fonts to the Docs Server To add Custom Fonts to your Docs Server, simply copy the .ttf font files in the /opt/zimbra/docs/zimbra-docs-core/share/fonts/custom/ directory, then generate the new font cache and restart the docs server running zdocs restart as root.
To generate the new font cache, run the following command based on the Docs Server’s Operating System:
dpkg-reconfigure zimbra-docs-server
fc-cache /opt/zimbra/docs/zimbra-docs-core/share/fonts
|
Warning
|
The server will briefly be unavailable during a restart, and clients will need to close and re-open documents to see the new fonts in the list. |
While the NG modules contain the Zimbra Docs extension, the com_zextras_docs Zimlet needs to be deployed on the server and enabled for all users and COS that need to have access to the Zimbra Docs features.
The com_zextras_docs Zimlet is available in the Zimbra repository, so it can be easily downloaded and deployed by running apt-get install zimbra-docs.
No configuration on the mailboxd side is needed after the Zimlet has been deployed and enabled.
The proxy configuration must be re-generated after adding one or more Zimbra Docs Servers to the infrastructure: to do so, run /opt/zimbra/libexec/zmproxyconfgen as the zimbra user and then restart the proxy service running zmproxyctl restart as the same user.
The new docs nodes' addresses get distributed via LDAP, so no manual configuration is needed.
The standalone installer is released under the MPLv2 license while the extension and Zimlet are under a proprietary license.
Before uninstalling the software, the node must be removed from LDAP either from the docs node via the command:
zdocs remove-local-server
or via the zmprov command from any Zimbra node
zmprov deleteServer {servername}
On a Docs server, the zdocs (/usr/local/bin/zdocs as root) command can generate the config for LOOL (it’s already on cron), add/remove the docs server from LDAP, test configuration and manage the service.
zdocs commandusage: zdocs [-h] [--auto-restart] [--ldap-dn LDAP_DN] [--ldap-pass LDAP_PASS]
[--ldap-url LDAP_URL] [--hostname HOSTNAME] [--debug][--cron]
{genkey,write-local-server,remove-local-server,generate-config,ldap-write-config,ldap-test,start,stop,restart,status,setup}
Manage Zimbra Docs service.
Available commands:
genkey Generate a private key needed for authentication between docs and mailbox servers.
write-local-server Add or update in ldap the necessary server entry for this server in order to be reachable from other servers.
remove-local-server Remove local server entry in LDAP.
generate-config Populate the config template with LDAP values and write a new configuration file.
ldap-write-config Write new configuration about the ldap access needed to generate the docs configuration file.
ldap-test Check the ldap connection.
start Start the service.
stop Stop the service.
restart Restart the service.
status Print service status.
setup Start the initial setup.
positional arguments:
{genkey,write-local-server,remove-local-server,generate-config,ldap-write-config,ldap-test,start,stop,restart,status,setup} Command to execute
optional arguments:
-h, --help show this help message and exit
--auto-restart Automatically restart the service if configuration is changed (to be used with generate-config)
--ldap-dn LDAP_DN Ldap dn (distinguish name) to bind to (to be used with ldap-test and ldap-settings)
--ldap-pass LDAP_PASS Ldap password used of the DN (to be used with ldap-test and ldap-settings)
--ldap-url LDAP_URL Ldap url completed with schema (ex.: ldaps://ldap.example.com, to be used with ldap-test and ldap-settings)
--hostname HOSTNAME Hostname of this server (to be used with add-local-server)
--debug Show complete errors when things go bad.
--cron Start in cron mode, avoid any output unless there is an error (to be used with generate-config).
examples:
#regenerate the config and restart the server if config changed
zdocs --auto-restart generate-config
#restart the service
zdocs restart
#check ldap connection availability using current settings
zdocs ldap-test
#check ldap connection using custom settings
zdocs --ldap-url ldaps://ldap.example.com/ --ldap-dn 'uid=zimbra,cn=admins,cn=zimbra' --ldap-pass password ldap-test
#change the ldap connection settings
zdocs --ldap-url ldap://ldap2.example.com/ --ldap-dn 'uid=zimbra,cn=admins,cn=zimbra' --ldap-pass password
ldap-write-config
#add the local server
zdocs write-local-server
#add the local server with a custom hostname in LDAP, this command should be already invoked during setup.
zdocs --hostname myhostname write-local-server
#remove the local server from LDAP, useful when destroying the server, you can also use 'zmprov deleteServer' from a mailbox server.
zdocs remove-local-serverOn a Mailbox server, the zxsuite docs command is available.
This command allows you to check and control the Docs service’s status, to force a configuration to reload, and to see the Docs Servers' status.
zxsuite docs
Commands regarding docs module
doReloadConfig - reload docs configuration from ldap, which
would happen once a minute.
zxsuite docs doReloadConfig
doRestartService - restart a given service
zxsuite docs doRestartService
{service_name}
doStartService - start a given service
zxsuite docs doStartService {service_name}
doStopService - stop a given service
zxsuite docs doStopService {service_name}
getServices - show current status of all services for
this module
zxsuite docs getServices
status - show zimbra docs servers status with their
resource usage (if connected).
zxsuite docs statusThis problem is most likely due to a connection issue between the mailbox server and the Docs server.
Check the mailbox.log and see the reason for the connection failure.
If there are no connection errors, check the Docs server with zdocs status on the docs node.
The mailbox will log every connection and disconnection for each Docs server.
The proxy configuration needs to be re-generated, and the proxy restarted.
You may see this happen if the Docs server cannot connect back to the mailbox server to read and write the document.
Check name resolution and SSL certificate of mailboxd, which must be valid for the Docs server that does not inherit Zimbra certificate management.