We have a new documentation site for cPanel & WHM! You can find our new documentation site at docs.cpanel.net.

We will continue to maintain our API documentation on this server.

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

Description

This function sets a global ModSecurity™ configuration directive.

Important:

In cPanel & WHM version 76 and later, when you disable the Web Server role, the system disables this function.

Examples


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/modsec_set_setting?api.version=1&setting_id=8&state=2000 
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/modsec_set_setting?api.version=1&setting_id=8&state=2000 
 Command Line
whmapi1 modsec_set_setting setting_id=8 state=2000 


Notes:

  • Unless otherwise noted, you must URI-encode values.
  • For more information and additional output options, read our Guide to WHM API 1 documentation or run the whmapi1 --help command.
  • If you run CloudLinux™, you must use the full path of the whmapi1 command:

    /usr/local/cpanel/bin/whmapi1

 Output (JSON)
{
    "data": {
        "setting_id": 8,
        "name": "Perl Compatible Regular Expressions Library Match Limit",
        "default": 1500,
        "validation": [
            "positiveInteger"
        ],
        "description": "Define the match limit of the Perl Compatible Regular Expressions library.",
        "state": "2000",
        "url": "https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secpcrematchlimit",
        "directive": "SecPcreMatchLimit",
        "type": "number"
    },
    "metadata": {
        "version": 1,
        "reason": "OK",
        "result": 1,
        "command": "modsec_set_setting"
    }
}
 Output (XML)
<result>
  <data>
    <name>Perl Compatible Regular Expressions Library Match Limit</name>
    <default>1500</default>
    <description>Define the match limit of the Perl Compatible Regular Expressions library.</description>
    <directive>SecPcreMatchLimit</directive>
    <setting_id>8</setting_id>
    <state>2000</state>
    <type>number</type>
    <url>https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secpcrematchlimit</url>
    <validation>positiveInteger</validation>
  </data>
  <metadata>
    <command>modsec_set_setting</command>
    <reason>OK</reason>
    <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

ParameterTypeDescriptionPossible valuesExample
setting_idinteger

Required

The setting's ID.


A non-negative integer.

Note:

The WHM API 1 modsec_get_settings function returns this value.

8
statestring

Required

The setting's new state. The function uses this as a valid argument for the directive.

A valid string.

Note:

For more information, read SpiderLabs' ModSecurity documentation.

2000

Returns

ReturnTypeDescriptionPossible valuesExample
default
string

The setting's default value.

A valid string
1500
description
stringThe setting's description.

A valid string.


 Click to view...
This setting allows you to define the match limit of the PCRE library.
directive
stringThe setting's Apache directive.A valid directive name.
SecPcreMatchLimit
name
stringThe setting's name.A valid string.
PCRE library match limit
radio_options
array of hashes

An array of hashes of the options that the client should display, as buttons, for this setting in a user interface.

Note:

The function only returns this array of hashes when you set the type parameter's value to radio.

Each hash includes the option  and name returns.


option 

string

The setting that the system used to select the setting's state.

Note:

This value is identical to the string that the client sends in as state value when users select the specified setting. In most cases, you should not display this value to the user. Instead, display the name value.

The function returns this value in the radio_options array.

A valid string.On 

name

string

The setting name to display to the user. The user's locale may translate this value.

The function returns this value in the radio_options array.

A valid string.Log all transactions. 
setting_id
integer

The setting's ID.

A valid non-negative integer.
8
state
integerThe setting's new state.The argument to the directive.
2000
typestringThe type of UI control that the client should use to represent the setting.
  • text — WHM users modify this setting via a text box.
  • radio — WHM users modify this setting via a radio button.

    Note:

    If the type parameter's value is radio, the function also returns the radio_options array of hashes. 

  • number — WHM users modify this setting via a text box that only allows numeric values.
text
url
stringThe URL for the setting's documentation.A valid URL.
 Click to view...
https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secpcrematchlimit
validationarray

A validator or array of validators to apply. Use these validators to perform frontend validation through your preferred implementation methods.

Note:

The function may represent each validator as either a string or a hash.

  • When the function represents the validator as a string, no arguments exist for the validator. 
  • When the function returns the validator as a hash, the API may also include an argument for the validator.
  • path — An instruction to verify whether the user's input is a valid path.
  • A regular expression that contains startsWith — An instruction to verify that the user's input begins with the pattern the regular expression specifies.

  • honeypotAccessKey — An instruction to verify whether the user's input fits the constraints of an Http:BL API access key.
  • positiveInteger — An instruction to verify whether the user's input is a positive integer.
{
"name":"startsWith",
"arg":"[Ee]xample"
}

Note:

This example is JSON-encoded, to illustrate the validator's structure.