Skip to main content

BlueMind Major Version Update: Upgrade from v4 to v5

BlueMind's major version change requires special attention to a number of points. We recommend that you read the following page carefully, to help you prepare for the transition to the new version.

Check the points to watch​

Installation Prerequisites​

As with any upgrade, it's important to ensure that the prerequisites for installing BlueMind version 5 have been met.

For further information, see:

Disk space

BlueMind recommends paying particular attention to disk space requirements, which have changed with version 5.5: Installation requirements: Disk space.

BlueMind Version​

In order to upgrade to version 5, version 4 must be installed and up to date of the latest available version.

System​

Disk space​

In view of PostgreSQL's upgrade from version 14 to 16, the /var/lib/postgresql partition must have an occupancy rate of less than 50%.

Similarly, if archiving is in place, it is necessary to have at least 50% free space in the size of the fast spool.

Network​

Tika​

The memory value of the bm-tika service must be overestimated. To do this, create the file /etc//bm/local/bm-tika.ini with the values :

MEM=2028
DMEM=128

Hardware​

Hardware requirements have changed between BlueMind 4 and BlueMind 5. It is strongly recommended to consult Hardware Sizing to adjust the server configuration.

Specific setup​

CAS configuration​

In BlueMind 5, CAS configuration is carried out per domain, rather than for the entire server as in v4. The server's CAS configuration is therefore not migrated.

OpenID configuration​

In the case of a remote authentication service, ensure that it is properly configured and that you have a URL accessible from the BM server.

For further information, see:

Installation with Edge server​

In the case of an installation with an Edge server not managed by BlueMind, correct its Nginx configuration.

Discontinuation of the old type of shared mailboxes and group folders​

In BlueMind version 5.6, the legacy shared mailboxes — which were simply email inboxes — have been replaced by modern, fully-featured shared mailboxes.

The upgrade tool automatically handles the migration to the new version. Group mailboxes are migrated to independent shared mailboxes that are designated as group members and thus receive emails addressed to the group. They retrieve the emails they contained and the shares that were affected.

For further information see Release Notes 5.6 > Exchange-style shared mailboxes replace the old mailboxes.

Maximum size of stored emails​

The maximum email size currently supported by BlueMind is 96 MB; however, in versions prior to BlueMind 4.6.0, larger emails could be uploaded to the server using an IMAP client. It is therefore necessary to ensure that no emails larger than 96 MB remain on the server. The find command can be used to perform this search:

find /var/spool/cyrus/data/ -type f -size +96M
find /var/spool/bm-hsm/ -type f -size +96M

If messages are found, they must be deleted or moved out of BlueMind before continuing. For example, they can be placed in /var/backups/bluemind. They can then be returned to their owners, who will be able to view them using third-party client software but will not be able to restore them to BlueMind.

If the eligibility test has already been completed (see below), it must be repeated after the relevant emails have been deleted.

It is also necessary to ensure that the maximum allowed email size is set to less than 96 MB in the BlueMind configuration:

[ "$(bm-cli sysconf list | grep message_size | grep -oE '[0-9]+')" -lt $((100*1024*1024)) ] && echo "OK" || echo "KO"

↳ A KO response indicates that the value should be corrected.

For further information see the page System configuration > Mail.

Post-upgrade problems​

See known problems at the end of the page: Known problems

Start eligibility test​

Mandatory execution

This Eligibility Test must not be completed before updating BlueMind from v4 to v5.

A check-upgrade-v5 eligibility test, complemented by a pre-upgrade-5 verification test, have been added to CLI Admin Client to avoid any loss of data and ensure a controlled and secure upgrade to v5.

These tests verify these 5 major points:

  • Checking custom settings
  • Checking hotupgrades
  • Checking elasticsearch cluster status
  • Checking cyrus replication
  • Cyrus email checks

Execute and validate tests​

  1. Run the eligibility test by executing the following command:

    bm-cli setup check-upgrade-5 --force-delete-many-orphans

    **⚠️ Test duration and resource consumption

    Depending on sizing, the chek-upgrade-5 command can take over an hour. It is recommended to run in a screen or tmux session. Testing and subsequent maintenance operations can be resource-intensive. It is therefore recommended to perform them during long periods of low activity, for example at the end of the day.

  2. Execute the suggested repair commands, according to the faults identified. The command list follows as follows (example):

    Recommended repair commands to run: 
    bm-cli hotupgrade start --no-delay --scheduled
    bm-cli index coherency --all --run-consolidate --workers=1 all
    bm-cli maintenance repair --ops replication.parentUid 1518B471-729C-4C99-AEC0-86D4D87DCB12@734ea413.internal
    bm-cli maintenance repair --ops replication.parentUid,message_bodies B9584543-273B-43F0-A450-09FCB38526A6@734ea413.internal

  3. **Start the verification test **.

    ⚠️ Depending on the platform, this operation consumes resources and can therefore take some time. To reduce downtime at the time of the update, you can therefore play the pre-upgrade a few days before, so that it runs faster when replayed just before the update. To do this, run the following command in a screen or tmux session:

    bm-cli setup pre-upgrade-5

    This allows you to refresh the list of errors and potentially track those that have not been reported or repaired.

