Child pages
  • Installation Guide - Customize Your Installation
For cPanel & WHM version 76

Skip to end of metadata
Go to start of metadata

Overview

Before you begin the installation process, you can customize the configuration for certain portions of cPanel & WHM.

Installation methods

New installations of cPanel & WHM use the fast installation method by default. This method handles certain aspects of cPanel & WHM differently to drastically reduce installation time. For example, the fast installation method:

  • Uses tarballs to download certain code cPanel & WHM files.
  • Uses system RPMs, if they are available, to set up the Perl local::lib library.

Note:

When you install cPanel & WHM on a CentOS server with a CloudLinux™ license, the installer will automatically convert the server to CloudLinux.

Installation options

You can use the following options to customize cPanel & WHM's installation process:

Option

Description

--confirm

Require confirmation before the installation script runs.

--noexec

Do not run the installation script.

--keep

Do not delete the target directory after installation.

--nox11

Do not spawn an X terminal input terminal.

--nochown

Do not assign permissions for the extracted files to the current user.

--target NewDirectory

Extract the cPanel & WHM installation files to the NewDirectory directory.

--tar arg1 [arg2 ...]

Access the contents of the arg1 archive through the tar command.

--force

Force installation on an unrecommended configuration.

--skip-cloudlinux

Skip the automatic CloudLinux conversion process even if a license exists.

Legacy installation method

Some system administrators may wish to override this default in order to use the legacy installation method.

Important:

This method requires substantially more time than the fast installation method. We strongly recommend that you use the fast installation method.

To disable the fast installation method, create the /etc/cpanel/disable_fast_install touch file before you begin the cPanel & WHM installation process.

Basic server setup

The /etc/wwwacct.conf file contains the basic setup information for cPanel & WHM. After you install cPanel & WHM, you can find and edit this information in WHM's Basic WebHost Manager Setup interface (WHM >> Home >> Server Configuration >> Basic WebHost Manager® Setup).

To customize this configuration, perform the following steps:

  1. As the root user, create the /etc/wwwacct.conf file.
  2. Enter all of the wwwacct.conf file's parameters, with one entry per line:

     Click for an example file to copy-paste from...

    Note:

    Separate each parameter and its value with a space.

    ADDR 10.0.0.1
    NS2 ns2.domain.tld
    CONTACTPAGER user@examplesms.com
    LOGSTYLE combined
    CONTACTEMAIL user@example.com
    HOMEMATCH home
    TTL 14400
    NSTTL 86400
    NS ns1.domain.tld
    ETHDEV eth0
    ADDR6 
    HOST 
    NS4 
    DEFMOD paper_lantern
    HOMEDIR /home
    NS3 
    SCRIPTALIAS y
  3. Define the following required values:

    • DEFMOD
    • HOMEDIR
    • LOGSTYLE
    • NS
    • NS2
    • SCRIPTALIAS

    Important:

    If you do not define these values, account creation will fail.

     Click for an example file to copy-paste from...
    DEFMOD paper_lantern
    HOMEDIR /home
    LOGSTYLE combined
    NS ns1.domain.tld
    NS2 ns2.domain.tld
    SCRIPTALIAS y
    

    Note:

    In this example, ns1.domain.tld and ns2.domain.tld are your nameservers' identities.

  4. Specify values for any other parameters that you wish to configure. Refer to the configuration values table for a complete list of available parameters.

Configuration values

You can configure the following values in the /etc/wwwacct.conf file:

ValueDescriptionExample
ADDRThe server's shared IPv4 address.
10.0.0.1
ADDR6The server's shared IPv6 address.10.0.0.1
CONTACTEMAILThe system administrator's contact email address.user@example.com

CONTACTPAGER

The number to which the server sends Short Message Service (SMS) notifications.user@examplesms.com
DEFMOD

Required

The default cPanel theme that you wish to use for newly-created accounts.

Note:

This value does not impact cPanel theme behavior for existing accounts.

paper_lantern
ETHDEV

The default ethernet device. This parameter defaults to the eth0 value.

Note:

Specify venet0:0 if the server runs Virtuozzo®.

eth0
HOMEDIR

Required

The path to the default home directory.

/home
HOMEMATCHA string that determines which partitions to use as home directories for new accounts. (For example, a value of users matches system mounts of usersusers1, or users3.)home
HOSTThe server's hostname.hostname
LOGSTYLE

Required

The Apache log format to use.

Important:

You must define this value as combined.

combined
NS

Required

The primary nameserver to add to DNS zones by default.

Important:

If you do not specify a value for NS, account creation will fail.

ns1.domain.tld

NS2

Required

A second nameserver to add to DNS zones by default.

Important:

If you do not specify a value for NS2, account creation will fail.

ns2.domain.tld
NS3An additional nameserver to add to DNS zones by default.ns3.domain.tld
NS4An additional nameserver to add to DNS zones by default.ns4.domain.tld
NSTTLThe default time to live (TTL) value that DNS zones will use.86400
SCRIPTALIAS

