IMPORTANT: Zimbra Daffodil (v10.1) Licensing Changes

  1. Zimbra Daffodil (v10.1) introduced a new license service with significant changes in licensing management. A new service named License Daemon Service (LDS) has been added and is a required service to support the management of the license.

  2. Zimbra Daffodil (v10.1) will not support legacy license (license.xml) post-upgrade.

  3. Before attempting the upgrade, please see the next section on License and Installer changes. Also see the Daffodil v10.1 Licensing section for detailed information.

  4. Please contact the Support Team to upgrade you old license to Zimbra Daffodil (v10.1) license.

Zimbra Daffodil (v10.1) introduced an automated licensing and entitlement system for better flexibility in managing licenses and allows for future growth. It continues to support the Automatic and Manual license methods. Zimbra Daffodil (v10.1) onwards, the terms has been changed to Online Activation and Offline Activation.

Following are the Zimbra Daffodil (v10.1) licensing changes:

Licensing Changes

  1. An 18-26 alphanumeric character key is required which replaces the older license.xml file.

  2. Zimbra Collaboration licenses are restrictive to the entitlement defined within the license and do not support multiple activations.

  3. Once the Zimbra Collaboration license is activated no future license management by the user is required. License management is real-time and is managed by Zimbra Collaboration. Any changes required in the license, it will be done by Zimbra Collaboration team and the updates will be reflected on the server in approximately 5-15 minutes.

  4. For environments that don’t have access to the public network, a separate offline service named Offline Lan Daemon has to be set up that acts as a locally run license manager. Please refer to the Offline License Activation section for more details.

  5. All data gathered is based on license requirements and total usage which meets GDPR and other legal regulations.

  6. Independent lab licenses are available. Contact Zimbra Sales or Support team.

Installer Changes

For more information on License Daemon Service (LDS) and how to setup a separate node, please refer to LDS section.
  1. A new license daemon service (LDS) is now part of the Zimbra installation. It gets displayed as zimbra-license-daemon in the packages list and required for the normal functioning of Zimbra.

  2. You also have a flexibility of setting up a dedicated LDS node.

  3. In case you plan to setup a dedicated LDS server, please note that it has to be installed after upgrading the LDAP server and before upgrading the mailbox server.

  4. Internet access is required for the node where the LDS is installed.

  5. If you attempt to upgrade the mailbox server before installing LDS, the installer will exit with the following message - zimbra-license-daemon should be installed prior to zimbra-store.

  6. Online Activation

    1. When upgrading to Zimbra Daffodil (v10.1), you will be prompted to enter the license key. The installer will validate whether the provided license key is valid or not. If valid, it will continue with the upgrade else it will give an error and abort the upgrade.

      DO NOT use --skip-activation-check if you are using Online/Automatic license. In case you use it, services will not start after the upgrade until you activate Zimbra Daffodil (v10.1) Online License.
  7. Offline Activation

    1. If you are using an Offline License, you will have to pass the parameter --skip-activation-check to skip the license check.

      After the upgrade, perform the Offline License Activation immediately else there will be downtime for the users until the license is activated. Please refer to the Offline License Activation section for more details.
  8. When upgrading, a new menu of License Activation, Store Configuration → zimbra-store has been added. Under License Activation, it will display following options:

    1. Activate license with installation - This is an online method of activation. You need to specify the 18-26 alphanumeric character license key.

    2. Activate license after installation - In case you have not received the license key or want to use the offline method of license activation, you can choose this option. The installation will be completed but the services will not be started.

If the LDS is not installed or not running, Zimbra’s network features will not be able to validate and will be disabled which will affect Zimbra’s functionality.

Multi-Server In-place Upgrade:

  1. When upgrading a multi server setup with a single mailbox server, the LDS has to be installed on the server that has internet access. Following are a few examples:

    1. LDAP, MTA, Proxy, Mailbox:

      1. Install LDS on the Mailbox server.

      2. Mailbox server is the node that connects to LDS service for all transactions related to licensing.

      3. If the LDS is installed on the mailbox node, then it will identify that the LDS service is running on it’s own node and does not need to connect to any other node.

    2. LDAP, MTA, Proxy, Mailbox:

      1. Install LDS on any of the server - LDAP, MTA or Proxy.

      2. When upgrading Mailbox server, the installer will identify the LDS node from the LDAP database and continue the upgrade.

      3. In case the server failed to connect the LDS server, the installer will print a warning license-daemon should be running and healthy and abort the upgrade. Please refer to the Troubleshooting section.

      4. Review the connection to the LDS server and restart the upgrade.

Rolling Upgrade:

  1. When upgrading, the LDS has to be installed on the server that has internet access. Following are a few examples:

    1. LDAP, MTA, Proxy, Mailbox1, Mailbox2:

      1. Install LDS on the Mailbox1 server.

      2. When upgrading Mailbox2 server, enter N for zimbra-license-daemon.

      3. It will then prompt you to specify the LDS node hostname which is the Mailbox1 server in this case.

    2. LDAP, MTA, Proxy, Mailbox1, Mailbox2:

      1. Install LDS on any of the server - LDAP, MTA or Proxy.

      2. When upgrading Mailbox servers, the installer will identify the LDS node from the LDAP database and continue the upgrade.

      3. In case the server failed to connect the LDS server, the installer will print a warning license-daemon should be running and healthy and abort the upgrade. Please refer to the Troubleshooting section.

      4. Please review the connection to the LDS server and restart the upgrade.

Before you upgrade

