cPHulk Management on the Command Line


Overview

This document describes how to manage the cPHulk service from the command line.

Note:
  • You can also manage the cPHulk service with WHM’s cPHulk Brute Force Protection interface (WHM >> Home >> Security Center >> cPHulk Brute Force Protection).

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

  • In cPanel & WHM version 62, we updated cPHulk to the 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.

Important:

The system requires several configuration changes to properly enable the cPHulk service. We strongly recommend that you do not enable it from the command line. Instead, we recommend that you 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, run the following command:

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

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

  2. Restart the cPHulk service:

    /usr/local/cpanel/scripts/restartsrv_cphulkd

To disable debug mode, perform the following steps:

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

  2. Restart the cPHulk service:

    /usr/local/cpanel/scripts/restartsrv_cphulkd

Check cPHulk’s service status

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

  • Use the WHM API 1 cphulk_status function.

  • Run the following command:

    ps aux | grep -i cphulk
    The system will return an output that resembles the following:
    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’s service

To restart the cPHulk service, perform one of the following actions:

  • Use the WHM API 1 configureservice function to perform the restart. This also performs the Dovecot® service rebuild and restart. 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, rebuild the Dovecot service, and restart the Dovecot service. 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, rebuild the Dovecot service, and restart the Dovecot service. 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 the cPHulk service

To disable the cPHulk service, perform one of the following actions:

  • Use the WHM API 1 disable_cphulk function.

  • Use the WHM API 1 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

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

  1. Remove the enabled touch file in the /var/cpanel/hulkd/ directory.

  2. Edit the /etc/dovecot/dovecot.conf file and 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:

    1
    
    /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 will override an IP address on the whitelist. To unblock an IP address, use the WHM API 1 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, IP represents an IP address or IP address range:

/usr/local/cpanel/scripts/cphulkdwhitelist IP

Blacklist an IP address

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

/usr/local/cpanel/scripts/cphulkdblacklist IP

Remove lockouts

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

  1. Log in to WHM.

  2. Append the following to the WHM URL address:

    /scripts2/doautofixer?autofix=disable_cphulkd
    For example, append this script to the following URL. 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 Block IP addresses at the firewall level if they trigger brute force protection or the Block IP addresses at the firewall level if they trigger a one-day block options in WHM’s cPHulk Brute Force Protection interface (WHM >> Home >> Security Center >> cPHulk Brute Force Protection), remove the iptables rule that the system created. To do this, run the following command:

Note:

This command removes all of the cPHulk service’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.

cPanel & WHM version 62 and later

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

cPanel & WHM version 60 and earlier

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

Additional Documentation