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

Description

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:

  • 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

ParameterTypeDescriptionPossible valuesExample
setting_idinteger

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
statestring

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
removeBoolean

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

ReturnTypeDescriptionPossible valuesExample
updated_settingsarray of hashesAn 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