Please review the following information to decide if Zimbra Daffodil (v10) is suitable for you.

  • Zimbra Touch Client, Zimbra Mobile Client, and Zimbra HTML (Standard) Client are no longer a part of Zimbra starting from Version 9.0.0.

  • A Zimbra Network Edition license is required to use Zimbra Daffodil (v10).

  • The customizations implemented for SAML and SPNEGO will be overridden during updrade. It is recommended to backup these configurations before upgrade.

  • In case of rolling upgrades, if some mailstore nodes are upgraded to Zimbra 10 and some mailstore nodes are on Zimbra 9.0.x or Zimbra 8.8.15 then, zimbraReverseProxyUpstreamLoginServers should only contain list of Zimbra 10 mailboxes. If this is not followed then in some cases, users on Zimbra 10 mailstore nodes will not be able to see Modern Web App after login.

  • Zimbra 10 continues to support two versions of Zimbra Web Client — Modern and Classic.

    • To know more about highlights of the Modern Web App, please refer to Introducing the Modern Web Application

    • The Classic Web App offers the same functionality as the Advanced Web Client in Zimbra version 8.8.15.

    • Existing customized themes, logo branding changes, and crontab changes are incompatible with, and hence do not reflect in the Modern Web App. Branding needs to be re-configured to work with the Modern Web App. The Modern Web App does not currently support themes. Please refer to the Customizing Modern Web App section of Admin Guide for more information related to configuration.

    • Zimlets are supported on both the Web Clients.

    • Zimlets that work with the Classic Web App are incompatible with the Modern Web App. And due to technology changes, there is no way to migrate the Zimlets from the Classic Web App to the Modern Web App or vice-versa.

  • If you are using a RHEL based server (RHEL, Oracle Linux, Rocky Linux, Centos) then, please install pax/spax package on MTA node.

    • CentOS 7 and derivatives

      yum install pax
    • CentOS 8 and derivatives

      dnf install spax
  • Recommendations when using zmmboxmove

    • Always take full backup before doing zmmailboxmove.

    • zimbraMailboxMoveSkipBlobs and zimbraMailboxMoveSkipHsmBlobs attributes should be FALSE when doing mailboxmove

    • Always recommended to run HSM and move blobs to current primary / secondary volumes in case of multiple primary / secondary volumes present in system before doing mailboxmove

    • If you want to add new current secondary volume then customer need to use blobmover cli to move blobs from previous secondary volume to new volume

    • zmmailboxmove command should be run from Zimbra 10 mailbox

Be sure to read the release notes information before upgrading.

Supported Upgrade Paths

With this release the following upgrade paths are currently supported. Other upgrade paths will be supported in upcoming releases of Zimbra 10.

Setup Support

Single Node, without NG modules, in-place upgrade

Supported

Single Node, with NG modules, in-place upgrade

Supported**

Multi-Node, without NG modules, in-place upgrade

Supported

Multi-Node, with NG modules, in-place upgrade

Supported**

Rolling upgrade, without NG modules

Supported

Rolling upgrade, with NG modules

Supported**

** For guidance on upgrade with NG Modules, please refer to Migration Resources for NG Users section at https://www.zimbra.com/product/documentation/.

Database Integrity Checking

Some customers have had corrupted databases prior to upgrade, and the upgrade has in some of those cases exacerbated the problem. In order to detect any corrupted databases as early as possible, we have added an optional step to check the MariaDB database with zmdbintegrityreport prior to making any system changes. You are prompted to decide if you would like to run the zmdbintegrityreport.

zmdbintegrityreport can take minutes to an hour to run, depending on your system size and disk bandwidth.

zmdbintegrityreport is run on a weekly basis from cron on all zimbra-store nodes. Large sites can opt to disable this by setting zmlocalconfig -e zmdbintegrityreport_disabled=TRUE. If you choose to disable this, it is recommended that the integrity reports be run by hand during your normal maintenance windows and prior to running any Zimbra 10 upgrades.

Preparing your operating system

Before you upgrade, Zimbra recommends that the operating system is updated with the latest patches that have been tested with Zimbra Daffodil.

Ubuntu OS

  • Ubuntu 20.04 LTS Server Edition (64-bit)

  • Ubuntu 18.04 LTS Server Edition (64-bit)

Red Hat Enterprise Linux/CentOS Linux/Rocky Linux

  • If running the RHEL linux distribution, you must have a current valid license from RedHat.

  • The server must have a valid yum or apt-get configuration so that it can reach the Zimbra package servers.

  • RedHat® Enterprise Linux® 7 and 8 AS/ES (64-bit)

  • CentOS Linux® 7 (64-bit)

  • Oracle Linux® 7 and 8 (64-bit)

  • Rocky Linux® 8 (64-bit)

Zimbra Daffodil (v10.1) Licensing

With the introduction of the new license service within Zimbra Daffodil (v10.1) a new license service has been added named License Daemon Service (LDS) to allow enhanced and flexible license management.

The License Daemon is a required service to support the management of the license.

A Zimbra Collaboration license is required in order to create accounts and use Network features.

Following are the changes done to the licensing:

  1. A new license daemon is now part of the Zimbra installation. It gets displayed as zimbra-license-daemon in the modules list and is required for the normal functioning of Zimbra.

  2. A new format of the license, an 18-26 character alphanumeric key has been introduced replacing the older .xml file format.

When you purchase, renew, or change the Zimbra Collaboration license, you update the Zimbra Daffodil (v10.1) server with the new license information.

License Activation

  • At the beginning of an upgrade installation, you will be prompted to enter the license key. Without the new license key, you will not be able to proceed with the upgrade. Contact Zimbra Support to get the new license key for your upgrade.

  • One license key can be used for at the most for one Zimbra setup. You cannot reuse the same license key on the multiple setup.

  • An upgrade will not proceed without the license key.

All Zimbra Daffodil (v10.1) upgrades require license activation and continues to support the Automatic and Manual license methods. Zimbra Daffodil (v10.1) onwards, the terms has been changed to Online Activation and Offline Activation.

License activation is automatic during the upgrade with systems that have external access to the Zimbra license servers. A method of Offline License activations will be provided for systems that do not have external access to the Zimbra license servers. Please refer to the Offline License Activation section for more details.

When you upgrade to Zimbra Daffodil (v10.1) license, all the network features will now be enforced as per your licensing limit. Network features which are not part of your license, will not be available for use.

Update Default Proxy SSL Ciphers Attribute

Whenever upgrading, it is recommended that you check the values of the following attributes (zmprov gcf <attr>) and compare them with the current default values (zmprov desc -a <attr>).

