docs/qmail/README.html

<html>
  <head>
    <title>README</title>
  </head>

  <body>
    <h2>README</h2>
    <pre>

File:   README
Author: James Couzens &lt;jcouzens@codeshare.ca&gt;
Desc:   README file for working with libSPF and qmail
Date:   Tue Aug  3 10:01:28 PDT 2004 - Updated

=======================================================================================

TCPSERVER GLOBAL VARS:

SPF_ACTION        (control/spfaction)
SPF_TARPIT        (control/spftarpit)
SPF_TARPIT_TIME   (control/spftarpittime)
SPF_EXPLAIN_STATE (control/spfexplainstate)
SPF_TRUSTED_STATE (control/spftrustedstate)
SPF_GUESS_STATE   (control/spfguesstate)
SPF_HEADER_STATE  (control/spfheaderstate)
SPF_DEBUG_STATE   (control/spfdebugstate)

By setting these in your environment with appropriate values you can nicely alter the
behaviour of libspf for individual persons on your network.  A great example is by
placing SPF_ACTION inside of tcp.smtp and setting it to a 0 for 127.0.0.1 eg:

127.:allow,RELAYCLIENT=&quot;&quot;,RBLSMTPD=&quot;&quot;,SPF_ACTION=&quot;0&quot;

This way 127.0.0.1 never has SPF checks performed on them.  I'm sure you get the idea.

=======================================================================================

CONTROL FILE:

spfaction

Inside this file place a single digit between 0 and 7.

Below describes the behaviour of these digits:

0: disabled
1: enabled (only prepends headers, and only if spfheaderstate == 1)
2: REJECT: fail; ACCEPT: pass, none, softfail, error, netural, unknown; 
3: REJECT: fail, softfail; ACCEPT: pass, none, error, netural, unknown;
4: REJECT: fail, softfail, neutral; ACCEPT: pass, none, error, unknown;
5: REJECT: fail, softfail, neutral, none; ACCEPT: pass, error, unknown;
6: REJECT: fail, softfail, neutral, none, error; ACCEPT: pass, unknown;
7: REJECT: fail, softfail, neutral, none, error, unknown; ACCEPT: pass;

Chose one of the above error levels that best suits you.  Since this is still beta
I think 1 is best.  Youe mileage may vary.

=======================================================================================

CONTROL FILE:

spftarpit     - value (single integer)

0 (default) = disable tarpitting
1 (enabled) = enable tarpitting

spftarpittime - value (single integer)

0 = how long to tarpit for (default is 60)

Tarpitting happens based on the above set spfaction.  If the action 
was set to 2, then upon a softfail the process would sleep x seconds
and then call quit (where x is the value of spftarpittime or the 
default 60)
 
I suggest you use this with caution, perhaps only enabling it on 
FAIL which is something that can only happen when an SPF rule is supplied, and some
how the connecting client violates the policy.  You have been warned.  This could quite
EASILY LEAD TO YOUR SERVER BEING DOSSED BY SOME TURD.  DO NOT BLAME ME, DEFAULT IS OFF.
CONSIDER YOUR SELF WARNED.

=======================================================================================

CONTROL FILE:

spfheaderstate

value (single integer):

1 (default) = enabled prepending Received-SPF: headers
0 = no not prepend headers

When set to 1, libspf will pre-pend &quot;Received-SPF:&quot; headers as per the SPF RFC
Internet Draft.  This are useful for third party applications such as SpamAssassin,
and even email clients capable of parsing headers to know where to filter email to.

=======================================================================================

CONTROL FILE:

spfbestguess 

value: (single line of text)

default: v=spf1 a/24 mx/24 ptr 

This query is looked up in an attempt to make a guess against the user in the event
no record is found and the trusted forwarder lookup fails.  The default value exists
within libspf, so creating the control file is only necessary if you wish to change
this value.

=======================================================================================

CONTROL FILE:

spfguessstate

value (single integer):

1 (default) = perform best guess lookup when all else fails
0 = do not perofrm best best guess lookups.

When an SPF query fails, and then subsequently a trusted forwarder query possibly fails,
libspf will attempt to perform a &quot;best guess&quot; query using a default string which can 
be redefined using the 'spfguess' control file.  The default value exists within libspf,
so creating the control file is only necessary if you wish to change this value.

=======================================================================================

CONTROL FILE:

spfexplanation

value (single line of text)

default: See http://spf.pobox.com/why.html?sender=%{S}&amp;ip=%{I}&amp;receiver=%{xR}

This string (can include macros) is expanded and sent to the client for every result
case excluding pass.  The default value exists within libspf, so creating the control
file is only necessary if you wish to change this value.

=======================================================================================

CONTROL FILE:

spfexplainstate

value (single integer): 

1 (default) = append explanation
0 = do not append explanation

When set to 1, explanations will be automatically printed out after any spf query 
excluding pass.  This information is designed to be informative and helpful to a user
who has just likely had his or her email rejected.  See the above 'spfexplain' to
define your own string to use instead.  The default value exists within libspf, so
creating the control file is only necessary if you wish to change this value.

