WebSVN - Diff - Rev 3 and 29 - /branches/experimental/INSTALL


READ THIS FIRST
---------------
If you try to build with 'make' without editing the makefile for sa-exim to
see the exim source, and if you haven't patched your exim source with 
localscan_dlopen.patch, sa-exim will not build.
This is normal, see the BUILDING section below

This version of sa-exim now requires at least exim 4.11




BUILDING
--------
The code can be compiled in two ways:

0) Do not set LOCAL_SCAN_HAS_OPTIONS=yes in exim's Makefile. Leave the
   default which is disabled.

1) Unpack exim 4.11 or better, and overwrite src/local_scan.c with 
   sa-exim.c. 
   In the sa-exim distribution directory, type make sa-exim.h, and copy
   it in the same place than sa-exim.c.
   Rebuild exim, and you're done.
   Note that if you do this, you are responsible for modifying variables
   in sa-exim.c that would normally have been modified by the Makefile.
   
   This method might seem simpler, but it requires that you rebuild exim every
   time you upgrade sa-exim.

2) The better solution is to patch exim with localscan_dlopen.patch originally
   from David Woodhouse (provided in this archive), and rebuild exim.
   Here are details on how to patch exim if yours needs it (at least debian's
   exim4 is prepatched, yours may be too).
   Choose the patch for your exim version (Philip included the portion that 
   sets LOCAL_SCAN_ABI_VERSION_MAJOR and LOCAL_SCAN_ABI_VERSION_MINOR in exim
   4.20)
   - localscan_dlopen_exim_4.20_or_better.patch
   - localscan_dlopen_up_to_4.14.patch


   What you gain from doing this is that sa-exim, or another local_scan module
   can be plugged into exim without rebuilding exim itself (here too you need
   exim 4.11 or better)

   To build, you can edit EXIM_SRC in the Makefile and build sa-exim-x.y.so,
   or I have also recently modified the build environment so that you can
   now build sa-exim without having the exim sources.
   You can look in eximinc/version to see which source I included. While this
   should work for the forseable future, the exim local_scan API might change
   one day and not building against the current exim sources could cause issues
   (hopefully, at worst it will prevent sa-exim from using better functions in
   newer versions of the local_scan API).
   To be really safe, I modified the localscan_dlopen patch to include a
   minor and major version number for the API. Philip has agreed to including
   the piece of the patch that says which version of the API exim is using,
   so it will be obvious in the future whether exim becomes potentially
   incompatible with an older version of sa-exim. Note that when Philip adds
   this small portion of the patch, you will have a resulting conflict if
   you try to apply it again. This is obviously normal, just remove it :-)

   Once you're done building, you can copy sa-exim-x.y.so and optionally the
   dummy/test accept.so in /usr/lib/exim4/local_scan/, and add this to your
   exim4.conf (at the beginning of the file)
   #local_scan_path = /usr/lib/exim4/local_scan/accept.so
   local_scan_path = /usr/lib/exim4/local_scan/sa-exim.so

   If you are a package builder, note that you don't actually have
   to edit the values in the Makefile, you can override them as such:
   make SACONF=/etc/mail/sa-exim.conf LDFLAGS="-shared -fPIC"


The following is mostly obsolete, but left here for info purposes
-----------------------------------------------------------------
I would also recommend to edit exim/src/config.h.defaults as such:
#define STRING_SPRINTF_BUFFER_SIZE 32768
The default value is a bit too small for some of the strings that we need to
expand from SA.
That said, I found out that exim then complaints that the headers
it tries to add are too big even after I set "uschar buffer[32768];" in
src/header.c.
As a result, I haven't quite found out how to deal with more than 8KB worth
of SpamAssassin headers, but it may not be a huge deal, 8KB headers are too
long anyway. 
I asked the SA guys not to output such huge headers and I wrote a patch
to disable one of the "features" that outputs such huge headers.
See: http://bugzilla.spamassassin.org/showattachment.cgi?attach_id=195
This is included and turned on by default in Spamassassin 2.40 and later.


INSTALL
-------
Copy sa-exim.conf to /etc/exim4 (or whatever you set SACONF to),
and make sure to read it and edit the values to suit your environment.
So that you don't make any mistakes, SAEximRunCond is turned off by default.
This should force you to scan the docs before potentially shooting yourself
in the foot :)

See README for options


Subversion Repositories

(root)/branches/experimental/INSTALL - Rev 3 → 29