zimbraReverseProxySSLCiphers
zimbraReverseProxySSLProtocols
zimbraSSLExcludeCipherSuites
zimbraMailboxdSSLProtocols
If you have not performed any recent hardening of your settings, your config should already match the Zimbra 10 default; and no action would be required.

In addition, it is recommended to make the following changes:

  1. Remove the following from zimbraReverseProxySSLCiphers:

    ECDHE-RSA-RC4-SHA
    ECDHE-ECDSA-RC4-SHA
    RC4-SHA
  2. Add the following to zimbraReverseProxySSLCiphers:

    !RC4
    See https://wiki.zimbra.com/wiki/Cipher_suites for the most current information on cipher suite configuration.

Customizing ZCO Installations

Administrators who want to customize the ZCO installation MSI should use the unsigned version of the MSI (ZimbraConnectorOLK_nnnn_xnn-unsigned.msi), available in the Zimbra download directory. The modified MSI should then replace the standard signed MSI (ZimbraConnectorOLK_nnnn_xnn.msi) in order to be available to end users from /downloads/index.html and the ZCO auto-upgrade process. (Bug 85067).

Upgrade Instructions

Download the Software

Go to http://www.zimbra.com/downloads/zimbra-collaboration to access the downloads section.

  • Before you begin the upgrade, make sure you have a good backup for all users!

Follow the instructions in this release note to perform the upgrade. For additional information, refer to the installation guide.

Zimbra recommends that an install or upgrade session be run with a UNIX command such as screen to help prevent an install or upgrade session from terminating before it is completed. This is important when the upgrade includes restoring a configuration that has a large number of accounts.

Example command usage:

screen ./install.sh

Single Server Upgrade Steps

You do not need to stop the services before upgrading. The upgrade process automatically stops and starts the services as required for the upgrade.

  1. It is required to obtain a new license key before upgrading to Zimbra Daffodil (v10.1) to ensure the license features are enabled after the upgrade. You will not be able to upgrade the servers without the new license key.

Zimbra Daffodil (v10) does not support upgrade from previous versions with NG modules installed. For guidance on upgrade with NG Modules, please refer to Migration Resources for NG Users section at https://www.zimbra.com/product/documentation/.

Following error message is displayed if you try to upgrade when NG modules are installed.

NG Modules detected on this system. If you continue with this upgrade, NG module packages and the associated data will be deleted.
If you want to preserve NG data, consider migrating or a rolling upgrade strategy for upgrading your system. For more information, please contact Zimbra Support.
If you still want to continue, start upgrade using --skip-ng-check.

Process

  1. Log in as root to the Zimbra 10 server and cd to the directory where the Zimbra Daffodil (v10) archive tar file is saved. For example, cd /var/tmp. Then type the following commands:

    Unpack the file

    tar xzvf zcs.tgz

    Change to the correct directory.

    cd <expanded-directory>

    Begin the upgrade installation.

    ./install.sh
  1. DO NOT use --skip-activation-check if you are using Online/Automatic license. In case you use it, services will not start after the upgrade until you install Zimbra Daffodil (v10.1) Online License.

  2. If you are using an Offline/Manual license, use --skip-activation-check to upgrade the servers. After the upgrade, services will be down until you install Zimbra Daffodil (v10.1) Offline License.

  1. At the start of the upgrade, you will be prompted to enter the license key:

    # ./install.sh
    Operations logged to /tmp/install.log.0lN98RdO
    Checking for existing installation...
        zimbra-license-tools...FOUND zimbra-license-tools-8.8.15.1651485155-1
        zimbra-license-extension...FOUND zimbra-license-extension-8.8.15.1562147113-1
        zimbra-network-store...FOUND zimbra-network-store-8.8.15.1562147205-1
        .
        .
        .
    ZCS upgrade from 8.8.15 to 10.1.0 will be performed.
    Validating whether an existing license is expired or not and checking if it qualifies for an upgrade
    
    Please enter the license key (an alphanumeric string of 18-24 characters without any special characters):
  2. A validation check will be done if the provided license key is valid or not. In case the license key is not valid, an error will be displayed and upgrade will be aborted:

    # ./install.sh
    Operations logged to /tmp/install.log.0lN98RdO
    Checking for existing installation...
        zimbra-license-tools...FOUND zimbra-license-tools-8.8.15.1651485155-1
        zimbra-license-extension...FOUND zimbra-license-extension-8.8.15.1562147113-1
        zimbra-network-store...FOUND zimbra-network-store-8.8.15.1562147205-1
        .
        .
        .
    ZCS upgrade from 8.8.15 to 10.1.0 will be performed.
    Validating whether an existing license is expired or not and checking if it qualifies for an upgrade
    
    Please enter the license key (an alphanumeric string of 18-24 characters without any special characters):123456789012345678
    ERROR: VALIDATION ERROR: -5000
    Error while validating license
    Error: License is expired or not authorized for upgrade or cannot be upgraded.
           Aborting upgrade
  3. If the provided license key is valid, the upgrade will proceed to next step:

    # ./install.sh
    Operations logged to /tmp/install.log.0lN98RdO
    Checking for existing installation...
        zimbra-license-tools...FOUND zimbra-license-tools-8.8.15.1651485155-1
        zimbra-license-extension...FOUND zimbra-license-extension-8.8.15.1562147113-1
        zimbra-network-store...FOUND zimbra-network-store-8.8.15.1562147205-1
        .
        .
        .
    ZCS upgrade from 8.8.15 to 10.1.0 will be performed.
    Validating whether an existing license is expired or not and checking if it qualifies for an upgrade
    
    Please enter the license key (an alphanumeric string of 18-24 characters without any special characters):5332567329720607741
    SUCCESS: License valid
    License is valid and supports this upgrade.  Continuing.
    Validating ldap configuration
    If you have a valid a license key, you can pass it with the ./install.sh command - ./install.sh --licensekey 5332567329720607741. If the validation is successful, the upgrade will continue.
  4. The Zimbra 10 software agreement appears in 2 parts. Read this software license agreement and type Y when prompted.

  5. When Use Zimbra’s package repository [Y] appears, press Enter to continue. Your system will be configured to add the Zimbra packaging repository for yum or apt-get so it can install the Zimbra third party packages.

  6. When Do you wish to upgrade? [Y] is displayed, press Enter to continue. The upgrade packages are unpacked.

  7. For zimbra-license-daemon package, type Y.

    For single node upgrade, zimbra-license-daemon is required to be installed and the upgrade process will not continue if you type N.
  8. The packages are listed. The installer also lists packages that are not installed. If you want to install the packages at this time, type Y; otherwise press Enter. The upgrade checks that there is enough space to perform the upgrade. If there is not enough space, the upgrade stops.

  9. When The system will be modified. Continue? [N] is displayed, type Y and press Enter. The Zimbra 10 server is stopped, and the older packages are removed. The upgrade process verifies which version of Zimbra 10 is being run and proceeds to upgrade the services, restores the existing configuration files, and restarts the server. If you have a configuration with a large number of accounts created, this can take a while.

  10. If you have not set the time zone, you will be asked to set it. This sets the time zone in the default COS. The time zone that should be entered is the time zone that the majority of users in the COS will be located in.

  11. When the Configuration completes, press Enter.

  12. Once all the MTA nodes are upgraded to Zimbra Daffodil (v10), the following commands may be run to fix the default globalconfig values, if necessary.

    zmprov mcf zimbraMtaCommandDirectory /opt/zimbra/common/sbin
    zmprov mcf zimbraMtaDaemonDirectory /opt/zimbra/common/libexec
    zmprov mcf zimbraMtaMailqPath /opt/zimbra/common/sbin/mailq
    zmprov mcf zimbraMtaManpageDirectory /opt/zimbra/common/share/man
    zmprov mcf zimbraMtaNewaliasesPath /opt/zimbra/common/sbin/newaliases
    zmprov mcf zimbraMtaSendmailPath /opt/zimbra/common/sbin/sendmail
  13. DSPAM is no longer shipped starting Zimbra Collaboration 8.7. Please enter the following commands to disable it.

    zmprov ms `zmhostname` zimbraAmavisDSPAMEnabled FALSE
    zmlocalconfig -e amavis_dspam_enabled=false
    zmamavisdctl restart
  14. It is recommended that you perform a full backup after a major upgrade, due to database schema changes.

  15. Activate your Offline License. After the upgrade, services will be down until you install Zimbra Daffodil (v10.1) Offline License. Please refer to Offline License section for more details.

  16. For the next steps after the upgrade, refer to the section After the Upgrade is Complete.

