svn commit: r1933510 - httpd/httpd/trunk/docs/manual/mod

[rb...@apache.org]

Author: rbowen
Date: Wed Apr 29 17:55:21 2026
New Revision: 1933510

Log:
mod_unique_id: Update docs for 2.4.29 PRNG change — 160-bit/27-char encoding, remove stale IP/pid references (Bug 62184)

Modified:
   httpd/httpd/trunk/docs/manual/mod/mod_unique_id.xml

Modified: httpd/httpd/trunk/docs/manual/mod/mod_unique_id.xml
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/mod_unique_id.xml	Wed Apr 29 16:07:53 2026	(r1933509)
+++ httpd/httpd/trunk/docs/manual/mod/mod_unique_id.xml	Wed Apr 29 17:55:21 2026	(r1933510)
@@ -68,12 +68,16 @@ identifier for each request</description
     <ul>
       <li>The machines' times are synchronized via NTP or other
       network time protocol.</li>
-
-      <li>The machines' hostnames all differ, such that the module
-      can do a hostname lookup on the hostname and receive a
-      different IP address for each machine in the cluster.</li>
     </ul>
 
+    <note><title>Change in 2.4.29 and later</title>
+    <p>In previous versions, uniqueness also required that each
+    machine have a distinct IP address. Since 2.4.29, the module
+    uses a cryptographic pseudo-random number generator (PRNG)
+    seeded at startup, eliminating the IP address and pid from the
+    identifier and removing the need for distinct hostnames or a
+    startup delay.</p></note>
+
     <p>As far as operating system assumptions go, we assume that
     pids (process ids) fit in 32-bits. If the operating system uses
     more than 32-bits for a pid, the fix is trivial but must be
@@ -81,9 +85,9 @@ identifier for each request</description
 
     <p>Given those assumptions, at a single point in time we can
     identify any httpd process on any machine in the cluster from
-    all other httpd processes. The machine's IP address and the pid
-    of the httpd process are sufficient to do this. A httpd process
-    can handle multiple requests simultaneously if you use a
+    all other httpd processes. The PRNG-generated root value and the
+    thread index are sufficient to do this. A httpd process can
+    handle multiple requests simultaneously if you use a
     multi-threaded MPM. In order to identify threads, we use a thread
     index Apache httpd uses internally. So in order to
     generate unique identifiers for requests we need only
@@ -156,19 +160,19 @@ identifier for each request</description
     correct very shortly after reboot.</p>
 
     <!-- FIXME: thread_index is unsigned int, so not always 32bit.-->
-    <p>The <code>UNIQUE_ID</code> environment variable is
-    constructed by encoding the 144-bit (32-bit IP address, 32 bit
-    pid, 32 bit time stamp, 16 bit counter, 32 bit thread index)
-    quadruple using the
+    <p>Since 2.4.29, the <code>UNIQUE_ID</code> environment variable is
+    constructed by encoding a 160-bit value (32-bit time stamp,
+    80-bit PRNG root, 16-bit counter, 32-bit thread index)
+    using the
     alphabet <code>[A-Za-z0-9_-]</code> in a manner similar to MIME
-    base64 encoding, producing 24 characters. The MIME base64
+    base64 encoding, producing 27 characters. The MIME base64
     alphabet is actually <code>[A-Za-z0-9+/]</code> however
     <code>+</code> and <code>/</code> need to be specially encoded
     in URLs, which makes them less desirable. All values are
     encoded in network byte ordering so that the encoding is
-    comparable across architectures of different byte ordering. The
-    actual ordering of the encoding is: time stamp, IP address,
-    pid, counter. This ordering has a purpose, but it should be
+    comparable across architectures of different byte ordering.
+    The actual ordering of the encoding is: time stamp, root,
+    counter, thread index. This ordering has a purpose, but it should be
     emphasized that applications should not dissect the encoding.
     Applications should treat the entire encoded
     <code>UNIQUE_ID</code> as an opaque token, which can be
@@ -193,11 +197,8 @@ identifier for each request</description
     communication is required between machines in the cluster (only
     NTP synchronization is required, which is low overhead), and no
     communication between httpd processes is required (the
-    communication is implicit in the pid value assigned by the
-    kernel). In very specific situations the identifier can be
-    shortened, but more information needs to be assumed (for
-    example the 32-bit IP address is overkill for any site, but
-    there is no portable shorter replacement for it). </p>
+    communication is implicit in the PRNG seed assigned at
+    startup).</p>
 </section>