qmail/sme9/moreipme.README

###########
### WHO ###
###########

This patch was written by Scott Gifford <sgifford@suspectclass.com>.
The design and much of the code for supporting "notipme" was
contributed by Charles Cazabon <charlesc@discworld.dyndns.org>.


############
### WHAT ###
############

This patch may be necessary in some configurations that involve network
address translation or port forwarding.  It prevents a problem caused
by an MX or other mail routing directive instructing qmail to connect to
itself without realizing it's connecting to itself.  When this happens,
it accepts the message, finds out where to deliver it to (itself), and
promptly reconnects to itself to deliver the message.  Eventually, when
it has done this 20 or 30 times, it will give up and bounce the message,
but not before sucking up all of your CPU while it's happening.

It may also be useful in some configurations that have multiple qmail
servers configured on different interfaces of the same system.  qmail
will normally refuse to deliver mail by SMTP to the machine it's
running on, but with multiple copies of qmail, you may want to prevent
this behavior.

Normally, qmail can detect what IP addresses refer to itself by getting
a list of all network interfaces with IP addresses from the operating
system.  It uses this list to determine whether connecting to an address
will cause it to connect to itself, and avoid the situation (it calls
the perm_ambigmx() function, which prints the message:

   Sorry. Although I'm listed as a best-preference MX or A for that host,
   it isn't in my control/locals file, so I don't treat it as local. (#5.4.6)

But in situations where the OS is not aware of all IP addresses that
connect back to itself, this detection fails, causing the CPU-sucking
phenomenon described above.  This can happen if there is a network
address translation device in front of the qmail server, such as a
load-balancer or a router which allows you to share one IP address among
several machines; if there is a port forwarder forwarding connections
from some other machine to the SMTP server on the qmail server; or in
configurations where a "dumb" mailserver is configured to use your qmail
server as a "smarthost", delivering all mail to it without inspection.

To solve this, other IP addresses which will ultimately connect back to
your machine can be added to the file "control/moreipme", one per line.
qmail will treat all addresses in this file exactly as if they were
local, and if it finds an MX record or other mail routing information
which would cause it to connect to any of these addresses, it will call
perm_ambigmx(), and print the above error message.

Additionally, IP addresses which the system detects but which should
*not* be treated as local can be removed from qmail's ipme list by
adding them to the file "control/notipme".

IP addresses can be specified as individual addresses in the usual
dotted-quad format, or as entire networks using a slash followed by
the full dotted-quad netmask:

    127.0.0.1
    127.0.0.1/255.255.255.255
    127.0.0.0/255.0.0.0
    10.0.0.0/255.255.255.0

An individual address is treated exactly like a network with a mask of
255.255.255.255.  Addresses of interfaces found on the system are
added with their individual addresses.  In addition, these addresses
are implicitly added:

    0.0.0.0
    127.0.0.0/255.0.0.0

So the list of system addresses (the "ipme" list) is, in order,
127.0.0.0/255.0.0.0, 0.0.0.0, then all actual interfaces on the system
in the order they are reported, then the contents of the "moreipme"
file.  The list of excluded addresses (the "notipme" list) is just the
contents of the "notipme" file.

If an address appears in both the ipme list and the notipme list, the
entry with the longest netmask wins.  If the netmask lengths are the
same, notipme wins.

For example, if the ipme list has 127.0.0.0/255.0.0.0 and notipme has
127.0.0.2, then 127.0.0.2 will not be considered me because the entry
in notipme has a 32-bit mask.  If the notipme list has
127.0.0.0/255.0.0.0, all of 127.* will not be considered me.

You can run the program "ipmeprint" from the source directory to see
what interfaces qmail is detecting or finds in moreipme.

You can run the program "ipmetest" from the source directory to test
your configuration.  It takes as its first and only parameter an IP
address to test, and prints either "me" or "not me".

###########
### HOW ###
###########

To apply the patch, download and save it somewhere, then cd into your
qmail source directory.

For stock qmail, download qmail-1.03-moreipme-0.6.patch then run:

    cd qmail-1.03
    patch -p1 </path/to/qmail-1.03-moreipme-0.6.patch

For netqmail, first download netqmail-1.05, and run the included
collate.sh script.  Then download netqmail-1.05-moreipme-0.6.patch and
apply it to the netqmail base directory, after runn:

    cd netqmail-1.05
    patch -p1 </path/to/netqmail-1.05-moreipme-0.6.patch
 

###################
### OTHER NOTES ###
###################

This patch also incorporates the "0.0.0.0" patch, which causes qmail 
to recognize the IP address 0.0.0.0 as a local address.  See:

    http://www.suspectclass.com/~sgifford/qmail/qmail-0.0.0.0.README

for more information, and

    http://www.suspectclass.com/~sgifford/qmail/qmail-0.0.0.0.patch

for a copy of the patch.


###############
### HISTORY ###
###############

2004 May 22 - Patch version 0.6 released.  Fix from Richard Dawe where
              masks weren't handled properly, removed some dead code,
              updated comments and docs.  Produce a copy of the patch
              for netqmail-1.05.

2003 Apr 29 - Patch version 0.5 released.  Added support for netmasks
              in moreipme and notipme, ipmetest utility, 127/8 as
              implicit ipme.

2002 Apr 26 - Patch version 0.4 released.  Includes support for "notipme" file.
              Many other small fixes and cleanups.  Fixes ipmeprint to
              chdir(/var/qmail) before running.

2001 Oct  8 - Original release of patch.

2001 Jan 22 - (roughly) Original release of 0.0.0.0 patch.

1	unnilennium	1.1	###########
2			### WHO ###
3			###########
4
5			This patch was written by Scott Gifford <sgifford@suspectclass.com>.
6			The design and much of the code for supporting "notipme" was
7			contributed by Charles Cazabon <charlesc@discworld.dyndns.org>.
8
9
10			############
11			### WHAT ###
12			############
13
14			This patch may be necessary in some configurations that involve network
15			address translation or port forwarding. It prevents a problem caused
16			by an MX or other mail routing directive instructing qmail to connect to
17			itself without realizing it's connecting to itself. When this happens,
18			it accepts the message, finds out where to deliver it to (itself), and
19			promptly reconnects to itself to deliver the message. Eventually, when
20			it has done this 20 or 30 times, it will give up and bounce the message,
21			but not before sucking up all of your CPU while it's happening.
22
23			It may also be useful in some configurations that have multiple qmail
24			servers configured on different interfaces of the same system. qmail
25			will normally refuse to deliver mail by SMTP to the machine it's
26			running on, but with multiple copies of qmail, you may want to prevent
27			this behavior.
28
29			Normally, qmail can detect what IP addresses refer to itself by getting
30			a list of all network interfaces with IP addresses from the operating
31			system. It uses this list to determine whether connecting to an address
32			will cause it to connect to itself, and avoid the situation (it calls
33			the perm_ambigmx() function, which prints the message:
34
35			Sorry. Although I'm listed as a best-preference MX or A for that host,
36			it isn't in my control/locals file, so I don't treat it as local. (#5.4.6)
37
38			But in situations where the OS is not aware of all IP addresses that
39			connect back to itself, this detection fails, causing the CPU-sucking
40			phenomenon described above. This can happen if there is a network
41			address translation device in front of the qmail server, such as a
42			load-balancer or a router which allows you to share one IP address among
43			several machines; if there is a port forwarder forwarding connections
44			from some other machine to the SMTP server on the qmail server; or in
45			configurations where a "dumb" mailserver is configured to use your qmail
46			server as a "smarthost", delivering all mail to it without inspection.
47
48			To solve this, other IP addresses which will ultimately connect back to
49			your machine can be added to the file "control/moreipme", one per line.
50			qmail will treat all addresses in this file exactly as if they were
51			local, and if it finds an MX record or other mail routing information
52			which would cause it to connect to any of these addresses, it will call
53			perm_ambigmx(), and print the above error message.
54
55			Additionally, IP addresses which the system detects but which should
56			not be treated as local can be removed from qmail's ipme list by
57			adding them to the file "control/notipme".
58
59			IP addresses can be specified as individual addresses in the usual
60			dotted-quad format, or as entire networks using a slash followed by
61			the full dotted-quad netmask:
62
63			127.0.0.1
64			127.0.0.1/255.255.255.255
65			127.0.0.0/255.0.0.0
66			10.0.0.0/255.255.255.0
67
68			An individual address is treated exactly like a network with a mask of
69			255.255.255.255. Addresses of interfaces found on the system are
70			added with their individual addresses. In addition, these addresses
71			are implicitly added:
72
73			0.0.0.0
74			127.0.0.0/255.0.0.0
75
76			So the list of system addresses (the "ipme" list) is, in order,
77			127.0.0.0/255.0.0.0, 0.0.0.0, then all actual interfaces on the system
78			in the order they are reported, then the contents of the "moreipme"
79			file. The list of excluded addresses (the "notipme" list) is just the
80			contents of the "notipme" file.
81
82			If an address appears in both the ipme list and the notipme list, the
83			entry with the longest netmask wins. If the netmask lengths are the
84			same, notipme wins.
85
86			For example, if the ipme list has 127.0.0.0/255.0.0.0 and notipme has
87			127.0.0.2, then 127.0.0.2 will not be considered me because the entry
88			in notipme has a 32-bit mask. If the notipme list has
89			127.0.0.0/255.0.0.0, all of 127.* will not be considered me.
90
91			You can run the program "ipmeprint" from the source directory to see
92			what interfaces qmail is detecting or finds in moreipme.
93
94			You can run the program "ipmetest" from the source directory to test
95			your configuration. It takes as its first and only parameter an IP
96			address to test, and prints either "me" or "not me".
97
98			###########
99			### HOW ###
100			###########
101
102			To apply the patch, download and save it somewhere, then cd into your
103			qmail source directory.
104
105			For stock qmail, download qmail-1.03-moreipme-0.6.patch then run:
106
107			cd qmail-1.03
108			patch -p1 </path/to/qmail-1.03-moreipme-0.6.patch
109
110			For netqmail, first download netqmail-1.05, and run the included
111			collate.sh script. Then download netqmail-1.05-moreipme-0.6.patch and
112			apply it to the netqmail base directory, after runn:
113
114			cd netqmail-1.05
115			patch -p1 </path/to/netqmail-1.05-moreipme-0.6.patch
116
117
118			###################
119			### OTHER NOTES ###
120			###################
121
122			This patch also incorporates the "0.0.0.0" patch, which causes qmail
123			to recognize the IP address 0.0.0.0 as a local address. See:
124
125			http://www.suspectclass.com/~sgifford/qmail/qmail-0.0.0.0.README
126
127			for more information, and
128
129			http://www.suspectclass.com/~sgifford/qmail/qmail-0.0.0.0.patch
130
131			for a copy of the patch.
132
133
134			###############
135			### HISTORY ###
136			###############
137
138			2004 May 22 - Patch version 0.6 released. Fix from Richard Dawe where
139			masks weren't handled properly, removed some dead code,
140			updated comments and docs. Produce a copy of the patch
141			for netqmail-1.05.
142
143			2003 Apr 29 - Patch version 0.5 released. Added support for netmasks
144			in moreipme and notipme, ipmetest utility, 127/8 as
145			implicit ipme.
146
147			2002 Apr 26 - Patch version 0.4 released. Includes support for "notipme" file.
148			Many other small fixes and cleanups. Fixes ipmeprint to
149			chdir(/var/qmail) before running.
150
151			2001 Oct 8 - Original release of patch.
152
153			2001 Jan 22 - (roughly) Original release of 0.0.0.0 patch.
154