Multi-Server Environment Upgrade Steps

Before you begin the upgrade, please review the following details related to the license daemon service (LDS):

  • When upgrading a multi-server setup, the LDS has to be installed on the server that has internet access - LDAP, Proxy, MTA, Mailstore.

Zimbra recommends installing LDS either on a dedicated server or on the server that has internet access in the following preference - Proxy OR MTA OR Mailstore node.
  • You also have a flexibility of setting up a dedicated LDS node.

  • In case you plan to setup a dedicated LDS server, please note that it has to be installed after upgrading the LDAP server and before upgrading a mailbox server. Please refer to Installing Separate LDS node section for detailed steps.

  • In case you plan to upgrade multiple mailbox servers and have not installed the LDS on any of the other nodes (LDAP, MTA, Proxy), then the LDS has to be installed on the first mailbox which will be upgraded in the setup.

    • Following steps needs to be performed when upgrading the other mailbox servers:

      • Select N for Install zimbra-license-daemon option.

        Install zimbra-license-daemon [Y] N
      • Installer will show the following prompt. Enter 'Y'

        Have you installed zimbra-license-daemon package on different node: Y
      • Installer will prompt to enter the host where the LDS is installed. Specify the <mailbox1> hostname:

        Please enter the zimbra-license-daemon host: mailbox1.server.com
      • If LDS is running on mailbox1.server.com server, the installation will continue.

      • In case the server failed to connect the LDS on mailbox1.server.com, the installer will print the message license-daemon should be running and healthy and abort the installation. Please review the connection to the server and restart the installation.

You can also setup a dedicated LDS node. Please refer to Installing Separate LDS node section for detailed steps.

Upgrade the servers in the following order. Update each server one at a time, following the instructions under Process below.

  1. LDAP master server. The LDAP master servers must all be upgraded before proceeding, and they must be running as you upgrade the other servers.

  2. LDAP replicas

  3. MTA servers - see Using LMDB as the Supported Back-end for On-disk Database Maps.

  4. Proxy servers

  5. Setup new OnlyOffice server

  6. Mailstore servers

