Cpanel Introduction

Cpanel Introduction
--------------------

Cpanel Important directories.

/usr/local/cpanel
/var/cpanel
/scripts

/usr/local/cpanel
---------------
cpsrvd
cpsrvd-ssl
cpkeyclt

/usr/local/cpanel/bin
-------------------

*Houses only scripts and binaries which provide installation
and configuration of many cPanel managed services

Notable Contents:
eximstats
checkperlmodules

/usr/local/cpanel/logs
--------------------

CPSRVD -------access_log, error_log
CPANELLOGD---stats_log
CPKEYCLT------license_lo

/usr/local/cpanel/base
--------------------

frontend-------x, x2,xmail,monsoon
webmail-------x, monsoon
neomail
horde
3rdparty-------squirrelmail, phpPgAdmin, phpMyAdmin

/usr/local/cpanel/etc
-------------------

init -----------start | stop cpsrvd AND start | stop AND start | stop cppop
exim----------cf, perl
ftptemplates ---proftpd
httptemplates --apache1--default, ssldefault
zonetemplates--simple, standard, standardvirtualftp

/usr/local/cpanel/3rdparty
-----------------------
bin------php, stunnel, analog, awstats, webalizer
etc------php.ini, ixed, ioncube

/var/cpanel
----------
Houses proprietary configuration data for cPanel, including:
● Primary cPanel configuration
● User configurations
● Reseller configurations
● Accounting, conversion, and update logs
● Bandwidth data
● Customized service templates

/var/cpanel
----------

cpanel.conf
resellers
accounting.log
features--packages--logs
updatelogs--bandwidth--zone templates
users---mainips

/var/cpanel/cpanel.config
-----------------------
● The primary cPanel configuration file
● Each variable within influences the way cPanel behaves
● Variables are line delimited, with variables separated by an equal sign
● If file does not exist, cpanel falls back to defaults

/var/cpanel/resellers
------------------

Lists each reseller with a comma-delimited list of WHM
resources that reseller has access to.

/var/cpanel/accounting.log
------------------------
Contains a list of accounting functions performed through
WHM, including account removal and creation.

/var/cpanel/bandwidth
--------------------
● Files contain a list of the bandwidth history for each account.
Each named after their respective user.
● History files are stored in human-readable format, while actual
bandwidth data are stored in round robin databases.

/var/cpanel/features
------------------

● File name is inherited from the feature list name
● Contains a line delimited list of feature variables and a zero or
one value
● Variables control what cPanel resources are available to users

/var/cpanel/packages
-------------------

● Contains a list of packages, named after the packages they represent
● If package belongs to reseller, file name is prefixed with reseller name
● Each of these values determines the values created in cPanel user file

/var/cpanel/users
----------------

● Contains a list of cPanel user configuration files, named after the user
they pertain to.
● Variables define account resources, themes, domains, etc.

Other notable /var/cpanel directories
--------------------------------

● LOGS
– This directory contains logs from account copies/transfers.
Training Seminar 2006
● UPDATELOGS
– Contains the output of each cPanel update executed on the server.
● MAINIPS
– Named after the respective reseller users they represent, each
contains only the IP address which should be used as that
resellersmain shared ip
● ZONETEMPLATES
– Contains customized DNS zone templates created inWHM

/scripts
-------

This directory houses a large number of scripts which serve
as building blocks for many cPanel/WHM features.
The scripts can be used to:
● Update cPanel, and many of the services of which it
manages
● Customize account creation routines
● Perform backups of cPanel accounts
● Install and update cPanel managed services

cPanel Services
-------------

Services
● CPSRVD
● CHKSERVD
● CPANELLOGD
● CPBACKUP
● EXIMSTATS

cpsrvd
------

● cpsrvd is the 'master' process for cPanel.
● Handles and dispatches all requests made through the cPanel,
WHM, and Webmail interfaces.
● Logs to access_log and error_log

cpsrvd and stunnel relationship
---------------------------

CPSRVD--2082-->cpanel<--2083<--stunnel
CPSRVD--2086-->WHM<--2087<--stunnel
CPSRVD--2095-->Webmail<--2096<--stunnel

SSL Certificates
-------------

● Default certificate and key are stored in /
usr/local/cpanel/etc/cpanel.pem
● User installed cert and cabundle are stored in:
– /usr/local/cpanel/etc/mycpanel.pem
– /usr/local/cpanel/etc/mycpanel.cabundle

cPanel Startup
------------

● The following services are controlled by the cPanel
init script
– cpsrvd, both plain and secure
– cPanel POP Services
– cPanel Log Services
– Eximstats
– Chat Services
– Mailman
– Interchange

