cPHulk Management on the Command Line


Last modified: March 17, 2020

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

Important:

The system requires several configuration changes to properly enable cPHulk. Do not enable it from the command line.

To enable cPHulk, use WHM’s cPHulk Brute Force Protection interface (WHM >> Home >> Security Center >> cPHulk Brute Force Protection).

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