Process

  1. Log in as root to the Zimbra 10 server and cd to the directory where the Zimbra Daffodil (v10) archive tar file is saved. For example, cd /var/tmp. Then type the following commands:

    Unpack the file

    tar xzvf zcs.tgz

    Change to the correct directory.

    cd <expanded-directory>

    Begin the upgrade installation.

    ./install.sh
  1. DO NOT use --skip-activation-check if you are using Online/Automatic license. In case you use it, services will not start after the upgrade until you install Zimbra Daffodil (v10.1) Online License.

  2. If you are using an Offline/Manual license, use --skip-activation-check to upgrade the servers. After the upgrade, services will be down until you install Zimbra Daffodil (v10.1) Offline License.

  1. At the start of the upgrade, you will be prompted to enter the license key:

    # ./install.sh
    Operations logged to /tmp/install.log.0lN98RdO
    Checking for existing installation...
        zimbra-license-tools...FOUND zimbra-license-tools-8.8.15.1651485155-1
        zimbra-license-extension...FOUND zimbra-license-extension-8.8.15.1562147113-1
        zimbra-network-store...FOUND zimbra-network-store-8.8.15.1562147205-1
        .
        .
        .
    ZCS upgrade from 8.8.15 to 10.1.0 will be performed.
    Validating whether an existing license is expired or not and checking if it qualifies for an upgrade
    
    Please enter the license key (an alphanumeric string of 18-24 characters without any special characters):
  2. A validation check will be done if the provided license key is valid or not. In case the license key is not valid, an error will be displayed and upgrade will be aborted:

    # ./install.sh
    Operations logged to /tmp/install.log.0lN98RdO
    Checking for existing installation...
        zimbra-license-tools...FOUND zimbra-license-tools-8.8.15.1651485155-1
        zimbra-license-extension...FOUND zimbra-license-extension-8.8.15.1562147113-1
        zimbra-network-store...FOUND zimbra-network-store-8.8.15.1562147205-1
        .
        .
        .
    ZCS upgrade from 8.8.15 to 10.1.0 will be performed.
    Validating whether an existing license is expired or not and checking if it qualifies for an upgrade
    
    Please enter the license key (an alphanumeric string of 18-24 characters without any special characters):123456789012345678
    ERROR: VALIDATION ERROR: -5000
    Error while validating license
    Error: License is expired or not authorized for upgrade or cannot be upgraded.
           Aborting upgrade
  3. If the provided license key is valid, the upgrade will proceed to next step:

    # ./install.sh
    Operations logged to /tmp/install.log.0lN98RdO
    Checking for existing installation...
        zimbra-license-tools...FOUND zimbra-license-tools-8.8.15.1651485155-1
        zimbra-license-extension...FOUND zimbra-license-extension-8.8.15.1562147113-1
        zimbra-network-store...FOUND zimbra-network-store-8.8.15.1562147205-1
        .
        .
        .
    ZCS upgrade from 8.8.15 to 10.1.0 will be performed.
    Validating whether an existing license is expired or not and checking if it qualifies for an upgrade
    
    Please enter the license key (an alphanumeric string of 18-24 characters without any special characters):5332567329720607741
    SUCCESS: License valid
    License is valid and supports this upgrade.  Continuing.
    Validating ldap configuration
    If you have a valid a license key, you can pass it with the ./install.sh command - ./install.sh --licensekey 5332567329720607741. If the validation is successful, the upgrade will continue.
  4. The Zimbra 10 software agreement appears in 2 parts. Read this software license agreement and type Y when prompted.

  5. When Use Zimbra’s package repository [Y] appears, press Enter to continue. Your system will be configured to add the Zimbra packaging repository for yum or apt-get so it can install the Zimbra third party packages.

  6. When Do you wish to upgrade? [Y] is displayed, press Enter to continue. The upgrade packages are unpacked.

  7. For zimbra-license-daemon package, type Y.

    For single node upgrade, zimbra-license-daemon is required to be installed and the upgrade process will not continue if you type N.
  8. The packages are listed. The installer also lists packages that are not installed. If you want to install the packages at this time, type Y; otherwise press Enter. The upgrade checks that there is enough space to perform the upgrade. If there is not enough space, the upgrade stops.

  9. When The system will be modified. Continue? [N] is displayed, type Y and press Enter. The Zimbra 10 server is stopped, and the older packages are removed. The upgrade process verifies which version of Zimbra 10 is being run and proceeds to upgrade the services, restores the existing configuration files, and restarts the server. If you have a configuration with a large number of accounts created, this can take a while.

  10. If you have not set the time zone, you will be asked to set it. This sets the time zone in the default COS. The time zone that should be entered is the time zone that the majority of users in the COS will be located in.

  11. When the Configuration completes, press Enter.

  12. Once all the MTA nodes are upgraded to Zimbra Daffodil (v10), the following commands may be run to fix the default globalconfig values, if necessary.

    zmprov mcf zimbraMtaCommandDirectory /opt/zimbra/common/sbin
    zmprov mcf zimbraMtaDaemonDirectory /opt/zimbra/common/libexec
    zmprov mcf zimbraMtaMailqPath /opt/zimbra/common/sbin/mailq
    zmprov mcf zimbraMtaManpageDirectory /opt/zimbra/common/share/man
    zmprov mcf zimbraMtaNewaliasesPath /opt/zimbra/common/sbin/newaliases
    zmprov mcf zimbraMtaSendmailPath /opt/zimbra/common/sbin/sendmail
  13. DSPAM is no longer shipped starting Zimbra Collaboration 8.7. Please enter the following commands to disable it.

    zmprov ms `zmhostname` zimbraAmavisDSPAMEnabled FALSE
    zmlocalconfig -e amavis_dspam_enabled=false
    zmamavisdctl restart
  14. It is recommended that you perform a full backup after a major upgrade, due to database schema changes.

  15. Activate your Offline License. After the upgrade, services will be down until you install Zimbra Daffodil (v10.1) Offline License. Please refer to Offline License section for more details.

  16. For the next steps after the upgrade, refer to the section After the Upgrade is Complete.

Using LMDB as the Supported Back-end for On-disk Database Maps

Starting with Zimbra Collaboration 8.5 and later, Postfix is linked to LMDB, the same back-end Zimbra 10 uses with OpenLDAP. Prior to Zimbra Collaboration 8.0, Postfix was linked to Berkeley DB.

Zimbra 10 has not officially supported using any Postfix on-disk database maps prior to Zimbra Collaboration 8.5. However, these have been used through custom non-preserved modifications to the postconf configuration. These modifications will be lost on upgrade.

To restore the modifications post-upgrade, the following steps need to be performed:

  1. Run postmap against the database input file to generate an LMDB database.

  2. It will be necessary to iterate through the postconf keys that have hash:/path/to/db values and update them in LDAP to use lmdb:/path/to/db values instead.

Many previously unsupported features that could be used with on-disk database maps are now fully supported by Zimbra 10. Check if your customizations are correctly carried forward when upgrading. See Bug 77586.

Offline License Activation

The method of generating and activating an Offline License in Zimbra Daffodil (v10.1) has changed. As a pre-requisite, a new package zimbra-nalpeiron-offline-daemon has to be installed on the server that is running the license daemon service. After installing the package, an offline daemon service is started which acts as a locally run license manager.

The Offline License activation will not work if the package is not installed or the offline daemon service is not running.
The Offline Daemon service is a critical and important service for the functioning of a Offline License and its management. You are recommended to have a service monitoring setup to check the state of the service.

