cPanel Linked Nodes Guide
Valid for versions 98 through the latest version
Last modified: July 31, 2023
cPanel linked nodes are two or more servers (nodes) connected to each other via WHM’s Link Server Nodes interface (WHM » Home » Server Configuration » Link Server Nodes). This feature lets you optimize your primary (parent node) node’s resource usage by distributing functionality across multiple nodes.
For example, you can assign a cPanel account’s mail functionality to a secondary server (child node) optimized for mail. As a result, your primary node’s resource usage is lower. This helps optimize the user experience for non-mail services, such as web hosting.
One way you can optimize your child nodes is to set a server profile. To do this, you can configure a node’s profile directly in WHM’s Server Profile interface (WHM » Home » Server Configuration » Server Profile).
The parent node in a linked node configuration only uses a Standard server profile. A parent node cannot use any other server profile.
For information about server profiles, read our How to Use Server Profiles documentation.
Parent and child nodes
Linking nodes together creates a “parent and child” node configuration. For example:
- A parent node is the authoritative controller in a configuration. This node assigns tasks to one or more child nodes.
- A child node is the non-authoritative node that receives tasks from the parent node. For example, a child node configured to handle mail-related functions for accounts on the parent node.
For more information about linking nodes, read our Link Server Nodes interface documentation.
Child node restrictions
The following restrictions apply to all child nodes on a linked node configuration:
- cPanel users cannot log in directly to cPanel on a child node. They must log in to cPanel on the parent node.
- You must call APIs on the parent node, which proxies requests to the child node.
- The system blocks all cPanel API calls on the child node.
- The system blocks WHM API functions that call a distributed cPanel account on the child node.
- You can only assign one child node to a cPanel account when offloading a specific functionality to the account. However, a parent node can have more than one child node that manages a specific functionality. For example, the system supports a parent node with two child nodes that both handle mail functionality. However, the system does not support a cPanel account using two child nodes for its mail functionality.
- We do not currently support configurations that link more than one parent node to a single child node.
- You can only link a parent node to a child node that uses the same major version or later of cPanel & WHM.
The following restrictions apply to only mail child node on a linked node configuration:
- cPanel users must log in to their Webmail accounts via the
webmailsubdomain. For example, the
https://example.com:2096URL. They cannot log into Webmail via the parent node.
- A distributed cPanel account’s
webmailsubdomains resolve to the child node.
- You cannot enable IPv6 on a cPanel account if you want to distribute that account to a mail node.
- Your hosting provider must enable API Tokens for the linked cPanel account in WHM’s Feature Manager interface (WHM » Home » Packages » Feature Manager).
- You must use DNS Domain Control Validation (DCV).
- If you are using AutoSSL or SSL certificates purchased via your cPanel account, your cPanel & WHM nodes must be able to manage the authoritative DNS server.
User access and security on a child node
Server profiles provide performance improvements, not necessarily additional security.
Distributed accounts have the same level of access on the child node as they do on the parent node. This access allows linked nodes to work smoothly with existing systems. For example, we disable the Pipe to a Program option in cPanel’s Forwarders interface (cPanel » Home » Email » Forwarders). We do not support email forwarders that execute programs. Users can still manually create these forwarders. However, we will not preserve this functionality in future versions.
We are researching methods to transition to a reduced access security model in a future version.
cPanel accounts and linked nodes
A cPanel account that offloads specific functions (such as mail) to a child node is called a distributed cPanel account. This basic process consists of the following steps:
- The system creates two versions of the account: one on the parent node and one on the child node.
- The system moves the desired functionality (for example, mail services) from the account on the parent node to the account on the child node. The account that exists on the parent node manages all other functionality.
AutoSSL certificates on distributed accounts require DNS Domain Control Validation (DCV) to secure the site.
To view all distributed cPanel accounts on a child node, click View Distributed Accounts in WHM’s Link Server Nodes interface (WHM » Home » Server Configuration » Link Server Nodes).
Creating distributed accounts
When you create a new account in WHM’s Create a New Account interface (WHM » Home » Account Functions » Create a New Account), you can choose how to distribute the account. For example, to distribute the new account’s mail, use the Mail Routing Section to assign a child node on which the account’s mail will reside.
Make an existing account a distributed account
To distribute an existing account, use the Linked Nodes section in WHM’s Modify an Account interface (WHM » Home » Account Functions » Modify an Account). The system will create the modified account on the child node as part of this process and offload the desired functionality to the child node’s version of the account.
If you modify a cPanel account to use a mail child node, the system copies the account’s existing mail to that child node. After the system successfully distributes the account, it removes the account’s mail stored on the parent node.
Distributed accounts on a linked mail child node
In most cases, all IMAP, POP3, and SMTP traffic for distributed cPanel accounts goes to the mail child node. However, if this traffic arrives at the parent node (for example, cached DNS lookups), the parent node will:
- Create proxy IMAP and POP3 connections to the mail child node.
- Reroute SMTP mail delivery to the mail child node.
The following intructions apply to distributed cPanel accounts on a mail child node:
Managing distributed accounts
Only system administrators can perform these actions.
You can manage your distributed cPanel accounts using one of the following methods:
Undoing account distribution
The process of moving some or all a distributed cPanel account’s functionality from a child node back to the parent node is called dedistribution. During this process, the system configures service proxying and mail routing to point to the parent node and terminates any IMAP or POP3 connections.
To dedistribute an account, use the Linked Server Nodes section in WHM’s Modify an Account interface (WHM » Home » Account Functions » Modify an Account).
In some cases, you may need to forcefully dedistribute an account. For example, a child node is permanently offline or a child node’s security is compromised. You can use WHM’s Link Server Nodes interface (WHM » Home » Server Configuration » Link Server Nodes) to perform this action. However, performing this action will result in account data loss.
Transfer accounts that have been distributed to a linked server
If you want to transfer a distributed account from one parent/child pair to another parent/child pair, use WHM’s Transfer Tool interface (WHM » Home » Transfers » Transfer Tool) to perform this action.
If you want to transfer a distributed account to a new parent node while keeping the account on the same child node, perform the following steps:
- Dedistribute all of the accounts from the child node. Use the Linked Server Nodes section in WHM’s Modify an Account interface (WHM » Home » Account Functions » Modify an Account) to perform this action.
- For additional information on this process read Undoing account distribution in this document.
- The account must be fully dedistributed before it can be redistributed to the child node.
- Unlink the child node from the old parent node. Use WHM’s Link Server Nodes interface (WHM » Home » Server Configuration » Link Server Nodes) to perform this action.
- Transfer the account from old parent node to new parent node with WHM’s Transfer Tool.
- Link the child node to the new parent node. Select Mail Node under the account configuration options in WHM’s Transfer Tool to distribute the child node to the new parent (standard profile) node.
- Redistribute the account(s) to the child node. Use the Linked Server Nodes section in WHM’s Modify an Account interface (WHM » Home » Account Functions » Modify an Account) to perform this action.
Distributed reseller accounts
Distributed reseller accounts do not have their reseller privileges on the child node. Because of this, distributed reseller accounts cannot log in to WHM on a child node.
When a distributed reseller creates a cPanel account, the new account will use the same distribution status as the reseller: distributed or not distributed. However, if the reseller account’s distribution status changes, its cPanel accounts do not also change.
For example, a distributed reseller creates a new cPanel account. Afterward, the server administrator dedistributes the reseller account back to the parent node. All of the reseller’s owned accounts will remain distributed to the child node unless the server administrator updates those accounts’ distribution status.
If one of a distributed reseller’s cPanel accounts’ distribution status changes, the reseller’s distribution status does not change.
When using linked nodes, there are some things to consider for distributed cPanel account passwords:
- A child node’s password strength configuration only affects passwords that relate to the functions the child node serves. For example, if an account’s mail is distributed, the child node controls only that account’s email account and mailing list password strength settings. The parent node controls all other password strength settings (for example, FTP and cPanel account passwords).
- An account’s password age on the parent node and child node will not match when you update this setting on the parent node.