How can we help?


Upgrade CoS from v1.x to v2.x

Stewart -


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


  • atmail CoS


Requirement to upgrade CoS version.


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

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


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

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
  • Anti spam OFF
  • Anti Malware OFF
  • Anti spam ON
  • Anti Malware ON
  • Anti spam ON
  • Anti Malware OFF
  • 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.


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.


Contact our support team

+61 (7) 5357 6605