Developers Documentation



301 error for file:

User Tools

Site Tools

Upgrading from ClearOS 5.x to ClearOS 6

This guide contains an overview of the requirements and tasks associated with migrating from ClearOS 5.x to ClearOS 6. There are a number of changes which make ClearOS difficult to go from 5 to 6. Namely, there are changes in the LDAP system with the password structure and also with the mail attributes to the database (Horde).

Getting Ready

Different aspects of your server can be individually migrated but this mostly entails backing up the data and running scripts that transform that configuration data into a ClearOS 6 format.

We offer this service for free through support for clients who upgrade to ClearOS Professional Premium and for a fixed cost of $250 for other versions of ClearOS Professional.

The scope of the project largely depends on 3 things:

  • Will the transition take place from one hardware box to another or do you require that we use the same hardware.
  • Do you have users and groups defined on the old box? In particular, are you using ClearOS as a Windows Domain Controller.
  • Do you have any custom, community-based, or 3rd party apps installed on your old system that need special consideration?

Once we know these things, we can help create an action plan for a migration. We are available on nights and weekends to complete this with as little disruption as possible with advanced notice so that our engineers can be available. If you have multiple systems, we can also impart all of the ins and outs so that you are comfortable doing the migrations on your own.

You will want to make sure that your original system is up to date before starting the migration.

yum update

Next, make sure to backup your system. Backup everything. Better yet, use a new hard drive and retain your existing structure.

Upgrade by Technology

This document is still in progress; if your section does NOT yet exist, please contact support. Additionally, the information here is provided As Is without any warranty. Be sure to have a solid backup of your data or even better, use a different drive or system for your new ClearOS 6 system.




There are 4 different mail systems currently on ClearOS.

  • Zarafa Community Edition
  • Zarafa Small Business Edition
  • Google Apps
  • Cyrus IMAP and POP server

The migration of mail services is can be a difficult transition if you don't have a plan. If you are using the functions of Horde, you will NOT be able to keep Horde related settings in the migration. If you just use ClearOS for POP3 or IMAP, then this can be an easy transition for your users. The method of the transition depends on what you want to transition to:

Zarafa Community Edition

Here is an extensive guide for Zarafa migrations. Please use this guide and the followup document to migrate to Zarafa.

Zarafa Small Business Edition

Since you are coming off of POP3/LDAP, you will follow the same guide as above even if you are eventually moving to using Outlook as your email client.

Google Apps

If you are migrating to Google Apps, you will want to use a 2 machine approach so that you can stub in and create all of your users and structure on Google Apps before moving any user data. The key here is to not pull the trigger on the MX record change until the Google Apps integration is all functioning and test. Then switch the MX records. You will need to enable IMAP functionality under each user to move the data. Next, using their client's existing mail client, add the Google apps IMAP account.

This guide from Google covers how to do this.

Cyrus IMAP and POP server

With Cyrus, you have two options. Since Cyrus is what is running on 5.x, migrating the data to 6.x is a possibility. This will require more testing. However, to be very safe, you might want to use the two mail server approach. This entails keeping your existing server running and then having your clients attach to both servers. Alternately you can use the migration command line 'imapsync'


Migrating MySQL data is pretty straight forward. For MySQL, use the mysqldump command from command line. This howto covers both the backup and restore procedure.


For Directory services, you have two options with ClearOS 6:

  • OpenLDAP
  • Active Directory Connector

For OpenLDAP, currently you will need to contact ClearCenter support to have this option. While the code for the migration is published, it requires very close hand holding. It may be improved in the future but it is very much a tool for those who are intimately familiar with the backend of ClearOS. As stated above, if you are migrating from ClearOS 5.x to ClearOS Professional Premium, this service is included. Or you can pay a fixed price for other versions of ClearOS Professional which include support.

The process, which includes the migration of the Samba requirements of LDAP requires you to submit a password protected ZIP file of your configuration backup from 5.x. Navigate to System » Backup Settings in ClearOS 5.2 to get the file then use a zip program to password protect it. (ie. under Mac or Windows.) Once you have gotten your recovery file back from ClearCenter, you will need to follow these steps in order to successfully complete the import.

  • Install a ClearOS Professional 6.5 system, skip installing any Marketplace apps. In the Account Synchronization either select 'Master' (recommended) or Standalone.
  • Go to “System - Account Manager” in the menu and initialize the accounts system.
  • Go to “System - Configuration Backup” in the menu and import the attached file.
  • Install the Windows Networking app from the marketplace.
  • Go to “Server - Windows Networking” in the menu and initialize the software. Note: Samba is already initialized under the hood, but this step cleans up the old trivial database (TDB) files.

For the Active Directory Connector, there is no supported migration path for creating these users in Active Directory. If your directory is very large, consider using the export tool in 5.x to get a list of all your users in a spreadsheet. Then use AD LDIF tools to add the users. This guide can provide some assistance.

FTP Server

Windows Networking

Windows Networking is closely tied into the Directory server. Please refer to the directory process above for more information.


Web Server


Bandwidth Manager

The bandwidth manager is managed by the /etc/firewall file in ClearOS 5. See the Firewall subsection below for migration details.


If you have a lot of firewall rules, they can easily be migrated from one system to the next. The firewall rules configuration files change somewhat between 5 and 6.

  • ClearOS 5
    • /etc/firewall
  • ClearOS 6
    • /etc/clearos/firewall.conf
    • /etc/clearos/network.conf
    • /etc/clearos/bandwidth.conf
    • /etc/clearos/multiwan.conf

The bulk of the settings in an extensive firewall configuration are contained in the RULES section. ClearOS 6 uses the same format as ClearOS 5 for these rules, simply inject them into the appropriate RULES section in ClearOS 6.

The following states the location of the parameters in a ClearOS 5.x /etc/firewall file and where they have moved to:

  • MODE
    • /etc/clearos/network.conf
    • /etc/clearos/network.conf
    • /etc/clearos/network.conf
    • /etc/clearos/network.conf
    • /etc/clearos/network.conf
    • /etc/clearos/network.conf
    • /etc/clearos/dynamic_dns.conf
    • /etc/clearos/bandwidth.conf
    • /etc/clearos/bandwidth.conf
    • /etc/clearos/bandwidth.conf
    • /etc/clearos/multiwan.conf
    • /etc/clearos/multiwan.conf
    • /etc/clearos/firewall.conf
    • /etc/clearos/firewall.conf
    • /etc/clearos/firewall.conf
    • /etc/clearos/dynamic_vpn.conf
    • /etc/clearos/protocol_filter.conf
    • /etc/clearos/firewall.conf

After making changes, you can cause them to go into effect with the following command:

service firewall restart

Mistakes in firewall configuration can cause you to lose connectivity to your server. Ensure that you have a monitor and keyboard attached in case you need to stop the firewall (service firewall stop)

DHCP Server

DNS Server

NTP Server

IP Settings

There is no real migration path for IP settings other than to ensure that the network interface name are the same between the old and new system.



PPTP Server


MultiWAN is managed by the /etc/firewall file in ClearOS 5. See the Firewall subsection above for migration details.




Content Filter

Intrusion Prevention/Detection

content/en_us/kb_o_upgrading_from_clearos_5.x_to_clearos_6.txt · Last modified: 2017/10/25 14:01 by cjones