Software Development Kit

cPanel & WHM's API [+] cPanel & WHM's API [-]

Modules and Plugins [+] Modules and Plugins [-]

cPanel & WHM Hooks [+] cPanel & WHM Hooks [-]

cPAddons (Site Software) [+] cPAddons (Site Software) [-]

System Administration [+] System Administration [-]

Developer Software [+] Developer Software [-]

Back to All Documentation



TailWatch is a process that handles the tasks previously handled by 4 separate processes: eximstats, chkservd, antirelayd and cpbandwd. Each of these older processes performed very similar functions. The common functionality has been merged into a single process. As a result, the system resource requirements are reduced.

How TailWatch works

As the name indicates, TailWatch monitors a log file for a certain activity and takes action based upon the activity. The specifics, such as which log to monitor and what to do with the information, is handled by a driver module. The stock drivers as shipped by cPanel are:

  • antirelayd
  • chkservd
  • eximstats
  • jailmanager (new in 11.38)
  • cpbandwd

These drivers are much improved versions of the prior stand-alone processes. These drivers now build on the features of the older implementations. Additional information about the function of each TailWatch driver is available in the Service Manager documentation.

Upgrade to TailWatch

The TailWatch drivers for chkservd, antirelayd, cpbandwd and eximstats are removed with the upgrade to TailWatch. You can control which TailWatch drivers are enabled in the Service Manager screen in WHM (Home >> Service Configuration >> Service Manager).

Once the upgrade to TailWatch is complete, the older scripts, such as /usr/local/cpanel/bin/eximstats, will no longer be used. These scripts will eventually be removed at a later update. An attempt to start the older process will result in failure, and a message will inform the user to use TailWatch instead.

Introduction to the chkservd Driver

chkservd is the driver used to determine if a process is online and whether the process needs to be restarted. You can decide which services are monitored via the Home >> Service Configuration >> Service Manager interface.

By default, chkservd checks each service every five minutes to determine if the server is online. This setting, along with other chkservd configuration options, can be modified in WHM via Home >> Server Configuration>> Tweak Settings >> System .

The Tweak Settings screen in WHM.

The chkservd log file contains the results from the check. This file can be found at


If a service is online, chkservd will move onto the next service. If a service is offline, chkservd will attempt to restart the service via the cPanel restart scripts located in:

  • /scripts/restartsrv_*

The results are displayed in the Server Information screen in WHM (Home >> Server Status >> Server Information). You can also have the results emailed to you.

Common Error for chkservd Driver

One of the most common issues occurs when a service is not monitored or has been disabled and the service is still listed on the service status page as offline. To fix this error, you may need to remove or edit a few files. In the following examples, the service is clamd.

PICK Remember: In the example below, clamd can be replaced with any other service.

  1. Remove the run file:
     rm -f /var/run/chkservd/clamd 
  2. Remove the chkservd configuration file:
     rm -f  /etc/chkserv.d/clamd 
  3. Edit the chkservd configuration file with your preferred text editor. You may need to remove the line for clamd. The chkservd configuration file can be found at:
  4. Restart chkservd:
    • This action will restart tailwatchd.

After you have made the necessary changes, return to the Service Manager interface and click Save at the bottom without any additional changes.

Other drivers (antirelayd, eximstats, jailmanager, and cpbandwd)

Unlike chkservd, the other drivers do not have their own log files or configuration. Information for these drivers are logged to the main tailwatchd log file at


Process Control and Status

You can control the TailWatch process with various command line flags passed to /usr/local/cpanel/bin/tailwatchd. You can obtain a full list of flags is obtainable via the -help flag:

/usr/local/cpanel/bin/tailwatchd - Driver based real time log processing 

--help This screen 
--version Show version of Cpanel::TailWatch  
--version=long Same as --version but also include active driver modules version 
information also. 
--status Status information  
--status=long Same as --status but also include information about the PID if its running  
--stop Stop current tailwatch daemon  
--start Start tailwatch daemon  
--restart Start tailwatch daemon, stopping it first if necessary  
--trace log the first 10,000 lines the drivers collectively process  
--trace=n log the first 'n' lines the drivers collectively process  
Trace only takes effect on --[re]start.  
--start --trace (equivalent to --start --trace=10000)  
--restart --trace='perl -e 'print 12+3-4+5+67+8+9;''  
--start --trace=1729  
--status --trace (--trace has no effect here)  
--debug This tells all driver's to log() debug messages.  
Debug only takes effect in --[re]start. Typically the message should be prefaced with 
‘[debug]’ and are about processed lines that result in an entry of some sort 
--perldoc This shows the POD for Cpanel::TailWatch 

Custom Functionality

It is possible to add custom functionality via a new driver. The PerlDoc for the TailWatch Module contains full documentation and examples. To access this documentation, execute:

  • /usr/local/cpanel/bin/tailwatchd --perldoc

New drivers need to be placed in /usr/local/cpanel/Cpanel/TailWatch. Once the drivers are in place, you can restart TailWatch to load the new drivers; this action will provide the driver's functionality.

Topic revision: r10 - 24 Apr 2013 - 18:55:28 - Main.GeorgeAlpizar
AllDocumentation/AutomationIntegration.TailWatch moved from Trash.AllDocumentationTailWatch on 15 Jun 2009 - 17:17 by Main.MelanieSeibert