Last modified: March 26, 2024

Overview

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.

Server profiles

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).

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.
• A parent node manages the child nodes’ AutoSSL certificates.

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 webmail subdomain. For example, the https://webmail.example.com URL, not https://example.com:2096 URL. They cannot log into Webmail via the parent node.
• A distributed cPanel account’s mail and webmail subdomains 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

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:

1. The system creates two versions of the account: one on the parent node and one on the child node.
2. 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.

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.

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.

Managing distributed accounts

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).

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:

1. 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.
   Note:

   • 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.
2. 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.
3. Transfer the account from old parent node to new parent node with WHM’s Transfer Tool.
4. 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.
5. 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.

Reseller-owned accounts

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.

Password management

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.