Following is the architectural view of the Offline License process:

Offline License Flow 2

Following are the steps. Execute the commands as a root user:

As a pre-requisite, FIPS should be disabled on the system before installing the packages. This is required only when using Offline License Activation

Following are the steps to disable FIPS. Execute the commands as root user:

  • For RHEL/CentOS/Rocky Linux systems:

    sudo fips-mode-setup --disable
    sudo reboot
    • Verify FIPS is disabled. Check the /proc/sys/crypto/fips_enabled file. If disabled, following will be the output:

      $ cat /proc/sys/crypto/fips_enabled
      0
  • For Ubuntu systems:

    sudo ua disable fips
    sudo reboot
    • Verify FIPS is disabled. Check the /proc/sys/crypto/fips_enabled file. If disabled, following will be the output:

      $ cat /proc/sys/crypto/fips_enabled
      0

Following are the steps to install the offline daemon packages:

  • For RHEL/CentOS/Rocky Linux systems:

yum clean metadata
yum check-update
yum install zimbra-nalpeiron-offline-daemon
  • For Ubuntu systems:

apt-get update
apt-get install zimbra-nalpeiron-offline-daemon
  • Verify the nalpdaemon service is active:

$ systemctl status nalpdaemon
● nalpdaemon.service - Nalpeiron Licensing Daemon
   Loaded: loaded (/usr/lib/systemd/system/nalpdaemon.service; enabled; vendor preset: disabled)
   Active: active (running) since Sat 2024-06-08 02:03:37 EDT; 1s ago

In case the service is not active, restart the service:

$ systemctl restart nalpdaemon

As a zimbra user, restart the LDS and configdctl service:

$ su - zimbra
$ zmlicensectl --service restart
$ zmconfigdctl restart

Requesting and Activating Offline license

The method is supported through Admin Console and CLI.

Following are the steps:

Admin Console

  1. Contact Sales and get the Network Key and License Key.

  2. Login to Admin Console and go to Home → Get Started → Install Licenses → Offline Activation

  3. Under Step 1, specify the Network Key and License Key and click on Generate Activation Request.

  4. After the network and product activation files are generated successfully, Download button will appear next to the text box.

  5. Click on Download button next to the text box and save the files. The name and filetype will be pre-populated when saving - network_activation_fingerprint, product_activation_fingerprint.

  6. Login to Support Portal and select the License tab.

  7. Select Generate an Offline License Activation file for versions 10.1 or greater.

  8. Specify the Product License Key and Network License Key.

  9. Copy the contents of network_activation_fingerprint.txt file and paste in the Network Activation Fingerprint text box.

  10. Copy the contents of product_activation_fingerprint.txt file and paste in Product Activation Fingerprint text box.

  11. Specify the product version in Product Verstion text box.

  12. Click on Generate License Certificate

  13. Save the generated License Activation XML file.

  14. Go back to the Admin Console License page.

  15. Under Offline Activation → Step3, upload the License Activation XML file and click on Activate.

  16. After successful activation, you will see a success message - Your license is successfully activated.

Command Line

  1. Contact Sales and get the Network Key and License Key.

  2. As a zimbra user, run zmlicense command to generate Network Key and License Key

    zmlicense --offlineActivationRequestCert --network <network_key> --product <product_key>
  3. Save the certificates printed on the screen as network_activation_fingerprint.txt, and product_activation_fingerprint.txt.

  4. Login to Support Portal and select the License tab.

  5. Select Generate an Offline License Activation file for versions 10.1 or greater.

  6. Specify the Product License Key and Network License Key.

  7. Copy the contents of network_activation_fingerprint.txt file and paste in the Network Activation Fingerprint text box.

  8. Copy the contents of product_activation_fingerprint.txt file and paste in Product Activation Fingerprint text box.

  9. Specify the product version in Product Verstion text box.

  10. Click on Generate License Certificate

  11. Save the generated License Activation XML file on the server.

  12. As a zimbra user, run zmlicense command to activate the offline license

    zmlicense -A /path_to_XML/activation_file.xml
  13. After successful activation, you will see a success message - Your license is successfully activated.

If you have problems accessing the Support Portal or facing any issues when activating the Offline License, contact Zimbra Sales or Support.

License Daemon Service [LDS]

The License Daemon Service (LDS) is a new service that communicates with the Zimbra License Server in online mode and the LAN daemon (local installation) in offline mode.

LDS is responsible for managing license information with Zimbra License Server. During Install/Upgrade, it gets displayed as zimbra-license-daemon in the modules list and is a required service. All real-time licensing operations are carried out through the LDS.

The license daemon service is a critical and important service for normal functioning of Zimbra and license management. You are recommended to have a service monitoring setup to check the state of the service.

Overview

  1. LDS is a simple Java service that is included when you install Zimbra.

  2. It offers an API for managing licenses, like activating them, allocating features for accounts, or releasing them.

  3. It is secure because it uses TLS Authentication, and only mailstores can access it.

  4. It keeps a local cache of licenses.

  5. The LDS is a required service to support the management of the license.

  6. If the license daemon service is not installed or not running, Zimbra’s network features will not be able to validate and will be disabled which will affect license functionality and account management.

  7. You can use the zmlicensectl command to manage the service.

Following is the architecture view:

LDS Architecture 2

System Requirements

LDS is not a resource intensive (CPU / Memory) service.

If it is deployed on a dedicated node, below minimum configurations are required: If deploying on a dedicated node, following are the minimum system requirements:

  • Processor Family: Intel/AMD w/ PassMark CPU Mark > 7,000

  • vCPU count: 2

  • RAM (GB): 8

Ports

Following ports on LDS node should be internally accessible from Mailbox:

Process Port

LDS

8081

Offline LAN daemon

80

Offline pg daemon

16700

Following ports should be externally accessible from LDS:

Process Port

Http

80

Https

443

Installing a separate License Daemon Service node

To separate the license daemon service from rest of the Zimbra services, you can setup a dedicated LDS node. You need to setup this node after upgrading the LDAP server and before you begin to upgrade the Mailbox servers.

