ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/libspf/docs/qmail/control_files.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

File Contents

# User Rev Content
1 root 1.1 <html>
2     <head>
3     <link rel="stylesheet" type="text/css" href="./libSPF.css">
4     <title>qmail - tcpserver variables defined by libSPF</title>
5     </head>
6     <body>
7    
8     <!-- File: control_vars.txt -->
9     <!-- Author: James Couzens <jcouzens@codeshare.ca> -->
10     <!-- Date: February 4, 2004 -->
11     <!-- Updated: August 3, 2004 - Added spfdebugstate -->
12     <!-- MTA: qmail - http://qmail.org -->
13     <!-- Info: Describes the 'control' variables added to qmail by libSPF -->
14     <!-- in order to interact with libSPF. -->
15    
16     <!-- Start outside table -->
17     <table cellspacing=0 cellpadding=0 border=0 width=600>
18     <tr>
19     <td class=out>
20    
21     <!-- Start inside header table -->
22     <table cellspacing=1 cellpadding=1 border=0 width=100%>
23     <tr>
24     <td class=hdr colspan=2>tcpserver Global Vars:</td>
25     </tr>
26     </table>
27     <!-- End inside header table -->
28    
29     </td>
30     </tr>
31     <tr>
32     <td></td>
33     </tr>
34     <tr>
35     <td class=out>
36    
37     <!-- Start inside control vars tabel -->
38     <table cellpadding=4 cellspacing=1 border=0 width=100%>
39     <tr>
40     <td>&nbsp;<b>control/<a href=#spfaction>spfaction</a></b>&nbsp;</td>
41     <td>&nbsp;Type of action to take based on SPF result</td>
42     </tr>
43     <tr>
44     <td>&nbsp;<b>control/<a href=#spftarpit>spftarpit</a></b>&nbsp;</td>
45     <td>&nbsp;Enable/Disable tarpitting</td>
46     </tr>
47     <tr>
48     <td>&nbsp;<b>control/<a href=#spftarpittime>spftarpittime</a></b>&nbsp;</td>
49     <td>&nbsp;How long to tarpit for</td>
50     </tr>
51     <tr>
52     <td>&nbsp;<b>control/<a href=#spfexplainstate>spfexplainstate</a></b>&nbsp;</td>
53     <td>&nbsp;Enable/Disable 'SPF Explanations'</td>
54     </tr>
55     <tr>
56     <td>&nbsp;<b>control/<a href=#spfexplanation>spfexplanation</a></b>&nbsp;</td>
57     <td>&nbsp;SPF Explanation to use</td>
58     </tr>
59     <tr>
60     <td>&nbsp;<b>control/<a href=#spftrustedstate>spftrustedstate</a></b>&nbsp;</td>
61     <td>&nbsp;Enable/Disable 'Trusted Forwarder' mode</td>
62     </tr>
63     <tr>
64     <td>&nbsp;<b>control/<a href=#spftrustedforwarder>spftrustedforwarder</a></b>&nbsp;</td>
65     <td>&nbsp;SPF Query to use during Trusted Forwarder mode</td>
66     </tr>
67     <tr>
68     <td>&nbsp;<b>control/<a href=#spfguessstate>spfguesstate</a></b>&nbsp;</td>
69     <td>&nbsp;Enable/Disable 'Best Guess' support</td>
70     </tr>
71     <tr>
72     <td>&nbsp;<b>control/<a href=#spfbestguess>spfbestguess</a></b>&nbsp;</td>
73     <td>&nbsp;SPF Query to use during Best Guess mode</td>
74     </tr>
75     <tr>
76     <td>&nbsp;<b>control/<a href=#spfheaderstate>spfheaderstate</a></b>&nbsp;</td>
77     <td>&nbsp;Enable/Disable 'Received-SPF:' header tagging</td>
78     </tr>
79     <tr>
80     <td>&nbsp;<b>control/<a href=#spfdebugstate>spfdebugstate</a></b>&nbsp;</td>
81     <td>&nbsp;Enable/Disable libSPF debug logging (/var/log/spf.log)</td>
82     </tr>
83     </table>
84     <!-- End inside control vars table -->
85    
86     </td>
87     </tr>
88     <tr>
89     <td><br></td>
90     </tr>
91     <tr>
92     <td class=out>
93    
94     <!-- Start inside spfaction table -->
95     <table cellspacing=1 cellpadding=4 border=0 width=100%>
96     <tr><a name=spfaction></A>
97     <td class=example>spfaction</td>
98     </tr>
99     <tr>
100     <td>
101     <b>Description:</b>&nbsp;Define how to react to various SPF results<br>
102     <br>
103     <b>Contents:</b>&nbsp;Inside this file place a single digit between 0 and 7.<br>
104     <br>
105     <b>Type:</b>&nbsp;Integer<br>
106     <b>Default:</b>&nbsp;1 (enabled)<br>
107     <br>
108     Below describes the behaviour of these digits:<br>
109     <br>
110     <b>0</b>: disabled<br>
111     <b>1</b>: enabled (only prepends headers, and only if spfheaderstate == 1)<br>
112     <b>2</b>: REJECT: fail; ACCEPT: pass, none, softfail, error, netural, unknown;<br>
113     <b>3</b>: REJECT: fail, softfail; ACCEPT: pass, none, error, netural, unknown;<br>
114     <b>4</b>: REJECT: fail, softfail, neutral; ACCEPT: pass, none, error, unknown;<br>
115     <b>5</b>: REJECT: fail, softfail, neutral, none; ACCEPT: pass, error, unknown;<br>
116     <b>6</b>: REJECT: fail, softfail, neutral, none, error; ACCEPT: pass, unknown;<br>
117     <b>7</b>: REJECT: fail, softfail, neutral, none, error, unknown; ACCEPT: pass;<br>
118     <br>
119     </td>
120     </tr>
121     <tr>
122     <td class=hdr>
123    
124     <table cellpadding=1 cellspacing=1 border=1 width=100%>
125     <tr>
126     <td class=example>
127     Default: 1 (enabled)
128     </td>
129     </tr>
130     </table>
131    
132     </td>
133     </tr>
134     <tr>
135     <td class=hdr>
136     Running higher than 2 or 3 will definitely result in a loss of email.
137     Consult the Adoption role at http://spftools.net and see the number of
138     SPF records that are parsed incorrectly, so be careful.
139     </td>
140     </tr>
141     </table>
142     <!-- End inside spfaction table -->
143    
144     </td>
145     </tr>
146     <tr>
147     <td><br></td>
148     </tr>
149     <tr>
150     <td class=out>
151    
152     <!-- Start inside spftarpit table -->
153     <table cellspacing=1 cellpadding=4 border=0 width=100%>
154     <tr><a name=spftarpit>
155     <td class=example>spftarpit</td>
156     </tr>
157     <tr>
158     <td>
159     <b>Description:</b>&nbsp; Tarpit or 'latch-on' to a client you don't like<br>
160     <br>
161     0 (default) = disable tarpitting<br>
162     1 (enabled) = enable tarpitting<br>
163     <br>
164     <b>Type:</b>&nbsp;Integer (time in seconds)<br>
165     <b>Default:</b>&nbsp;0 (off)<br>
166     <br>
167     Tarpitting happens based on the above set spfaction. If the action
168     was set to 2, then upon a softfail the process would sleep x seconds
169     and then call quit (where x is the value of spftarpittime or the
170     default 60)<br>
171     <br>
172     </td>
173     </tr>
174     <tr>
175     <td class=hdr>
176    
177     <table cellpadding=1 cellspacing=1 border=1 width=100%>
178     <tr>
179     <td class=example>
180     Default: 0 (off)
181     </td>
182     </tr>
183     </table>
184    
185     </td>
186     </tr>
187     <tr>
188     <td class=hdr>
189     I suggest you use this with caution, perhaps only enabling it on
190     FAIL which is something that can only happen when an SPF rule is
191     supplied, and some how the connecting client violates the policy.
192     You have been warned. This could quite EASILY LEAD TO YOUR SERVER
193     BEING DOSSED BY SOME TURD. DO NOT BLAME ME, DEFAULT IS OFF.
194     CONSIDER YOUR SELF WARNED.
195     </td>
196     </tr>
197     </table>
198     <!-- End inside spftarpit table -->
199    
200     </td>
201     </tr>
202     <tr>
203     <td><br></td>
204     </tr>
205     <tr>
206     <td class=out>
207    
208     <!-- Start inside spftarpittime table -->
209     <table cellspacing=1 cellpadding=4 border=0 width=100%>
210     <tr><a name=spftarpittime>
211     <td class=example>spftarpittime</td>
212     </tr>
213     <tr>
214     <td>
215     <b>Description:</b>&nbsp; How long to tarpit a client<br>
216     <b>Type:</b>&nbsp;Integer (time in seconds)<br>
217     <br>
218     </td>
219     </tr>
220     <tr>
221     <td class=hdr>
222    
223     <table cellpadding=1 cellspacing=1 border=1 width=100%>
224     <tr>
225     <td class=example>
226     Default: 60 (seconds)
227     </td>
228     </tr>
229     </table>
230    
231     </td>
232     </tr>
233     <tr>
234     <td class=hdr>
235     Not too short, or its pointless, but not too long or you'll be clientless
236     </td>
237     </tr>
238     </table>
239     <!-- End inside spftarpittime table -->
240    
241     </td>
242     </tr>
243     <tr>
244     <td><br></td>
245     </tr>
246     <tr>
247     <td class=out>
248    
249     <!-- Start inside spfexplainstate table -->
250     <table cellspacing=1 cellpadding=4 border=0 width=100%>
251     <tr><a name=spfexplainstate>
252     <td class=example>spfexplainstate</td>
253     </tr>
254     <tr>
255     <td>
256     <b>Description:</b>&nbsp; Enable or Disable giving of 'SPF Explanations'<br>
257     <br>
258     <b>Type:</b>&nbsp;Integer<br>
259     <b>Default:</b>&nbsp;0 (off)<br>
260     <br>
261     When set to 1, explanations will be automatically printed out after any SPF
262     query excluding SPF_PASS. This information is designed to be informative and
263     helpful to a user who has just likely had his or her email rejected. See the
264     above 'spfexplain' to define your own string to use instead. The default value
265     exists within libSPF, so creating the control file is only necessary if you
266     wish to change this value.<br>
267     <br>
268     </td>
269     </tr>
270     <tr>
271     <td class=hdr>
272    
273     <table cellpadding=1 cellspacing=1 border=1 width=100%>
274     <tr>
275     <td class=example>
276     Default: 0 (off)
277     </td>
278     </tr>
279     </table>
280    
281     </td>
282     </tr>
283     <tr>
284     <td class=hdr>When set to 0, explanations are not appended.
285     </td>
286     </tr>
287     </table>
288     <!-- End inside spfexplainstate table -->
289    
290     </td>
291     </tr>
292     <tr>
293     <td><br></td>
294     </tr>
295     <tr>
296     <td class=out>
297    
298     <!-- Start inside spfexplanation table -->
299     <table cellspacing=1 cellpadding=4 border=0 width=100%>
300     <tr><a name=spfexplanation>
301     <td class=example>spfexplanation</td>
302     </tr>
303     <tr>
304     <td>
305     <b>Description:</b>&nbsp; Explanation to provide client in any event result but SPF_PASS<br>
306     <br>
307     <b>Type:</b>&nbsp;String<br>
308     <br>
309     This string (can include macros) is expanded and sent to the client for every
310     result case excluding pass. The default value exists within libspf, so creating
311     the control file is only necessary if you wish to change this
312     value.<br>
313     <br>
314     </td>
315     </tr>
316     <tr>
317     <td class=hdr>
318    
319     <table cellpadding=1 cellspacing=1 border=1 width=100%>
320     <tr>
321     <td class=example>
322     Default: See http://spf.pobox.com/why.html?sender=%{S}&ip=%{I}&receiver=%{xR}
323     </td>
324     </tr>
325     </table>
326    
327     </td>
328     </tr>
329     <tr>
330     <td class=hdr>When set to 0, explanations are not appended.
331     </td>
332     </tr>
333     </table>
334     <!-- End inside spfexplanation table -->
335    
336     </td>
337     </tr>
338     <tr>
339     <td><br></td>
340     </tr>
341     <tr>
342     <td class=out>
343    
344     <!-- Start inside spftrustedstate table -->
345     <table cellspacing=1 cellpadding=4 border=0 width=100%>
346     <tr><a name=spftrustedstate>
347     <td class=example>spftrustedstate</td>
348     </tr>
349     <tr>
350     <td>
351     <b>Description:</b>&nbsp; Enable or Disable SPF Trusted Forwarder mode<br>
352     <br>
353     <b>Type:</b>&nbsp;Integer<br>
354     <br>
355     When set to 1, libspf will attempt to contact the site contained within that text,
356     which would be ideally a whitelisting site (anything can really go there, but this
357     particular file is here specifically to handle larger whitelisting services) that
358     would be contacted in the event an SPF query returns NONE. The default value exists
359     within libspf, so creating the control file is only necessary if you wish to change
360     this value.<br>
361     <br>
362     </td>
363     </tr>
364     <tr>
365     <td class=hdr>
366    
367     <table cellpadding=1 cellspacing=1 border=1 width=100%>
368     <tr>
369     <td class=example>
370     Default: 0 (off)
371     </td>
372     </tr>
373     </table>
374    
375     </td>
376     </tr>
377     <tr>
378     <td class=hdr>
379     This is a great way to get around any hosts who refuse to publish! Simply
380     publish for them in your own local DNS server, or you can make use of the the real
381     "Trusted Forwarder" service which has many well known "non-SPF-publishing" sites
382     already. http://trusted-forwarder.org
383     </td>
384     </tr>
385     </table>
386     <!-- End inside spftrustedstate table -->
387    
388     </td>
389     </tr>
390     <tr>
391     <td><br></td>
392     </tr>
393     <tr>
394     <td class=out>
395    
396     <!-- Start inside spftrustedforwarder table -->
397     <table cellspacing=1 cellpadding=4 border=0 width=100%>
398     <tr><a name=spftrustedforwarder>
399     <td class=example>spftrustedforwarder</td>
400     </tr>
401     <tr>
402     <td>
403     <b>Description:</b>&nbsp; Define your Trusted Forwarder SPF Query<br>
404     <br>
405     <b>Type:</b>&nbsp;String<br>
406     <br>
407     This string (can include macros) is expanded and is used in the event that a
408     connecting client's query results in NONE (no SPF record published). libSPF
409     will then (if enabled) attempt to contact trusted-forwarder.org (default) which
410     is a global whitelisting system. You can add additional sites, or provide your
411     own. The default value exists withinlibSPF, so creating the control file is
412     only necessary if you wish to change this value<br>
413     <br>
414     </td>
415     </tr>
416     <tr>
417     <td class=hdr>
418    
419     <table cellpadding=1 cellspacing=1 border=1 width=100%>
420     <tr>
421     <td class=example>
422     Default: v=spf1 include:spf.trusted-forwarder.org
423     </td>
424     </tr>
425     </table>
426    
427     </td>
428     </tr>
429     <tr>
430     <td class=hdr>
431     Its VERY important that this string end with a SPACE at the end!
432     Failure to do so will likely result in parse failures.
433     </td>
434     </tr>
435     </table>
436     <!-- End inside spftrustedforwarder table -->
437    
438     </td>
439     </tr>
440     <tr>
441     <td><br></td>
442     </tr>
443     <tr>
444     <td class=out>
445    
446     <!-- Start inside spfguessstate table -->
447     <table cellspacing=1 cellpadding=4 border=0 width=100%>
448     <tr><a name=spfguessstate>
449     <td class=example>spfguessstate</td>
450     </tr>
451     <tr>
452     <td>
453     <b>Description:</b>&nbsp; Enable or Disable SPF Best Guess mode<br>
454     <br>
455     <b>Type:</b>&nbsp;Integer<br>
456     <br>
457     When an SPF query fails, and then subsequently a trusted forwarder query possibly fails,
458     libspf will attempt to perform a "best guess" query using a default string which can
459     be redefined using the 'spfguess' control file. The default value exists within libspf,
460     so creating the control file is only necessary if you wish to change
461     this value.<br>
462     <br>
463     </td>
464     </tr>
465     <tr>
466     <td class=hdr>
467    
468     <table cellpadding=1 cellspacing=1 border=1 width=100%>
469     <tr>
470     <td class=example>
471     Default: 0 (off)
472     </td>
473     </tr>
474     </table>
475    
476     </td>
477     </tr>
478     <tr>
479     <td class=hdr>
480     </td>
481     </tr>
482     </table>
483     <!-- End inside spfguessstate table -->
484    
485     </td>
486     </tr>
487     <tr>
488     <td><br></td>
489     </tr>
490     <tr>
491     <td class=out>
492    
493     <!-- Start inside spfbestguess table -->
494     <table cellspacing=1 cellpadding=4 border=0 width=100%>
495     <tr><a name=spfbuestguess>
496     <td class=example>spfbestguess</td>
497     </tr>
498     <tr>
499     <td>
500     <b>Description:</b>&nbsp; Define your Best Guess SPF Query<br>
501     <br>
502     <b>Type:</b>&nbsp;String<br>
503     <br>
504     This query is looked up in an attempt to make a guess against the user in the event
505     no record is found and the trusted forwarder lookup fails. The default value exists
506     within libspf, so creating the control file is only necessary if you wish to change
507     this value.<br>
508     <br>
509     </td>
510     </tr>
511     <tr>
512     <td class=hdr>
513    
514     <table cellpadding=1 cellspacing=1 border=1 width=100%>
515     <tr>
516     <td class=example>
517     Default: v=spf1 a/24 mx/24 ptr
518     </td>
519     </tr>
520     </table>
521    
522     </td>
523     </tr>
524     <tr>
525     <td class=hdr>
526     Its VERY important that this string end with a SPACE at the end!
527     Failure to do so will likely result in parse failures.
528     </td>
529     </tr>
530     </table>
531     <!-- End inside spfbestguess table -->
532    
533     </td>
534     </tr>
535     <tr>
536     <td><br></td>
537     </tr>
538     <tr>
539     <td class=out>
540    
541     <!-- Start inside spfheaderstate table -->
542     <table cellspacing=1 cellpadding=4 border=0 width=100%>
543     <tr><a name=spfheaderstate>
544     <td class=example>spfheaderstate</td>
545     </tr>
546     <tr>
547     <td>
548     <b>Description:</b>&nbsp; Enable or Disable Received-SPF: header prepending<br>
549     <br>
550     <b>Type:</b>&nbsp;Integer<br>
551     <br>
552     When set to 1, libspf will pre-pend "Received-SPF:" headers as per the SPF RFC
553     Internet Draft. This are useful for third party applications such as SpamAssassin,
554     and even email clients capable of parsing headers to know where to
555     filter email to.<br>
556     <br>
557     </td>
558     </tr>
559     <tr>
560     <td class=hdr>
561    
562     <table cellpadding=1 cellspacing=1 border=1 width=100%>
563     <tr>
564     <td class=example>
565     Default: 1 (on)
566     </td>
567     </tr>
568     </table>
569    
570     </td>
571     </tr>
572     <tr>
573     <td class=hdr>
574     You should leave this ON. Failure to pre-pend Received-SPF: headers will nullify
575     any possible benefit had through 3rd party Anti-Spam implementations such as SpamAssassin
576     which will look at headers and evaluate them based on their content. It should be noted
577     however, that SpamAssassin (unless someone intentionally does this) will only
578     consider FAIL messages, because to do otherwise would be stupid. Spammers would
579     simply tag their own messages with Received-SPF: pass messages :-)
580     <br>
581     </td>
582     </tr>
583     </table>
584     <!-- End inside spfheaderstate table -->
585    
586     </td>
587     </tr>
588     <tr>
589     <td><br></td>
590     </tr>
591     <tr>
592     <td class=out>
593    
594     <!-- Start inside spfdebugstate table -->
595     <table cellspacing=1 cellpadding=4 border=0 width=100%>
596     <tr><a name=spfdebugstate>
597     <td class=example>spfdebugstate</td>
598     </tr>
599     <tr>
600     <td>
601     <b>Description:</b>&nbsp; Enable or Disable libSPF debugging<br>
602     <br>
603     <b>Type:</b>&nbsp;Integer<br>
604     <br>
605     When set to anything above 0 this will enable debugging in libSPF (provided that
606     when you configured libSPF you supplied --enable-debug). To learn more about how
607     debugging works in libSPF please read the "Debugging libSPF" PDF or TXT that
608     accompanied your distribution or see the on-line version at:
609     <a href=http://libspf.org/debugging_libspf.html target=_new>
610     http://libspf.org/debugging_libspf.html</a>.<br>
611     <br>
612     </td>
613     </tr>
614     <tr>
615     <td class=hdr>
616    
617     <table cellpadding=1 cellspacing=1 border=1 width=100%>
618     <tr>
619     <td class=example>
620     Default: 0 (off)
621     </td>
622     </tr>
623     </table>
624    
625     </td>
626     </tr>
627     <tr>
628     <td class=hdr>
629     It should be noted that Autoconf enables _SPF_DEBUG_LOGFILE by default, and the
630     only way to disable this (to get deubgging to show up on STDOUT) is to manually
631     edit the Makefile and comment out or remove the _SPF_DEBUG_LOGFILE macro leaving
632     only _SPF_DEBUG.
633     </td>
634     </tr>
635     </table>
636     <!-- End inside spfdebugstate table -->
637    
638     </td>
639     </tr>
640     </table>
641     <!-- End outside table -->
642    
643     <br>
644     <br>
645    
646     <!-- Start footer table -->
647     <table cellpadding=0 cellspacing=0 border=0 width=600>
648     <tr>
649     <td><p class=footer align=center>
650     (c) 2004 James Couzens (jcouzens@codeshare.ca)
651     </p>
652     </td>
653     </tr>
654     </table>
655     <!-- End footer table -->
656    
657     <br>
658    
659     </body>
660     </html>