WHM API 1 Functions - modsec_batch_settings

This function adds, updates, and removes global ModSecurity™ configuration directives. The function modifies these directives in the /usr/local/apache/conf/modsec2.cpanel.conf file.

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_batch_settings?api.version=1&setting_id1=0&state1=On&setting_id2=3&state2=Off&setting_id3=1&state3=On

XML API

https://hostname.example.com:2087/cpsess##########/xml-api/modsec_batch_settings?api.version=1&setting_id1=0&state1=On&setting_id2=3&state2=Off&setting_id3=1&state3=On

Command Line

whmapi1 modsec_batch_settings setting_id1=0 state1=On setting_id2=3 state2=Off setting_id3=1 state3=On

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":{  
      "updated_settings":[  
         {  
            "setting_id":0,
            "name":"Audit Log Level",
            "default":"Off",
            "description":"This setting controls the behavior of the audit engine.",
            "state":"On",
            "engine":1,
            "url":"https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secauditengine",
            "radio_options":[  
               {  
                  "name":"Log all transactions.",
                  "option":"On"
               },
               {  
                  "name":"Do not log any transactions.",
                  "option":"Off"
               },
               {  
                  "name":"Only log noteworthy transactions.",
                  "option":"RelevantOnly"
               }
            ],
            "directive":"SecAuditEngine",
            "type":"radio"
         },
         {  
            "setting_id":3,
            "name":"Backend Compression",
            "default":"Off",
            "description":"Disables backend compression while leaving the frontend compression enabled.",
            "state":"Off",
            "radio_options":[  
               {  
                  "name":"Disabled",
                  "option":"On"
               },
               {  
                  "name":"Enabled",
                  "option":"Off"
               }
            ],
            "url":"https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secdisablebackendcompression",
            "directive":"SecDisableBackendCompression",
            "type":"radio"
         },
         {  
            "setting_id":1,
            "name":"Connections Engine",
            "default":"Off",
            "description":"This setting controls the behavior of the connections engine.",
            "state":"On",
            "engine":1,
            "radio_options":[  
               {  
                  "name":"Process the rules.",
                  "option":"On"
               },
               {  
                  "name":"Do not process the rules.",
                  "option":"Off"
               },
               {  
                  "name":"Process the rules in verbose mode, but do not execute disruptive actions.",
                  "option":"DetectionOnly"
               }
            ],
            "url":"https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secconnengine",
            "directive":"SecConnEngine",
            "type":"radio"
         }
      ]
   },
   "metadata":{  
      "version":1,
      "reason":"OK",
      "result":1,
      "command":"modsec_batch_settings"
   }
}

Output (XML)

<result>
    <data>
        <updated_settings>
            <setting_id>0</setting_id>
            <name>Audit Log Level</name>
            <default>Off</default>
            <description>
                This setting controls the behavior of the audit engine.
            </description>
            <state>On</state>
            <engine>1</engine>
            <url>
                https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secauditengine
            </url>
            <radio_options>
                <name>Log all transactions.</name>
                <option>On</option>
            </radio_options>
            <radio_options>
                <name>Do not log any transactions.</name>
                <option>Off</option>
            </radio_options>
            <radio_options>
                <name>Only log noteworthy transactions.</name>
                <option>RelevantOnly</option>
            </radio_options>
            <directive>SecAuditEngine</directive>
            <type>radio</type>
        </updated_settings>
        <updated_settings>
            <setting_id>3</setting_id>
            <name>Backend Compression</name>
            <default>Off</default>
            <description>
                Disables backend compression while leaving the frontend compression enabled.
            </description>
            <state>Off</state>
            <radio_options>
                <name>Disabled</name>
                <option>On</option>
            </radio_options>
            <radio_options>
                <name>Enabled</name>
                <option>Off</option>
            </radio_options>
            <url>
                https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secdisablebackendcompression
            </url>
            <directive>SecDisableBackendCompression</directive>
            <type>radio</type>
        </updated_settings>
        <updated_settings>
            <setting_id>1</setting_id>
            <name>Connections Engine</name>
            <default>Off</default>
            <description>
                This setting controls the behavior of the connections engine.
            </description>
            <state>On</state>
            <engine>1</engine>
            <radio_options>
                <name>Process the rules.</name>
                <option>On</option>
            </radio_options>
            <radio_options>
                <name>Do not process the rules.</name>
                <option>Off</option>
            </radio_options>
            <radio_options>
                <name>
                    Process the rules in verbose mode, but do not execute disruptive actions.
                </name>
                <option>DetectionOnly</option>
            </radio_options>
            <url>
                https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secconnengine
            </url>
            <directive>SecConnEngine</directive>
            <type>radio</type>
        </updated_settings>
    </data>
    <metadata>
        <version>1</version>
        <reason>OK</reason>
        <result>1</result>
        <command>modsec_batch_settings</command>
    </metadata>