Transmitting results​

We strongly recommend that you forward the two log files generated (check-upgrade-5 and pre-upgrade-5) to the Support team via the creation of a ticket.

Update subscription​

The subscription should only be upgraded once the eligibility check has been approved.

Upgrading BlueMind to a major version change requires a change in the addresses of the software periods. The subscription file must therefore be updated for you to perform the version upgrade. For further information, see Setting up the subscription.

Purge trash​

During data transfer, e-mails in the double bottom of the recycle trash can and drafts marked for deletion (old draft versions) are not migrated. For further information on the use of the double-bottom trash can, see the documentation Recovering deleted emails.

To free up disk space, we recommend purging these emails before the upgrade (this is a Cyrus server-specific process, no longer used in version 5) with the following command:

cyr_expire -X 0

Then repair the boxes using the following options:

bm-cli maintenance repair --ops missed.deletions all

Run BlueMind Update​

Once the points to watch and eligibility test have been validated:

  1. Run the verification test again to ensure that no new errors have appeared since the initial validation:

    bm-cli setup pre-upgrade-5

    ⚠️ If any errors occur, please refer to Run eligibility test.

  2. Follow the procedure of Updating BlueMind

    ⚠️ Request Support

    If you encounter any difficulties, create a ticket containing the following information:

    • the contents of /var/log/ in tgz or zip format. If too large, please provide at least the following logs:
      • /var/log/bm/core.log
      • /var/log/bm/imap.log
      • /var/log/bm-webserver/webserver.log
      • /var/log/bm-webserver/setup.log
      • /var/log/bm-keycloak/keycloak.log
      • /var/log/postgresql/postgresql-??-main.log
    • the return of these commands: 
      bm-cli node status
      bmctl status
      nproc
      free -m
      df -h; 
      uptime

  3. Clean up backups v4

    ⚠️ Once the upgrade is complete, it is recommended that you purge the BlueMind 4 backups.

    BlueMind 5 backs up e-mails using a new method in /var/backups/bluemind/sds-spool. The first backup includes all e-mails, which can trigger a disk saturation alert if the available space is < 50%.

    V4 backups are no longer compatible. Removing them saves space.

Run post-upgrade operations​

Automatic BlueMind operations​

Background operations are performed after the update. They have been designed to run without impacting the service in production.

Some features are unlocked over time following these post-ugrade operations. These include advanced e-mail sorting and message conversation settings.

To check the progress of post-upgrade operations, run the command :

bm-cli hotupgrade progress --details --filterSuccess

If these operations fail, a banner appears in the administration console, informing administrators. In this case, create a ticket (or update the one concerning the eligibility test - see above) on our ticket tracking tool.

Nginx configuration​

If the Nginx configuration for a domain has been customized, copy the /etc/nginx/bm-local.d/\<domain>.conf file to /etc/nginx/bm-local.d/\<xxxxxtechnical_domain>/ and update the configuration there.

Known issues​

Quotas for some mailboxes are very different after the upgrade​

Quotas in version 5 are not calculated in the same way as in version 4, in which the data reported by Cyrus lacked reliability. In some cases, mailboxes may appear more or less full than they were before the upgrade.

Ref. BM-22057

DataProtect task in error​

When upgrading to Bluemind 5, one of the operations that takes place is a change of mail spool: e-mails are migrated from the cyrus spool to a Bluemind-specific spool. During this operation, the DataProtect task does not work properly and falls into error — if there are several terra-bytes of mail, this operation can take several days (the time depends on the speed of the disks, in addition to the volume of data).

Ref. BM-22759

Non-terminal filters​

The mail filters created since the old preferences were obligatorily terminal: once a filter had been applied to an email, no other filter was applied. With the new webmail and preferences, you can now choose whether a filter is terminal or not. When upgrading from BlueMind 4 to BlueMind 5, this option is not activated by the filter recovery, so all filters are non-terminal and can lead to confusing sorting for users.

Ref. BM-22085

Find out more​

Related BlueMind documentation pages

Related BlueMind Blog articles

Last updated on