The package zimbra-license-daemon gets installed by default during Zimbra installation unless the administrator marks N for the package during Zimbra installation.

Type y and press Enter to install the zimbra-license-daemon package.

Install zimbra-license-daemon [Y]

Installing the zimbra-license-daemon package on a separate server

Unpack the Zimbra Daffodil (v10.1) and execute the installer script ./install.sh.

Type y and press Enter to install the zimbra-license-daemon package.

Select the packages to install

Install zimbra-ldap [Y] N

Install zimbra-logger [Y] N

Install zimbra-mta [Y] N

Install zimbra-dnscache [Y] N

Install zimbra-snmp [Y] N

Install zimbra-license-daemon [Y] Y

Install zimbra-store [Y] N

Install zimbra-apache [Y] N

Install zimbra-spell [Y] N

Install zimbra-convertd [Y] N

Install zimbra-memcached [Y] N

Install zimbra-proxy [Y] N

Install zimbra-archiving [N] N

Install zimbra-onlyoffice [Y] N

Install zimbra-patch [Y] N

Install zimbra-mta-patch [Y] N

Install zimbra-proxy-patch [Y] N

Complete the rest of the installation.

Setting up Mailbox Server

After the installation of the LDS Node is successfully completed, you can now install/upgrade the Mailbox servers.

Unpack the Zimbra Daffodil (v10.1) and execute the installer script ./install.sh.

If upgrading an existing mailbox server, provide a valid license key when prompted and continue till the package selection step.

ZCS upgrade from 8.8.15 to 10.1.0 will be performed.
Validating whether an existing license is expired or not and checking if it qualifies for an upgrade

Please enter the license key (an alphanumeric string of 18-24 characters without any special characters):5332567329720607741
SUCCESS: License valid
License is valid and supports this upgrade.  Continuing.
Validating ldap configuration

You can also specify the license key with the ./install.sh command. If the validation is successful, the installer will continue:

./install.sh --licensekey 5332567329720607741

If installing a new mailbox server, continue till the package selection step.

  • Following are the steps to setup mailbox server to use the dedicated LDS node:

    • Select N for Install zimbra-license-daemon option.

      Install zimbra-license-daemon [Y] N
    • Installer will show the following prompt. Enter Y

      Have you installed zimbra-license-daemon package on different node [N] Y
    • Installer will prompt to enter the host where the LDS is installed. Specify the LDS hostname:

      Please enter the zimbra-license-daemon host [] <LDS_Hostname>
    • If LDS is running on server, the installation will continue.

    • In case the server failed to connect the LDS, the installer will display the license-daemon should be running and healthy and abort the installation. Please review the connection to the server and restart the installation. Refer to Troubleshooting section for common errors and its solution.

LDS Management command zmlicensectl

A new command zmlicensectl has been introduced to manage the various operations for LDS.

Since the license daemon service is a critical and important service, this is not managed through the zmcontrol command. The zmcontrol command will show the status but you cannot start/stop/restart the LDS.

Following are the details on the options:

Operations Parameter Description

Display Help

--help

Display Help

Service Management

--service <arg>

Manage various operations

--service start, restart, stop, status

Start, Restart, Stop or Check the service status

--service setLogLevel=INFO,DEBUG,ERROR,WARN

Set the various log levels. Helpful for debugging.

--service setOfflineMode=true,false

Enable/disable the offline mode

Offline Service Management

--nalpeiron <arg>

When Offline License mode is enabled, this parameters is used to manage the offline service

--nalpeiron start, restart, stop, status

Start, Restart, Stop or Check the offline service status

Export offline Data

--exportOfflineLicenseData

Extracts offline license usage data for analysis and billing

Clear license directory

--clearLicenseWorkDir

A troubleshooting option for resolving potential license caching issues on LDS

Example:

  • To restart the LDS, execute the command as zimbra user:

zmlicensectl --service restart
  • To set the log level in debug mode, execute the command as zimbra user:

zmlicensectl --service setLogLevel=DEBUG
  • To change the license mode from Online to Offline, execute the command as zimbra user:

zmlicensectl --service setOfflineMode=true
  • To restart the LAN daemon required for offline mode, execute the command as zimbra user:

zmlicensectl --nalpeiron restart
  • To export the Offline Usage data (required only for BSP’s), execute the command as zimbra user:

zmlicensectl --exportOfflineLicenseData

Troubleshooting

Logging

Following are the logs where all the licensing operations are logged:

  • Mailstore Logs:

    • Contains logs for the mailstore operations

    • Location: /opt/zimbra/log/mailbox.log

  • License Daemon Service logs

    • Contains logs relate to API communication between mailstore and LDS

    • Location: /opt/zimbra/log/license-daemon-service.log

  • Native Library Logs​

    • Contains library errors occurred while communicating to nalpeiron server.

    • Location: /opt/zimbra/license/work/15xx.log

Error conditions/codes

There might be scenarios where you encounter various license errors/code or specific errors.

Following are some of the common scenarios and their resolution:

License Activation Failed:
  • license-daemon should be running and healthy error when mailstore trying to connect to LDS:

    • Make sure LDS is up and running.

    • Check status - zmlicensectl --service status

    • If not running, Restart the service - zmlicensectl --service restart

  • Failed to activate License:

    • Make sure LDS node have internet access.

  • Invalid License error with code “4001”:

    • Verify license is not expired.

  • Invalid license error with code “-10116”:

    • Check Account has valid support end date.

  • Invalid license error with code  “-5000”:

    • Support end date might be empty.

  • Invalid license error with code  “-401”: 

    • License  activation restricted or license inactive.

  • Invalid license error with error code “4000”:

    • License usage are not valid. May happen if you are trying to change the license.

  • Invalid license error with code “4002”:

    • Trial cannot be activated on regular license setup.