</result>

Note:

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

Parameters

Parameter	Type	Description	Possible values	Example
`setting_id`	integer	Required The configuration setting's ID. Note: Increment the parameter name to specify more than one `setting_id` parameter (for example, `setting_id1` and `setting_id` `2` ).	A positive integer.	`1`
`state`	string	Required The configuration setting's current state. Note: Increment the parameter name to specify more than one `state` parameter (for example, `state1` and `state2`).	`On` `Off` Note: Some settings can accept additional values for this parameter.	`Off`
`remove`	Boolean	Whether to add or remove the configuration setting in the `/usr/local/apache/conf/modsec2.cpanel.conf` file. Note: Increment the parameter name to specify more than one `state` parameter (for example, `remove1` and `remove2` ).	`1` — Remove the configuration setting. `0` — Add the configuration setting.	`0`

Returns

Return	Type	Description	Possible values	Example
`updated_settings`	array of hashes	An array of hashes of setting information.	Each hash contains the `setting_id`, `name`, `default`, `description`, `state`, `engine`, `url`, `directive`, and `type` returns and the `radio_options` array of hashes.
`setting_id`	string	The setting ID. The function returns this value in the `updated_settings` array.	A positive integer.	`1`
`name`	string	The setting's name. The function returns this value in the `updated_settings` array.	A valid string.	`Audit Log Level`
`default`	string	The setting's default value. The function returns this value in the `updated_settings` array.	A positive integer. Note: The `modsec2.cpanel.conf` file defines this value.	`1500`
`description`	string	The setting's description. The function returns this value in the `updated_settings` array.	A valid string.	Click to view... `define the match limit of the PCRE library.`
`state`	string	The setting's current state. The function returns this value in the `updated_settings` array.	The `state` input parameter's value for the setting.	`On`
`engine`	Boolean	Whether the setting is an engine directive. The function returns this value in the `updated_settings` array.	`1` — Engine directive. `0` — Normal directive.	`1`
`url`	string	The URL of the setting's entry in the ModSecurity reference manual. The function returns this value in the `updated_settings` array.	A valid URL.	Click to view... https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#secpcrematchlimit
`radio_options`	array of hashes	An array of hashes that contain the setting's options' display information. The function returns this array in the `updated_settings` array.	Each hash contains the `name` and `option` returns.
`name`	string	The option's display name. The function returns this value in the `radio_options` array.	A valid string.	`Log all transactions.`
`option`	string	The option. The function returns this value in the `radio_options` array.	A valid option name.	`On`
`directive`	string	The setting's Apache configuration directive. The function returns this value in the `updated_settings` array.	A valid directive name.	`SecAuditEngine`
`type`	string	The form element that the WHM interface uses to display this setting. The function returns this value in the `updated_settings` array.	`text` — WHM users modify this setting via a text box. `radio` — WHM users modify this setting via a radio button. `number` — WHM users modify this setting via a text box that only allows numeric values.	`radio`

Function information

API Version:

WHM API 1

Available in:

WHM 11.46+

Methods:

GET, POST

Required Parameters:

setting_id,state

Return Formats:

JSON, XML

Important:

cPanel & WHM version 66 deprecated XML output.

About WHM API 1

WHM API 1 performs functions and accesses data in WHM.

Notes:

Some functions and parameters may require that you authenticate as the root user.
You must use the appropriate WHM ports (2086 or 2087) to call WHM API functions.

Find a function

Related functions

Page:

WHM API 1 Sections - ModSecurity — ModSecurity functions allow you to manage ModSecurity rules and vendors on your server.
Page:

WHM API 1 Functions - modsec_add_rule — This function adds a new rule to a ModSecurity™ configuration staging file.
Page:

WHM API 1 Functions - modsec_assemble_config_text — This function adds text to a ModSecurity™ configuration file.
Page:

WHM API 1 Functions - modsec_add_vendor — This function adds a new ModSecurity™ vendor rule set to the server.
Page:

WHM API 1 Functions - modsec_clone_rule — This function copies a ModSecurity™ rule with a new rule ID.

Child pages