From 6beeb1b708550be0d4a53b272283e17e5e35fe17 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:01:30 +0200 Subject: Adding upstream version 2.4.57. Signed-off-by: Daniel Baumann --- docs/manual/mod/mod_substitute.html.en | 224 +++++++++++++++++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 docs/manual/mod/mod_substitute.html.en (limited to 'docs/manual/mod/mod_substitute.html.en') diff --git a/docs/manual/mod/mod_substitute.html.en b/docs/manual/mod/mod_substitute.html.en new file mode 100644 index 0000000..db1aef3 --- /dev/null +++ b/docs/manual/mod/mod_substitute.html.en @@ -0,0 +1,224 @@ + + + + + +mod_substitute - Apache HTTP Server Version 2.4 + + + + + + + +
+

Modules | Directives | FAQ | Glossary | Sitemap

+

Apache HTTP Server Version 2.4

+
+
<-
+ +
+

Apache Module mod_substitute

+
+

Available Languages:  en  | + fr 

+
+ + + + +
Description:Perform search and replace operations on response bodies
Status:Extension
Module Identifier:substitute_module
Source File:mod_substitute.c
Compatibility:Available in Apache HTTP Server 2.2.7 and later
+

Summary

+ +

mod_substitute provides a mechanism to perform + both regular expression and fixed string substitutions on + response bodies.

+
+ + +
top
+

Substitute Directive

+ + + + + + + +
Description:Pattern to filter the response content
Syntax:Substitute s/pattern/substitution/[infq]
Context:directory, .htaccess
Override:FileInfo
Status:Extension
Module:mod_substitute
+

The Substitute directive specifies a + search and replace pattern to apply to the response body.

+ +

The meaning of the pattern can be modified by using any + combination of these flags:

+ +
+
i
+
Perform a case-insensitive match.
+
n
+
By default the pattern is treated as a regular expression. + Using the n flag forces the pattern to be treated + as a fixed string.
+
f
+
The f flag causes mod_substitute to flatten the + result of a substitution allowing for later substitutions to + take place on the boundary of this one. This is the default.
+
q
+
The q flag causes mod_substitute to not + flatten the buckets after each substitution. This can + result in much faster response and a decrease in memory + utilization, but should only be used if there is no possibility + that the result of one substitution will ever match a pattern + or regex of a subsequent one.
+
+ +

The substitution may contain literal text and regular + expression backreferences

+ +

Example

<Location "/">
+    AddOutputFilterByType SUBSTITUTE text/html
+    Substitute "s/foo/bar/ni"
+</Location>
+
+ +

The character which is used to separate (or "delimit") the + various parts of the substitution string is referred to as the + "delimiter", and it is most common to use a slash for this + purpose.

+ +

If either the pattern or the substitution contain a slash + character then an alternative delimiter may be used to make the + directive more readable:

+ +

Example of using an alternate delimiter

<Location "/">
+    AddOutputFilterByType SUBSTITUTE text/html
+    Substitute "s|<BR */?>|<br />|i"
+</Location>
+
+ +

Backreferences can be used in the comparison and in the substitution, + when regular expressions are used, as illustrated in the following example:

+

Example of using backreferences and captures

<Location "/">
+    AddOutputFilterByType SUBSTITUTE text/html
+    # "foo=k,bar=k" -> "foo/bar=k"
+    Substitute "s|foo=(\w+),bar=\1|foo/bar=$1|"
+</Location>
+
+ +

A common use scenario for mod_substitute is the + situation in which a front-end server proxies requests to a back-end + server which returns HTML with hard-coded embedded URLs that refer + to the back-end server. These URLs don't work for the end-user, + since the back-end server is unreachable.

+ +

In this case, mod_substitute can be used to rewrite + those URLs into something that will work from the front end:

+ +

Rewriting URLs embedded in proxied content

ProxyPass        "/blog/" "http://internal.blog.example.com/"
+ProxyPassReverse "/blog/" "http://internal.blog.example.com/"
+
+Substitute "s|http://internal.blog.example.com/|http://www.example.com/blog/|i"
+
+ +

ProxyPassReverse + modifies any Location (redirect) headers that are sent + by the back-end server, and, in this example, + Substitute takes care of the rest of the problem by + fixing up the HTML response as well.

+ + +
+
top
+

SubstituteInheritBefore Directive

+ + + + + + + + + +
Description:Change the merge order of inherited patterns
Syntax:SubstituteInheritBefore on|off
Default:SubstituteInheritBefore off
Context:directory, .htaccess
Override:FileInfo
Status:Extension
Module:mod_substitute
Compatibility:Available in httpd 2.4.17 and later
+

Whether to apply the inherited Substitute + patterns first (on), or after the ones of the current + context (off). + SubstituteInheritBefore is itself inherited, + hence contexts that inherit it (those that don't specify their own + SubstituteInheritBefore value) will apply the + closest defined merge order.

+ +
+
top
+

SubstituteMaxLineLength Directive

+ + + + + + + + + +
Description:Set the maximum line size
Syntax:SubstituteMaxLineLength bytes(b|B|k|K|m|M|g|G)
Default:SubstituteMaxLineLength 1m
Context:directory, .htaccess
Override:FileInfo
Status:Extension
Module:mod_substitute
Compatibility:Available in httpd 2.4.11 and later
+

The maximum line size handled by mod_substitute + is limited to restrict memory use. The limit can be configured + using SubstituteMaxLineLength. + The value can be given as the number of bytes and can be suffixed + with a single letter b, B, k, + K, m, M, g, + G to provide the size in bytes, kilobytes, megabytes + or gigabytes respectively.

+ +

Example

<Location "/">
+    AddOutputFilterByType SUBSTITUTE text/html
+    SubstituteMaxLineLength 10m
+    Substitute "s/foo/bar/ni"
+</Location>
+
+ + +
+
+
+

Available Languages:  en  | + fr 

+
top

Comments

Notice:
This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Libera.chat, or sent to our mailing lists.
+
+ \ No newline at end of file -- cgit v1.2.3