Child pages
  • WHM API 1 Functions - set_cphulk_config_key
Skip to end of metadata
Go to start of metadata

Description

This function sets cPHulk's configuration settings.

Examples


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/set_cphulk_config_key?api.version=1&key=block_brute_force_with_firewall&value=0
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/set_cphulk_config_key?api.version=1&key=block_brute_force_with_firewall&value=0
 Command Line
whmapi1 set_cphulk_config_key key=block_brute_force_with_firewall value=0
 Output (JSON)
{  
   "data":{  
      "cphulk_config":{  
         "block_brute_force_with_firewall":0,
         "block_excessive_brute_force_with_firewall":1,
         "brute_force_period_mins":5,
         "brute_force_period_sec":300,
         "can_temp_ban_firewall":1,
         "command_to_run_on_brute_force":"",
         "command_to_run_on_excessive_brute_force":"",
         "country_blacklist":"PK,BR",
         "country_whitelist":"US,AU",
         "ip_based_protection":0,
         "ip_brute_force_period_mins":15,
         "ip_brute_force_period_sec":900,
         "is_enabled":1,
         "lookback_period_min":360,
         "lookback_time":21600,
         "mark_as_brute":30,
         "max_failures":15,
         "max_failures_byip":5,
         "notify_on_brute":0,
         "notify_on_root_login":0,
         "notify_on_root_login_for_known_netblock":0,
         "username_based_protection":0,
         "username_based_protection_for_root":0,
         "username_based_protection_local_origin":0
      }
   },
   "metadata":{  
      "reason":"OK",
      "command":"set_cphulk_config_key",
      "result":1,
      "version":1
   }
}
 Output (XML)
<result>
	<data>
		<cphulk_config>
			<block_brute_force_with_firewall>0</block_brute_force_with_firewall>
			<block_excessive_brute_force_with_firewall>1</block_excessive_brute_force_with_firewall>
			<brute_force_period_mins>5</brute_force_period_mins>
			<brute_force_period_sec>300</brute_force_period_sec>
			<can_temp_ban_firewall>1</can_temp_ban_firewall>
			<command_to_run_on_brute_force></command_to_run_on_brute_force>
			<command_to_run_on_excessive_brute_force></command_to_run_on_excessive_brute_force>
			<country_blacklist>PK,BR</country_blacklist>
			<country_whitelist>US,AU</country_whitelist>
			<ip_based_protection>0</ip_based_protection>
			<ip_brute_force_period_mins>15</ip_brute_force_period_mins>
			<ip_brute_force_period_sec>900</ip_brute_force_period_sec>
			<is_enabled>1</is_enabled>
			<lookback_period_min>360</lookback_period_min>
			<lookback_time>21600</lookback_time>
			<mark_as_brute>30</mark_as_brute>
			<max_failures>15</max_failures>
			<max_failures_byip>5</max_failures_byip>
			<notify_on_brute>0</notify_on_brute>
			<notify_on_root_login>0</notify_on_root_login>
			<notify_on_root_login_for_known_netblock>0</notify_on_root_login_for_known_netblock>
			<username_based_protection>0</username_based_protection>
			<username_based_protection_for_root>0</username_based_protection_for_root>
			<username_based_protection_local_origin>0</username_based_protection_local_origin>
		</cphulk_config>
	</data>
	<metadata>
		<reason>OK</reason>
		<command>set_cphulk_config_key</command>
		<result>1</result>
		<version>1</version>
	</metadata>
</result>


Note:

Use WHM's API Shell interface (WHM >> Home >> Development >> API Shell) to directly test WHM API calls.

Parameters

Notes:

  • You must set at least one key and value pair.
  • You can only enter one key and value pair per call.


ParameterTypeDescriptionPossible valuesExample

block_brute_force_with_firewall

Boolean

Whether to use cPanel & WHM's firewall to block brute force attacks.

This parameter defaults to 0.

  • 1 — Use the firewall.
  • 0 — Do not use the firewall.
0

block_excessive_brute_force_with_firewall

Boolean

Whether to use cPanel & WHM's firewall to block excessive brute force attacks.

This parameter defaults to 0.

  • 1 — Use the firewall.
  • 0 — Do not use the firewall.
0

brute_force_period_mins

integer

The number of minutes over which cPHulk measures all login attempts to a specific user's account.

This parameter defaults to 5.

A valid integer.5

brute_force_period_sec

integer

The number of seconds over which cPHulk measures all login attempts to a specific user's account.

The parameter defaults to the brute_force_period_mins parameter's value multiplied by 60.

A valid integer.300

command_to_run_on_brute_force

string

The command to run when an IP address triggers brute force protection.

Note:

For a list of commands, read the Command variables section of our cPHulk Brute Force Protection documentation.

