changeset 4126:68ceb7e0cfe6

mod_firewall: Add docs for list types and parameters
author Matthew Wild <mwild1@gmail.com>
date Tue, 15 Sep 2020 11:45:09 +0100
parents 24404c289014
children e9e10ec1b91c
files mod_firewall/README.markdown
diffstat 1 files changed, 38 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/mod_firewall/README.markdown	Mon Sep 14 18:16:31 2020 +0100
+++ b/mod_firewall/README.markdown	Tue Sep 15 11:45:09 2020 +0100
@@ -121,6 +121,44 @@
   file         %LIST spammers: file:/etc/spammers.txt
   http         %LIST spammers: http://example.com/spammers.txt
 
+#### List types
+##### memory
+
+```
+%LIST name: memory (limit: number)
+```
+
+A memory-only list, with an optional limit. Supports addition and removal of items by scripts.
+
+If a limit is provided, the oldest item will be discarded to make room for a new item if the
+list is full. The limit is useful to prevent infinite memory growth on busy servers.
+
+##### file
+
+```
+%LIST name: file:/path/to/file (missing: string)
+```
+
+Reads a list from a file. The list can be added to and removed from by scripts, but
+these changes do not persist between restarts.
+
+If the file is missing, an error will be raised. The optional 'missing' parameter can be set
+to 'ignore' (e.g. `(missing: ignore)`) to ignore a missing file.
+
+##### http
+
+```
+%LIST name: http://example.com/ (ttl: number, pattern: pat, hash: sha1, checkcerts: when-sni)
+```
+
+Fetches a list from a HTTP or HTTPS URL. The following options are accepted:
+
+  Option    Description
+  -------   -----------
+  ttl       Seconds to cache the list for. After expiry, it will be refetched. Default 3600 (1 hour).
+  pattern   Optional pattern used to extract list entries from the response. Default is to treat each line as a single item.
+  hash      Optional hash to be applied to items before looking them up in the list, e.g. sha1 or sha256.
+
 #### CHECK LIST
 
 Checks whether a simple expression is found in a given list.