From: Rich Bowen Date: Fri, 3 Apr 2026 19:31:59 +0000 (+0000) Subject: addresses bz69256: X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a418da6da3fdbac11d0ce3dbc9f347e95f8ca798;p=thirdparty%2Fapache%2Fhttpd.git addresses bz69256: * Replaced example rewritemap in Perl with one in Python, since it's 2026 now * Clarifies that keys must be newline-terminated, and that keys cannot contain newlines. * Adds note about what happens if the program terminates, and when the server is shutdown/restarted. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1932819 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/rewrite/rewritemap.xml b/docs/manual/rewrite/rewritemap.xml index c733dde2a5..ef16f845e6 100644 --- a/docs/manual/rewrite/rewritemap.xml +++ b/docs/manual/rewrite/rewritemap.xml @@ -349,16 +349,31 @@ by many requests.

When a MapType of prg is used, the MapSource is a filesystem path to an executable program which will providing the mapping behavior. This can be a compiled binary file, or a program - in an interpreted language such as Perl or Python.

+ in an interpreted language such as Python or Perl.

This program is started once, when the Apache HTTP Server is started, and then communicates with the rewriting engine via - STDIN and STDOUT. That is, for each map - function lookup, it expects one argument via STDIN, and - should return one new-line terminated response string on - STDOUT. If there is no corresponding lookup value, the - map program should return the four-character string - "NULL" to indicate this.

+ STDIN and STDOUT. For each map function + lookup, the key is written to the program's STDIN, + followed by a newline character. The program should read one line + from STDIN (up to and including the newline), and + write its response as a single newline-terminated line on + STDOUT. Keys will never contain newline characters; + if a key containing a newline is encountered, the lookup will + fail.

+ +

If there is no corresponding lookup value, the map program + should return the four-character string "NULL" to + indicate this. Note that this comparison is case-insensitive, so + "null", "Null", etc. are also treated as a failed lookup. As a + consequence, it is not possible for a mapping program to return + the literal string "NULL" as a mapped value.

+ +

The program's STDERR is inherited from the + httpd parent process, so anything the program writes to + STDERR will end up in the same place as httpd's + own error output (typically the ErrorLog).

External rewriting programs are not started if they're defined in a context that does not have Rewrite configuration

-RewriteMap d2u "prg:/www/bin/dash2under.programlisting" apache:apache +RewriteMap d2u "prg:/www/bin/dash2under.py" apache:apache RewriteRule "-" "${d2u:%{REQUEST_URI}}" -

dash2under.pl

- -#!/usr/bin/perl -$| = 1; # Turn off I/O buffering -while (<STDIN>) { - s/-/_/g; # Replace dashes with underscores - print $_; -} +

dash2under.py

+ +#!/usr/bin/env python3 +import sys + +for line in sys.stdin: + print(line.strip().replace('-', '_'), flush=True) Caution! @@ -401,14 +415,22 @@ while (<STDIN>) { hangs, it will cause httpd to wait indefinitely for a response from the map, which will, in turn, cause httpd to stop responding to requests. -
  • Be sure to turn off buffering in your program. In Perl this is done -by the second line in the example script: $| = 1; This will -of course vary in other languages. Buffered I/O will cause httpd to wait -for the output, and so it will hang.
    • +
  • Be sure to turn off buffering in your program. In the Python example +above, this is done by passing flush=True to +print(). Buffered I/O will cause httpd to wait for the +output, and so it will hang.
  • Remember that there is only one copy of the program, started at server startup. All requests will need to go through this one bottleneck. This can cause significant slowdowns if many requests must go through this process, or if the script itself is very slow.
    • +
  • If the mapping program terminates, it will not be automatically +restarted. Subsequent lookups will fail until the server is +restarted.
    • +
  • The mapping program is always killed and restarted on any server +restart (graceful or otherwise), regardless of whether the related +configuration directives have changed. On shutdown, the program is +sent SIGTERM; if it does not exit within 3 seconds, it +is sent SIGKILL.
    •