src/README

   1 THE EXIM MAIL TRANSFER AGENT VERSION 4
   2 --------------------------------------
   3
   4 Copyright (c) 1995 - 2018 University of Cambridge.
   5 See the file NOTICE for conditions of use and distribution.
   6
   7 There is a book about Exim by Philip Hazel called "The Exim SMTP Mail Server",
   8 published by UIT Cambridge in May 2003. This is the official guide for Exim 4.
   9 The current edition covers release 4.10 and a few later extensions.
  10
  11 The O'Reilly book about Exim ("Exim The Mail Transfer Agent" by Philip Hazel)
  12 covers Exim 3, which is now deprecated. Exim 4 has a large number of changes
  13 from Exim 3, though the basic structure and philosophy remains the same. The
  14 older book may be helpful for the background, but a lot of the detail has
  15 changed, so it is likely to be confusing to newcomers.
  16
  17 There is a website at https://www.exim.org; this contains details of the
  18 mailing list exim-users@exim.org.
  19
  20 A copy of the Exim FAQ should be available from the same source that you used
  21 to obtain the Exim distribution. Additional formats for the documentation
  22 (PostScript, PDF, Texinfo, and HTML) should also be available there.
  23
  24
  25 EXIM DISTRIBUTION
  26 -----------------
  27
  28 Unpacking the tar file should produce a single directory called exim-<version>,
  29 containing the following files and directories:
  30
  31 ACKNOWLEDGMENTS  some acknowledgments
  32 CHANGES          a conventional file name; it indirects to some files in doc/
  33 LICENCE          the GNU General Public Licence
  34 Local/           an empty directory for local configuration files
  35 Makefile         top level Makefile
  36 NOTICE           notice about conditions of use
  37 OS/              directory containing OS-specific files
  38 README           this file
  39 README.UPDATING  special notes about updating from previous versions
  40 doc/             directory of documentation files
  41 exim_monitor/    directory of source files for the Exim monitor
  42 scripts/         directory of scripts used in the build process
  43 src/             directory of source files
  44 util/            directory of independent utilities
  45
  46 Please see the documentation files for full instructions on how to build,
  47 install, and run Exim. For straightforward installations on operating systems
  48 to which Exim has already been ported, the building process is as follows:
  49
  50 . Ensure that the top-level Exim directory (e.g. exim-4.80) is the current
  51   directory (containing the files and directories listed above).
  52
  53 . Edit the file called src/EDITME and put the result in a new file called
  54   Local/Makefile. There are comments in src/EDITME telling you what the various
  55   parameters are. You must at least provide values for BIN_DIRECTORY,
  56   CONFIGURE_FILE, EXIM_USER and EXIM_GROUP (if EXIM_USER is numeric), and it is
  57   recommended that SPOOL_DIRECTORY also be defined here if it is a fixed path.
  58
  59 . There are a number of additional parameters whose defaults can also be
  60   overridden by additions to Local/Makefile. The basic defaults are in
  61   OS/Makefile-Default, but these settings are overridden for some operating
  62   systems by values on OS/Makefile-<osname>. The most commonly-required change
  63   is probably the setting of CC, which defines the command to run the C
  64   compiler, and which defaults to gcc. To change it to cc, add the following
  65   line to Local/Makefile:
  66
  67   CC=cc
  68
  69   If you are running the Berkeley DB package as your dbm library, then it is
  70   worth putting USE_DB=yes in Local/Makefile, to get Exim to use the native
  71   interface. This is the default for some operating systems. See
  72   doc/dbm.discuss.txt for discussion on dbm libraries.
  73
  74 . If you want to compile the Exim monitor, edit the file called
  75   exim_monitor/EDITME and put the result in a file called Local/eximon.conf.
  76   If you are not going to compile the Exim monitor, you should have commented
  77   out the line starting EXIM_MONITOR= when creating Local/Makefile. There are
  78   comments in exim_monitor/EDITME about the values set therein, but in this
  79   case everything can be defaulted if you wish.
  80
  81 . If your system is not POSIX compliant by default, then you might experience
  82   fewer problems if you help point the build tools to the POSIX variants. For
  83   instance, on Solaris:
  84
  85   PATH=/usr/xpg4/bin:$PATH make SHELL=/usr/xpg4/bin/sh
  86
  87 . Type "make". This will determine what your machine's architecture and
  88   operating system are, and create a build directory from those names (e.g.
  89   "build-SunOS5-sparc"). Symbolic links are created from the build directory
  90   to the source directory. A configured make file called <build-dir>/makefile
  91   is then created, and "make" then goes on to use this to build various
  92   binaries and scripts inside the build directory.
  93
  94 . Type "make install", while running as root, to install the binaries,
  95   scripts, and a default configuration file. To see what this command is
  96   going to do before risking it, run "../scripts/exim_install -n" (not as
  97   root) from within the build directory.
  98
  99 . When you are ready to try running Exim, see the section entitled "Testing"
 100   in the chapter called "Building and Installing Exim" in doc/spec.txt, or in
 101   one of the other forms of the documentation.
 102
 103 . Running the install script does NOT replace /usr/sbin/sendmail or
 104   /usr/lib/sendmail with a link to Exim. That step you must perform by hand
 105   when you are satisfied that Exim is running correctly.
 106
 107 . Note that the default configuration refers to an alias file called
 108   /etc/aliases. It used to be the case that every Unix had that file, because
 109   it was the Sendmail default. These days, there are systems that don't have
 110   /etc/aliases, so you might need to set it up. Your aliases should at least
 111   include an alias for "postmaster".
 112
 113 . Consider notifying users of the change of MTA. Exim has different
 114   capabilities, and there are various operational differences, such as stricter
 115   adherence to the RFCs than some MTAs, and differences in the text of
 116   messages produced by various command-line options.
 117
 118 . The default configuration file will use your host's fully qualified name (as
 119   obtained from the uname() function) as the only local mail domain and as the
 120   domain which is used to qualify unqualified local mail addresses. See the
 121   comments in the default configuration file if you want to change these.
 122
 123 The operating systems currently supported are: AIX, BSD/OS (aka BSDI), Darwin
 124 (Mac OS X), DGUX, FreeBSD, GNU/Hurd, GNU/Linux, HI-OSF (Hitachi), HP-UX, IRIX,
 125 MIPS RISCOS, NetBSD, OpenBSD, QNX, SCO, SCO SVR4.2 (aka UNIX-SV), Solaris (aka
 126 SunOS5), SunOS4, Tru64-Unix (formerly Digital Unix, formerly DEC-OSF1), Ultrix,
 127 and Unixware. However, code is not available for determining system load
 128 averages on Ultrix. There are also configuration files for compiling Exim in
 129 the Cygwin environment that can be installed on systems running Windows.
 130 However, the documentation supplied with the distribution does not contain any
 131 information about running Exim in the Cygwin environment.
 132
 133
 134 ******* Modifying the building process ******
 135
 136 Instructions for overriding the build-time options for Exim are given in the
 137 manual. You should never have to modify any of the supplied files; it should be
 138 possible to override everything that is necessary by creating suitable files in
 139 the Local directory. This means that you won't need to redo your modifications
 140 for the next release of Exim. If you find you can't avoid changing some other
 141 file, let me know and I'll see if I can find a way of making that unnecessary.
 142
 143 Briefly, the building process concatenates a number of files in order to
 144 construct its working makefile. If <ostype> and <archtype> are the operating
 145 system and architecture types respectively, the files used are:
 146
 147   OS/Makefile-Default
 148   OS/Makefile-<ostype>
 149   Local/Makefile
 150   Local/Makefile-<ostype>
 151   Local/Makefile-<archtype>
 152   Local/Makefile-<ostype>-<archtype>
 153   Local/Makefile-<buildname>
 154   OS/Makefile-Base
 155
 156 Of the Local/* files, only Local/Makefile is required to exist; the rest are
 157 optional. Because of the way "make" works, values set in later files override
 158 values set in earlier ones. Thus you can set up general options that are
 159 overridden for specify operating systems and/or architectures if you wish.
 160
 161
 162 ******* IMPORTANT FOR GNU/LINUX USERS *******
 163
 164 Exim 4 won't work with some versions of Linux if you put its spool directory on
 165 an NFS partition. You get an error about "directory sync failed". This is
 166 because of a bug in Linux NFS. A fix has been promised in due course. It is in
 167 any case much better to put Exim's spool directory on local disc.
 168
 169 If you get an error complaining about the lack of functions such as dbm_open()
 170 when building Exim, the problem is that it hasn't been able to find a DBM
 171 library. See the file doc/dbm.discuss.txt for a discussion about the various
 172 DBM libraries.
 173
 174 Different versions of Linux come with different DBM libraries, stored in
 175 different places. As well as setting USE_DB=yes in Local/Makefile if Berkeley
 176 DB is in use, it may also be necessary to set a value in DBMLIB to specify the
 177 inclusion of the DBM library, for example: DBMLIB=-ldb or DBMLIB=-lgdbm.
 178
 179 If you are using RedHat 7.0, which has DB3 as its DBM library, you need to
 180 install the db-devel package before building Exim. This will have a name like
 181 db3-devel-3.1.14-16.i386.rpm (but check which release of DB3 you have).
 182
 183 The building scripts now distinguish between versions of Linux with the older
 184 libc5 and the more recent ones that use libc6. In the latter case, USE_DB and
 185 -ldb are the default settings, because DB is standard with libc6.
 186
 187 It appears that with glibc-2.1.x (a minor libc upgrade), they have standardised
 188 on Berkeley DB2 (instead of DB1 in glibc-2.0.x). If you want to get DB1 back,
 189 you need to set
 190
 191   INCLUDE=-I/usr/include/db1
 192   DBMLIB=-ldb1
 193
 194 in your Local/Makefile. If you omit DBMLIB=-ldb1 Exim will link successfully
 195 using the DB1 compatibility interface to DB2, but it will expect the file
 196 format to be that of DB2, and so will not be able to read existing DB1 files.
 197
 198
 199 ******* IMPORTANT FOR FREEBSD USERS *******
 200
 201 On FreeBSD there is a file called /etc/mail/mailer.conf which selects what to
 202 run for various MTA calls. Instead of changing /usr/sbin/sendmail, you should
 203 edit this file instead, to read something like this:
 204
 205 sendmail          /usr/exim/bin/exim
 206 send-mail         /usr/exim/bin/exim
 207 mailq             /usr/exim/bin/exim -bp
 208 newaliases        /usr/bin/true
 209
 210 You will most probably need to add the line:
 211
 212 daily_status_include_submit_mailq="NO"  # No separate 'submit' queue
 213
 214 to /etc/periodic.conf. This stops FreeBSD running the command "mailq -Ac"
 215 (which Exim doesn't understand) to list a separate submit queue (which Exim
 216 doesn't have).
 217
 218 If you are using FreeBSD prior to 3.0-RELEASE, and you are not using the ports
 219 mechanism to install Exim, then you should install the perl5 package
 220 (/usr/local/bin/perl) and use that instead of perl in the base system, which is
 221 perl4 up until 3.0-RELEASE. If you are using the ports mechanism, this is
 222 handled for you.
 223
 224 If you are upgrading from version 2.11 of Exim or earlier, and you are using
 225 DBM files, and you did not previously have USE_DB=yes in your Local/Makefile,
 226 then you will either have to put USE_DB=no in your Local/Makefile or (better)
 227 rebuild your DBM data files. The default for FreeBSD has been changed to
 228 USE_DB=yes, since FreeBSD comes with Berkeley DB. However, using the native DB
 229 interface means that the data files no longer have the ".db" extension.
 230
 231
 232
 233 ******* IMPORTANT FOR Tru64 (aka Digital Unix aka DEC-OSF1) USERS *******
 234
 235 The default compiler may not recognize ANSI C by default. You may have to set
 236
 237 CC=cc
 238 CFLAGS=-std1
 239
 240 in Local/Makefile in order to compile Exim. A user reported another small
 241 problem with this operating system: In the file /usr/include/net/if.h a
 242 semicolon was missing at the end of line 143.
 243
 244
 245
 246 ******* IMPORTANT FOR SCO USERS *******
 247
 248 The building scripts assume the existence of the "ar" command, which is part of
 249 the Development System. However, it is also possible to use the "gar" command
 250 that is part of the GNU utilities that are distributed with the 5.0.7 release.
 251 If you have "gar" and not "ar" you should include
 252
 253 AR=gar
 254
 255 in your Local/Makefile.
 256
 257
 258
 259 ******* IMPORTANT FOR Unixware 2.x USERS *******
 260
 261 Unixware does not include db/dbm/ndbm with its standard compiler (it is
 262 available with /usr/ucb/cc, but that has bugs of its own). You should install
 263 gcc and Berkeley DB (or another dbm library if you really insist). If you use a
 264 different dbm library you will need to override the default setting of DBMLIB.
 265
 266 DB 1.85 and 2.x can be found at http://www.sleepycat.com/. They have different
 267 characteristics. See the discussion of dbm libraries in doc/dbm.discuss.txt. DB
 268 needs to be compiled with gcc and you need a 'cc' in your path before the
 269 Unixware CC to compile it.
 270
 271 Don't bother even starting to install exim on Unixware unless you have
 272 installed gcc and use it for everything.
 273
 274
 275 ******* IMPORTANT FOR SOLARIS 2.3 (SUNOS 5.3) USERS *******
 276
 277 The file /usr/include/sysexits.h does not exist on Solaris 2.3 (and presumably
 278 earlier versions), though it is present in 2.4 and later versions. To compile
 279 Exim on Solaris 2.3 it is necessary to include the line
 280
 281 CFLAGS=-O -DNO_SYSEXITS -DEX_TEMPFAIL=75
 282
 283 in your Local/Makefile.
 284
 285
 286 ******* IMPORTANT FOR IRIX USERS *******
 287
 288 There are problems with some versions of gcc on IRIX, as a result of which all
 289 DNS lookups yield either 0.0.0.0 or 255.255.255.255. Releases of gcc after
 290 2.7.2.3 (which works ok) are affected. Specifically, 2.8.* is affected, as are
 291 the 2.95 series. From release 3.21 of Exim, a workaround for this problem
 292 should automatically be enabled when Exim is compiled on IRIX using gcc.
 293
 294 As from version 2.03 there is IRIX-specific code in Exim to obtain a list of
 295 all the IP addresses on local interfaces, including alias addresses, because
 296 the standard code gives only non-alias addresses in IRIX. The code came from
 297 SGI, with the comment:
 298
 299 "On 6.2 you need the libc patch to get the sysctl() stub and the networking
 300 kernel patch to get the support."
 301
 302 It seems that this code doesn't work on at least some earlier versions of IRIX
 303 (e.g. IRIX 5.3). If you can't compile under IRIX and the problem appears to
 304 relate to sysctl(), try commenting or #ifdef-ing out all the code in the
 305 file OS/os.c-IRIX.
 306
 307
 308 ******* IMPORTANT FOR HP-UX USERS *******
 309
 310 There are two different sets of configuration files for HP-UX. Those ending in
 311 HP-UX-9 are used for HP-UX version 9, and have been tested on HP-UX version
 312 9.05. Those ending in HP-UX are for later releases, and have been tested on
 313 HP-UX version 11.00. If you are using a version of HP-UX between 9.05 and
 314 11.00, you may need to edit the file OS/os.h-HP-UX if you encounter problems
 315 building Exim.
 316
 317 If you want to use the Sieve facility in Exim, the alias iso-8859-1 should be
 318 added to the alias definition for iso81 in /usr/lib/nls/iconv/config.iconv. You
 319 also need to add a new alias definition: "alias utf8 utf-8".
 320
 321
 322 ******* IMPORTANT FOR QNX USERS *******
 323
 324 1. Exim makes some assumptions about the shell in the makefiles. The "normal"
 325    QNX shell (ksh) will not work. You need to install "bash", which can be
 326    obtained from the QNX freeware on QUICS. Install it to /usr/local/bin/bash
 327    Then you need to change the SHELL definition at the top of the main Makefile
 328    to SHELL=/usr/local/bin/bash. The file OS/Makefile-QNX sets the variable
 329    MAKE_SHELL to /usr/local/bin/bash. If you install bash in a different place,
 330    you will need to set MAKE_SHELL in your Local/Makefile in order to override
 331    this.
 332
 333 2. For some strange reason make will fail at building "exim_dbmbuild" when
 334    called the first time. However simply calling make a second time will solve
 335    the problem. Alternatively, run "make makefile" and then "make".
 336
 337
 338 ******* IMPORTANT FOR ULTRIX USERS *******
 339
 340 You need to set SHELL explicitly in the make call when building on ULTRIX,
 341 that is, type "make SHELL=sh5".
 342
 343
 344 ******* IMPORTANT FOR GNU/HURD USERS *******
 345
 346 GNU/Hurd doesn't (at the time of writing, June 1999) have the ioctls for
 347 finding out the IP addresses of the local interfaces. You therefore have to set
 348 local_interfaces yourself. Otherwise it will treat only 127.0.0.1 as local.
 349
 350 Philip Hazel