mod_publisher: Configuration Directives

This is the reference guide to mod_publisher's configuration directives. For tutorial information on how to use them, please refer to the topics.



Syntax: MLBufSize nnnn

Set the buffer size increment for buffering text and cdata contents for MLRewriteRule where enabled in MLRewriteOptions.

The default is 8192, and will work well for almost all pages. However, if you know you're applying MLRewriteRules to uninterrupted text passages over 8Kb, it will be more efficient to set a larger buffer size and avoid the need to resize the buffer dynamically during a request. Note that this only applies to uninterrupted text; any kind of markup interrupts it.


Syntax: MLCommentMode level

Sets comment handling behaviour. Options are:

  1. Pass comments through as-is (default).
  2. Erase all comments.
  3. Enable processing of comments as SSI.

Note that if namespace processing is in operation, a namespace module may override this setting.


Syntax: MLDTD url-of-dtd

Loads a DTD which will be enforced on documents served.


Syntax: MLEnableNS code

Determines whether XML Namespace processing is enabled:
0 - Disable namespace processing.
1 - Enable namespace processing for XML.
2 - Enable namespace processing and force text/html to be parsed as XML with namespaces enabled.
4 - Enable namespace processing for XML but suppress printing of xmlns attributes.
6 - As (4), but also parse text/html as XML with namespaces.

Use mode 4 for exact compatibility with mod_xmlns.


Syntax: MLExtendedFixups On|Off

Preprocess markup to be more tolerant of malformed input in the parser. Note that this is a significant processing overhead. It has nothing to do with the simple fixups in MLFixups.


Syntax: MLFixups [lowercase] [dospath] [reset]

This is identical to ProxyHTMLFixups.


Syntax: MLLogVerbose On|Off

Turns on verbose logging. This causes mod_publisher to make extensive error log entries (at LogLevel Info and Debug). When Off, only errors and warnings (if any) are logged.


Syntax: MLMacro name insert|replace|hide [start|end] [string|var|file|url] [value]

Identical to MLMacroPath except in that the path option is disabled for security, so that MLMacro can be enabled in .htaccess files without compromising the system.


Syntax: MLMacroPath name insert|replace|hide [start|end] [string|var|file|path|url] [value]

Defines a markup macro.

  • name is the name of the macro, and may be any element that is syntactically well-formed as XML. It may be a valid element in the markup language being processed, but this is not required.
  • The action is one of insert|replace|hide. insert inserts the value inside the element, while replace substitutes value for it. hide hides the element and everything within it.
  • The optional position argument determines whether an insert or replace operates on the opening or closing tag of an element. Default is start.
  • The optional type argument determines what the value argument means. A string or var is a variable that will be inserted. A file or path point to a local file whose contents will be inserted. A url value is a URL whose contents will be inserted. A string or path is treated as a literal value; a var, file or url is interpolated based on the attributes of the macro. Any string of the form @foo; will be replaced by the value of the attribute foo.
  • The value argument is required for insert and replace macros, and will be interpreted according to the type argument as described above. For details, see the topics page on macros.

Syntax: MLMeta On|Off

Parses HTML <meta http-equiv ...> elements to real HTTP headers.


Syntax: MLNamespace URI on|off version

Activates or deactivates processing for namespace URI, using the processor defined in the version paramater. Only applicable if MLEnableNS is On, and a module implementing the namespace and version is loaded.


Syntax: MLOutputMode XML|XHTML|HTML [prologue]

Determines whether empty elements use HTML (<br>), XHTML (<br />) or XML (<br/>) syntax. If a prologue argument is given, it will be prepended to the document in place of any xmldecl and/or DTD. The default is to use the external or internal subset from the document itself, and to prepend an xmldecl for XML document types (but not for text/html).


Syntax: MLProxyHost proxy-name.example.tld

Set a proxy for when mod_publisher includes remote contents.


Syntax: MLProxyPort portnum

Set a proxy for when mod_publisher includes remote contents.


Syntax: MLRewriteOptions ([+|-]urls|events|attributes|cdata|characters|comments)*

This determines what parts of a document will be parsed for text search-and-replace using MLRewriteRules. Note that parsing document text is an expensive operation, so for performance reasons the MLRewriteOptions should be kept to a minimum. This applies particularly to characters, cdata and comments, which may involve parsing large chunks of text. See also MLBufSize.

Apply rewrites to attributes defined in HTML4/XHTML1 as URLs. This differs from the other options, in that no more than one rewrite will apply to a single URL. This takes precedence if attributes is also set.
Apply rewrites to attributes defined in HTML4/XHTML1 as scripting events.
Apply rewrites to all attributes.
Apply rewrites to CDATA sections. When parsing text/html, CDATA sections are scripts and stylesheets; otherwise XML rules apply.
Apply rewrites to character data (text).
Apply rewrites to comments.

MLRewriteOptions +urls is equivalent to basic processing in mod_proxy_html. MLRewriteOptions +urls +events +cdata is equivalent to mod_proxy_html with ProxyHTMLExtended On.


Syntax: MLRewriteRule from-pattern to-pattern flags

This is the key directive for markup rewriting. When parsing a document, whenever a match is found for from-pattern, the matching portion will be rewritten to to-pattern. What text is matched is controlled by the MLRewriteOptions in effect and the flags to each MLRewriteRule.

Flags for MLRewriteRule

Flags are case-sensitive.


Ignore HTML links (pass through unchanged)


Ignore attributes and scripting events (pass through unchanged)


Pass text sections (characters, cdata, comments) through untouched.


Interpolate Vars. If the to-pattern takes the form $varname|default;, it is substituted with the value of the environment variable varname, or default if the variable isn't defined. If the to-pattern takes the form $varname;, it is substituted with the value of the environment variable varname, and the rule is skipped if the variable isn't defined. Variable interpolation happens before running search-and-replace with the from-pattern on the data being rewritten.


Last-match. If this rule matches, no more rules are applied (note that this happens automatically for HTML links).


Use Regular Expression matching-and-replace. from-pattern is a regexp, and to-pattern a replacement string that may be based on the regexp. Regexp memory is supported: you can use brackets () in the from-pattern and retrieve the matches with $1 to $9 in the to-pattern.

If R is not set, it will use string-literal search-and-replace. Logic is starts-with in HTML links, but contains in all other cases.


Use POSIX extended Regular Expressions. Only applicable with R.


Case-insensitive matching. Only applicable with R.


Disable regexp memory (for speed). Only applicable with R.


Line-based regexp matching. Only applicable with R.


Match at start only. This applies only to string matching (not regexps) and is irrelevant to HTML links.


Match at end only. This applies only to string matching (not regexps) and is irrelevant to HTML links.


Syntax: SSIerrmsg default-error-message

Sets the error message sent to the browser when an SSI processing directive fails.


Syntax: SSIsizefmt size-format

Sets the format for printing SSI size values.


Syntax: SSItimefmt time-format

Sets the format for displaying SSI times.