DKIM downgrade example again; this time debugged

[exim.git] / doc / doc-txt / openssl.txt

diff --git a/doc/doc-txt/openssl.txt b/doc/doc-txt/openssl.txt
index f572034058d27b609f5982b856bf78fdbee7fe4e..7bcd47907402b1e055ae26fc970a091108fda6fb 100644 (file)
--- a/doc/doc-txt/openssl.txt
+++ b/doc/doc-txt/openssl.txt
@@ -36,10 +36,23 @@ Extract the current source of OpenSSL.  Change into that directory.
 This assumes that `/opt/openssl` is not in use.  If it is, pick
 something else.  `/opt/exim/openssl` perhaps.
 
 This assumes that `/opt/openssl` is not in use.  If it is, pick
 something else.  `/opt/exim/openssl` perhaps.
 

-    ./config --prefix=/opt/openssl --openssldir=/etc/ssl enable-ssl-trace
+If you pick a location shared amongst various local packages, such as
+`/usr/local` on Linux, then the new OpenSSL will be used by all of those
+packages.  If that's what you want, great!  If instead you want to
+ensure that only software you explicitly set to use the newer OpenSSL
+will try to use the new OpenSSL, then stick to something like
+`/opt/openssl`.
+
+    ./config --prefix=/opt/openssl --openssldir=/etc/ssl  \
+        -L/opt/openssl/lib -Wl,-R/opt/openssl/lib         \
+        enable-ssl-trace shared

     make
     make install
 
     make
     make install
 

+On some systems, the linker uses `-rpath` instead of `-R`; on such systems,
+replace the parameter starting `-Wl` with: `-Wl,-rpath,/opt/openssl/lib`.
+There are more variations on less common systems.
+

 You now have an installed OpenSSL under /opt/openssl which will not be
 used by any system programs.
 
 You now have an installed OpenSSL under /opt/openssl which will not be
 used by any system programs.
 


@@ -47,17 +60,19 @@ When you copy `src/EDITME` to `Local/Makefile` to make your build edits,
 choose the pkg-config approach in that file, but also tell Exim to add
 the relevant directory into the rpath stamped into the binary:
 
 choose the pkg-config approach in that file, but also tell Exim to add
 the relevant directory into the rpath stamped into the binary:
 

+    PKG_CONFIG_PATH=/opt/openssl/lib/pkgconfig
+

     SUPPORT_TLS=yes
     USE_OPENSSL_PC=openssl
     SUPPORT_TLS=yes
     USE_OPENSSL_PC=openssl

-    EXTRALIBS_EXIM=-ldl -Wl,-rpath,/opt/openssl/lib
+    LDFLAGS+=-ldl -Wl,-rpath,/opt/openssl/lib

 
 

-The -ldl is needed by OpenSSL 1.1+ on Linux and is not needed on most
-other platforms.
+The -ldl is needed by OpenSSL 1.0.2+ on Linux and is not needed on most
+other platforms.  The LDFLAGS is needed because `pkg-config` doesn't know
+how to emit information about RPATH-stamping, but we can still leverage
+`pkg-config` for everything else.

 
 

-Then tell pkg-config how to find the configuration files for your new
-OpenSSL install, and build Exim:
+Then build Exim:

 
 

-    export PKG_CONFIG_PATH=/opt/openssl/lib/pkgconfig

     make
     sudo make install
 
     make
     sudo make install
 


@@ -85,6 +100,27 @@ If the `chrpath` package is installed, then:
 
 will show the DT_RPATH stamped into the binary.
 
 
 will show the DT_RPATH stamped into the binary.
 

+Your `binutils` package should come with `readelf`, so an alternative
+is to run:
+
+    readelf -d $(which exim) | grep RPATH
+
+It is important to use `RPATH` and not `RUNPATH`!
+
+The gory details about `RUNPATH` (skip unless interested):
+The OpenSSL library might be opened indirectly by some other library
+which Exim depends upon.  If the executable does have `RUNPATH` then
+that will inhibit using either of `RPATH` or `RUNPATH` from the
+executable for finding the OpenSSL library when that other library tries
+to load it.
+In fact, if the intermediate library has a `RUNPATH` stamped into it,
+then this will block `RPATH` too, and will create problems with Exim.
+If you're in such a situation, and those libraries were supplied to you
+instead of built by you, then you're reaching the limits of sane
+repairability and it's time to prioritize rebuilding your mail-server
+hosts to be a current OS release which natively pulls in an
+upstream-supported OpenSSL, or stick to the OS releases of Exim.
+

 
 Very Advanced
 -------------
 
 Very Advanced
 -------------