cPHulk Management on the Command Line

Last modified: February 20, 2024

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.
cPHulk uses an SQLite database.
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.
cPHulk uses GeoLite2 data created by MaxMind.

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:

WHM’s cPHulk Brute Force Protection interface (WHM » Home » Security Center » cPHulk Brute Force Protection).
From the command line, run the WHM API 1 enable_cphulk command:
```
whmapi1 enable_cphulk
```

Enable and disable debug mode

To enable debug mode, perform the following steps:

Create the debug touch file in the /var/cpanel/hulkd directory:
```
echo 3 > /var/cpanel/hulkd/debug
```

Restart cPHulk:

/usr/local/cpanel/scripts/restartsrv_cphulkd

To disable debug mode, perform the following steps:

Remove the debug touch file:
```
rm /var/cpanel/hulkd/debug
```

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:

Remove the enabled touch file:
```
rm /var/cpanel/hulkd/enabled
```

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

Rebuild Dovecot’s configuration file. To do this, run the following script:
```
/usr/local/cpanel/scripts/builddovecotconf
```
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:

Log in to WHM.
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 the following command:

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

Note:

These commands remove all of cPHulk’s lockouts. To remove the lockout for a specific IP address, call WHM API 1’s flush_cphulk_login_history_for_ips function.