doc/html-multipage/configuration-directives.html

   1 <html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Configuration Directives</title><link href="modsecurity-reference.css" rel="stylesheet" type="text/css"><meta content="DocBook XSL Stylesheets V1.69.1" name="generator"><link rel="start" href="index.html" title="ModSecurity&reg; Reference
   2   Manual"><link rel="up" href="index.html" title="ModSecurity&reg; Reference
   3   Manual"><link rel="prev" href="installation.html" title="Installation"><link rel="next" href="processing-phases.html" title="Processing Phases"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background:#F5F5F5;width:100%;border-top:1px solid #DDDDDD;border-bottom:1px solid #DDDDDD"><table width="100%" cellspacing="0" cellpadding="0"><tr><td><a href="http://www.modsecurity.org"><img style="margin:4px" src="modsecurity.gif" width="120" height="36" alt="ModSecurity" border="0"></a></td><td align="right"><a href="http://www.breach.com"><img style="margin:6px" src="breach-logo-small.gif" height="36" width="100" border="0"></a></td></tr></table></div><div id="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Configuration Directives</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="installation.html">Prev</a>&nbsp;</td><td align="center" width="60%">&nbsp;<a accesskey="h" href="index.html">Home</a></td><td align="right" width="20%">&nbsp;<a accesskey="n" href="processing-phases.html">Next</a></td></tr></table><hr size="1"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuration-directives"></a>Configuration Directives</h2></div></div><div></div></div><p>The following section outlines all of the ModSecurity directives.
   4     Most of the ModSecurity directives can be used inside the various Apache
   5     Scope Directives such as <code class="literal">VirtualHost</code>,
   6     <code class="literal">Location</code>, <code class="literal">LocationMatch</code>,
   7     <code class="literal">Directory</code>, etc... There are others, however, that can
   8     only be used once in the main configuration file. This information is
   9     specified in the Scope sections below. The first version to use a given
  10     directive is given in the Version sections below.</p><p>These rules, along with the Core rules files, should be contained is
  11     files outside of the httpd.conf file and called up with Apache "Include"
  12     directives. This allows for easier updating/migration of the rules. If you
  13     create your own custom rules that you would like to use with the Core
  14     rules, you should create a file called -
  15     <code class="filename">modsecurity_crs_15_customrules.conf</code> and place it in
  16     the same directory as the Core rules files. By using this file name, your
  17     custom rules will be called up after the standard ModSecurity Core rules
  18     configuration file but before the other Core rules. This allows your rules
  19     to be evaluated first which can be useful if you need to implement
  20     specific "allow" rules or to correct any false positives in the Core rules
  21     as they are applied to your site.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>It is highly encouraged that you do not edit the Core rules files
  22       themselves but rather place all changes (such as
  23       <code class="literal">SecRuleRemoveByID</code>, etc...) in your custom rules file.
  24       This will allow for easier upgrading as newer Core rules are released by
  25       Breach Security on the ModSecurity website.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N101B0"></a><code class="literal">SecAction</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Unconditionally processes the
  26       action list it receives as the first and only parameter. It accepts one
  27       parameter, the syntax of which is identical to the third parameter
  28       of<code class="literal"> SecRule</code>.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAction
  29       action1,action2,action3</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAction
  30       nolog,phase:1,initcol:RESOURCE=%{REQUEST_FILENAME}</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p>SecAction is best used when you unconditionally execute an action.
  31       This is explicit triggering whereas the normal Actions are conditional
  32       based on data inspection of the request/response. This is a useful
  33       directive when you want to run certain actions such as
  34       <code class="literal">initcol</code> to initialize collections.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N101E1"></a><code class="literal">SecArgumentSeparator</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Specifies which character to use
  35       as separator for<code class="literal">
  36       application/x-www-form-urlencoded</code> content. Defaults to
  37       <code class="literal">&amp;</code>. Applications are sometimes
  38       (very rarely) written to use a semicolon (<code class="literal">;</code>).</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecArgumentSeparator character</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecArgumentSeparator ;</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Main</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p>This directive is needed if a backend web application is using a
  39       non-standard argument separator. If this directive is not set properly
  40       for each web application, then ModSecurity will not be able to parse the
  41       arguments appropriately and the effectiveness of the rule matching will
  42       be significantly decreased.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10216"></a><code class="literal">SecAuditEngine</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the audit logging
  43       engine.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditEngine On|Off|RelevantOnly</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditEngine On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Can be set/changed with
  44       the "<code class="literal">ctl</code>" action for the current transaction.</p><p>Example: The following example shows the various audit directives
  45       used together.</p><pre class="programlisting"><span class="emphasis"><em>SecAuditEngine RelevantOnly</em></span>
  46 SecAuditLog logs/audit/audit.log
  47 SecAuditLogParts ABCFHZ
  48 SecAuditLogType concurrent
  49 SecAuditLogStorageDir logs/audit
  50 <span class="emphasis"><em>SecAuditLogRelevantStatus ^(?:5|4\d[^4])</em></span></pre><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - log all transactions
  51           by default.</p></li><li><p><code class="literal">Off</code> - do not log
  52           transactions by default.</p></li><li><p><code class="literal">RelevantOnly</code> - by default
  53           only log transactions that have triggered a warning or an error, or
  54           have a status code that is considered to be relevant (see<code class="literal"> SecAuditLogRelevantStatus</code>).</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10263"></a><code class="literal">SecAuditLog</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the path to the main
  55       audit log file.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLog
  56       /path/to/auditlog</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLog
  57       /usr/local/apache/logs/audit.log</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This file is open on
  58       startup when the server typically still runs as<span class="emphasis"><em>
  59       root</em></span>. You should not allow non-root users to have write
  60       privileges for this file or for the directory it is stored in..</p><p>This file will be used to store the audit log entries if serial
  61       audit logging format is used. If concurrent audit logging format is used
  62       this file will be used as an index, and contain a record of all audit
  63       log files created. If you are planning to use Concurrent audit logging
  64       and sending your audit log data off to a remote Console host or
  65       commercial ModSecurity Management Appliance, then you will need to
  66       configure and use the ModSecurity Log Collector (mlogc) and use the
  67       following format for the audit log:</p><p><pre class="programlisting">SecAuditLog "|/path/to/mlogc /path/to/mlogc.conf"</pre></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10293"></a><code class="literal">SecAuditLog2</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the path to the
  68       secondary audit log index file when concurrent logging is enabled. See
  69       <code class="literal">SecAuditLog2</code> for more details.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLog2
  70       /path/to/auditlog2</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLog2
  71       /usr/local/apache/logs/audit2.log</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.1.2</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> A main audit log must be
  72       defined via <code class="literal">SecAuditLog</code> before this
  73       directive may be used. Additionally, this log is only used for
  74       replicating the main audit log index file when concurrent audit logging
  75       is used. It will <span class="emphasis"><em>not</em></span> be used for non-concurrent
  76       audit logging.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N102C5"></a><code class="literal">SecAuditLogDirMode</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the mode
  77       (permissions) of any directories created for concurrent audit logs using
  78       an octal mode (as used in chmod). See <code class="literal">SecAuditLogFileMode</code> for controlling the mode
  79       of audit log files.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLogDirMode octal_mode|"default"</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLogDirMode 02750</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.10</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This feature is not
  80       available on operating systems not supporting octal file modes. The
  81       default mode (0600) only grants read/write access to the account writing
  82       the file. If access from another account is needed (using mpm-itk is a
  83       good example), then this directive may be required. However, use this
  84       directive with caution to avoid exposing potentially sensitive data to
  85       unauthorized users. Using the value "default" will revert back to the
  86       default setting.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The process umask may still limit the mode if it is being more
  87         restrictive than the mode set using this directive.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N102F3"></a><code class="literal">SecAuditLogFileMode</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the mode
  88       (permissions) of any files created for concurrent audit logs using an
  89       octal mode (as used in chmod). See <code class="literal">SecAuditLogDirMode</code> for controlling the mode of
  90       created audit log directories.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLogFileMode
  91       octal_mode|"default"</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLogFileMode 00640</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.10</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This feature is not
  92       available on operating systems not supporting octal file modes. The
  93       default mode (0600) only grants read/write access to the account writing
  94       the file. If access from another account is needed (using mpm-itk is a
  95       good example), then this directive may be required. However, use this
  96       directive with caution to avoid exposing potentially sensitive data to
  97       unauthorized users. Using the value "default" will revert back to the
  98       default setting.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The process umask may still limit the mode if it is being more
  99         restrictive than the mode set using this directive.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10321"></a><code class="literal">SecAuditLogParts</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines which part of each
 100       transaction are going to be recorded in audit log. Each part is assigned
 101       a single letter. If a letter appears in the list then the equivalent
 102       part of each transactions will be recorded. See below for the list of
 103       all parts.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLogParts PARTS</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLogParts ABCFHZ</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> At this time ModSecurity
 104       does not log response bodies of stock Apache responses (e.g. <code class="literal">404</code>), or the <code class="literal">Server</code> and <code class="literal">Date</code> response headers.</p><p>Default:<code class="literal"> ABCFHZ</code>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Please refer to the ModSecurity Data Formats document for a
 105         detailed description of every available part.</p></div><p>Available audit log parts:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">A</code> - audit log header
 106           (mandatory)</p></li><li><p><code class="literal">B</code> - request headers</p></li><li><p><code class="literal">C</code> - request body (present
 107           only if the request body exists and ModSecurity is configured to
 108           intercept it)</p></li><li><p><code class="literal">D</code> - RESERVED for
 109           intermediary response headers, not implemented yet.</p></li><li><p><code class="literal">E</code> - intermediary response
 110           body (present only if ModSecurity is configured to intercept
 111           response bodies, and if the audit log engine is configured to record
 112           it). Intermediary response body is the same as the actual response
 113           body unless ModSecurity intercepts the intermediary response body,
 114           in which case the actual response body will contain the error
 115           message (either the Apache default error message, or the
 116           ErrorDocument page).</p></li><li><p><code class="literal">F</code> - final response headers
 117           (excluding the Date and Server headers, which are always added by
 118           Apache in the late stage of content delivery).</p></li><li><p><code class="literal">G</code> - RESERVED for the actual
 119           response body, not implemented yet.</p></li><li><p><code class="literal">H</code> - audit log
 120           trailer</p></li><li><p><code class="literal">I</code> - This part is a
 121           replacement for part C. It will log the same data as C in all cases
 122           except when <code class="literal">multipart/form-data</code>
 123           encoding in used. In this case it will log a fake <code class="literal">application/x-www-form-urlencoded</code> body
 124           that contains the information about parameters but not about the
 125           files. This is handy if you don't want to have (often large) files
 126           stored in your audit logs.</p></li><li><p><code class="literal">J</code> - RESERVED. This part,
 127           when implemented, will contain information about the files uploaded
 128           using <code class="literal">multipart/form-data</code> encoding.</p></li><li><p><code class="literal">K</code> - This part contains a
 129           full list of every rule that matched (one per line) in the order
 130           they were matched. The rules are fully qualified and will thus show
 131           inherited actions and default operators. Supported as of
 132           v2.5.0</p></li><li><p><code class="literal">Z</code> - final boundary,
 133           signifies the end of the entry (mandatory)</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N103B4"></a><code class="literal">SecAuditLogRelevantStatus</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures which response status
 134       code is to be considered relevant for the purpose of audit
 135       logging.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLogRelevantStatus REGEX</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLogRelevantStatus
 136       ^(?:5|4\d[^4])</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Must have the
 137       <code class="literal">SecAuditEngine</code> set to
 138       <code class="literal">RelevantOnly</code>. The parameter is a regular
 139       expression.</p><p>The main purpose of this directive is to allow you to configure
 140       audit logging for only transactions that generate the specified HTTP
 141       Response Status Code. This directive is often used to the decrease the
 142       total size of the audit log file. Keep in mind that if this parameter is
 143       used, then successful attacks that result in a 200 OK status code will
 144       not be logged.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N103E5"></a><code class="literal">SecAuditLogStorageDir</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the storage directory
 145       where concurrent audit log entries are to be stored.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLogStorageDir
 146       /path/to/storage/dir</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLogStorageDir
 147       /usr/local/apache/logs/audit</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> SecAuditLogType must be
 148       set to Concurrent. The directory must already be created before starting
 149       Apache and it must be writable by the web server user as new files are
 150       generated at runtime.</p><p>As with all logging mechanisms, ensure that you specify a file
 151       system location that has adequate disk space and is not on the root
 152       partition.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1040E"></a><code class="literal">SecAuditLogType</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the type of audit
 153       logging mechanism to be used.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLogType Serial|Concurrent</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLogType Serial</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Must specify
 154       <code class="literal">SecAuditLogStorageDir</code> if you use concurrent
 155       logging.</p><p>Possible values are:</p><div class="orderedlist"><ol type="1"><li><p><code class="literal">Serial</code> - all audit log
 156           entries will be stored in the main audit logging file. This is more
 157           convenient for casual use but it is slower as only one audit log
 158           entry can be written to the file at any one file.</p></li><li><p><code class="literal">Concurrent</code> - audit log
 159           entries will be stored in separate files, one for each transaction.
 160           Concurrent logging is the mode to use if you are going to send the
 161           audit log data off to a remote ModSecurity Console host.</p></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1044A"></a><code class="literal">SecCacheTransformations</code>
 162       (Deprecated/Experimental)</h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Controls caching of
 163       transformations. Caching is off by default starting with 2.5.6, when it
 164       was deprecated and downgraded back to experimental.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecCacheTransformations On|Off
 165       [options]</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecCacheTransformations On
 166       "minlen:64,maxlen:0"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> N/A</p><p>First parameter:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - cache transformations
 167           (per transaction, per phase) allowing identical transformations to
 168           be performed only once. (default)</p></li><li><p><code class="literal">Off</code> - do not cache any
 169           transformations, forcing all transformations to be performed for
 170           each rule executed.</p></li></ul></div><p>The following options are allowed (comma separated):</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">incremental:on|off</code> -
 171           enabling this option will cache every transformation instead of just
 172           the final transformation. (default: off)</p></li><li><p><code class="literal">maxitems:N</code> - do not allow
 173           more than N transformations to be cached. The cache will then be
 174           disabled. A zero value is interpreted as "unlimited". This option
 175           may be useful to limit caching for a form with a large number of
 176           ARGS. (default: 512)</p></li><li><p><code class="literal">minlen:N</code> - do not cache the
 177           transformation if the value's length is less than N bytes. (default:
 178           32)</p></li><li><p><code class="literal">maxlen:N</code> - do not cache the
 179           transformation if the value's length is more than N bytes. A zero
 180           value is interpreted as "unlimited". (default: 1024)</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1049C"></a><code class="literal">SecChrootDir</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the directory path
 181       that will be used to jail the web server process.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecChrootDir
 182       /path/to/chroot/dir</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecChrootDir /chroot</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Main</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This feature is not
 183       available on Windows builds. The internal chroot functionality provided
 184       by ModSecurity works great for simple setups. One example of a simple
 185       setup is Apache serving static files only, or running scripts using
 186       modules.builds. Some problems you might encounter with more complex
 187       setups:</p><div class="orderedlist"><ol type="1"><li><p>DNS lookups do not work (this is because this feature requires
 188           a shared library that is loaded on demand, after chroot takes
 189           place).</p></li><li><p>You cannot send email from PHP because it uses sendmail and
 190           sendmail is outside the jail.</p></li><li><p>In some cases Apache graceful (reload) no longer works.</p></li></ol></div><p>You should be aware that the internal chroot feature might not be
 191       100% reliable. Due to the large number of default and third-party
 192       modules available for the Apache web server, it is not possible to
 193       verify the internal chroot works reliably with all of them. A module,
 194       working from within Apache, can do things that make it easy to break out
 195       of the jail. In particular, if you are using any of the modules that
 196       fork in the module initialisation phase (e.g.
 197       <code class="literal">mod_fastcgi</code>, <code class="literal">mod_fcgid</code>,
 198       <code class="literal">mod_cgid</code>), you are advised to examine each Apache
 199       process and observe its current working directory, process root, and the
 200       list of open files. Consider what your options are and make your own
 201       decision.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N104DD"></a><code class="literal">SecComponentSignature</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description</em></span>: Appends component signature to
 202       the ModSecurity signature.</p><p><span class="emphasis"><em>Syntax</em></span>: <code class="literal">SecComponentSignature
 203       "COMPONENT_NAME/X.Y.Z (COMMENT)"</code></p><p><span class="emphasis"><em>Example usage</em></span>: <code class="literal">SecComponentSignature
 204       "Core Rules/1.2.3"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope</em></span>: Main</p><p><span class="emphasis"><em>Version</em></span>: 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes</em></span>: This directive should be
 205       used to make the presence of significant ModSecurity components known.
 206       The entire signature will be recorded in transaction audit log. It
 207       should be used by ModSecurity module and rule set writers to make
 208       debugging easier.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10504"></a><code class="literal">SecContentInjection</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Enables content injection using
 209       actions <code class="literal">append</code> and <code class="literal">prepend</code>.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecContentInjection
 210       (On|Off)</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecContentInjection
 211       On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope</em></span>: Any</p><p><span class="emphasis"><em>Version</em></span>: 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> N/A</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10533"></a><code class="literal">SecCookieFormat</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Selects the cookie format that
 212       will be used in the current configuration context.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecCookieFormat 0|1</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecCookieFormat 0</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">0</code> - use version 0
 213           (Netscape) cookies. This is what most applications use. It is the
 214           default value.</p></li><li><p><code class="literal">1</code> - use version 1
 215           cookies.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10569"></a><code class="literal">SecDataDir</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Path where persistent data (e.g.
 216       IP address data, session data, etc) is to be stored.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecDataDir
 217       /path/to/dir</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecDataDir /usr/local/apache/logs/data</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Main</p><p><span class="emphasis"><em>Dependencies/Notes: </em></span> This directive is needed
 218       when initcol, setsid an setuid are used. Must be writable by the web
 219       server user.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1058C"></a><code class="literal">SecDebugLog</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Path to the ModSecurity debug
 220       log file.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecDebugLog
 221       /path/to/modsec-debug.log</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecDebugLog
 222       /usr/local/apache/logs/modsec-debug.log</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N105B3"></a><code class="literal">SecDebugLogLevel</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the verboseness of
 223       the debug log data.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecDebugLogLevel 0|1|2|3|4|5|6|7|8|9</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecDebugLogLevel 4</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Levels <code class="literal">1 - 3</code> are always sent to the Apache error log.
 224       Therefore you can always use level <code class="literal">0</code>
 225       as the default logging level in production. Level <code class="literal">5</code> is useful when debugging. It is not
 226       advisable to use higher logging levels in production as excessive
 227       logging can slow down server significantly.</p><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">0</code> - no logging.</p></li><li><p><code class="literal">1</code> - errors (intercepted
 228           requests) only.</p></li><li><p><code class="literal">2</code> - warnings.</p></li><li><p><code class="literal">3</code> - notices.</p></li><li><p><code class="literal">4</code> - details of how
 229           transactions are handled.</p></li><li><p><code class="literal">5</code> - as above, but including
 230           information about each piece of information handled.</p></li><li><p><code class="literal">9</code> - log everything,
 231           including very detailed debugging information.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10613"></a><code class="literal">SecDefaultAction</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the default action to
 232       take on a rule match.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecDefaultAction
 233       action1,action2,action3</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecDefaultAction
 234       log,auditlog,deny,status:403,phase:2</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Rules following a
 235       <code class="literal">SecDefaultAction</code> directive will inherit this setting
 236       unless a specific action is specified for an individual rule or until
 237       another <code class="literal">SecDefaultAction</code> is specified. Take special
 238       note that in the logging disruptive actions are not allowed, but this
 239       can inadvertently be inherited using a disruptive action in
 240       <code class="literal">SecDefaultAction</code>.</p><p>The default value is minimal (differing from previous
 241       versions):</p><pre class="programlisting">SecDefaultAction phase:2,log,auditlog,pass</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p><code class="literal">SecDefaultAction</code> must specify a disruptive
 242         action and a processing phase and cannot contain metadata
 243         actions.</p></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p><code class="literal">SecDefaultAction</code> is <span class="emphasis"><em>not</em></span>
 244         inherited across configuration contexts. (For an example of why this
 245         may be a problem for you, read the following ModSecurity Blog entry
 246         <a href="http://blog.modsecurity.org/2008/07/modsecurity-tri.html" target="_top">http://blog.modsecurity.org/2008/07/modsecurity-tri.html</a>).</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1065E"></a><code class="literal">SecGeoLookupDb</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the path to the
 247       geographical database file.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecGeoLookupDb /path/to/db</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecGeoLookupDb
 248       /usr/local/geo/data/GeoLiteCity.dat</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Check out
 249       <code class="literal">maxmind.com</code> for free database files.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10689"></a><code class="literal">SecGuardianLog</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configuration directive to use
 250       the httpd-guardian script to monitor for Denial of Service (DoS)
 251       attacks.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecGuardianLog |/path/to/httpd-guardian</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecGuardianLog
 252       |/usr/local/apache/bin/httpd-guardian</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Main</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> By default httpd-guardian
 253       will defend against clients that send more than 120 requests in a
 254       minute, or more than 360 requests in five minutes.</p><p>Since 1.9, ModSecurity supports a new directive, SecGuardianLog,
 255       that is designed to send all access data to another program using the
 256       piped logging feature. Since Apache is typically deployed in a
 257       multi-process fashion, making information sharing difficult, the idea is
 258       to deploy a single external process to observe all requests in a
 259       stateful manner, providing additional protection.</p><p>Development of a state of the art external protection tool will be
 260       a focus of subsequent ModSecurity releases. However, a fully functional
 261       tool is already available as part of the <a href="http://www.apachesecurity.net/tools/" target="_top">Apache httpd tools
 262       project</a>. The tool is called httpd-guardian and can be used to
 263       defend against Denial of Service attacks. It uses the blacklist tool
 264       (from the same project) to interact with an iptables-based (Linux) or
 265       pf-based (*BSD) firewall, dynamically blacklisting the offending IP
 266       addresses. It can also interact with SnortSam (http://www.snortsam.net).
 267       Assuming httpd-guardian is already configured (look into the source code
 268       for the detailed instructions) you only need to add one line to your
 269       Apache configuration to deploy it:</p><pre class="programlisting">SecGuardianLog |/path/to/httpd-guardian</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N106BC"></a><code class="literal">SecMarker</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Adds a fixed rule marker in the
 270       ruleset to be used as a target in a <code class="literal">skipAfter</code> action.
 271       A <code class="literal">SecMarker</code> directive essentially creates a rule that
 272       does nothing and whose only purpose it to carry the given ID.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecMarker
 273       ID</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecMarker 9999</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p><pre class="programlisting">SecRule REQUEST_URI "^/$" \
 274     "chain,t:none,t:urlDecode,t:lowercase,t:normalisePath,<span class="emphasis"><em>skipAfter:99</em></span>"
 275 SecRule REMOTE_ADDR "^127\.0\.0\.1$" "chain"
 276 SecRule REQUEST_HEADERS:User-Agent \
 277     "^Apache \(internal dummy connection\)$" "t:none"
 278 SecRule &amp;REQUEST_HEADERS:Host "@eq 0" \
 279     "deny,log,status:400,id:08,severity:4,msg:'Missing a Host Header'"
 280 SecRule &amp;REQUEST_HEADERS:Accept "@eq 0" \
 281     "log,deny,log,status:400,id:15,msg:'Request Missing an Accept Header'"
 282 <span class="emphasis"><em>
 283 SecMarker 99</em></span></pre></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N106F4"></a><code class="literal">SecPdfProtect</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Enables the PDF XSS protection
 284       functionality. Once enabled access to PDF files is tracked. Direct
 285       access attempts are redirected to links that contain one-time tokens.
 286       Requests with valid tokens are allowed through unmodified. Requests with
 287       invalid tokens are also allowed through but with forced download of the
 288       PDF files. This implementation uses response headers to detect PDF files
 289       and thus can be used with dynamically generated PDF files that do not
 290       have the <code class="filename">.pdf</code> extension in the request URI.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecPdfProtect On|Off</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecPdfProtect On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1071F"></a><code class="literal">SecPdfProtectMethod</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configure desired protection
 291       method to be used when requests for PDF files are detected. Possible
 292       values are <code class="literal">TokenRedirection</code> and
 293       <code class="literal">ForcedDownload</code>. The token redirection approach will
 294       attempt to redirect with tokens where possible. This allows PDF files to
 295       continue to be opened inline but only works for GET requests. Forced
 296       download always causes PDF files to be delivered as opaque binaries and
 297       attachments. The latter will always be used for non-GET requests. Forced
 298       download is considered to be more secure but may cause usability
 299       problems for users ("This PDF won't open anymore!").</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecPdfProtectMethod method</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecPdfProtectMethod TokenRedirection</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p><span class="emphasis"><em>Default:</em></span>
 300       <code class="literal">TokenRedirection</code></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10755"></a><code class="literal">SecPdfProtectSecret</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the secret that will be
 301       used to construct one-time tokens. You should use a reasonably long
 302       value for the secret (e.g. 16 characters is good). Once selected the
 303       secret should not be changed as it will break the tokens that were sent
 304       prior to change. But it's not a big deal even if you change it. It will
 305       just force download of PDF files with tokens that were issued in the
 306       last few seconds.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecPdfProtectSecret secret</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecPdfProtectSecret
 307       MyRandomSecretString</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1077C"></a><code class="literal">SecPdfProtectTimeout</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the token timeout. After
 308       token expires it can no longer be used to allow access to PDF file.
 309       Request will be allowed through but the PDF will be delivered as
 310       attachment.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecPdfProtectTimeout timeout</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecPdfProtectTimeout 10</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p><span class="emphasis"><em>Default:</em></span> <code class="literal">10</code></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N107AA"></a><code class="literal">SecPdfProtectTokenName</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the name of the token.
 311       The only reason you would want to change the name of the token is if you
 312       wanted to hide the fact you are running ModSecurity. It's a good reason
 313       but it won't really help as the adversary can look into the algorithm
 314       used for PDF protection and figure it out anyway. It does raise the bar
 315       slightly so go ahead if you want to.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecPdfProtectTokenName name</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecPdfProtectTokenName PDFTOKEN</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p><span class="emphasis"><em>Default:</em></span> <code class="literal">PDFTOKEN</code></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N107D8"></a><code class="literal">SecRequestBodyAccess</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures whether request
 316       bodies will be buffered and processed by ModSecurity by default.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRequestBodyAccess On|Off</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRequestBodyAccess On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive is
 317       required if you plan to inspect <code class="literal">POST_PAYLOAD</code>. This
 318       directive must be used along with the "phase:2" processing phase action
 319       and <code class="literal">REQUEST_BODY</code> variable/location. If any of these 3
 320       parts are not configured, you will not be able to inspect the request
 321       bodies.</p><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - access request
 322           bodies.</p></li><li><p><code class="literal">Off</code> - do not attempt to
 323           access request bodies.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10816"></a><code class="literal">SecRequestBodyLimit</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the maximum request
 324       body size ModSecurity will accept for buffering.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRequestBodyLimit NUMBER_IN_BYTES</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRequestBodyLimit 134217728</code></p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> 131072 KB (134217728
 325       bytes) is the default setting. Anything over this limit will be rejected
 326       with status code 413 Request Entity Too Large. There is a hard limit of
 327       1 GB.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10839"></a><code class="literal">SecRequestBodyNoFilesLimit</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the maximum request
 328       body size ModSecurity will accept for buffering, excluding the size of
 329       files being transported in the request. This directive comes handy to
 330       further reduce susceptibility to DoS attacks when someone is sending
 331       request bodies of very large sizes. Web applications that require file
 332       uploads must configure <code class="literal">SecRequestBodyLimit</code> to a high
 333       value. Since large files are streamed to disk file uploads will not
 334       increase memory consumption. However, it's still possible for someone to
 335       take advantage of a large request body limit and send non-upload
 336       requests with large body sizes. This directive eliminates that
 337       loophole.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRequestBodyNoFilesLimit
 338       NUMBER_IN_BYTES</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRequestBodyLimit 131072</code></p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> 1 MB (1048576 bytes) is
 339       the default setting. This value is very conservative. For most
 340       applications you should be able to reduce it down to 128 KB or lower.
 341       Anything over the limit will be rejected with status code <code class="literal">413
 342       Request Entity Too Large</code>. There is a hard limit of 1
 343       GB.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10864"></a><code class="literal">SecRequestBodyInMemoryLimit</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the maximum request
 344       body size ModSecurity will store in memory.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRequestBodyInMemoryLimit
 345       NUMBER_IN_BYTES</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRequestBodyInMemoryLimit 131072</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p>By default the limit is 128 KB:</p><pre class="programlisting"># Store up to 128 KB in memory
 346 SecRequestBodyInMemoryLimit 131072</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10890"></a><code class="literal">SecResponseBodyLimit</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the maximum response
 347       body size that will be accepted for buffering.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecResponseBodyLimit NUMBER_IN_BYTES</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecResponseBodyLimit 524228</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Anything over this limit
 348       will be rejected with status code 500 Internal Server Error. This
 349       setting will not affect the responses with MIME types that are not
 350       marked for buffering. There is a hard limit of 1 GB.</p><p>By default this limit is configured to 512 KB:</p><pre class="programlisting"># Buffer response bodies of up to 512 KB in length
 351 SecResponseBodyLimit 524288</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N108BC"></a><code class="literal">SecResponseBodyLimitAction</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description</em></span>: Controls what happens once a
 352       response body limit, configured with
 353       <code class="literal">SecResponseBodyLimit</code>, is encountered. By default
 354       ModSecurity will reject a response body that is longer than specified.
 355       Some web sites, however, will produce very long responses making it
 356       difficult to come up with a reasonable limit. Such sites would have to
 357       raise the limit significantly to function properly defying the purpose
 358       of having the limit in the first place (to control memory consumption).
 359       With the ability to choose what happens once a limit is reached site
 360       administrators can choose to inspect only the first part of the
 361       response, the part that can fit into the desired limit, and let the rest
 362       through. Some could argue that allowing parts of responses to go
 363       uninspected is a weakness. This is true in theory but only applies to
 364       cases where the attacker controls the output (e.g. can make it arbitrary
 365       long). In such cases, however, it is not possible to prevent leakage
 366       anyway. The attacker could compress, obfuscate, or even encrypt data
 367       before it is sent back, and therefore bypass any monitoring
 368       device.</p><p><span class="emphasis"><em>Syntax</em></span>: <code class="literal">SecResponseBodyLimitAction
 369       Reject|ProcessPartial</code></p><p><span class="emphasis"><em>Example Usage</em></span>:
 370       <code class="literal">SecResponseBodyLimitAction ProcessPartial</code></p><p><span class="emphasis"><em>Processing Phase</em></span>: N/A</p><p><span class="emphasis"><em>Scope</em></span>: Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N108E7"></a><code class="literal">SecResponseBodyMimeType</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures which<code class="literal"> MIME</code> types are to be considered for response
 371       body buffering.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecResponseBodyMimeType mime/type</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecResponseBodyMimeType text/plain
 372       text/html</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Multiple<code class="literal"> SecResponseBodyMimeType</code> directives can be
 373       used to add<code class="literal"> MIME</code> types.</p><p>The default value is <code class="literal">text/plaintext/html</code>:</p><pre class="programlisting">SecResponseBodyMimeType text/plain text/html</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10923"></a><code class="literal">SecResponseBodyMimeTypesClear</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Clears the list of <code class="literal">MIME</code> types considered for response body
 374       buffering, allowing you to start populating the list from
 375       scratch.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecResponseBodyMimeTypesClear</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecResponseBodyMimeTypesClear</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1094E"></a><code class="literal">SecResponseBodyAccess</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures whether response
 376       bodies are to be buffer and analysed or not.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecResponseBodyAccess On|Off</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecResponseBodyAccess On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive is
 377       required if you plan to inspect HTML responses. This directive must be
 378       used along with the "phase:4" processing phase action and RESPONSE_BODY
 379       variable/location. If any of these 3 parts are not configured, you will
 380       not be able to inspect the response bodies.</p><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - access response bodies
 381           (but only if the MIME type matches, see above).</p></li><li><p><code class="literal">Off</code> - do not attempt to
 382           access response bodies.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10984"></a><code class="literal">SecRule</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> <code class="literal">SecRule</code> is the main ModSecurity directive. It
 383       is used to analyse data and perform actions based on the results.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRule
 384       VARIABLES OPERATOR [ACTIONS]</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRule REQUEST_URI "attack" \</code></p><p><code class="literal">
 385       "phase:1,t:none,t:urlDecode,t:lowercase,t:normalisePath"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p>In general, the format of this rule is as follows:</p><pre class="programlisting">SecRule VARIABLES OPERATOR [ACTIONS]</pre><p>The second part, <code class="literal">OPERATOR</code>,
 386       specifies how they are going to be checked. The third (optional) part,
 387       <code class="literal">ACTIONS</code>, specifies what to do
 388       whenever the operator used performs a successful match against a
 389       variable.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N109C2"></a>Variables in rules</h4></div></div><div></div></div><p>The first part,<code class="literal"> VARIABLES</code>,
 390         specifies which variables are to be checked. For example, the
 391         following rule will reject a transaction that has the word<span class="emphasis"><em>
 392         dirty</em></span> in the URI:</p><pre class="programlisting">SecRule ARGS dirty</pre><p>Each rule can specify one or more variables:</p><pre class="programlisting">SecRule ARGS|REQUEST_HEADERS:User-Agent dirty</pre><p>There is a third format supported by the selection operator -
 393         XPath expression. XPath expressions can only used against the special
 394         variable XML, which is available only of the request body was
 395         processed as XML.</p><pre class="programlisting">SecRule XML:/xPath/Expression dirty</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Not all collections support all selection operator format
 396           types. You should refer to the documentation of each collection to
 397           determine what is and isn't supported.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N109DE"></a>Collections</h4></div></div><div></div></div><p>A variable can contain one or many pieces of data, depending on
 398         the nature of the variable and the way it is used. We've seen examples
 399         of both approaches in the previous section. When a variable can
 400         contain more than one value we refer to it as a
 401         <span class="emphasis"><em>collection</em></span>.</p><p>Collections are always expanded before a rule is run. For
 402         example, the following rule:</p><pre class="programlisting">SecRule ARGS dirty</pre><p>will be expanded to:</p><pre class="programlisting">SecRule ARGS:p dirty
 403 SecRule ARGS:q dirty</pre><p>in a requests that has only two parameters, named
 404         <code class="literal">p</code> and <code class="literal">q</code>.</p><p>Collections come in several flavours:</p><div class="variablelist"><dl><dt><span class="term">Read-only</span></dt><dd><p>Created at runtime using transaction data. For example:
 405               <code class="literal">ARGS</code> (contains a list of all request
 406               parameter values) and <code class="literal">REQUEST_HEADERS</code>
 407               (contains a list of all request header values).</p></dd><dt><span class="term">Transient Read/Write</span></dt><dd><p>The <code class="literal">TX</code> collection is created (empty)
 408               for every transaction. Rules can read from it and write to it
 409               (using the <code class="literal">setvar</code> action, for example), but
 410               the information stored in this collection will not survive the
 411               end of transaction.</p></dd><dt><span class="term">Persistent Read/Write</span></dt><dd><p>There are several collections that can be written to, but
 412               which are persisted to the storage backend. These collections
 413               are used to track clients across transactions. Examples of
 414               collections that fall into this type are <code class="literal">IP</code>,
 415               <code class="literal">SESSION</code> and <code class="literal">USER</code>.</p></dd></dl></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N10A2B"></a>Operators in rules</h4></div></div><div></div></div><p>In the simplest possible case you will use a regular expression
 416         pattern as the second rule parameter. This is what we've done in the
 417         examples above. If you do this ModSecurity assumes you want to use the
 418         <code class="literal">rx</code> (regular expression) operator.
 419         You can also explicitly specify the operator you want to use by using
 420         <code class="literal">@</code>, followed by the name of an
 421         operator, at the beginning of the second <code class="literal">SecRule</code>
 422         parameter:</p><pre class="programlisting">SecRule ARGS "@rx dirty"</pre><p>Note how we had to use double quotes to delimit the second rule
 423         parameter. This is because the second parameter now has whitespace in
 424         it. Any number of whitespace characters can follow the name of the
 425         operator. If there are any non-whitespace characters there, they will
 426         all be treated as a special parameter to the operator. In the case of
 427         the regular expression operator the special parameter is the pattern
 428         that will be used for comparison.</p><p>The @ can be the second character if you are using negation to
 429         negate the result returned by the operator:</p><pre class="programlisting">SecRule &amp;ARGS "!@rx ^0$"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N10A46"></a>Operator negation</h4></div></div><div></div></div><p>Operator results can be negated by using an exclamation mark at
 430         the beginning of the second parameter. The following rule matches if
 431         the word <code class="literal">dirty</code> does <span class="emphasis"><em>not</em></span> appear
 432         in the <code class="literal">User-Agent</code> request header:</p><pre class="programlisting">SecRule REQUEST_HEADERS:User-Agent !dirty</pre><p>You can use the exclamation mark in combination with any
 433         parameter. If you do, the exclamation mark needs to go first, followed
 434         by the explicit operator reference. The following rule has the same
 435         effect as the previous example:</p><pre class="programlisting">SecRule REQUEST_HEADERS:User-Agent "!@rx dirty"</pre><p>If you need to use negation in a rule that is going to be
 436         applied to several variables then it may not be immediately clear what
 437         will happen. Consider the following example:</p><pre class="programlisting">SecRule ARGS:p|ARGS:q !dirty</pre><p>The above rule is identical to:</p><pre class="programlisting">SecRule ARGS:p !dirty
 438 SecRule ARGS:q !dirty</pre><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>Negation is applied to operations against individual
 439           operations, not agains the entire variable list.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N10A6B"></a>Actions in rules</h4></div></div><div></div></div><p>The third parameter, <code class="literal">ACTIONS</code>,
 440         can be omitted only because there is a helper feature that specifies
 441         the default action list. If the parameter isn't omitted the actions
 442         specified in the parameter will be merged with the default action list
 443         to create the actual list of actions that will be processed on a rule
 444         match.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10A74"></a><code class="literal">SecRuleInheritance</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures whether the current
 445       context will inherit rules from the parent context (configuration
 446       options are inherited in most cases - you should look up the
 447       documentation for every directive to determine if it is inherited or
 448       not).</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRuleInheritance On|Off</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRuleInheritance Off</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Resource-specific
 449       contexts (e.g.<code class="literal"> Location</code>, <code class="literal">Directory</code>, etc) cannot override
 450       <span class="emphasis"><em>phase1</em></span> rules configured in the main server or in
 451       the virtual server. This is because phase 1 is run early in the request
 452       processing process, before Apache maps request to resource. Virtual host
 453       context can override phase 1 rules configured in the main server.</p><p>Example: The following example shows where ModSecurity may be
 454       enabled in the main Apache configuration scope, however you might want
 455       to configure your VirtualHosts differently. In the first example, the
 456       first VirtualHost is not inheriting the ModSecurity main config
 457       directives and in the second one it is.</p><pre class="programlisting">SecRuleEngine On
 458 SecDefaultAction log,pass,phase:2
 459 ...
 460
 461 &lt;VirtualHost *:80&gt;
 462 ServerName app1.com
 463 ServerAlias www.app1.com<span class="emphasis"><em>
 464 SecRuleInheritance Off</em></span>
 465 SecDefaultAction log,deny,phase:1,redirect:http://www.site2.com
 466 ...
 467 &lt;/VirtualHost&gt;
 468
 469 &lt;VirtualHost *:80&gt;
 470 ServerName app2.com
 471 ServerAlias www.app2.com
 472 <span class="emphasis"><em>SecRuleInheritance On</em></span> SecRule ARGS "attack"
 473 ...
 474 &lt;/VirtualHost&gt;</pre><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - inherit rules from the
 475           parent context.</p></li><li><p><code class="literal">Off</code> - do not inherit rules
 476           from the parent context.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Configuration contexts are an Apache concept. Directives
 477             <code class="literal">&lt;Directory&gt;</code>,
 478             <code class="literal">&lt;Files&gt;</code>,
 479             <code class="literal">&lt;Location&gt;</code> and
 480             <code class="literal">&lt;VirtualHost&gt;</code> are all used to create
 481             configuration contexts. For more information please go to the
 482             Apache documentation section <a href="http://httpd.apache.org/docs/2.0/sections.html" target="_top">Configuration
 483             Sections</a>.</p></div></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10AD7"></a><code class="literal">SecRuleEngine</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the rules
 484       engine.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRuleEngine On|Off|DetectionOnly</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRuleEngine On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive can also
 485       be controlled by the ctl action (ctl:ruleEngine=off) for per rule
 486       processing.</p><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - process rules.</p></li><li><p><code class="literal">Off</code> - do not process
 487           rules.</p></li><li><p><code class="literal">DetectionOnly</code> - process
 488           rules but never intercept transactions, even when rules are
 489           configured to do so.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10B13"></a><code class="literal">SecRuleRemoveById</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Removes matching rules from the
 490       parent contexts.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRuleUpdateActionById RULEID
 491       ACTIONLIST</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRuleRemoveByID 1 2 "9000-9010"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive supports
 492       multiple parameters, where each parameter can either be a rule ID, or a
 493       range. Parameters that contain spaces must be delimited using double
 494       quotes.</p><pre class="programlisting">SecRuleRemoveById 1 2 5 10-20 "400-556" 673</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10B3D"></a><code class="literal">SecRuleRemoveByMsg</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Removes matching rules from the
 495       parent contexts.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRuleRemoveByMsg REGEX</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRuleRemoveByMsg "FAIL"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive supports
 496       multiple parameters. Each parameter is a regular expression that will be
 497       applied to the message (specified using the <code class="literal">msg</code> action).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10B68"></a><code class="literal">SecRuleScript</code> (Experimental)</h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> This directive creates a special
 498       rule that executes a Lua script to decide whether to match or not. The
 499       main difference from <code class="literal">SecRule</code> is that there are no
 500       targets nor operators. The script can fetch any variable from the
 501       ModSecurity context and use any (Lua) operator to test them. The second
 502       optional parameter is the list of actions whose meaning is identical to
 503       that of <code class="literal">SecRule</code>.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRuleScript
 504       /path/to/script.lua [ACTIONS]</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRuleScript "/path/to/file.lua"
 505       "block"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>All Lua scripts are compiled at configuration time and cached in
 506         memory. To reload scripts you must reload the entire ModSecurity
 507         configuration by restarting Apache.</p></div><p>Example script:</p><pre class="programlisting">-- Your script must define the <span class="emphasis"><em>main</em></span> entry
 508 -- point, as below.
 509 function main()
 510     -- Log something at level 1. Normally you shouldn't be
 511     -- logging anything, especially not at level 1, but this is
 512     -- just to show you can. Useful for debugging.
 513     m.log(1, "Hello world!");
 514
 515     -- Retrieve one variable.
 516     local var1 = m.getvar("REMOTE_ADDR");
 517
 518     -- Retrieve one variable, applying one transformation function.
 519     -- The second parameter is a string.
 520     local var2 = m.getvar("ARGS", "lowercase");
 521
 522     -- Retrieve one variable, applying several transformation functions.
 523     -- The second parameter is now a list. You should note that m.getvar()
 524     -- requires the use of comma to separate collection names from
 525     -- variable names. This is because only one variable is returned.
 526     local var3 = m.getvar("ARGS.p", { "lowercase", "compressWhitespace" } );
 527
 528     -- If you want this rule to match return a string
 529     -- containing the error message. The message <span class="emphasis"><em>must</em></span> contain the name
 530     -- of the variable where the problem is located.
 531     -- return "Variable ARGS:p looks suspicious!"
 532
 533     -- Otherwise, simply return nil.
 534     return nil;
 535 end</pre><p>In this first example we were only retrieving one variable at the
 536       time. In this case the name of the variable is known to you. In many
 537       cases, however, you will want to examine variables whose names you won't
 538       know in advance, for example script parameters.</p><p>Example showing use of <code class="literal">m.getvars()</code> to retrieve
 539       many variables at once:</p><pre class="programlisting">function main()
 540     -- Retrieve script parameters.
 541     local d = m.getvars("ARGS", { "lowercase", "htmlEntityDecode" } );
 542
 543     -- Loop through the paramters.
 544     for i = 1, #d do
 545         -- Examine parameter value.
 546         if (string.find(d[i].value, "&lt;script")) then
 547             -- Always specify the name of the variable where the
 548             -- problem is located in the error message.
 549             return ("Suspected XSS in variable " .. d[i].name .. ".");
 550         end
 551     end
 552
 553     -- Nothing wrong found.
 554     return nil;
 555 end</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Go to <a href="http://www.lua.org/" target="_top">http://www.lua.org/</a> to find more
 556         about the Lua programming language. The reference manual too is
 557         available online, at <a href="http://www.lua.org/manual/5.1/" target="_top">http://www.lua.org/manual/5.1/</a>.</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Lua support is marked as <span class="emphasis"><em>experimental</em></span> as
 558         the way the progamming interface may continue to evolve while we are
 559         working for the best implementation style. Any user input into the
 560         programming interface is appreciated.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10BC2"></a><code class="literal">SecRuleUpdateActionById</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Updates the action list of the
 561       specified rule.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRuleRemoveById RULEID ACTIONLIST</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRuleUpdateActionById 12345
 562       deny,status:403</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive merges the
 563       specified action list with the rule's action list. There are two
 564       limitations. The rule ID cannot be changed, nor can the phase. Further
 565       note that actions that may be specified multiple times are appended to
 566       the original.</p><pre class="programlisting">SecAction \
 567   "t:lowercase,phase:2,id:12345,pass,msg:'The Message',log,auditlog"
 568 SecRuleUpdateActionById 12345 "t:compressWhitespace,deny,status:403,msg:'A new message'</pre><p>The example above will cause the rule to be executed as if it was
 569       specified as follows:</p><pre class="programlisting">SecAction \
 570   "t:lowercase,phase:2,id:12345,log,auditlog,t:compressWhitespace,deny,status:403,msg:'A new message'"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10BF1"></a><code class="literal">SecServerSignature</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Instructs ModSecurity to change
 571       the data presented in the "Server:" response header token.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecServerSignature "WEB SERVER
 572       SOFTWARE"</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecServerSignature
 573       "Netscape-Enterprise/6.0"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Main</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> In order for this
 574       directive to work, you must set the Apache ServerTokens directive to
 575       Full. ModSecurity will overwrite the server signature data held in this
 576       memory space with the data set in this directive. If ServerTokens is not
 577       set to Full, then the memory space is most likely not large enough to
 578       hold the new data we are looking to insert.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10C18"></a><code class="literal">SecTmpDir</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the directory where
 579       temporary files will be created.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecTmpDir
 580       /path/to/dir</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecTmpDir /tmp</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Needs to be writable by
 581       the Apache user process. This is the directory location where Apache
 582       will swap data to disk if it runs out of memory (more data than what was
 583       specified in the SecRequestBodyInMemoryLimit directive) during
 584       inspection.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10C3F"></a><code class="literal">SecUploadDir</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the directory where
 585       intercepted files will be stored.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecUploadDir
 586       /path/to/dir</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecUploadDir /tmp</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directory must be on
 587       the same filesystem as the temporary directory defined with <code class="literal">SecTmpDir</code>. This directive is used with
 588       <code class="literal">SecUploadKeepFiles</code>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10C6E"></a><code class="literal">SecUploadFileMode</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the mode
 589       (permissions) of any uploaded files using an octal mode (as used in
 590       chmod).</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecUploadFileMode octal_mode|"default"</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecUploadFileMode 0640</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.1.6</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This feature is not
 591       available on operating systems not supporting octal file modes. The
 592       default mode (0600) only grants read/write access to the account writing
 593       the file. If access from another account is needed (using clamd is a
 594       good example), then this directive may be required. However, use this
 595       directive with caution to avoid exposing potentially sensitive data to
 596       unauthorized users. Using the value "default" will revert back to the
 597       default setting.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The process umask may still limit the mode if it is being more
 598         restrictive than the mode set using this directive.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10C98"></a><code class="literal">SecUploadKeepFiles</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures whether or not the
 599       intercepted files will be kept after transaction is processed.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecUploadKeepFiles On|Off|RelevantOnly</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecUploadKeepFiles On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive requires
 600       the storage directory to be defined (using <code class="literal">SecUploadDir</code>).</p><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - Keep uploaded
 601           files.</p></li><li><p><code class="literal">Off</code> - Do not keep uploaded
 602           files.</p></li><li><p><code class="literal">RelevantOnly</code> - This will
 603           keep only those files that belong to requests that are deemed
 604           relevant.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10CD8"></a><code class="literal">SecWebAppId</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Creates a partition on the
 605       server that belongs to one web application.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecWebAppId
 606       "NAME"</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecWebAppId "WebApp1"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Partitions are used to
 607       avoid collisions between session IDs and user IDs. This directive must
 608       be used if there are multiple applications deployed on the same server.
 609       If it isn't used, a collision between session IDs might occur. The
 610       default value is<code class="literal"> default</code>.
 611       Example:</p><pre class="programlisting">&lt;VirtualHost *:80&gt;
 612 ServerName app1.com
 613 ServerAlias www.app1.com
 614 <span class="emphasis"><em>SecWebAppId "App1"</em></span>
 615 SecRule REQUEST_COOKIES:PHPSESSID !^$ chain,nolog,pass
 616 SecAction setsid:%{REQUEST_COOKIES.PHPSESSID}
 617 ...
 618 &lt;/VirtualHost&gt;
 619
 620 &lt;VirtualHost *:80&gt;
 621 ServerName app2.com
 622 ServerAlias www.app2.com<span class="emphasis"><em>
 623 SecWebAppId "App2"</em></span>
 624 SecRule REQUEST_COOKIES:PHPSESSID !^$ chain,nolog,pass
 625 SecAction setsid:%{REQUEST_COOKIES.PHPSESSID}
 626 ...
 627 &lt;/VirtualHost&gt;</pre><p>In the two examples configurations shown, SecWebAppId is being
 628       used in conjunction with the Apache VirtualHost directives. What this
 629       achieves is to create more unique collection names when being hosted on
 630       one server. Normally, when setsid is used, ModSecurity will create a
 631       collection with the name "SESSION" and it will hold the value specified.
 632       With using SecWebAppId as shown in the examples, however, the name of
 633       the collection would become "App1_SESSION" and "App2_SESSION".</p><p>SecWebAppId is relevant in two cases:</p><div class="orderedlist"><ol type="1"><li><p>You are logging transactions/alerts to the ModSecurity Console
 634           and you want to use the web application ID to search only the
 635           transactions belonging to that application.</p></li><li><p>You are using the data persistence facility (collections
 636           SESSION and USER) and you need to avoid collisions between sessions
 637           and users belonging to different applications.</p></li></ol></div></div></div><div id="navfooter"><hr size="1"><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="installation.html">Prev</a>&nbsp;</td><td align="center" width="20%">&nbsp;</td><td align="right" width="40%">&nbsp;<a accesskey="n" href="processing-phases.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Installation&nbsp;</td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%">&nbsp;Processing Phases</td></tr></table></div><div align="center" class="copyright">Copyright (C) 2004-2009 <a href="http://www.breach.com">Breach Security</a></div></body></html>