● Verify if ports are in use
– netstat -lnp | egrep '20(8|9)'

Troubleshooting Startup Issues(SSL)
-------------------------------

● If SSL services are not available
– execute /usr/local/cpanel/startstunnel
– check /usr/local/cpanel/3rdparty/bin/stunnel.log
● If cpsrvd is not available
– execute it directly `/usr/local/cpanel/cpsrvd`
– check /usr/local/cpanel/logs/error_log

Licensing
--------

● License requests are handled by /usr/local/cpanel/cpkeyclt
● Requests are transmitted to auth.cpanel.net over port 2089
● License requests are logged to license_log
● License key is stored at /usr/local/cpanel/cpanel.lisc

A valid license request:
root@server [~]# /
usr/local/cpanel/cpkeyclt
Updating Internal cPanel
Information.....Done
root@server [~]#

Troubleshooting License Issues
---------------------------

CHECKLIST:
● Verify if license is active for main server IP at http://verify.cpanel.net
● Check if server can establish connection to auth.cpanel.net over port 2089
● If the previous steps fail, check license_log for notable errors.
● If license is active, but refused with no notable errors, lodge support request.

root@server [~]# telnet auth.cpanel.net 2089
Trying 198.66.78.9...
Connected to auth.cpanel.net (198.66.78.9).
Escape character is '^]'.
200 cPanel License Service Version 12.0
root@server [~]#

cPanel Requests
--------------

cPanel Requests
● Logins are authenticated against the system passwd and shadow files.
● Documents root is /usr/local/cpanel/base
● Theme is defined by RS variable in user's cPanel configuration file.
● Resources are limited by the feature list of assigned to the given user.

WHM Requests
-------------

WHM Requests
● Root password will authenticate any reseller user
● Document root is /usr/local/cpanel/whostmgr/docroot/
● Reseller resources are limited by Access Control List
– Defined in WHM > Resellers > Reseller Center > Edit
Privileges/Nameservers
– Privileges are stored in /var/cpanel/resellers

cPanel Services
--------------

Services
● CPSRVD
● CHKSERVD
● CPANELLOGD
● CPBACKUP
● EXIMSTATS

Service Monitoring
----------------
● Located at /usr/local/cpanel/libexec/chkservd
● chkservd is a scalable connection and process based service monitoring
tool
● Provides monitoring of CPU, Memory, and Disk usage
● chkservd scans services once every eight minutes
– Logs to /var/log/chkservd.log
● Alerts are dispatched to server contact defined in Basic cPanel/WHM
Setup

chkservd Configuration
--------------------

● Monitored services are determined by values stored in /
etc/chkserv.d/chkservd.conf.
– Syntax: servicename:0 for no monitoring, servicename:1 for
monitoring
● Actions, expected responses, and failure events are defined in
service configuration files stored in /etc/chkserv.d/{servicename}
● Status files are stored in /var/run/chkservd/{servicename}
– Plus (+) sign for active, Minus (-) sign for failed

cpanellogd
----------

● cpanellogd is responsible for parsing and updating bandwidth logs, and dispatching
statistics generators on each account, per their individual configurations.
● Configured through Statistics Software Configuration and Tweak Settings in WHM
● Statistics are compiled and stored for each account in /home/{username}/tmp, with
each respective statistics application being assigned it's own individual subdirectory.

/home/{username}/tmp ----webalizer, analog, awstats, urchin

● Optional server-wide statistics configurations are stored in /
etc/stats.conf, while user-specific configurations may reside in /home/
{username}/tmp.
● Notable Variables in /etc/stats.conf:
– BLACKHOURS: Comma separated list of numeric values, which
specify hours that logs may not be parsed.
– VALIDUSERS:Users which are allowed to supply their own
combination of statistics generators. By default users are
restricted to the generators defined by the administrator.

Calling cpanellogd
----------------

● cpanellogd is started with the cPanel service, but can be executed
directly with:
– No Argument: Daemonize, and wait for a suitable time to scan
logs
– One Argument (username): Execute an immediate statistics run
for the specified user, and exit once completed.
● Two scripts are available to provide these functions as well:
– /scripts/runlogsnow - Execute a full log run immediately
– /scripts/runweblogs {username} - Execute a log run for a single
user

Bandwidth Statistics
-----------------

