rewrite: add ACME challenge exemption recipe alongside HTTPS redirect

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1934454 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/docs/manual/rewrite/TODO.md b/docs/manual/rewrite/TODO.md
index d914dd67f02c755644ba56b2a88a4bd7bced7cc3..10361e546d4814ad7ff505c9224fc8b7df48fb7f 100644 (file)
--- a/docs/manual/rewrite/TODO.md
+++ b/docs/manual/rewrite/TODO.md
@@ -1,7 +1,5 @@
 # Rewrite Docs —  Suggested addition
 
-- [ ] **Let's Encrypt ACME challenge exemption** — one-liner recipe,
-      universally needed alongside HTTPS redirect. Add to remapping.xml.
-
 - [ ] **flags** - Add examples to flags that lack them. (See bz #70043)
 
+

diff --git a/docs/manual/rewrite/remapping.xml b/docs/manual/rewrite/remapping.xml
index c9c7694c04927789bcfa8b8d2eab252e0a7cc62e..b1be63c187bf8cb8a09ea27d55b376d2ce864fa6 100644 (file)
--- a/docs/manual/rewrite/remapping.xml
+++ b/docs/manual/rewrite/remapping.xml
@@ -166,6 +166,70 @@ RewriteRule "^(.*)" "https://%{SERVER_NAME}$1" [R=301,L]
 
 </section>
 
+<section id="acme-exemption">
+
+  <title>Exempting ACME challenge requests from HTTPS redirect</title>
+
+  <dl>
+    <dt>Description:</dt>
+
+    <dd>
+      <p>You have forced all traffic to HTTPS (as above), but your
+      ACME client (Let's Encrypt, Certbot, etc.) needs plain HTTP
+      access to <code>/.well-known/acme-challenge/</code> to complete
+      domain validation.</p>
+    </dd>
+
+    <dt>Solution:</dt>
+
+    <dd>
+      <p>Place an exception <em>before</em> your HTTPS redirect
+      rule:</p>
+
+<highlight language="config">
+RewriteEngine On
+RewriteRule "^/\.well-known/acme-challenge/" - [L]
+RewriteCond "%{HTTPS}" !=on
+RewriteRule "^(.*)" "https://%{SERVER_NAME}$1" [R=301,L]
+</highlight>
+    </dd>
+
+    <dt>Discussion:</dt>
+
+    <dd>
+      <p>The dash (<code>-</code>) substitution means "do not rewrite."
+      Combined with <code>[L]</code>, it stops rule processing for any
+      request matching the ACME challenge path, allowing it to be
+      served over plain HTTP. All other requests continue to the
+      next rule and are redirected to HTTPS as usual.</p>
+
+      <p>If you are using the <directive
+      module="mod_alias">Redirect</directive> approach in a dedicated
+      port-80 VirtualHost, use an
+      <directive module="mod_alias">Alias</directive> and
+      <directive module="mod_alias">RedirectMatch</directive>
+      instead:</p>
+
+<highlight language="config">
+&lt;VirtualHost *:80&gt;
+    ServerName www.example.com
+
+    # Allow ACME challenges over HTTP
+    Alias "/.well-known/acme-challenge/" "/var/www/acme/.well-known/acme-challenge/"
+    &lt;Directory "/var/www/acme/.well-known/acme-challenge"&gt;
+        Require all granted
+    &lt;/Directory&gt;
+
+    # Everything else goes to HTTPS
+    RedirectMatch permanent "^/(?!\.well-known/acme-challenge/)" "https://www.example.com/$0"
+&lt;/VirtualHost&gt;
+</highlight>
+
+    </dd>
+  </dl>
+
+</section>
+
 <section id="trailing-slash">
 
   <title>Trailing Slash Normalization</title>