Creating a CrossBox Cluster


If you are a service provider, or if you ever plan to have more than one CrossBox server, then we advise you to think about creating a CrossBox Cluster. Here we will explain how you should plan your deployment and what are the benefits of building a CrossBox Cluster.


  • A single IMAP/SMTP/POP3 hostname for all customers, no matter what specific slave server they are hosted on (
  • A single Webmail URL (CrossBox) for all customers, no matter what specific slave server they are hosted on (
  • Mix different cPanel, Plesk, Direct Admin and Standalone servers within the cluster.
  • Scale indefinitely by simply adding more Slave servers to the Master server.
  • Manage all servers from the Admin area.

Master-Slave(s) Topology

As you can see in the picture below, there is a single Master server with multiple Slave servers attached to it. You are free to mix any combination of cPanel/Plesk/Stand-alone servers within the cluster.


Building a CrossBox Cluster

First, install a Master server, log in to Admin area and then add Slave server(s).

Master Server

This server is used to resolve domains and email addresses to your slave servers (where they are actually hosted) and it acts as a single point entry for all your customers.

For example, this is where would reside. 

However, the master server does not do any heavy lifting and it just delegates everything to the slave server which is resolved for that hosting account.
Because there is no heavy work happening on the master server itself, you can install it on a small dedicated server or a VPS/VM (Virtual Machine).

Installing a CrossBox Master server

Pick a small dedicated server or a VPS and install CrossBox as explained in a Quick Start Guide, making sure that you choose "Master" as a server type during the installation.

Slave Server(s)

These servers hold all your customer's CrossBox data and do all the work related to the activity of CrossBox accounts that are hosted there.

You can install a slave server on cPanelPlesk, other control panels, or on a Standalone (empty) server.

Adding a Slave server to the cluster

To connect your Slave server to Master server, please log in as admin user and go to "Servers" area.

The list of all your CrossBox servers will appear. In the bottom right corner click on the  + ADD  fab button.


Here you will be instructed to log in as root to the slave server's SSH so you can issue the following command:

sh <(curl || wget -O - --slave 

Now just copy the URL that the command outputs, paste it back to the "Installer URL" box and click the "Add Slave" button.


This will start up the installation of CrossBox on the targeted server and you'll be able to complete the installation from the Admin area.
You can tweak all the CrossBox Options during the installation to customize the settings for that particular server.
After the installation is completed, the added server will now be a part of your CrossBox Cluster.