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