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 WebServer role, the system disables this function. For more information, read our How to Use Server Profiles documentation.

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:

  • 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 string as a valid argument for the directive.

A valid string.

Note:

For more information, read our 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.

Read the Radio options section below for a list of possible values.

 
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

An array of validators to apply.

Read the Validators section below for a list of possible values.

 

Radio options

 Click to view...

The function only returns this data if the setting's value for the type parameter is radio. The function returns this information as a set of hashes within the radio_options array.

Each hash contains the following returns:

ReturnTypeDescriptionPossible valuesExample
optionstring

The setting name that the WHM API uses to select the setting's state.

Note:

The string that the option key returns is identical to the string that the client sends in the state field when users select this option. In most cases, do not display this value to the user. Instead, display the name value.

A valid string.
On
namestringThe setting name to display to the user. The user's locale may translate this value.A valid string.
Log all transactions.

Validators

 Click to view...

The function may specify one or more validators for a setting. The client should use these validators to perform front-end validation through the preferred implementation methods.

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 represents the validator as a hash, the WHM API may also include an argument for the validator.
ValidatorValidator descriptionArgument descriptionExample
pathInstructs the client to verify that the user's input is a valid path.(none)

path

startsWithInstructs the client to verify that the user's input begins with the pattern that the argument specifies.A string that represents a regular expression to apply against the user input.
{ name: 'startsWith', arg: '[Ee]xample' }

Note:

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

honeypotAccessKeyInstructs the client to verify that the user's input fits the constraints of an Http:BL API access key.(none)honeypotAccessKey
positiveIntegerInstructs the client to verify that the user's input is a positive integer.(none)positiveInteger