For cPanel & WHM version 58
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. Some system administrators may wish to override this default in order to use the legacy installation method. The fast installation method handles certain aspects of cPanel & WHM differently, in order to drastically reduce installation time:
- Fast installations use prebuilt locale databases, while legacy installations run the
/scripts/build_locale_databases
script to compile locale databases during installation. - Fast installations use tarballs to download certain code cPanel & WHM files.
- Fast installations use system RPMs, if they are available, to set up the Perl
local::lib
library.
To disable the fast installation method and use the legacy installation method, create the /etc/cpanel/disable_fast_install
touch file before you begin the cPanel & WHM installation process.
Important:
The legacy installation method requires substantially more time than the fast installation method. We strongly recommend that you use the fast installation method.
EasyApache
cPanel & WHM installs EasyApache 4 (Home >> Software >> EasyApache 4) by default. If you wish to use EasyApache 3 (Home >> Software >> EasyApache 3) instead, create the /etc/install_legacy_ea3_instead_of_ea4
touch file before you begin the cPanel & WHM installation process.
If your chosen version of EasyApache fails to build, the installer will continue and you must troubleshoot the issue.
Note:
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.
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 cPanel & WHM Setup interface (Home >> Server Configuration >> Basic cPanel & WHM Setup).
Important:
You must include all of the parameters in your /etc/wwwacct.conf
file, even if you do not specify a value for a parameter.
To customize this configuration, perform the following steps:
As the
root
user, create the/etc/wwwacct.conf
file.Enter all of the
wwwacct.conf
file's parameters, with one entry per line.Specify values for the following parameters that require values:
LOGSTYLE
NS
andNS2
SCRIPTALIAS
Specify values for any other parameters that you wish to configure.
Remember:
Separate each parameter and its value with a space. For example:
CONTACTEMAIL user@example.com
You can configure the following values in the /etc/wwwacct.conf
file:
ADDR
— Your server's shared IPv4 address.ADDR6
— Your server's shared IPv6 address.CONTACTEMAIL
— The system administrator's contact email address.CONTACTPAGER
— The number to which the server sends Short Message Service (SMS) notifications.DEFMOD
— The default cPanel theme that you wish to use.ETHDEV
— The default ethernet device.- This parameter's value defaults to
eth0
on Linux servers. - Specify
venet0:0
if the server runs Virtuozzo.
- This parameter's value defaults to
HOMEDIR
— The path to the default home directory.HOMEMATCH
— A string that determines which partitions to use as home directories for new accounts. (For example, a value ofusers
matches system mounts ofusers
,users1
, orusers3
.)LOGSTYLE
— The Apache log format to use.Important:
Always set
combined
as this parameter's value.NS
,NS2
,NS3
, andNS4
— Nameservers to add to DNS zones by default.Important:
If you do not specify values for
NS
andNS2
, account creation will fail.NSTTL
— The default time to live (TTL) value that DNS zones will use.SCRIPTALIAS
— Whether the system aliases a/cgi-bin/
directory on account creation.Important:
You must enter a value of
y
orn
.
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 certain configuration settings for other cPanel & WHM features. The system uses the values here 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. Before you create a/root/cpanel_profile/cpanel.config
file, you must read our The cpanel.config File documentation. - 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. This is because 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.
To set these parameters, perform the following steps:
- As the
root
user, create the/root/cpanel_profile/cpanel.config
file. 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.
To restore a list of cPanel accounts during the cPanel & WHM installation process, perform the following steps:
- As the
root
user, use a text editor to create the/etc/cpanelacctrestore
file. With one entry per line, list the user account names.
Upload the backup file or files to one of the following directories:
/home
/home2
/home3
/root
/usr
/usr/home
/web
Note:
The backup's filename 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
Release tiers
The /etc/cpupdate.conf
file determines the release tier for your installation of cPanel & WHM. When you preconfigure this file, cPanel & WHM will install the major version that corresponds to the tier that you selected. The chosen release tier also controls when your server performs the automatic upgrades to new major versions of cPanel & WHM.
- For more information about our release tiers, read our cPanel & WHM Product Versions and the Release Process documentation.
- For more information about the
/etc/cpupdate.conf
file, read our The cPanel & WHM Update Configuration File documentation.
To preconfigure your release tier, perform the following steps:
As the
root
user, create the/etc/cpupdate.conf
file.In the
/etc/cpupdate.conf
file, use theCPANEL
parameter to set your desired release tier.
For example, to configure your server to use the STABLE tier, add CPANEL=stable
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. via our httpupdate.cpanel.net
pool of update servers.
Warning:
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 modifications to this file may cause serious problems (for example, servers with invalid /etc/cpsources.conf
files cannot perform necessary updates).
If you see the following error in your server's logs, your /etc/cpsources.conf
file likely contains invalid data:
[2015-12-08 14:12:54 +0200] ***** FATAL: Unable to retrieve tier version info: timeout
To solve this problem, move the /etc/cpsources.conf
file to another location, and then run the /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, log in to your server via SSH and run the following command as the root
user:
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
Yum (Yellowdog Updater Modifier) is an RPM package management tool for Linux servers. Yum automatically installs with your operating system.
Warning:
- When you install cPanel & WHM, you must only use vendor-provided repositories.
- Third-party repositories, such as RepoForge, 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:
As the
root
user, use a text editor to edit the/etc/yum.conf
file.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*
If you do not find the line that begins with
exclude=
, add it to the file under the[main]
line.Important:
In this document, this code appears as two lines for formatting purposes. In your
/etc/yum.conf
file, make certain that you enter it as one line of code.- Save and close the file. You may then use your preferred method to install yum on your server.
Remove yum groups
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 obtain a list of yum groups, run the yum
grouplist
command.
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
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. This file must be a valid JSON file and must be a valid EasyApache 4 profile. The install process will install this profile and then copy it to the /etc/cpanel/ea4/profiles/custom/
directory when completed.
Note:
If your JSON file contains errors, no data, or the installation fails, the system installs the default EasyApache 4 profile instead.
For more information about how to create an EasyApache 4 profile, read our EasyApache 4 - Create a Profile documentation.
EasyApache 3
Remember:
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.
If you plan to install EasyApache 3 on your system rather than EasyApache 4, 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.
Note:
The cPanel & WHM installation process installs Apache 2.4 and PHP 5.5 by default.
To set up a new profile and customize its options and preferences, perform the following steps:
- Create a new EasyApache profile.
- Command line — Log in to the existing server via 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).
- Command line — Log in to the existing server via SSH as the
- Run EasyApache 3.
- In the Exhaustive Options List stage, perform the following steps:
- Assign a file name, a display name, and a brief profile description to the new EasyApache profile.
- 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. - Run the
scp
command to copy it to the/etc/cp_easyapache_profile.yaml
file on the new server.
- To create a
/var/cpanel/easy/apache/prefs.yaml
file, which stores your preferences separately from the build profile, perform the following steps:- Set the desired preferences in EasyApache.
On your new server, run the following command:
mkdir -p /var/cpanel/easy/apache/
- Copy the
/var/cpanel/easy/apache/prefs.yaml
file from the existing system to the/var/cpanel/easy/apache/
directory on the new server. - Place your build profile in the
/etc/cp_easyapache_profile.yaml
file on the new server.
Override customizations
If you wish 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 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' content.