DOC: install: describe how to choose options used in the DEBUG variable
This enumerates a few of the options that are expected to have an effect
on the process' self-checks at the expense of more or less performance,
and how to choose sets of options for different deployments.
diff --git a/INSTALL b/INSTALL
index bdcf7d5..f9d94f3 100644
--- a/INSTALL
+++ b/INSTALL
@@ -529,6 +529,76 @@
recommended way to build when developing, and it is expected that contributed
patches were tested with ERR=1.
+The DEBUG variable is used to extend the CFLAGS and is preset to a list of
+build-time options that are known for providing significant reliability
+improvements and a barely perceptible performance cost. Unless instructed to do
+so by some project developers, or trying to save the last ounce of performance,
+these options should not be changed. Among the usable ones are:
+ - -DDEBUG_STRICT: enable some runtime assertions at key places in the code.
+ The goal is to emit a warning or stop the program if certain expected
+ conditions are not met, and whose violation will result in a misbehaving
+ process due to memory corruption or other significant trouble, possibly
+ caused by an attempt to exploit a bug in the program or a library it relies
+ on. The option knows 3 values: 0 (disable all such assertions, the default
+ when the option is not set), 1 (enable all inexpensive assertions), and
+ 2 (enable all assertions even in fast paths). Setting the option with no
+ value corresponds to 1, which is the recommended value for production.
+
+ - -DDEBUG_STRICT_ACTION: indicates how to react to a check violation. There
+ are 3 types of checks: BUG (condition that is known to have serious
+ consequences), WARN (warning about a highly suspicious condition which the
+ process may recover from, but whose unknown cause may also have serious
+ consequences), CHECK (verification whether a condition that developers now
+ consider impossible still happens). The variable takes a value from 0 to 3,
+ that adjusts the behavior on these 3 violations:
+
+ BUG WARN CHECK
+ 0 warn warn warn
+ 1 stop warn warn
+ 2 stop stop warn
+ 3 stop stop stop
+
+ The default value is 1, which is the best balance for production in that it
+ will do its best to prevent a known bogus process from running away, but
+ will let it run if it believes it can recover. Users running the process in
+ sensitive environments (finance etc) may prefer to run at level 2 to make
+ sure to stop any detected anomaly before it may have an impact. Level 3
+ should only be used at the request of developers. In any case, any emitted
+ warning should be reported to developers.
+
+ - -DDEBUG_MEMORY_POOLS: this enables by default extra controls around memory
+ allocation that will help detect coding errors such as double-frees and
+ freeing a bad memory location. It will also detect earlier risks of memory
+ overflows, which may have security implications. The cost is extremely low
+ (less than 1% increase in memory footprint). This is equivalent to adding
+ "-dMtag" on the command line. This option is enabled in the default build
+ options.
+
+ - -DDEBUG_DONT_SHARE_POOLS: this will keep separate pools for same-sized
+ objects of different types. Using this increases the memory usage a little
+ bit but further reduces the risk of memory management related bugs and will
+ lead to more accurate traces in case of error. It is equivalent to adding
+ "-dMno-merge" on the command line. It is not enabled in the default build
+ options.
+
+ - -DDEBUG_POOL_INTEGRITY: this will enable runtime detection and stopping of
+ a class of bugs known as "use after free", which consists in modifying a
+ memory area after freeing it while it was reused for something else. This
+ option is quite powerful but such bugs are fortunately extremely rare, and
+ it will cause a measurable performance degradation (a few percent). This is
+ equivalent to adding "-dMcold-first,integrity" on the command line. This
+ option is not enabled by default but users running development versions on
+ moderate performance sites in order to participate to reliability testing
+ are encouraged to use it, in combination with -DDEBUG_DONT_SHARE_POOLS and
+ -DDEBUG_MEMORY_POOLS, as this could catch dangerous regressions.
+
+As such, for regular production, "-DDEBUG_STRICT -DDEBUG_MEMORY_POOLS" is
+recommended. For security sensitive environments, it is recommended to use
+"-DDEBUG_STRICT -DDEBUG_STRICT_ACTION=2 -DDEBUG_MEMORY_POOLS \
+-DDEBUG_DONT_SHARE_POOLS". For deployments dedicated to testing new versions or
+when trying to nail a bug down, use "-DDEBUG_STRICT=2 -DDEBUG_STRICT_ACTION=2 \
+-DDEBUG_MEMORY_POOLS -DDEBUG_DONT_SHARE_POOLS -DDEBUG_POOL_INTEGRITY".
+
The DEP variable is automatically set to the list of include files and also
designates a file that contains the last build options used. It is used during
the build process to compute dependencies and decide whether or not to rebuild