This parameter defaults to an empty string.

  • A valid command.
  • An empty string.
""

command_to_run_on_excessive_brute_force

string

The command to run when the system blocks an IP address blocked for a one day period.

Note:

For a list of commands, read the Command variables section of our cPHulk Brute Force Protection documentation.

This parameter defaults to an empty string.

  • A valid command.
  • An empty string.
""

country_blacklist

string

The countries to blacklist.

Notes:

  • This value overwrites the current blacklist.
  • Enter a comma-separated list to enter more than one value.
  • For a list of countries, run the WHM API 1 function get_countries_with_known_ip_ranges .

This parameter defaults to an empty string.

PK,BR

country_whitelist

string

The countries to whitelist.

Notes:

  • This value overwrites the current whitelist.
  • Enter a comma-separated list to enter more than one value.
  • For a list of countries, run the WHM API 1 function get_countries_with_known_ip_ranges .

This parameter defaults to an empty string.

US,AU

ip_based_protection

Boolean

Whether to enable IP address-based protection on all requests.

Note:

If you set the ip_based_protection parameter to 0, you cannot use the following parameters:

  • block_brute_force_with_firewall
  • block_excessive_brute_force_with_firewall
  • ip_brute_force_period_mins
  • ip_brute_force_period_sec

This parameter defaults to 1.

  • 1 — Enable IP-based protection.
  • 0 — Disable IP-based protection.
1

ip_brute_force_period_mins

integer

The number of minutes in which cPHulk measures an attacker's login attempts.

The parameter defaults to 15.

A valid integer.15

ip_brute_force_period_sec

integer

The number of seconds in which cPHulk measures an attacker's login attempts.

The parameter defaults to the ip_brute_force_period_mins parameter's value multiplied by 60.

A valid integer.900

is_enabled

Boolean

Whether to enable the cPHulk service.

This parameter defaults to 1.

  • 1 — Enable.
  • 0 — Disable.
1

lookback_period_min

integer

The number of minutes over which cPHulk counts failed logins against a user.

This parameter defaults to 360.

A valid integer.360

lookback_time

integer

The number of seconds over which cPHulk counts failed logins against a user.

The parameter defaults to the lookback_period_min parameter's value multiplied by 60.

A valid integer.21600

mark_as_brute

integer

The maximum number of failures from a specific IP address before cPHulk blocks that address for a two-week period.

This parameter defaults to 30.

A valid integer.30

max_failures

integer

The maximum number of failures that cPHulk allows per account within the defined time range.

This parameter defaults to 30.

A valid integer.30

max_failures_byip

integer

The maximum number of failures from a specific IP address before cPHulk locks out that address.

This parameter defaults to 5.

A valid integer.5

notify_on_brute

Boolean

Whether cPHulk will send a notification when it detects a brute force attack.

This parameter defaults to 0 .


  • 1 — Send the notification.
  • 0 — Do not send the notification.
0

notify_on_root_login

Boolean

Whether cPHulk will send a notification when the root user successfully logs in from an IP address that is not on the whitelist.

This parameter defaults to 0.

  • 1 — Send the notification.
  • 0 — Do not send the notification.
0

notify_on_root_login_for_known_netblock

Boolean

Whether cPHulk sends a notification upon successful root login when the IP address is not on the whitelist, but from a known netblock

This parameter defaults to 0.

  • 1 — Send the notification.
  • 0 — Do not send the notification.
0

username_based_protection

Boolean

Whether to enable username-based protection on all requests.

This parameter defaults to 0.

  • 1 — Enable.
  • 0 — Disable.
0

username_based_protection_for_root

Boolean

Whether to allow username-based protection to lock out the root user.

This parameter defaults to 0 .

  • 1 — Allow.
  • 0 — Do not allow.
0

username_based_protection_local_origin

Boolean

Whether to enable username-based protection only on requests that originate from a local IP address.

This parameter defaults to 1 .

  • 1 — Enable.
  • 0 — Disable.
1

Returns

ReturnTypeDescriptionPossible valuesExample
cphulk_confighash

A hash of cPHulk configuration settings.



This hash contains the 

block_brute_force_with_firewall, block_excessive_brute_force_with_firewall, brute_force_period_mins, brute_force_period_sec, can_temp_ban_firewall, command_to_run_on_brute_force, command_to_run_on_excessive_brute_force, country_blacklist, country_whitelist, ip_based_protection, ip_brute_force_period_mins, ip_brute_force_period_sec, is_enabled
lookback_period_min, lookback_time, mark_as_brute, max_failures, max_failures_byip, notify_on_brute, notify_on_root_login, notify_on_root_login_for_known_netblock, username_based_protection, username_based_protection_for_root, and username_based_protection_local_origin returns.

 

block_brute_force_with_firewall

Boolean

