cPHulk Management on the Command Line


Last modified: August 20, 2021

Overview

This document describes how to manage cPHulk from the command line. You can also manage cPHulk with WHM’s cPHulk Brute Force Protection interface (WHM >> Home >> Security Center >> cPHulk Brute Force Protection).

Note:
  • This feature requires that you use SSH to access your server as the root user.

  • In cPanel & WHM version 62 and later, cPHulk uses an SQLite database.

  • In cPanel & WHM version 72 and later, you can use cPanel’s Terminal interface (cPanel >> Home >> Advanced >> Terminal) or WHM’s Terminal interface (WHM >> Home >> Advanced >> Terminal) to access the command line from within the interface.

Manage cPHulk

Use the following methods to manage the cPHulk service (cphulkd) on your server.

Enable cPHulk

To enable cPHulk, you can use the following methods:

Enable and disable debug mode

To enable debug mode, perform the following steps:

  1. Create the debug touch file in the /var/cpanel/hulkd directory:

    echo 3 > touch /var/cpanel/hulkd/debug

  2. Restart cPHulk:

    /usr/local/cpanel/scripts/restartsrv_cphulkd

To disable debug mode, perform the following steps:

  1. Remove the debug touch file:

    rm /var/cpanel/hulkd/debug

  2. Restart cPHulk:

    /usr/local/cpanel/scripts/restartsrv_cphulkd

Check cPHulk’s status

To check the status of cPHulk, perform one of the following actions:

  • Call WHM API 1’s cphulk_status function.

  • Run the following command:

    ps aux | grep -i cphulk
    The system will return output that resembles the following example:
    root 1501 0.0 0.4 34816 5076 ? S 07:58 0:00 cPhulkd - processor
    In this example, the output indicates that cPHulk is enabled.

Restart cPHulk

To restart cPHulk, perform one of the following actions:

  • Call WHM API 1’s configureservice function. This also rebuilds and restarts Dovecot. To do this, run the following commands:

    1
    2
    
    whmapi1 configureservice service=cphulkd enabled=0 monitored=0
    whmapi1 configureservice service=cphulkd enabled=1 monitored=1

  • Perform a soft restart. Then, rebuild and then restart Dovecot. To do this, run the following scripts:

    1
    2
    3
    
    /usr/local/cpanel/scripts/restartsrv_cphulkd
    /usr/local/cpanel/scripts/builddovecotconf
    /usr/local/cpanel/scripts/restartsrv_dovecot

  • Perform a hard restart and force the system to flush the service’s memory. Then, rebuild and restart Dovecot. To do this, run the following commands:

    1
    2
    3
    
    /usr/local/cpanel/scripts/restartsrv_cphulkd --stop; /scripts/restartsrv_cphulkd --start
    /usr/local/cpanel/scripts/builddovecotconf
    /usr/local/cpanel/scripts/restartsrv_dovecot

Disable cPHulk

To disable cPHulk, perform one of the following actions:

  • Call WHM API 1’s disable_cphulk function.

  • Call WHM API 1’s configureservice function. For example:

    whmapi1 configureservice service=cphulkd enabled=0 monitored=0

  • Run the following commands:

    1
    2
    
    /usr/local/cpanel/etc/init/stopcphulkd
    /usr/local/cpanel/bin/cphulk_pam_ctl --disable

Keep cPHulk offline

To disable cPHulk so that it remains offline, even after a restart of cPanel & WHM, perform the following steps:

  1. Remove the enabled touch file:

    rm /var/cpanel/hulkd/enabled

  2. Edit the /etc/dovecot/dovecot.conf file to remove the following line:

    auth_policy_server_url = http://127.0.0.1:579/dovecot-auth-policy

  3. Rebuild Dovecot’s configuration file. To do this, run the following script:

    /usr/local/cpanel/scripts/builddovecotconf

  4. Restart Dovecot. To do this, run the following script:

    /usr/local/cpanel/scripts/restartsrv_dovecot

Log files

cPHulk stores its logs in the following files:

  • /usr/local/cpanel/logs/cphulkd.log

  • /usr/local/cpanel/logs/cphulkd_errors.log

IP address management

You can use the following commands to add an IP address to cPHulk’s whitelist and blacklist:

Note:
  • If an IP address exists on both lists, the system will override the blacklist entry.

  • An IP address block in the iptables application will override an IP address on the whitelist. To unblock an IP address, call WHM API 1’s flush_cphulk_login_history_for_ips function.

Whitelist an IP address

To add an IP address to the whitelist, run the following script. In this example, 192.0.2.0 represents an IP address or IP address range:

/usr/local/cpanel/scripts/cphulkdwhitelist 192.0.2.0

Blacklist an IP address

To add an IP address to the blacklist, run the following script. In this example, 192.0.2.0 represents an IP address or IP address range:

/usr/local/cpanel/scripts/cphulkdblacklist 192.0.2.0

Remove lockouts

If cPHulk locks you out of your cPanel account, perform the following steps:

  1. Log in to WHM.

  2. Append the following string to the WHM URL:

    /scripts2/doautofixer?autofix=disable_cphulkd
    The resulting URL may resemble the following example. In this example, www.example.com is your server’s hostname:
    https://www.example.com:2087/scripts2/doautofixer?autofix=disable_cphulkd

If you enabled the following settings in WHM’s cPHulk Brute Force Protection interface (WHM >> Home >> Security Center >> cPHulk Brute Force Protection), you must remove the iptables rule that the system created:

  • Block IP addresses at the firewall level if they trigger brute force protection
  • Block IP addresses at the firewall level if they trigger a one-day block

To do this, run one of the following commands:

  • For cPanel & WHM version 62 and later, run:

    iptables -F cphulk && /usr/local/cpanel/3rdparty/bin/sqlite3 /var/cpanel/hulkd/cphulk.sqlite "DELETE FROM login_track;"

  • For cPanel & WHM version 60 and earlier, run:

    iptables -F cphulk && mysql -e "Delete from cphulkd.login_track;"

Note:

These commands remove all of cPHulk’s lockouts. To remove the lockout for a specific IP address on servers that run cPanel & WHM version 11.50 or later, call WHM API 1’s flush_cphulk_login_history_for_ips function.

Additional Documentation