Rev 3		Rev 29
1	READ THIS FIRST	1	READ THIS FIRST
2	---------------	2	---------------
3	If you try to build with 'make' without editing the makefile for sa-exim to	3	If you try to build with 'make' without editing the makefile for sa-exim to
4	see the exim source, and if you haven't patched your exim source with	4	see the exim source, and if you haven't patched your exim source with
5	localscan_dlopen.patch, sa-exim will not build.	5	localscan_dlopen.patch, sa-exim will not build.
6	This is normal, see the BUILDING section below	6	This is normal, see the BUILDING section below
7		7
8	This version of sa-exim now requires at least exim 4.11	8	This version of sa-exim now requires at least exim 4.11
9		9
10		10
11		11
12		12
13	BUILDING	13	BUILDING
14	--------	14	--------
15	The code can be compiled in two ways:	15	The code can be compiled in two ways:
16		16
17	0) Do not set LOCAL_SCAN_HAS_OPTIONS=yes in exim's Makefile. Leave the	17	0) Do not set LOCAL_SCAN_HAS_OPTIONS=yes in exim's Makefile. Leave the
18	default which is disabled.	18	default which is disabled.
19		19
20	1) Unpack exim 4.11 or better, and overwrite src/local_scan.c with	20	1) Unpack exim 4.11 or better, and overwrite src/local_scan.c with
21	sa-exim.c.	21	sa-exim.c.
22	In the sa-exim distribution directory, type make sa-exim.h, and copy	22	In the sa-exim distribution directory, type make sa-exim.h, and copy
23	it in the same place than sa-exim.c.	23	it in the same place than sa-exim.c.
24	Rebuild exim, and you're done.	24	Rebuild exim, and you're done.
25	Note that if you do this, you are responsible for modifying variables	25	Note that if you do this, you are responsible for modifying variables
26	in sa-exim.c that would normally have been modified by the Makefile.	26	in sa-exim.c that would normally have been modified by the Makefile.
27		27
28	This method might seem simpler, but it requires that you rebuild exim every	28	This method might seem simpler, but it requires that you rebuild exim every
29	time you upgrade sa-exim.	29	time you upgrade sa-exim.
30		30
31	2) The better solution is to patch exim with localscan_dlopen.patch originally	31	2) The better solution is to patch exim with localscan_dlopen.patch originally
32	from David Woodhouse (provided in this archive), and rebuild exim.	32	from David Woodhouse (provided in this archive), and rebuild exim.
33	Here are details on how to patch exim if yours needs it (at least debian's	33	Here are details on how to patch exim if yours needs it (at least debian's
34	exim4 is prepatched, yours may be too).	34	exim4 is prepatched, yours may be too).
35	Choose the patch for your exim version (Philip included the portion that	35	Choose the patch for your exim version (Philip included the portion that
36	sets LOCAL_SCAN_ABI_VERSION_MAJOR and LOCAL_SCAN_ABI_VERSION_MINOR in exim	36	sets LOCAL_SCAN_ABI_VERSION_MAJOR and LOCAL_SCAN_ABI_VERSION_MINOR in exim
37	4.20)	37	4.20)
38	- localscan_dlopen_exim_4.20_or_better.patch	38	- localscan_dlopen_exim_4.20_or_better.patch
39	- localscan_dlopen_up_to_4.14.patch	39	- localscan_dlopen_up_to_4.14.patch
40		40
41		41
42	What you gain from doing this is that sa-exim, or another local_scan module	42	What you gain from doing this is that sa-exim, or another local_scan module
43	can be plugged into exim without rebuilding exim itself (here too you need	43	can be plugged into exim without rebuilding exim itself (here too you need
44	exim 4.11 or better)	44	exim 4.11 or better)
45		45
46	To build, you can edit EXIM_SRC in the Makefile and build sa-exim-x.y.so,	46	To build, you can edit EXIM_SRC in the Makefile and build sa-exim-x.y.so,
47	or I have also recently modified the build environment so that you can	47	or I have also recently modified the build environment so that you can
48	now build sa-exim without having the exim sources.	48	now build sa-exim without having the exim sources.
49	You can look in eximinc/version to see which source I included. While this	49	You can look in eximinc/version to see which source I included. While this
50	should work for the forseable future, the exim local_scan API might change	50	should work for the forseable future, the exim local_scan API might change
51	one day and not building against the current exim sources could cause issues	51	one day and not building against the current exim sources could cause issues
52	(hopefully, at worst it will prevent sa-exim from using better functions in	52	(hopefully, at worst it will prevent sa-exim from using better functions in
53	newer versions of the local_scan API).	53	newer versions of the local_scan API).
54	To be really safe, I modified the localscan_dlopen patch to include a	54	To be really safe, I modified the localscan_dlopen patch to include a
55	minor and major version number for the API. Philip has agreed to including	55	minor and major version number for the API. Philip has agreed to including
56	the piece of the patch that says which version of the API exim is using,	56	the piece of the patch that says which version of the API exim is using,
57	so it will be obvious in the future whether exim becomes potentially	57	so it will be obvious in the future whether exim becomes potentially
58	incompatible with an older version of sa-exim. Note that when Philip adds	58	incompatible with an older version of sa-exim. Note that when Philip adds
59	this small portion of the patch, you will have a resulting conflict if	59	this small portion of the patch, you will have a resulting conflict if
60	you try to apply it again. This is obviously normal, just remove it :-)	60	you try to apply it again. This is obviously normal, just remove it :-)
61		61
62	Once you're done building, you can copy sa-exim-x.y.so and optionally the	62	Once you're done building, you can copy sa-exim-x.y.so and optionally the
63	dummy/test accept.so in /usr/lib/exim4/local_scan/, and add this to your	63	dummy/test accept.so in /usr/lib/exim4/local_scan/, and add this to your
64	exim4.conf (at the beginning of the file)	64	exim4.conf (at the beginning of the file)
65	#local_scan_path = /usr/lib/exim4/local_scan/accept.so	65	#local_scan_path = /usr/lib/exim4/local_scan/accept.so
66	local_scan_path = /usr/lib/exim4/local_scan/sa-exim.so	66	local_scan_path = /usr/lib/exim4/local_scan/sa-exim.so
67		67
68	If you are a package builder, note that you don't actually have	68	If you are a package builder, note that you don't actually have
69	to edit the values in the Makefile, you can override them as such:	69	to edit the values in the Makefile, you can override them as such:
70	make SACONF=/etc/mail/sa-exim.conf LDFLAGS="-shared -fPIC"	70	make SACONF=/etc/mail/sa-exim.conf LDFLAGS="-shared -fPIC"
71		71
72		72
73	The following is mostly obsolete, but left here for info purposes	73	The following is mostly obsolete, but left here for info purposes
74	-----------------------------------------------------------------	74	-----------------------------------------------------------------
75	I would also recommend to edit exim/src/config.h.defaults as such:	75	I would also recommend to edit exim/src/config.h.defaults as such:
76	#define STRING_SPRINTF_BUFFER_SIZE 32768	76	#define STRING_SPRINTF_BUFFER_SIZE 32768
77	The default value is a bit too small for some of the strings that we need to	77	The default value is a bit too small for some of the strings that we need to
78	expand from SA.	78	expand from SA.
79	That said, I found out that exim then complaints that the headers	79	That said, I found out that exim then complaints that the headers
80	it tries to add are too big even after I set "uschar buffer[32768];" in	80	it tries to add are too big even after I set "uschar buffer[32768];" in
81	src/header.c.	81	src/header.c.
82	As a result, I haven't quite found out how to deal with more than 8KB worth	82	As a result, I haven't quite found out how to deal with more than 8KB worth
83	of SpamAssassin headers, but it may not be a huge deal, 8KB headers are too	83	of SpamAssassin headers, but it may not be a huge deal, 8KB headers are too
84	long anyway.	84	long anyway.
85	I asked the SA guys not to output such huge headers and I wrote a patch	85	I asked the SA guys not to output such huge headers and I wrote a patch
86	to disable one of the "features" that outputs such huge headers.	86	to disable one of the "features" that outputs such huge headers.
87	See: http://bugzilla.spamassassin.org/showattachment.cgi?attach_id=195	87	See: http://bugzilla.spamassassin.org/showattachment.cgi?attach_id=195
88	This is included and turned on by default in Spamassassin 2.40 and later.	88	This is included and turned on by default in Spamassassin 2.40 and later.
89		89
90		90
91	INSTALL	91	INSTALL
92	-------	92	-------
93	Copy sa-exim.conf to /etc/exim4 (or whatever you set SACONF to),	93	Copy sa-exim.conf to /etc/exim4 (or whatever you set SACONF to),
94	and make sure to read it and edit the values to suit your environment.	94	and make sure to read it and edit the values to suit your environment.
95	So that you don't make any mistakes, SAEximRunCond is turned off by default.	95	So that you don't make any mistakes, SAEximRunCond is turned off by default.
96	This should force you to scan the docs before potentially shooting yourself	96	This should force you to scan the docs before potentially shooting yourself
97	in the foot :)	97	in the foot :)
98		98
99	See README for options	99	See README for options
100		100