diff --git a/doc/modsecurity2-apache-reference.xml b/doc/modsecurity2-apache-reference.xml index d69256e6..fd4c8856 100644 --- a/doc/modsecurity2-apache-reference.xml +++ b/doc/modsecurity2-apache-reference.xml @@ -4409,77 +4409,12 @@ SecRule REQUEST_URI "^/cgi-bin/script\.pl" \ Note - Every collection contains several built-in variables that are - read-only: - - - - CREATE_TIME - date/time of - the creation of the collection. - - - - IS_NEW - set to 1 if the - collection is new (not yet persisted) otherwise set to 0. - - - - KEY - the value of the - initcol variable (the client's IP address in the example). - - - - LAST_UPDATE_TIME - - date/time of the last update to the collection. - - - - TIMEOUT - date/time in - seconds when the collection will be updated on disk from memory (if - no other updates occur). - - - - UPDATE_COUNTER - how many - times the collection has been updated since creation. - - - - UPDATE_RATE - is the - average rate updates per minute since creation. - - - Collections are loaded into memory when the initcol action is - encountered. The collection in storage will be updated (and the + encountered. The collection in storage will be persisted (and the appropriate counters increased) only if it was changed during transaction processing. - - To create a collection to hold session variables (SESSION) use action setsid. To create a collection to hold user - variables (USER) use action - setuid. - - - - At this time it is only possible to have three - collections: IP, SESSION, and USER. - - - - Please note that ModSecurity does not implement atomic updates - of persistent variables at this time. Variables are read from storage - whenever initcol is encountered in the rules and - persisted at the end of request processing. On busy servers requests - often run in parallel, leading to situations where one request - overwrites the changes made by another request. We anticipate - implementing atomic updates of counter values in a future - version. - + See the "Persistant Storage" section for further details.
@@ -5604,6 +5539,86 @@ SecRule REQUEST_METHOD "!@within %{tx.allowed_methods}" t:l RULE, SESSION, USERID, among others.
+
+ Persistant Storage + + At this time it is only possible to have three collections in which + data is stored persistantly (i.e. data available to multiple requests). + These are: IP, SESSION and USER. + + Every collection contains several built-in variables that are + available and are read-only unless otherwise specified: + + + + CREATE_TIME - date/time of + the creation of the collection. + + + + IS_NEW - set to 1 if the + collection is new (not yet persisted) otherwise set to 0. + + + + KEY - the value of the + initcol variable (the client's IP address in the example). + + + + LAST_UPDATE_TIME - date/time + of the last update to the collection. + + + + TIMEOUT - date/time in + seconds when the collection will be updated on disk from memory (if no + other updates occur). This variable may be set if you wish to specifiy + an explicit expiration time (default is 3600 seconds). + + + + UPDATE_COUNTER - how many + times the collection has been updated since creation. + + + + UPDATE_RATE - is the average + rate updates per minute since creation. + + + + To create a collection to hold session variables (SESSION) use action setsid. To create a collection to hold user + variables (USER) use action setuid. To create a collection to hold client + address variables (IP) use action + initcol. + + + ModSecurity implements atomic updates of persistent variables only + for integer variables (counters) at this time. Variables are read from + storage whenever initcol is encountered in the rules + and persisted at the end of request processing. Counters are adjusted by + applying a delta generated by re-reading the persisted data just before + being persisted. This keeps counter data consistent even if the counter + was modified and persisted by another thread/process during the + transaction. + + + + ModSecurity uses a Berkley Database (SDBM) for persistant storage. + This type of database is generally limited to storing a maximum of 1008 + bytes per key. This may be a limitation if you are attempting to store a + considerable amount of data in variables for a single key. Some of this + limitation is planned to be reduced in a future version of + ModSecurity. + +
+
Data Formats