Required

Whether the system aliases a /cgi-bin/ directory on account creation.

Important:

This value only accepts y or n.

y
TTLThe default time to live value.14400

Configuration settings

When you install cPanel & WHM, the system reads the /root/cpanel_profile/cpanel.config file. This file stores the settings that WHM's Tweak Settings interface (Home >> Server Configuration >> Tweak Settings) contains, as well as various configuration settings for other cPanel & WHM features. The system uses these settings to set the values in the /var/cpanel/cpanel.config file.

Warnings:

  • Some of the values that the /root/cpanel_profile/cpanel.config file contains are dynamic, or require specific values.
  • You can configure the version of MySQL ® or MariaDB to use in the /root/cpanel_profile/cpanel.config file's mysql-version key before you install cPanel & WHM. However, we do not support the configuration of existing installations of cPanel & WHM.
  • If you set MySQL to version 5.1 (mysql-version=5.1) or lower when you install cPanel DNSONLY™, the installation process automatically upgrades the MySQL installation to version 5.5. cPanel & WHM version 11.46 discontinued support for MySQL 5.1 and lower, and cPanel DNSONLY does not include an easy way in which to upgrade your MySQL installation.
  • Because cPanel & WHM displays the Feature Showcase after installation, Feature Showcase items can overwrite settings that you preconfigure on servers, such as the cpanel.config file.

To set these parameters, perform the following steps:

  1. As the root user, create the /root/cpanel_profile/cpanel.config file.
  2. With one entry per line, list the parameters and values that you wish to configure in key=value format. For example, to preconfigure your server to deny the nobody user the ability to send email to a remote address, add the nobodyspam=1 line to the /root/cpanel_profile/cpanel.config file before you install cPanel & WHM.

Account restoration

The /etc/cpanelacctrestore file contains a list of accounts to automatically restore during the cPanel & WHM installation process. You can use this file to restore accounts to a freshly-installed server.

Note:

When you create a backup file, you must use one of the following formats:

  • cpmove-{USER}
  • cpmove-{USER}.tar
  • cpmove-{USER}.tar.gz
  • {USER}.tar
  • {USER}.tar.gz
  • backup-{BACKUP-DATE_TIME}_{USER}.tar
  • backup-{BACKUP-DATE_TIME}_{USER}.tar.gz

To restore a list of cPanel accounts during the cPanel & WHM installation process, perform the following steps:

  1. As the root user, use a text editor to create the /etc/cpanelacctrestore file.
  2. List the user account names, one entry per line.

  3. Upload the backup file or files to one of the following directories:

    • /home
    • /home2
    • /home3
    • /root
    • /usr
    • /usr/home
    • /web

Release tiers

The /etc/cpupdate.conf file determines the product version for your installation of cPanel & WHM. This file also controls when your server performs the automatic upgrades to new major versions of cPanel & WHM.

When you preconfigure this file, cPanel & WHM will install the specified version or the major version that corresponds to the specified release tier.

Notes:

To preconfigure the cPanel & WHM release tier, perform the following steps:

  1. As the root user, create the /etc/cpupdate.conf file.

  2. In the /etc/cpupdate.conf file, use the CPANEL parameter to set your desired release tier. For example, to configure your server to use the STABLE tier, add the CPANEL=stable value to the /etc/cpupdate.conf file.

The /etc/cpsources.conf file

The /etc/cpsources.conf file determines the locations from which your server downloads updates. By default, cPanel & WHM servers retrieve updates directly from cPanel, Inc. through our httpupdate.cpanel.net pool of update servers.

Warning:

Invalid modifications to this file may cause serious problems. We strongly recommend that you do not modify this file unless you understand the full technical ramifications of your actions and can maintain these customizations.

Invalid data

If you see the following error in your server's logs, the /etc/cpsources.conf file likely contains invalid data:

[2015-12-08 14:12:54 +0200] ***** FATAL: Unable to retrieve tier version info: timeout

To resolve this issue, move the /etc/cpsources.conf file to another location, then run the /usr/local/cpanel/scripts/upcp script. The system will automatically restore a valid cPanel-supplied version of the /etc/cpsources.conf file.

Note:

To disable FastUpdate on your server, SSH to your server as the root user and run the following command:

touch /var/cpanel/never_ever_use_fast_update_not_even_a_check

To reenable FastUpdate on your server, run the following command as the root user:

rm /var/cpanel/never_ever_use_fast_update_not_even_a_check

yum

Yellowdog Updater, Modified (yum) is an RPM package management tool for Linux servers that automatically installs with your operating system. 

Warning:

When you install cPanel & WHM, you must only use vendor-provided repositories. Third-party repositories may replace vital parts of the system and cause unexpected results.

Exclude packages

