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.

Disappearance of old shared and group boxes​

In BlueMind version 5.6, the old-style shared boxes, which were simply mailboxes, have been replaced by modern, full-featured shared boxes.

The update tool automatically performs the migration to the new version, including group boxes that are positioned as group members and retrieve affected messages and shares.

For further information see the Release Notes 5.6 > Disappearance of old shared and group boxes.

Maximum size of stored messages​

On versions prior to BlueMind 4.6.0, large messages could be uploaded to the server using an IMAP client. It is therefore necessary to ensure that no messages larger than 100 MB remain on the server:

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

If messages are found, they must be deleted or moved out of BlueMind before continuing. They can, for example, be placed in /var/backups/bluemind and then returned to their owners.

It is also necessary to ensure that the maximum message size allowed is less than 100MB 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 Go to System configuration > Mail.

Post-upgrade problems​

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

Start eligibility test​

Execution required

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​

La souscription doit être mise à jour uniquement lorsque le test d'éligibilité est validé.

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 garbage 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

Lancer la mise à jour de BlueMind​

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. Suivre la procédure de Updating BlueMind

    ⚠️ Request Support

    En cas de difficulté, créer un ticket contenant les informations suivantes :

    • the contents of /var/log/ in tgz or zip format. Si trop important, fournir au minimum ces 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
    • le retour de ces commandes : 
      bm-cli node status
      bmctl status
      nproc
      free -m
      df -h; 
      uptime

  3. Nettoyer les sauvegardes v4

    ⚠️ Une fois la mise à jour terminée, il est recommandé de purger les sauvegardes de BlueMind 4.

    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.

Lancer les opérations post-mise à jour​

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