When set to 0, explanations are not appended.

=======================================================================================

CONTROL FILE:

spftrustedforwarder

value (single line of text)

default: v=spf1 include:spf.trusted-forwarder.org

This string (can include macros) is expanded and is used in the event that a connecting
client's query results in NONE (no SPF record published).  libspf will then (if enabled)
attempt to contact trusted-forwarder.org (default) which is a global whitelisting system
. You can add additional sites, or provide your own.  The default value exists within
libspf, so creating the control file is only necessary if you wish to change this value.

=======================================================================================

CONTROL FILE:

spftrustedstate

value (single integer):

1 (default) = enabled trusted forwarder lookups
0 = no not perform trusted forwarder lookups

When set to 1, libspf will attempt to contact the site contained within that text,
which would be ideally a whitelisting site (anything can really go there, but this
particular file is here specifically to handle larger whitelisting services) that 
would be contacted in the event an SPF query returns NONE.  The default value exists
within libspf, so creating the control file is only necessary if you wish to change 
this value.

=======================================================================================

CONTROL FILE:

spfdebugstate

value (single integer):

6 (default) = enabled full debugging (default is hardcoded in the libSPF source)
0 = no not perform trusted forwarder lookups

When set to anything above 0 this will enable debugging in libSPF (provided that
when you configured libSPF you supplied --enable-debug).  To learn more about how
debugging works in libSPF please read the &quot;Debugging libSPF&quot; PDF or TXT that
accompanied your distribution or see the on-line version at:
http://libspf.org/debugging_libspf.html

It should be noted that Autoconf enables _SPF_DEBUG_LOGFILE by default, and the 
only way to disable this (to get deubgging to show up on STDOUT) is to manually
edit the Makefile and comment out or remove the _SPF_DEBUG_LOGFILE macro leaving
only _SPF_DEBUG.

=======================================================================================


    </pre>
  </body
