Migrating from v2 to v3

This page is for administrators moving a working ModSecurity v2 (Apache mod_security2 or IIS) deployment to libModSecurity v3, typically because the web server changes to NGINX. Both versions are maintained by OWASP and implement the same rule language, so rule sets such as the OWASP CRS run on both; the differences are in the architecture, in a few evaluation details and in the legacy features v3 does not implement. If you stay on Apache httpd or IIS there is no need to migrate: v2 remains the supported choice there (current release 2.9.15).

What changed architecturally

Library plus connectors. v2 is a web server module and contains the engine, the Apache glue and the IIS module in one tree. v3 (current release 3.0.17) is only the engine, libmodsecurity, with a C and a C++ API. The web server integration is a separate connector project with its own release cycle: ModSecurity-nginx for NGINX (production ready) and ModSecurity-apache (not production ready, so Apache users should stay on v2). All Apache dependencies (APR, apxs) are gone from the engine. See Building libModSecurity v3 from source and libModSecurity v3 with NGINX.

Configuration scopes. In v2 the rules live in Apache’s configuration and inherit through <VirtualHost>, <Location>, <Directory> and .htaccess contexts. In v3 the connector loads the rules: with ModSecurity-nginx you point modsecurity_rules_file (or modsecurity_rules / modsecurity_rules_remote) at a file in an http, server or location block, and you can refine the global set per location with SecRuleRemoveById and similar directives. SecRuleInheritance On is rejected by the v3 parser.

Persistent storage. v2 keeps the IP, GLOBAL, RESOURCE, SESSION and USER collections in SDBM files under SecDataDir, shared by all worker processes. v3 keeps them in memory per process by default; the data is not shared between NGINX workers and is lost on restart. Build with --with-lmdb for an LMDB-backed shared store. SecDataDir is accepted but ignored. See Persistent Storage.

Request body buffering. SecRequestBodyInMemoryLimit is rejected at load time by v3, which follows the web server’s own buffering configuration (client_body_buffer_size in NGINX). Remove the directive from a configuration copied from v2.

Logging. v3 writes the same audit log formats (native and JSON, serial and concurrent) and a debug log, but there is no Apache error log: alerts go through the connector to the web server’s error log. mlogc, the v2 log collector, is not part of v3; ship the JSON audit log with a generic log forwarder instead. See Logging and Data Formats.

Base configuration. Start from the v3 modsecurity.conf-recommended, not the v2 file; the differences are listed in Recommended Base Configuration.

Rule evaluation differences to check in custom rules

  • Default phase. A rule without phase: runs in phase 2 in v2 but in phase 1 in v3. Set phase: on every rule.
  • SecDefaultAction. v3 allows one SecDefaultAction per phase and rejects a second one, requires it to name a real disruptive action (block is not accepted there), and applies its disruptive action to a rule only through block; a rule without any disruptive action does not inherit one. v2 lets a later SecDefaultAction replace an earlier one and applies its disruptive action to every rule that has none.
  • Phase 4 without body inspection. v2 runs phase 4 rules with an empty RESPONSE_BODY; v3 skips phase 4 when SecResponseBodyAccess is Off or the MIME type is not inspected.
  • skipAfter. If the named SecMarker does not exist, v3 skips every remaining rule of every later phase; v2 ends the skip with the phase.
  • ctl:ruleEngine=Off. v2 stops the current phase immediately; v3 only checks the engine state when a phase starts.
  • SecRuleRemoveByTag / SecRuleRemoveByMsg. v2 matches the parameter as an unanchored regular expression; v3 compares the whole tag or message literally.
  • initcol and setvar in one rule. v3 runs setvar before initcol within the same rule; initialize the collection in a separate, earlier rule.
  • SecUploadKeepFiles RelevantOnly is rejected by v3; use On or Off.
  • SecCookieFormat 1 is not supported by v3.
  • SecCollectionTimeout, SecStatusEngine and SecPcreMatchLimitRecursion are accepted by v3 but ignored, so a configuration that relies on collection expiry needs expirevar instead.

See Processing Phases for details.

Not supported in v3

The lists below contain the v2 features that libModSecurity v3 does not implement, verified against the v3.0.17 parser and cross-checked with the compatibility matrix of the SecLang specification (see SecLang specification). Most of them are tied to Apache internals or to retired services and are marked deprecated in the specification; no current rule set uses them.

Directives

Rejected by the v3 parser at load time (remove them from the configuration):

Variables

Actions

  • append and prepend (content injection)
  • deprecatevar
  • marker
  • pause
  • proxy - relied on Apache mod_proxy.
  • sanitiseArg, sanitiseMatched, sanitiseMatchedBytes, sanitiseRequestHeader, sanitiseResponseHeader - audit log masking.
  • The following ctl options, which the v3 parser rejects: debugLogLevel, hashEnforcement, hashEngine, requestBodyLimit, responseBodyAccess, responseBodyLimit, ruleRemoveByMsg, ruleRemoveTargetByMsg. v3 implements auditEngine, auditLogParts, parseXmlIntoArgs, requestBodyAccess, requestBodyProcessor, ruleEngine, ruleRemoveById, ruleRemoveByTag, ruleRemoveTargetById and ruleRemoveTargetByTag, and accepts forceRequestBodyVariable as a no-op (REQUEST_BODY is always populated).

Operators

  • gsbLookup, rsub and validateHash are rejected by the v3 parser at load time (Operator: ... is not yet supported). No other v2 operator is missing.

Transformations

All v2 transformation functions are available in v3. (t:uppercase exists in v3 but not in v2.)

Checklist

  1. Install libmodsecurity and the connector for your web server.
  2. Start from the v3 modsecurity.conf-recommended; copy only your site-specific values (limits, audit log location, MIME types) from the old file.
  3. Remove the directives listed above from your configuration; the v3 parser refuses to load a file that contains most of them.
  4. Grep your custom rules for the variables, actions and ctl options listed above and for rules without phase:.
  5. If you depend on IP, GLOBAL or other persistent collections (for example the CRS DoS-protection plugin), build with --with-lmdb or accept per-worker counters.
  6. Run in SecRuleEngine DetectionOnly, compare the audit log with the v2 deployment, then switch to On.
  7. Report anything that behaves differently and is not listed here at https://github.com/owasp-modsecurity/ModSecurity/issues.