● Bandwidth statistics are accumulated from a combination of the
following cPanel managed services:
– HTTP
– EXIM
– IMAP / POP
– FTP
● Bandwidth data is logged to /usr/local/apache/domlogs/*bytes_log
● Parsed bandwidth data is stored in /var/cpanel/bandwidth


COMMON ISSUES
● Bandwidth parsing is taking an exceedingly long time to complete
– First check the size of the logs being parsed. Excessively large
log files can and typically will take a long time to complete.
– Additionally, if RRDtool is not installed, bandwidth parsing
performance will drop signifigantly.
● RRDtool can be installed by executing `/scripts/rrdtoolinstall`

Log Processing
-------------

● Statistics are parsed for each child domain of the given account.
● Will be influenced by variables in /var/cpanel/cpanel.config
– Skip statistics generator
● skip{generator_name}
– Logs will be retained or deleted based on
● keeplogs – keep logs at the end of the month.
● dumplogs – dump logs after parsing

Common cpanellogd Issues
------------------------

● Statistics are stalling, or are taking unreasonable amounts of
time.
– Usually indiates that the server load average is consistently
exceeding the defined load limit.
● Limit is defined as 'extracpus' in /var/cpanel/cpanel.config
– Restrictive BLACKHOUR definitions in WHM > Statistics Software
Configuration.
– All other issues should be present in /
usr/local/cpanel/logs/stats_log

cPanel Backups
-------------

GENERAL INFORMATION
● Backup configuration is performed in WHM > Backup > Configure
Backup
● cPanel backups are performed by /scripts/cpbackup, which is
configured by default to execute at 1:00 AM in the root crontab.
● Backup archives are created using the /scripts/pkgacct utility, and
may be restored using /scripts/restorepkg respectfully.
● Uses CPU resource limits based upon extracpus definition in
cpanel.config

Backup Configuration
-------------------

BACKUP INTERVALS
● Backup script can be configured to operate in daily, weekly, and monthly intervals.
● Each interval is given it's own respective directory within the backup root.
● Backup intervals are executed when the current time minus the last modification time
of the interval directory is less than or equal to zero.

BACKUP METHODS
----------------
Three backup methods are available:
● Standard: This method entails archiving the accounts, and storing
them at the specified path/mount point. This is the default method
used by the backup script.
● Incremental: This method uses rsync to incrementally backup user
data. This option will only operate locally, storing the data at the
specified path/mount point.
● Remote: This method transmits account archives to a specified ftp
server. Remote backups are typically more time consuming, and
more error prone when transmitting large accounts.

Common Backup Issues
--------------------

● Backup intervals are not executed when expected.
– Modification times are incorrect or not functional
– System time is incorrect.
– Backups have not been defined to run on that day.
● Backups stall, or take an exceedingly long time to complete.
– Verify that the transmission rate to remote server is suitable
– Verify that server load average has not exceeded defined
resource limit.

● Can't call method "login" on an undefined value
This indicates the host or passive setting is not properly
defined for remote backups.
● Unable to login to remote FTP server.
This indicates that either the username and password
were not specified, or are incorrect in the backup configuration.
● Can't call method "prepare" on an undefined value
The password stored for the root mysql user in /root/.my.cnf is
incorrect. Reset or correct this password, and re-execute the backup
script.

eximstats
---------

● The eximstats daemon is responsible for harvesting bandwidth
information from exim transactions.
● Continually monitors the exim_mainlog, and stores information in the
eximstats database, including host and sender information, message
size, and transaction times.
● Is started with the cPanel service, but can be called directly at /
usr/local/cpanel/bin/eximstats

● Heavily mysql dependent
– data is stored in the 'eximstats' database.
● 'eximstats' mysql user password is stored in /var/cpanel/eximstatspass.
– password is generated by /usr/local/cpanel/bin/eximstatspass
● Database can be installed by running /
usr/local/cpanel/bin/updateeximstats

cPanel Maintenance
-----------------
● Update configuration
● Update scripts
● Applying updates

● By default, cPanel applies nightly updates at 2:13AM in the root crontab.
● /scripts/upcp dispatches these updates, using the following key
components:
– /scripts/updatenow - synchronize /scripts directory
– /scripts/sysup - updates cPanel managed rpms
– /scripts/rpmup - all other system updates
● Updates are logged to timestamped files in /var/cpanel/updatelogs
● Update configuration is stored in /etc/cpupdate.conf.

/etc/cpupdate.conf
-----------------

● The following variables are available in cpupdate.conf:
– CPANEL = [ manual- ] stable | release | current | edge
This variable controls which update branch is used for
cPanel updates, and controls whether the updates are applied
manually or automatically (Default value: release)
– SYSUP = never (all other values are assumed true)
– RPMUP = never (all other values are assumed true)

CPANEL=current
RPMUP=daily
SYSUP=daily

● cPanel updates can be called outside of the regularly scheduled cron
time simply by executing /scripts/upcp.
● If cPanel components are missing or corrupted that were not replaced
with the regular cPanel update, they can be replaced by executing /
scripts/upcp –force

Components of upcp
------------------

● /scripts/cpanelsync
● /scripts/updatenow
● /scripts/sysup
● /scripts/rpmup

/scripts/cpanelsync
-----------------
● /scripts/cpanelsync is called upon by /scripts/updatenow and /
scripts/upcp
● Provides md5sum based synchronization with update servers
● md5sum table is stored in /destination_directory/.cpanelsync
● Accepts three arguments host, remote path, local path :
/scripts/cpanelsync 'httpupdate.cpanel.net'
'/cpanelsync/RELEASE/scripts' '/scripts'

/scripts/updatenow
-----------------

Calls cpanelsync to update contents of scripts
directory, which then stores it's md5sum table
at /scripts/.cpanelsync
● Should only be run from upcp, but can be
executed from command line when '--fromupcp'
is passed.
● Is the first update script called upon from /scripts/upcp

UPCP-->updatenow-->FTPUP-->EXIMUP-->MYSQLUP-->BANDMINUP-->COURIERUP-->RPMUP

RPMUP
--------

● Calls the underlying package manager to apply system package
updates
● The package manager which is used is determined by the presence
of:
– /var/cpanel/useup2date (Redhat)
– /var/cpanel/useyum (CentOS,Fedora)
– /var/cpanel/useapt (Debian)
– /var/cpanel/useswup (Trustix)
– /var/cpanel/userug (SuSE)

cPanel Updates
----------------

● After updatenow, sysup, and rpmup complete, cpanelsync is used to
complete the cPanel updates based on md5sum table stored at /
usr/local/cpanel/.cpanelsync
● If any special configurations are required on server after updates,
they can be applied in /scripts/postupcp, which is executed if such a
file exists and is executable.
● Once updates complete, all cPanel services are restarted for changes
to take effect

cPanel Scripts
--------------

● Account Management
● Package Management
● Service Update and Configuration
– MySQL
– Exim
– Named
– Apache
● cPanel and System

Account Management Scripts
------------------------------

● /scripts/wwwacct (account creation)
Accounts can be created via the command line using the following
syntax: /scripts/wwwacct exampledomain.com username password 0
x n
● /scripts/killacct (account termination)
Takes a single argument of the user to terminate.
● /scripts/suspendacct (account suspension)
Will suspend an account from accessing all cPanel managed
services.
● /scripts/unsuspendacct
Will reinstate any account suspended via suspendacct

● /scripts/addpop (Create pop account)
Handles creation of virtual mail accounts. Accepts either no
arguments, or two arguments consisting of the e-mail address and
password.
● /scripts/updateuserdomains
Updates the user:owner and user:domain tables stored in:
– /etc/userdomains
– /etc/trueuserdomains
– /etc/trueuserowners
– These tables are used to enumerate and keep track of accounts
and their owners.

Package Management
----------------------

● /scripts/ensurerpm
Takes argument list of rpms, which are then passed to the
underlying package manager
● /scripts/ensurepkg
The equivalent of ensurerpm for FreeBSD. Updates specified
packages from ports.
● /scripts/realperlinstaller
Takes argument list of perl modules to install via CPAN
● Each of the aforementioned scripts can accept an argument of '--force'
to force package installations.

● /scripts/mysqlup
Can be called to apply MySQL updates independent of upcp
● /scripts/cleanupmysqlprivs
Will clean up the default MySQL privilege tables, by installing
a more restrictive privilege schema.
● /scripts/mysqlconnectioncheck
Will verify that mysql is accessible with password stored in /root/.my.cnf,
and force a reset with a random 16 character string if inaccessible.
● /scripts/restartsrv_mysql

● /scripts/eximup
Can be called to apply exim updates independent of upcp
● /scripts/buildeximconf
Will rebuild exim.conf, and merge local, distribution, and cPanel
configurations
● /scripts/restartsrv_exim

● /scripts/rebuildnamedconf
Rebuild named.conf based on existing zone files
● /scripts/restartsrv_bind

● /scripts/easyapache
Download, extract, and execute apache build script
● /scripts/rebuildhttpdconf
Rebuilds httpd.conf based on DNS entries found in each
cPanel user configuration
● /scripts/restartsrv_httpd

cPanel Scripts
--------------

Useful Scripts – cPanel and System
● /scripts/restartsrv_{servicename}
The majority of cPanel managed service can be scripts named
appropriately.
● /scripts/makecpphp
Will rebuild the PHP interpreter used internally by cpsrvd
● /usr/local/cpanel/bin/checkperlmodules
Will scan for and install any Perl modules required by cPanel.
● /scripts/fullhordereset
Updates horde and resets the horde mysql user password
● /scripts/fixquotas
Will attempt to rebuild quota database per information stored in /
etc/quota.conf