Subversion Repositories

?revision_form?Rev ?revision_input??revision_submit??revision_endform?

Rev 19 | Go to most recent revision | Only display areas with differences | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 19 Rev 23
1
.\"     Title: SPFQUERY
1
.\"     Title: SPFQUERY
2
.\"    Author: Magnus Holmgren <magnus@kibibyte.se>
2
.\"    Author: Magnus Holmgren <magnus@kibibyte.se>
3
.\"      Date: 2007-09-06
3
.\"      Date: 2007-09-06
4
.\"    Manual: libspf2 manuals for Debian
4
.\"    Manual: libspf2 manuals for Debian
5
.\"    Source: libspf2 1.2.5
5
.\"    Source: libspf2 1.2.5
6
.\"
6
.\"
7
.TH "SPFQUERY" "1" "2007-09-06" "libspf2 1.2.5" "libspf2 manuals for Debian"
7
.TH "SPFQUERY" "1" "2007-09-06" "libspf2 1.2.5" "libspf2 manuals for Debian"
8
.\" disable hyphenation
8
.\" disable hyphenation
9
.nh
9
.nh
10
.SH NAME
10
.SH NAME
11
spfquery, spfquery.libspf2 \- checks if an IP address is an SPF-authorized SMTP sender for a domain.
11
spfquery, spfquery.libspf2 \- checks if an IP address is an SPF-authorized SMTP sender for a domain.
12
.SH SYNOPSIS
12
.SH SYNOPSIS
13
.ad l
13
.ad l
14
.HP 9
14
.HP 9
15
.B spfquery
15
.B spfquery
16
.RB { \-i | \-\-ip }
16
.RB { \-i | \-\-ip }
17
.I ip\-address
17
.I ip\-address
18
.RB { -s | \-\-sender }
18
.RB { -s | \-\-sender }
19
.RI [ local-part \fB@\fP] domain
19
.RI [ local-part \fB@\fP] domain
20
.RB [{ \-h | \-\-helo } 
20
.RB [{ \-h | \-\-helo } 
21
.IR domain-name ]
21
.IR domain-name ]
22
.RB [ \-\-rcpt\-to
22
.RB [ \-\-rcpt\-to
23
.IR email-address(es) ]
23
.IR email-address(es) ]
24
.RI [ CONTROL-OPTIONS ]
24
.RI [ CONTROL-OPTIONS ]
25
.HP 9
25
.HP 9
26
.B spfquery
26
.B spfquery
27
.RB { \-f | \-\-file }
27
.RB { \-f | \-\-file }
28
.IR datafile " [" CONTROL-OPTIONS ] 
28
.IR datafile " [" CONTROL-OPTIONS ] 
29
.HP 9
29
.HP 9
30
.B spfquery
30
.B spfquery
31
.RB { \-\-help | \-v | \-\-version }
31
.RB { \-\-help | \-v | \-\-version }
32
.ad b
32
.ad b
33
.SH DESCRIPTION
33
.SH DESCRIPTION
34
This manual page documents briefly the
34
This manual page documents briefly the
35
\fBspfquery\fR
35
\fBspfquery\fR
36
command. It was written for the
36
command. It was written for the
37
Debian\*[R] distribution because the original program does not have a manual page.
37
Debian\*[R] distribution because the original program does not have a manual page.
38
.PP
38
.PP
39
\fBspfquery\fR performs Sender Policy Framework (SPF) authorization
39
\fBspfquery\fR performs Sender Policy Framework (SPF) authorization
40
checks based on the command-line arguments or data given in a file or
40
checks based on the command-line arguments or data given in a file or
41
on standard input. For information on SPF see http://www.openspf.org.
41
on standard input. For information on SPF see http://www.openspf.org.
42
.
42
.
43
.SH OPTIONS
43
.SH OPTIONS
44
Options are divided into two groups: Data options, which must be
44
Options are divided into two groups: Data options, which must be
45
given, though just enough of them to specify a query; and control
45
given, though just enough of them to specify a query; and control
46
options, which are optional and control the local policy, behaviour
46
options, which are optional and control the local policy, behaviour
47
and output format of spfquery.
47
and output format of spfquery.
48
.PP
48
.PP
49
This programs follows the GNU \fBgetopt_long_only\fR(3) command line
49
This programs follows the GNU \fBgetopt_long_only\fR(3) command line
50
syntax: Long options can be given with one or two dashes and can be
50
syntax: Long options can be given with one or two dashes and can be
51
abbreviated to a prefix long enough to be non-ambiguous. If an option
51
abbreviated to a prefix long enough to be non-ambiguous. If an option
52
starting with a single dash doesn't match a long option, it is taken
52
starting with a single dash doesn't match a long option, it is taken
53
as a short option with a following parameter, if applicable. An equals
53
as a short option with a following parameter, if applicable. An equals
54
sign between the option name and the parameter is optional for both
54
sign between the option name and the parameter is optional for both
55
short and long options.
55
short and long options.
56
.SS Data options
56
.SS Data options
57
The
57
The
58
\fB\-\-file\fR option conflicts with all the other data options. The
58
\fB\-\-file\fR option conflicts with all the other data options. The
59
\fB\-\-helo\fR and \fB\-\-rcpt\-to\fR are optional.
59
\fB\-\-helo\fR and \fB\-\-rcpt\-to\fR are optional.
60
.TP
60
.TP
61
\fB\-f\fR, \fB\-\-file\fR \fIfilename\fR
61
\fB\-f\fR, \fB\-\-file\fR \fIfilename\fR
62
Read SPF data from \fIfilename\fR. Specify \(lq-\(rq to read from standard input.
62
Read SPF data from \fIfilename\fR. Specify \(lq-\(rq to read from standard input.
63
.sp
63
.sp
64
The file should consist of one line per query, each query line consisting of the IP address, sender adress, and optional HELO string, separated by spaces.
64
The file should consist of one line per query, each query line consisting of the IP address, sender adress, and optional HELO string, separated by spaces.
65
.sp
65
.sp
66
\fBNote\fP
66
\fBNote\fP
67
Local parts containing spaces are currently not supported.
67
Local parts containing spaces are currently not supported.
68
.TP
68
.TP
69
\fB\-i\fP, \fB\-\-ip\fP \fIip-address\fP
69
\fB\-i\fP, \fB\-\-ip\fP \fIip-address\fP
70
Specify the IP address of the remote host that is delivering the mail.
70
Specify the IP address of the remote host that is delivering the mail.
71
.TP
71
.TP
72
\fB\-s\fP, \fB\-\-sender\fP [\fIlocal-part\fP\fB@\fP]\fIdomain\fP
72
\fB\-s\fP, \fB\-\-sender\fP [\fIlocal-part\fP\fB@\fP]\fIdomain\fP
73
Specify the email address that was used as the envelope sender. If no
73
Specify the email address that was used as the envelope sender. If no
74
username (local part) is given, \(lqpostmaster\(rq will be assumed.
74
username (local part) is given, \(lqpostmaster\(rq will be assumed.
75
.TP
75
.TP
76
\fB\-h\fP, \fB\-\-helo\fP \fIdomain-name\fP
76
\fB\-h\fP, \fB\-\-helo\fP \fIdomain-name\fP
77
Specify that \fIdomain-name\fP was provided in the SMTP HELO (or EHLO) command.
77
Specify that \fIdomain-name\fP was provided in the SMTP HELO (or EHLO) command.
78
.TP
78
.TP
79
\fB\-r\fP, \fB\-\-rcpt-to\fP \fIrcpt-address\fP[,\fIrcpt-address\fP,...]
79
\fB\-r\fP, \fB\-\-rcpt-to\fP \fIrcpt-address\fP[,\fIrcpt-address\fP,...]
80
Specify the recipients as comma-separated list. Any secondary mail exchangers of all
80
Specify the recipients as comma-separated list. Any secondary mail exchangers of all
81
recipient domains are automatically authorized.
81
recipient domains are automatically authorized.
82
.
82
.
83
.SS Control options
83
.SS Control options
84
.TP
84
.TP
85
\fB\-d\fP, \fB\-\-debug\fP[\fB=\fP\fIlevel\fP]
85
\fB\-d\fP, \fB\-\-debug\fP[\fB=\fP\fIlevel\fP]
86
Turn on debugging output.
86
Turn on debugging output.
87
.TP
87
.TP
88
\fB\-l\fP, \fB\-\-local\fP \fIspf\-terms\fP
88
\fB\-l\fP, \fB\-\-local\fP \fIspf\-terms\fP
89
Test against \fIspf\-terms\fR before the final (implicit or explicit)
89
Test against \fIspf\-terms\fR before the final (implicit or explicit)
90
\(lqall\(rq in an SPF record. This can be used to implement a local policy for whitelisting.
90
\(lqall\(rq in an SPF record. This can be used to implement a local policy for whitelisting.
91
.TP
91
.TP
92
\fB\-t, \fB\-\-trusted\fR [\fB1\fR]
92
\fB\-t, \fB\-\-trusted\fR [\fB1\fR]
93
Check the sender domain with trusted\-forwarder.org.
93
Check the sender domain with trusted\-forwarder.org.
94
\fBThis is a non\-standard feature.\fR
94
\fBThis is a non\-standard feature.\fR
95
.TP
95
.TP
96
\fB\-t\fP \fB0\fP, \fB\-\-trusted\fR \fB0\fP
96
\fB\-t\fP \fB0\fP, \fB\-\-trusted\fR \fB0\fP
97
Do not check the sender domain with trusted\-forwarder.org. This is the default.
97
Do not check the sender domain with trusted\-forwarder.org. This is the default.
98
.TP
98
.TP
99
\fB\-g\fP, \fB\-\-guess\fP \fIspf-mechanisms\fP
99
\fB\-g\fP, \fB\-\-guess\fP \fIspf-mechanisms\fP
100
Test the sender domain against \fIspf\-mechanisms\fP if the domain has no SPF record.
100
Test the sender domain against \fIspf\-mechanisms\fP if the domain has no SPF record.
101
.TP
101
.TP
102
\fB\-e\fP, \fB\-\-default\-explanation\fP \fIstring\fP
102
\fB\-e\fP, \fB\-\-default\-explanation\fP \fIstring\fP
103
Default explanation string to use if the SPF record does not specify an expla\%nation string itself.
103
Default explanation string to use if the SPF record does not specify an expla\%nation string itself.
104
.TP
104
.TP
105
\fB\-m\fP, \fB\-\-max\-lookup\fP \fInumber\fP
105
\fB\-m\fP, \fB\-\-max\-lookup\fP \fInumber\fP
106
Maximum number of DNS lookups to allow.
106
Maximum number of DNS lookups to allow.
107
.TP
107
.TP
108
\fB\-c\fP, \fB\-\-sanitize\fP [\fB0\fP|\fB1\fP]
108
\fB\-c\fP, \fB\-\-sanitize\fP [\fB0\fP|\fB1\fP]
109
Do [not] sanitize the output by condensing conse\%cutive white\%space
109
Do [not] sanitize the output by condensing conse\%cutive white\%space
110
into a single space and replacing non-printable characters with
110
into a single space and replacing non-printable characters with
111
question marks. Enabled by default.
111
question marks. Enabled by default.
112
.TP
112
.TP
113
\fB\-n\fP, \fB\-\-name\fP \fIhostname\fP
113
\fB\-n\fP, \fB\-\-name\fP \fIhostname\fP
114
Use
114
Use
115
\fIhostname\fP
115
\fIhostname\fP
116
as the name of the local system instead of
116
as the name of the local system instead of
117
\(lqspfquery\(rq
117
\(lqspfquery\(rq
118
(the name is used in the output).
118
(the name is used in the output).
119
.TP
119
.TP
120
\fB\-k\fP, \fB\-\-keep\-comments\fP
120
\fB\-k\fP, \fB\-\-keep\-comments\fP
121
Print comments found when reading from a file.
121
Print comments found when reading from a file.
122
.TP
122
.TP
123
\fB\-a\fP, \fB\-\-override\fP \fI...\fP
123
\fB\-a\fP, \fB\-\-override\fP \fI...\fP
124
.TP
124
.TP
125
\fB\-z\fP, \fB\-\-fallback\fP \fI...\fP
125
\fB\-z\fP, \fB\-\-fallback\fP \fI...\fP
126
Provide override and fallback SPF records for certain domains.
126
Provide override and fallback SPF records for certain domains.
127
\fBNot implemented yet.\fP
127
\fBNot implemented yet.\fP
128
\fBspfquery\fP
128
\fBspfquery\fP
129
would act as if the speci\%fied records were present before and after any existing record, respectively, of those domains.
129
would act as if the speci\%fied records were present before and after any existing record, respectively, of those domains.
130
.TP
130
.TP
131
\fB\-\-help\fP
131
\fB\-\-help\fP
132
Show summary of options.
132
Show summary of options.
133
.TP
133
.TP
134
\fB\-v\fP, \fB\-\-version\fP
134
\fB\-v\fP, \fB\-\-version\fP
135
Show version of program.
135
Show version of program.
136
.SH DIAGNOSTICS
136
.SH DIAGNOSTICS
137
The output ordinarily consists of four lines:
137
The output ordinarily consists of four lines:
138
.IP 1. 4
138
.IP 1. 4
139
the \fIresult code\fP;
139
the \fIresult code\fP;
140
.IP 2. 4
140
.IP 2. 4
141
the \fIexplanation\fP, suitable for use in an SMTP response message, empty
141
the \fIexplanation\fP, suitable for use in an SMTP response message, empty
142
except when a rejection (permanent or temporary) makes sense;
142
except when a rejection (permanent or temporary) makes sense;
143
.IP 3. 4
143
.IP 3. 4
144
the header comment on its own;
144
the header comment on its own;
145
.IP 4. 4
145
.IP 4. 4
146
the Received\-SPF header field as defined in RFC 4408 section 7,
146
the Received\-SPF header field as defined in RFC 4408 section 7,
147
incorporating the header comment.
147
incorporating the header comment.
148
.PP
148
.PP
149
If errors (including no SPF record found!) occur during processing, 
149
If errors (including no SPF record found!) occur during processing, 
150
one or more error blocks will be prepended.
150
one or more error blocks will be prepended.
151
These start with \(lqStartError\(lq and end with \(lqEndError\(lq.
151
These start with \(lqStartError\(lq and end with \(lqEndError\(lq.
152
.PP
152
.PP
153
The result codes and their corresponding exit codes are as follows:
153
The result codes and their corresponding exit codes are as follows:
154
.TP
154
.TP
155
.B 1 \(en neutral
155
.B 1 \(en neutral
156
The sender domain explicitly makes no assertion about the \fIip-address\fP.
156
The sender domain explicitly makes no assertion about the \fIip-address\fP.
157
This result must be interpreted exactly as if no SPF record at all existed.
157
This result must be interpreted exactly as if no SPF record at all existed.
158
.TP
158
.TP
159
.B 2 \(en pass
159
.B 2 \(en pass
160
The \fIip-address\fP is authorized to send mail for the sender domain.
160
The \fIip-address\fP is authorized to send mail for the sender domain.
161
.TP
161
.TP
162
.B 3 \(en fail
162
.B 3 \(en fail
163
The \fIip-address\fP is \fBunauthorized\fP to send mail for the sender domain.
163
The \fIip-address\fP is \fBunauthorized\fP to send mail for the sender domain.
164
.TP
164
.TP
165
.B 4 \(en softfail
165
.B 4 \(en softfail
166
The \fIip-address\fP is not authorized to send mail for the sender domain, but
166
The \fIip-address\fP is not authorized to send mail for the sender domain, but
167
the sender domain cannot or does not wish to make a strong assertion that no such mail can
167
the sender domain cannot or does not wish to make a strong assertion that no such mail can
168
ever come from it.
168
ever come from it.
169
.TP
169
.TP
170
.B 5 \(en none
170
.B 5 \(en none
171
No SPF record was found.
171
No SPF record was found.
172
.TP
172
.TP
173
.BR "6 \(en error" " (temporary)"
173
.BR "6 \(en error" " (temporary)"
174
A transient error occurred (e.g. failure to reach a DNS server), preventing a
174
A transient error occurred (e.g. failure to reach a DNS server), preventing a
175
result from being reached.
175
result from being reached.
176
.TP
176
.TP
177
.BR "7 \(en unknown" " (permanent error)"
177
.BR "7 \(en unknown" " (permanent error)"
178
One or more SPF records could not be interpreted.
178
One or more SPF records could not be interpreted.
179
.SH EXAMPLES
179
.SH EXAMPLES
180
.nf
180
.nf
181
spfquery \-ip=11.22.33.44 \-sender=user@aol.com \-helo=spammer.tld
181
spfquery \-ip=11.22.33.44 \-sender=user@aol.com \-helo=spammer.tld
182
spfquery \-f test_data
182
spfquery \-f test_data
183
echo "127.0.0.1 myname@mydomain.com helohost.com" | spfquery \-f \-
183
echo "127.0.0.1 myname@mydomain.com helohost.com" | spfquery \-f \-
184
.fi
184
.fi
185
.SH SEE ALSO
185
.SH SEE ALSO
186
\fBspftest\fR(1), \fBspfd\fR(8)
186
\fBspftest\fR(1), \fBspfd\fR(8)
187
.SH AUTHOR
187
.SH AUTHOR
188
\fBspfquery\fP was written by Wayne Schlitt.
188
\fBspfquery\fP was written by Wayne Schlitt.
189
.PP
189
.PP
190
This manual page was written by Magnus Holmgren for the Debian\*[R]
190
This manual page was written by Magnus Holmgren for the Debian\*[R]
191
system (but may be used by others). Heavily inspired by the spfquery manpage of 
191
system (but may be used by others). Heavily inspired by the spfquery manpage of 
192
libmail\-spf\-query\-perl (\fBspfquery.mail\-spf\-query\-perl\fR(1)) by Julian Mehnle.
192
libmail\-spf\-query\-perl (\fBspfquery.mail\-spf\-query\-perl\fR(1)) by Julian Mehnle.
193
Also based on the command\-line help of spfquery.
193
Also based on the command\-line help of spfquery.
194
.SH COPYRIGHT
194
.SH COPYRIGHT
195
Copyright \(co 2007 Magnus Holmgren. Permission is granted to copy,
195
Copyright \(co 2007 Magnus Holmgren. Permission is granted to copy,
196
distribute and/or modify this document under the terms of the BSD
196
distribute and/or modify this document under the terms of the BSD
197
License.
197
License.
198
.PP
198
.PP
199
On Debian systems, the complete text of the BSD License can be found in /usr/share/common\-licenses/BSD.
199
On Debian systems, the complete text of the BSD License can be found in /usr/share/common\-licenses/BSD.