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 users, no matter what specific slave server they are hosted on
  • A single Webmail URL (CrossBox) for all users, no matter what specific slave server they are hosted on
  • Unify a communication experience across different cPanel, Plesk, Direct Admin and Standalone servers within the cluster
  • Scale indefinitely by simply adding more Slave and Master servers to the cluster
  • Manage all servers from the Admin area

Master(s)-Slave(s) Topology

As you can see in the diagram below, the Master server creates an abstract around multiple Slave servers attached to it.

  • You can have a single master server or multiple master servers to achieve load-balancing and high availability of the master server
  • You can have a single or multiple slave servers
  • You can attach any combination of DirectAdmin/cPanel/Plesk/Standalone servers to the cluster


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 entry point for all your customers and users. For example, this is where would reside.

  • Master server hosts the application's static files (html, css, js)
  • Master servers runs MailProxify service that proxies IMAP/SMTP/POP3 traffic to the resolved slave server
  • Master server can also run a HTTP proxy that proxies app's HTTP traffic to the slave servers (useful for users that are unable to access non-standard ports behind a corporate firewall)
  • If the user's domain is using the master server in the MX record and the slave server is unreachable (offline), the master server will accept and queue any emails and deliver them once the slave server is reachable again
  • The master server delegates all of the storage and computing to the slave server which is resolved for the email account
  • Because there is no heavy computing happening on the master server itself, you can install it on a small dedicated server or a VPS/VM (Virtual Machine)
  • In larger setups, the master server can be load-balanced and made fully redundant by creating a multi-master setup

Slave Server(s)

These servers hold all your customer's CrossBox data (emails, files, databases, etc) and do all the computing related to the activity of CrossBox accounts that are hosted there.

You can install a slave server on

Building a CrossBox Cluster

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

Installing a 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.

Adding a server to the cluster

You can attach two types of servers to your cluster:

  • Slave server (DirectAdmin, cPanel, Plesk, Standalone)
  • Additional master server(s) for load-blancing and redundancy

To connect a new server to your cluster, log in as admin user and go to the "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 new server's SSH so you can issue the installation command:


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

This will start the installation of CrossBox on the targeted server and you'll be able to complete the installation from the Admin area.

- If you're adding a slave server, make sure that you choose "Server" license type during the installation
- If you're adding a master server for load-balancing and reduncancy (failover), make sure that you choose "Master Server" license type during the installation

You can tweak all the CrossBox Options during the installation to customize the settings for the new server.
After the installation is completed, the added server will be automatically connected and made part of your CrossBox Cluster.

Creating a Multi-master Setup


  • Make your master server fully redundant
  • Round robin master server's traffic across multiple servers

The process of creating a multi-master setup is the same as with adding a new server to the cluster - just make sure that you choose "Master Server" license type during the installation.

After the installation is completed, add a new IP to your DNS. For example, if your master server hostname is, this is how your A records should look like: IN A (where is the IP address of your first master server) IN A (where is the IP address of your second master server) IN A (where is the IP address of your third master server)

There is no limit on the number of master servers you can have within a cluster.