Feature Check Failed:
  • Make sure LDS is up and running - zmlicensectl --service status

    • If not running, restart the LDS service - zmlicensectl --service restart

  • Failed to use server level features such as Backup Restore, Storage Management, etc.

    •  Make sure feature is authorized to use - zmlicense -fc <feature_code> ** If it is enabled, then restart the mailbox - zmmailboxdctl restart

  • Failed to enabled feature on account/cos: 

    • Make sure feature is authorized to use - zmlicense -fc <feature_code>

    • If feature is of type limit, then make sure you have sufficient limit available - zmlicense -p | grep -E '(EwsAccountsLimit)' -A3

    • If feature is of type limit, then make sure you have sufficient limit available - zmlicense -p | grep -E '(EwsAccountsLimit)' -A3

After the Upgrade is Complete

After you completed the upgrade, the following might need to be addressed.

  • If you have configured the following keys, you will need to replace them as described here.

The following keys are deprecated:

httpclient_client_connection_timeout
httpclient_connmgr_connection_timeout
httpclient_connmgr_idle_reaper_connection_timeout
httpclient_connmgr_idle_reaper_sleep_interval
httpclient_connmgr_keepalive_connections
httpclient_connmgr_max_host_connections
httpclient_connmgr_max_total_connections
httpclient_connmgr_so_timeout
httpclient_connmgr_tcp_nodelay

They are replaced by the following keys:

httpclient_internal_client_connection_timeout
httpclient_internal_connmgr_connection_timeout
httpclient_internal_connmgr_idle_reaper_connection_timeout
httpclient_internal_connmgr_idle_reaper_sleep_interval
httpclient_internal_connmgr_keepalive_connections
httpclient_internal_connmgr_max_host_connections
httpclient_internal_connmgr_max_total_connections
httpclient_internal_connmgr_so_timeout
httpclient_internal_connmgr_tcp_nodelay
httpclient_external_client_connection_timeout
httpclient_external_connmgr_connection_timeout
httpclient_external_connmgr_idle_reaper_connection_timeout
httpclient_external_connmgr_idle_reaper_sleep_interval
httpclient_external_connmgr_keepalive_connections
httpclient_external_connmgr_max_host_connections
httpclient_external_connmgr_max_total_connections
httpclient_external_connmgr_so_timeout
httpclient_external_connmgr_tcp_nodelay

Installing External Zimlets for Modern Web App

These five zimlets are available.

  • Slack

  • Zoom

  • Dropbox

  • Google Drive

  • Onedrive

You have to install and configure them for users to integrate and use these zimlets. Once you are done installing the zimlet(s), you need to restart the mailbox service before configuring them.

Slack

  • As root run the below command:

    RHEL

    yum install zimbra-zimlet-slack

    Ubuntu

    apt-get install zimbra-zimlet-slack

  • Restart mailbox service as a zimbra user:

su - zimbra
zmmailboxdctl restart

Zoom

  • As root run the below command:

    RHEL

    yum install zimbra-zimlet-zoom

    Ubuntu

    apt-get install zimbra-zimlet-zoom

  • Restart mailbox service as a zimbra user:

su - zimbra
zmmailboxdctl restart

Dropbox

  • As root run the below command:

    RHEL

    yum install zimbra-zimlet-dropbox

    Ubuntu

    apt-get install zimbra-zimlet-dropbox

  • Restart mailbox service as a zimbra user:

su - zimbra
zmmailboxdctl restart

Google Drive

  • As root run the below command:

    RHEL

    yum install zimbra-zimlet-google-drive

    Ubuntu

    apt-get install zimbra-zimlet-google-drive

  • Restart mailbox service as a zimbra user:

su - zimbra
zmmailboxdctl restart

Onedrive

  • As root run the below command:

    RHEL

    yum install zimbra-zimlet-onedrive

    Ubuntu

    apt-get install zimbra-zimlet-onedrive

  • Restart mailbox service as a zimbra user:

su - zimbra
zmmailboxdctl restart

Please visit Configuring Zimlets for Modern Web App for instructions for on how to configure zimlets for Modern Web App users.

Ephemeral Data Migration

Versions of Zimbra prior to 9.0.0 stored ephemeral data in LDAP. Examples of ephemeral data include:

  • zimbraAuthTokens

  • zimbraCsrfTokenData

  • zimbraLastLogonTimestamp

Zimbra Collaboration versions after 9.0.0 introduced the ability to store ephemeral data in an external service such as SSDB. This is an optional feature; however, it can improve LDAP performance and stability.

Please refer to the Zimbra Daffodil Administration Guide for more information. Migration of ephemeral data out of LDAP and into SSDB must be performed after an install or upgrade has been completed.

Remove Current Version and Perform Clean Install of Zimbra 10

If you do not want to upgrade, but prefer to install Zimbra Daffodil (v10) as a new installation, when you run the Zimbra Daffodil (v10) install script, enter N when asked Do you wish to upgrade?

A warning displays asking if you want to delete all existing users and mail. If you enter Yes, all users, mail, and previous files are removed before proceeding with the new installation. Refer to the installation guides for installation instructions.

Status of Your Customization after Upgrade

Upgrading to the newest release does not delete your accounts or change your configuration. Configuration settings stored in LDAP and localconfig are preserved during upgrades. Any files installed by Zimbra Daffodil might be deprecated and/or overwritten during upgrades, removing any customizations. This includes customized themes, logo branding changes, and crontab changes.

Branding needs to be re-configured to work with the Modern Web App. And the Modern Web App currently does not support themes.

Only the core Zimlets are enabled after the upgrade. Zimlets that you customized and/or deployed are preserved during the upgrade but will be disabled. As upgrading of customized Zimlets cannot be tested before the release, Zimbra recommends that you verify that your customized Zimlets work correctly before re-enabling them for your end-users after the upgrade.

Zimlets are supported on both the Classic Web App and the Modern Web App. However, Zimlets used for Classic Web Client are not compatible with the Modern Web App. Currently, there is no way to migrate the zimlets from Classic to the Modern Web App or vice-versa. Existing zimlets need to be re-developed for them to work on the Modern Web App.

All entries between the designated comments in the Zimbra 10 crontab file are overwritten with new defaults upon upgrade. Customized backup schedules stored in the Zimbra 10 crontab and customizations to the crontab entry outside the designated comments are preserved.