Whether to use cPanel & WHM's firewall to block brute force attacks.

The function returns this value in the cphulk_config hash.

  • 1 — Use the firewall.
  • 0 — Do not use the firewall.
0

block_excessive_brute_force_with_firewall

Boolean

Whether to use cPanel & WHM's firewall to block excessive brute force attacks.

The function returns this value in the cphulk_config hash.

  • 1 — Use the firewall.
  • 0 — Do not use the firewall.
0

brute_force_period_mins

integer

The number of minutes over which cPHulk measures all login attempts to a specific user's account.

The function returns this value in the cphulk_config hash.

A valid integer.5

brute_force_period_sec

integer

The number of seconds over which cPHulk measures all login attempts to a specific user's account.

The function returns this value in the cphulk_config hash.

A valid integer.300

can_temp_ban_firewall

Boolean

Whether the system firewall can apply temporary IP address bans.

The function returns this value in the cphulk_config hash.

  • 1 — Can temporarily apply IP address bans.
  • 0 — Cannot temporarily apply IP address bans.

Note:

If this return's value is 0, then the ip_based_protection parameter is not available, which means that you cannot use the following parameters:

  • block_brute_force_with_firewall
  • block_excessive_brute_force_with_firewall
  • ip_brute_force_period_mins
  • ip_brute_force_period_sec
1

command_to_run_on_brute_force

string

The command to run when an IP address triggers brute force protection.

The function returns this value in the cphulk_config hash.

  • A valid command.
  • An empty string.
""

command_to_run_on_excessive_brute_force

string

The command to run when the system blocks an IP address blocked for a one day period.

The function returns this value in the cphulk_config hash.

  • A valid command.
  • An empty string.
""

country_blacklist

string

The countries to blacklist.

The function returns this value in the cphulk_config hash.


PK,BR

country_whitelist

string

The countries to whitelist.

The function returns this value in the cphulk_config hash.


US,AU

ip_based_protection

Boolean

Whether IP address-based protection on all requests is enabled.

The function returns this value in the cphulk_config hash.

  • 1 — Enabled.
  • 0 — Disabled.
1

ip_brute_force_period_mins

integer

The number of minutes in which cPHulk measures an attacker's login attempts.

The function returns this value in the cphulk_config hash.

A valid integer.15

ip_brute_force_period_sec

integer

The number of seconds in which cPHulk measures an attacker's login attempts.

The function returns this value in the cphulk_config hash.

A valid integer.900

is_enabled

Boolean

Whether the cPHulk service is enabled.

The function returns this value in the cphulk_config hash.

  • 1 — Enabled.
  • 0 — Disabled.
1

lookback_period_min

integer

The number of minutes over which cPHulk counts failed logins against a user.

The function returns this value in the cphulk_config hash.

A valid integer.360

lookback_time

integer

The number of seconds over which cPHulk counts failed logins against a user.

The function returns this value in the cphulk_config hash.

A valid integer.21600

mark_as_brute

integer

The maximum number of failures from a specific IP address before cPHulk blocks that address for a two-week period.

The function returns this value in the cphulk_config hash.

A valid integer.30

max_failures

integer

The maximum number of failures that cPHulk allows per account within the defined time range.

The function returns this value in the cphulk_config hash.

A valid integer.30

max_failures_byip

integer

The maximum number of failures from a specific IP address before cPHulk locks out that address.

The function returns this value in the cphulk_config hash.

A valid integer.5

notify_on_brute

Boolean

Whether cPHulk will send a notification when it detects a brute force attack.

The function returns this value in the cphulk_config hash.

  • 1 — Send the notification.
  • 0 — Do not send the notification.
0

notify_on_root_login

Boolean

Whether cPHulk will send a notification when the root user successfully logs in from an IP address that is not on the whitelist.

The function returns this value in the cphulk_config hash.

  • 1 — Send the notification.
  • 0 — Do not send the notification.
0

notify_on_root_login_for_known_netblock

Boolean

Whether cPHulk sends a notification upon successful root login when the IP address is not on the whitelist, but from a known netblock

The function returns this value in the cphulk_config hash.

  • 1 — Send the notification.
  • 0 — Do not send the notification.
0

username_based_protection

Boolean

Whether username-based protection on all requests is enabled.

The function returns this value in the cphulk_config hash.

  • 1 — Enabled.
  • 0Disabled.
0

username_based_protection_for_root

Boolean

Whether username-based protection can lock out the root user.

The function returns this value in the cphulk_config hash.

  • 1 — Allowed.
  • 0Not allowed.
0

username_based_protection_local_origin

Boolean

Whether username-based protection only on requests that originate from a local IP address.

The function returns this value in the cphulk_config hash.

  • 1 — Enabled.
  • 0 — Disabled.
1