From f242410d89570fb215226b7977bfab15c23b710b Mon Sep 17 00:00:00 2001
From: rlerdorf <rlerdorf@etsy.com>
Date: Mon, 5 Apr 2021 19:21:53 +0000
Subject: [PATCH] Update README

---
 README.md     | 44 +++++++++++++++++++++++++++++++++++++++-----
 mod_realdoc.c |  2 +-
 2 files changed, 40 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 4e03d6a..38de933 100644
--- a/README.md
+++ b/README.md
@@ -11,11 +11,11 @@ The realpath frequency can be adjusted in httpd.conf using:
         RealpathEvery 2
     </IfModule>
 
-By resolving the configured symlinked docroot directory to 
+By resolving the configured symlinked docroot directory to
 an absolute path at the start of a request we can safely
 switch this symlink to point to another directory on a
 deploy. Requests that started before the symlink change will
-continue to execute on the previous symlink target and 
+continue to execute on the previous symlink target and
 therefore will not be vulnerable to deploy race conditions.
 
 This module is intended for the prefork mpm. Threaded mpms
@@ -34,9 +34,9 @@ Please note that if you're granting access to your document root
 using a symlink, that will stop working, unless expanding the
 symlink also in your Apache configuration.
 
-If, for instance, your symlink is named "current" and your releases
-are something like "releases/20160519102200" (with "current" pointing
-to last release), you need to adapt your configration.
+If, for instance, your symlink is named "current" and your releases
+are something like "releases/20160519102200" (with "current" pointing
+to last release), you need to adapt your configration.
 
 ```apacheconf
 # Old configuration (without mod_realdoc):
@@ -51,3 +51,37 @@ symlink also in your Apache configuration.
 ```
 You need to adapt the regular expression `\d{14}` if you use a
 different schema from timestamp in your releases.
+
+If you want to map incremental releases to two static docroot
+symlinks in order to re-use your opcache cache entries, you can
+set
+
+```apacheconf
+UseReadlink On
+```
+
+This means that instead of calling `realpath()` it will call `readlink()`
+on the first symlink it finds in your configured docroot path. This means
+you can do:
+
+```
+                                  /var/www/release-11
+/var/www/current -> /var/www/A -> /var/www/release-12
+                    /var/www/B -> /var/www/release-13
+```
+
+Then when release-13 is ready to go live, flip the symlink to B. For PHP you
+are going to need the [resolve_symlinks](https://wiki.php.net/rfc/resolve_symlinks) patch
+in order to only have `/var/www/A` and `/var/www/B` opcache entries. Without that
+patch PHP will call `realpath()` and you will have `/var/www/release-*` cache entries
+which means no cache re-use.
+
+There is also a small optimization. Instead of just turning it on, you can
+tell it where to start checking for symlinks from in your docroot path like
+this:
+
+```apacheconf
+UseReadlink /var/www/current
+```
+
+this saves a couple of `lstat()` syscalls.
diff --git a/mod_realdoc.c b/mod_realdoc.c
index 585e13b..7ab9f83 100644
--- a/mod_realdoc.c
+++ b/mod_realdoc.c
@@ -1,5 +1,5 @@
 /*
- Copyright (c) 2013 Etsy
+ Copyright (c) 2013-2021 Etsy
 
  Permission is hereby granted, free of charge, to any person
  obtaining a copy of this software and associated documentation