From: Phil Pennock Date: Mon, 2 Jan 2017 13:59:17 +0000 (-0500) Subject: wip: OpenSSL docs on custom install X-Git-Tag: exim-4_89_RC1~48 X-Git-Url: https://git.exim.org/exim.git/commitdiff_plain/2eec84caa477a4b3b1f9fff999000768f65bd936?ds=inline wip: OpenSSL docs on custom install To fix before merge: ability to use `$ORIGIN` in linker line via Exim config file. --- diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 4497a8f9e..75f28ef67 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -434,6 +434,7 @@ directory are: .row &_filter.txt_& "specification of the filter language" .row &_Exim3.upgrade_& "upgrade notes from release 2 to release 3" .row &_Exim4.upgrade_& "upgrade notes from release 3 to release 4" +.row &_openssl.txt_& "installing a current OpenSSL release" .endtable The main specification and the specification of the filtering language are also diff --git a/doc/doc-txt/openssl.txt b/doc/doc-txt/openssl.txt new file mode 100644 index 000000000..6e6db9f69 --- /dev/null +++ b/doc/doc-txt/openssl.txt @@ -0,0 +1,108 @@ +OpenSSL +======= + +The OpenSSL Project documents their supported releases at +. The Exim +Maintainers are unwilling to try to support Exim built with a +version of a critical security library which is unmaintained. + +Thus as versions of OpenSSL become unsupported by OpenSSL, they become +unsupported by Exim. Exim might build with older releases of OpenSSL, +but that's risky behaviour. + +If your operating system vendor continues to ship an older version of +OpenSSL and is diligently backporting security fixes, and they support +Exim, then they will be backporting fixes to their packages of Exim too. +If you wish to stick purely to packages of OpenSSL, then stick to +packages of Exim too. + +If someone maintains "backports", that is worth exploring too. + +Note that a number of OSes use Exim with GnuTLS, not OpenSSL. + +Otherwise, assuming that your operating system has old OpenSSL, and you +wish to use current Exim with OpenSSL, then you need to build and +install your own, without interfering with the system libraries. +Fortunately, this is easy. + +So this only applies if you build Exim yourself. + + +Build +----- + +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. + + ./config --prefix=/opt/openssl --openssldir=/etc/ssl + enable-ssl-trace + make + make install + +You now have an installed OpenSSL under /opt/openssl which will not be +used by any system programs. + +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: + + SUPPORT_TLS=yes + USE_OPENSSL_PC=openssl + EXTRALIBS_EXIM=-ldl -Wl,-rpath,/opt/openssl/lib + +The -ldl is needed by OpenSSL 1.1+ on Linux and is not needed on most +other platforms. + +Then tell pkg-config how to find the configuration files for your new +OpenSSL install, and build Exim: + + export PKG_CONFIG_PATH=/opt/openssl/lib/pkgconfig + make + sudo make install + + +Confirming +---------- + +Run: + + exim -d-all+expand --version + +and look for the `Library version: OpenSSL:` lines. + +To look at the libraries _probably_ found by the linker, use: + + ldd $(which exim) # most platforms + otool -L $(which exim) # MacOS + +although that does not correclty handle restrictions imposed upon +executables which are setuid. + +If the `chrpath` package is installed, then: + + chrpath -l $(which exim) + +will show the DT_RPATH stamped into the binary. + + +Very Advanced +------------- + +You can not use $ORIGIN for portably packing OpenSSL in with Exim with +normal Exim builds, because Exim is installed setuid which causes the +runtime linker to ignore $ORIGIN in DT_RPATH. + +_If_ following the steps for a non-setuid Exim, _then_ you can use: + + EXTRALIBS_EXIM=-ldl '-Wl,-rpath,$$ORIGIN/../lib' + +The doubled `$$` is needed for the make(1) layer and the quotes needed +for the shell invoked by make(1) for calling the linker. + +Note that this is sufficiently far outside normal that the build-system +doesn't support it by default; you'll want to drop a symlink to the lib +directory into the Exim release top-level directory, so that lib exists +as a sibling to the build-$platform directory. + diff --git a/src/README.UPDATING b/src/README.UPDATING index 8cb59e91e..7ed0ffc0a 100644 --- a/src/README.UPDATING +++ b/src/README.UPDATING @@ -26,6 +26,16 @@ The rest of this document contains information about changes in 4.xx releases that might affect a running system. +Exim version 4.89 +----------------- + + * OpenSSL: oldest supported release series is now 1.0.2, which is the oldest + supported by the OpenSSL project. If you can build Exim with an older + release series, congratulations. If you can't, then upgrade. + The file doc/openssl.txt contains instructions for installing a current + OpenSSL outside the system library paths and building Exim to use it. + + Exim version 4.88 -----------------