PROBLEM

How can I upgrade my CoS (Class of Service) installation?

ENVIRONMENT

atmail CoS

CAUSE

Requirement to upgrade CoS version.

RESOLUTION

CoS v2.x can be installed on top of v1.x, which will leave all existing CoS 1.x data unchanged. This document covers how to migrate existing data from CoS 1.x into CoS 2.x.

Extra Database privileges

Migration process needs mysql database user having following privileges

Target	Priviliges
domains	select, update
accounts	select, update
cos_default, cos_accounts, cos_bundle, cos_profile, cos_profile_settings, cos_service_definition, cos_account_settings	full control
other	create temporary table

Database Backup

Please make sure your mailserver database backup has been done.

Upgrade Process

Download

If you have not already done so, add access to Atmail's on line software repository to your server by executing the following command:

bash <(curl -s https://repo.atmail.com/add_repo)

Install CoS v2

Install downloaded package via yum.

# yum install atmail-cosadm* -y -q

Install mail server 8.7.x

Upgrade mailserver database

CoS shares it's database with mailserver. Please use Cos Database Schema v2.1.x to update mailserver database.

Initialise on-premises

For on-premises installation, CoS needs to create a default virtual customer in order to function properly. We call this process 'initialise onprem'.

Please run below command:

# cosadm init-onprem

Above initialisation is required before the upgrade, and if there are new domain added into system after the upgrade. 

Create Profiles to cover legacy settings

Since CoS v2.x, a profile is used to control CoS settings for each user or domain. A profile is a set of preset CoS settings.

CoS profiles can be managed via the mail server admin portal. Login to mail server admin panel, go to Services > COS SERVICE > Manage Profile.

In Select a profile field, select Create new profile

Then input name (e.g Free) in New profile name area

Overwrite any system default settings as needed,

Then Save profile

Repeat above step to create other profiles.

Profiles need to be created to cover all current scenarios. For example:

Profile name	Settings
Free	Anti spam OFF Anti Malware OFF
Premium	Anti spam ON Anti Malware ON
Plus-A	Anti spam ON Anti Malware OFF
Plus-B	Anti spam OFF Anti Malware ON

There are some services (e.g total_quota, calendars etc), which are supported since CoS v2, should be assigned to proper profiles in above list, if system default value doesn't suit.

Above profile names are just examples, which can be changed to any text.

Upgrade

Below command will perform the upgrade

# cosadm upgrade

If the upgrade goes well, below message will be displayed

# cosadm upgrade
Congratulations! CoS upgrade completed.

Trouble shooting

Unmatched settings

The upgrading script will try to match cos 1.x user settings into cos 2.x profile which should have been created. If it cannot find proper profile to match, it will abort with below error.

Please create a profile to cover the combination: <settings>

Multiple matches

If multiple profiles match same cos 1.x settings, the first one found by the upgrading script will be chosen and the rests will be ignored.

How can we help?

Upgrade CoS from v1.x to v2.x