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 of vigilance
Installation requirements
As with any upgrade, it's important to ensure that the prerequisites for installing BlueMind version 5 have been met.
For further information, see:
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
- The KeyDB port must be authorized. For further information, see: BlueMind Ports
- External URL must be accessible. For further information, see:
Material
Hardware requirements have changed between BlueMind 4 and BlueMind 5. It is strongly recommended to consult Hardware sizing to adjust the server configuration.
Specific configurations
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:
- Setting up SSO with an external OpenID authentication server
- Configuring an OpenID client for BlueMind with a third-party Keycloak
Installation with Edge server
In the case of an installation with an Edge server not managed by BlueMind, correct its Nginx configuration.
Post-upgrade problems
See known problems at the end of the page: Known problems
Start the eligibility test {check-upgrade}
This Eligibility Test must not be completed before updating BlueMind from v4 to v5.
A check-upgrade-v5 eligibility test has been added to CLI Admin Client to avoid any loss of data and ensure a smooth and secure upgrade to v5.
This test checks these 5 major points:
- Checking custom settings
- Checking hotupgrades
- Checking elasticsearch cluster status
- Checking cyrus replication
- Cyrus email checks
Run and validate the test
- Run the test by executing the following command:
bm-cli setup check-upgrade-5 --force-delete-many-orphans
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.
Repair commands are then proposed, according to the failures 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
- Start a new verification once the recommended repairs are completed. 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 send our Support team the results of successive executions of these test commands via the creation of a ticket.
Update subscription
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, emails contained in the double bottom of the trash and drafts marked for deletion (old versions of drafts) are not migrated.
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
Start BlueMind upgrade
Once the prerequisites and eligibility test have been validated:
-
Follow the process of Updating BlueMind
⚠️ Support
In case of difficulty, create an issue ticket containing the following information:
- the contents of
/var/log/in tgz or zip format. If too large, provide at least these 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
- the contents of
-
Clean up v4 backups
⚠️ Once the update is complete, we recommend that you purge your 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-update 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 problems
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