Because cPanel & WHM handles its own installation of services through the rpm.versions system, you must exclude several packages before you install cPanel & WHM.

To exclude these packages, perform the following steps:

  1. As the root user, use a text editor to edit the /etc/yum.conf file.

  2. Locate the line that begins with exclude= and confirm that it contains the following entries:

    bind-chroot dovecot* exim* filesystem httpd* mod_ssl* mydns* mysql* nsd* php* proftpd* pure-ftpd* ruby* spamassassin* squirrelmail* 
    1. If you do not find the line that begins with exclude= , insert it in the file under the [main] line as one line of code.

    2. The squirrelmail* entry is optional. For more information, read our cPanel Deprecation Plan documentation.
  3. Save and close the file. You may then use your preferred method to install yum on your server.

Remove yum groups

Note:

To obtain a list of yum groups, run the yum grouplist command.

Before you install cPanel & WHM, make certain that the following yum groups are not installed on your server:

  • FTP Server
  • GNOME Desktop Environment
  • KDE (K Desktop Environment)
  • Mail Server or E-mail Server
  • Mono
  • Web Server
  • X Window System

To remove a yum group, run the yum groupremove command. For example, to remove the Mono and Mail Server groups, run the following command:

yum groupremove "Mono" "Mail Server"

Apache

EasyApache 4

cPanel & WHM installs EasyApache 4 by default.

EasyApache 4 allows you to preconfigure your profile before you install cPanel & WHM on your server. To preconfigure your profile before install, create the /etc/cpanel_initial_install_ea4_profile.json file. The installation process installs this profile then copies it to the /etc/cpanel/ea4/profiles/custom/ directory when complete.

Notes:

  • The /etc/cpanel_initial_install_ea4_profile.json file must exist as both a valid JSON file and a valid EasyApache 4 profile. If your JSON file contains errors, no data, or the installation fails, the system installs the default EasyApache 4 profile.
  • If your selected version of EasyApache fails to build, the installation process continues and you must troubleshoot the issue manually.
  • If your system runs CloudLinux™, the system installs the CloudLinux EasyApache 4 repository and the default CloudLinux profile.
  • Systems that do not run CloudLinux install cPanel & WHM's EasyApache 4 repository and default profile.

For information about how to create an EasyApache 4 profile, read our EasyApache 4 - Create a Profile documentation.

EasyApache 3

Important:

We no longer develop and only provide security updates for EasyApache 3. We will deprecate EasyApache 3 on December 31, 2018. After that date, we will no longer update EasyApache 3. In cPanel & WHM version 78, we will remove support for EasyApache 3. We strongly recommend that you install EasyApache 4.

For more information, read our cPanel Long-Term Support documentation.

If you wish to install EasyApache 3 on your system, you can use EasyApache 3 to configure the Apache web server before installation. To do this, you must also access an existing cPanel & WHM server that runs EasyApache. EasyApache allows you to adjust several configuration options.

Notes:

  • You must create the /etc/install_legacy_ea3_instead_of_ea4 touch file to install EasyApache 3 by default on a fresh install of cPanel & WHM version 58 or higher.
  • The cPanel & WHM installation process installs Apache 2.4 and PHP 5.5 by default.

To create and customize a new profile, perform the following steps:

  1. Create a new EasyApache profile:
    • Command line — Log in to the existing server through SSH as the root user and run the /scripts/easyapache script.
    • WHM — Log in to WHM on the existing server as the root user and use the EasyApache 3 interface (Home >> Software >> EasyApache 3).
  2. Run EasyApache 3.
  3. In the Exhaustive Options List stage, perform the following steps:
    1. Assign a file name, a display name, and a brief profile description to the new EasyApache profile.
    2. Select Save Only (Do Not Build). Your server stores the new profile in the /var/cpanel/easy/apache/profile/custom/ directory, but does not recompile Apache and PHP.
    3. Run the scp command to copy the profile to the /etc/cp_easyapache_profile.yaml file on the new server.
  4. To create a /var/cpanel/easy/apache/prefs.yaml file, which stores your preferences separately from the build profile, perform the following steps:
    1. Set the desired preferences in EasyApache.
    2. On your new server, run the following command:

      mkdir -p /var/cpanel/easy/apache/ 
    3. Copy the /var/cpanel/easy/apache/prefs.yaml file from the existing system to the /var/cpanel/easy/apache/ directory on the new server.
    4. Place your build profile in the /etc/cp_easyapache_profile.yaml file on the new server.

Override customizations

To override the cPanel & WHM installation system's default settings or any customizations that you made, run the /usr/local/cpanel/scripts/copy-etc-files script. This script performs the following actions:

  • Creates copies of the contents of your current system's /etc/bashrc, /etc/issue, and /etc/issue.net files.
  • Stores the copied files in the /usr/local/cpanel/etc directory.
  • Replaces the customized files with the copied files' contents.

Additional documentation