</html>
Revision:	1.1
Committed:	Tue Nov 13 00:51:34 2007 UTC (18 years, 11 months ago) by root
Content type:	text/html
Branch:	MAIN
CVS Tags:	HEAD
Log Message:	initial import of libspf-1.0.0-p5 from freebsd ports
#	User	Rev	Content
1	root	1.1	<html>
2			<head>
3			<title>README</title>
4			</head>
5
6			<body>
7			<h2>README</h2>
8			<pre>
9
10			File: README
11			Author: James Couzens <jcouzens@codeshare.ca>
12			Desc: README file for working with libSPF and qmail
13			Date: Tue Aug 3 10:01:28 PDT 2004 - Updated
14
15			=======================================================================================
16
17			TCPSERVER GLOBAL VARS:
18
19			SPF_ACTION (control/spfaction)
20			SPF_TARPIT (control/spftarpit)
21			SPF_TARPIT_TIME (control/spftarpittime)
22			SPF_EXPLAIN_STATE (control/spfexplainstate)
23			SPF_TRUSTED_STATE (control/spftrustedstate)
24			SPF_GUESS_STATE (control/spfguesstate)
25			SPF_HEADER_STATE (control/spfheaderstate)
26			SPF_DEBUG_STATE (control/spfdebugstate)
27
28			By setting these in your environment with appropriate values you can nicely alter the
29			behaviour of libspf for individual persons on your network. A great example is by
30			placing SPF_ACTION inside of tcp.smtp and setting it to a 0 for 127.0.0.1 eg:
31
32			127.:allow,RELAYCLIENT="",RBLSMTPD="",SPF_ACTION="0"
33
34			This way 127.0.0.1 never has SPF checks performed on them. I'm sure you get the idea.
35
36			=======================================================================================
37
38			CONTROL FILE:
39
40			spfaction
41
42			Inside this file place a single digit between 0 and 7.
43
44			Below describes the behaviour of these digits:
45
46			0: disabled
47			1: enabled (only prepends headers, and only if spfheaderstate == 1)
48			2: REJECT: fail; ACCEPT: pass, none, softfail, error, netural, unknown;
49			3: REJECT: fail, softfail; ACCEPT: pass, none, error, netural, unknown;
50			4: REJECT: fail, softfail, neutral; ACCEPT: pass, none, error, unknown;
51			5: REJECT: fail, softfail, neutral, none; ACCEPT: pass, error, unknown;
52			6: REJECT: fail, softfail, neutral, none, error; ACCEPT: pass, unknown;
53			7: REJECT: fail, softfail, neutral, none, error, unknown; ACCEPT: pass;
54
55			Chose one of the above error levels that best suits you. Since this is still beta
56			I think 1 is best. Youe mileage may vary.
57
58			=======================================================================================
59
60			CONTROL FILE:
61
62			spftarpit - value (single integer)
63
64			0 (default) = disable tarpitting
65			1 (enabled) = enable tarpitting
66
67			spftarpittime - value (single integer)
68
69			0 = how long to tarpit for (default is 60)
70
71			Tarpitting happens based on the above set spfaction. If the action
72			was set to 2, then upon a softfail the process would sleep x seconds
73			and then call quit (where x is the value of spftarpittime or the
74			default 60)
75
76			I suggest you use this with caution, perhaps only enabling it on
77			FAIL which is something that can only happen when an SPF rule is supplied, and some
78			how the connecting client violates the policy. You have been warned. This could quite
79			EASILY LEAD TO YOUR SERVER BEING DOSSED BY SOME TURD. DO NOT BLAME ME, DEFAULT IS OFF.
80			CONSIDER YOUR SELF WARNED.
81
82			=======================================================================================
83
84			CONTROL FILE:
85
86			spfheaderstate
87
88			value (single integer):
89
90			1 (default) = enabled prepending Received-SPF: headers
91			0 = no not prepend headers
92
93			When set to 1, libspf will pre-pend "Received-SPF:" headers as per the SPF RFC
94			Internet Draft. This are useful for third party applications such as SpamAssassin,
95			and even email clients capable of parsing headers to know where to filter email to.
96
97			=======================================================================================
98
99			CONTROL FILE:
100
101			spfbestguess
102
103			value: (single line of text)
104
105			default: v=spf1 a/24 mx/24 ptr
106
107			This query is looked up in an attempt to make a guess against the user in the event
108			no record is found and the trusted forwarder lookup fails. The default value exists
109			within libspf, so creating the control file is only necessary if you wish to change
110			this value.
111
112			=======================================================================================
113
114			CONTROL FILE:
115
116			spfguessstate
117
118			value (single integer):
119
120			1 (default) = perform best guess lookup when all else fails
121			0 = do not perofrm best best guess lookups.
122
123			When an SPF query fails, and then subsequently a trusted forwarder query possibly fails,
124			libspf will attempt to perform a "best guess" query using a default string which can
125			be redefined using the 'spfguess' control file. The default value exists within libspf,
126			so creating the control file is only necessary if you wish to change this value.
127
128			=======================================================================================
129
130			CONTROL FILE:
131
132			spfexplanation
133
134			value (single line of text)
135
136			default: See http://spf.pobox.com/why.html?sender=%{S}&ip=%{I}&receiver=%{xR}
137
138			This string (can include macros) is expanded and sent to the client for every result
139			case excluding pass. The default value exists within libspf, so creating the control
140			file is only necessary if you wish to change this value.
141
142			=======================================================================================
143
144			CONTROL FILE:
145
146			spfexplainstate
147
148			value (single integer):
149
150			1 (default) = append explanation
151			0 = do not append explanation
152
153			When set to 1, explanations will be automatically printed out after any spf query
154			excluding pass. This information is designed to be informative and helpful to a user
155			who has just likely had his or her email rejected. See the above 'spfexplain' to
156			define your own string to use instead. The default value exists within libspf, so
157			creating the control file is only necessary if you wish to change this value.
158
159			When set to 0, explanations are not appended.
160
161			=======================================================================================
162
163			CONTROL FILE:
164
165			spftrustedforwarder
166
167			value (single line of text)
168
169			default: v=spf1 include:spf.trusted-forwarder.org
170
171			This string (can include macros) is expanded and is used in the event that a connecting
172			client's query results in NONE (no SPF record published). libspf will then (if enabled)
173			attempt to contact trusted-forwarder.org (default) which is a global whitelisting system
174			. You can add additional sites, or provide your own. The default value exists within
175			libspf, so creating the control file is only necessary if you wish to change this value.
176
177			=======================================================================================
178
179			CONTROL FILE:
180
181			spftrustedstate
182
183			value (single integer):
184
185			1 (default) = enabled trusted forwarder lookups
186			0 = no not perform trusted forwarder lookups
187
188			When set to 1, libspf will attempt to contact the site contained within that text,
189			which would be ideally a whitelisting site (anything can really go there, but this
190			particular file is here specifically to handle larger whitelisting services) that
191			would be contacted in the event an SPF query returns NONE. The default value exists
192			within libspf, so creating the control file is only necessary if you wish to change
193			this value.
194
195			=======================================================================================
196
197			CONTROL FILE:
198
199			spfdebugstate
200
201			value (single integer):
202
203			6 (default) = enabled full debugging (default is hardcoded in the libSPF source)
204			0 = no not perform trusted forwarder lookups
205
206			When set to anything above 0 this will enable debugging in libSPF (provided that
207			when you configured libSPF you supplied --enable-debug). To learn more about how
208			debugging works in libSPF please read the "Debugging libSPF" PDF or TXT that
209			accompanied your distribution or see the on-line version at:
210			http://libspf.org/debugging_libspf.html
211
212			It should be noted that Autoconf enables _SPF_DEBUG_LOGFILE by default, and the
213			only way to disable this (to get deubgging to show up on STDOUT) is to manually
214			edit the Makefile and comment out or remove the _SPF_DEBUG_LOGFILE macro leaving
215			only _SPF_DEBUG.
216
217			=======================================================================================
218
219
220			</pre>
221			</body
222			</html>