1smtpd(n) Tcl SMTP Server Package smtpd(n)
2______________________________________________________________________________
6
8 smtpd - Tcl SMTP server implementation
9
11 package require Tcl 8.3
12 package require smtpd ?1.4?
14 ::smtpd::start ?myaddr? ?port?
16 ::smtpd::stop
18 ::smptd::configure ?option value? ?option value ...?
20 ::smtpd::cget ?option?
22_________________________________________________________________
24
26 The smtpd package provides a simple Tcl-only server library for the
27 Simple Mail Transfer Protocol as described in RFC 821 (http://www.rfc-
28 editor.org/rfc/rfc821.txt) and RFC 2821 (http://www.rfc-edi‐
29 tor.org/rfc/rfc2821.txt). By default the server will bind to the
30 default network address and the standard SMTP port (25).
31 This package was designed to permit testing of Mail User Agent code
33 from a developers workstation. It does not attempt to deliver mail to
34 your mailbox. Instead users of this package are expected to write a
35 procedure that will be called when mail arrives. Once this procedure
36 returns, the server has nothing further to do with the mail.
37
39 On Unix platforms binding to the SMTP port requires root privileges. I
40 would not recommend running any script-based server as root unless
41 there is some method for dropping root privileges immediately after the
42 socket is bound. Under Windows platforms, it is not necessary to have
43 root or administrator privileges to bind low numbered sockets. However,
44 security on these platforms is weak anyway.
45 In short, this code should probably not be used as a permanently run‐
47 ning Mail Transfer Agent on an Internet connected server, even though
48 we are careful not to evaluate remote user input. There are many other
49 well tested and security audited programs that can be used as mail
50 servers for internet connected hosts.
51
53 ::smtpd::start ?myaddr? ?port?
54 Start the service listening on port or the default port 25. If
55 myaddr is given as a domain-style name or numerical dotted-quad
56 IP address then the server socket will be bound to that network
57 interface. By default the server is bound to all network inter‐
58 faces. For example:
59 set sock [::smtpd::start [info hostname] 0]
62 will bind to the hosts internet interface on the first available
65 port.
66 At present the package only supports a single instance of a SMTP
68 server. This could be changed if required at the cost of making
69 the package a little more complicated to read. If there is a
70 good reason for running multiple SMTP services then it will only
71 be necessary to fix the options array and the ::smtpd::stopped
72 variable usage.
73 As the server code uses fileevent(n) handlers to process the
75 input on sockets you will need to run the event loop. This means
76 either you should be running from within wish(1) or you should
77 vwait(n) on the ::smtpd::stopped variable which is set when the
78 server is stopped.
79 ::smtpd::stop
81 Halt the server and release the listening socket. If the server
82 has not been started then this command does nothing. The
83 ::smtpd::stopped variable is set for use with vwait(n).
84 It should be noted that stopping the server does not disconnect
86 any currently active sessions as these are operating over an
87 independent channel. Only explicitly tracking and closing these
88 sessions, or exiting the server process will close down all the
89 running sessions. This is similar to the usual unix daemon prac‐
90 tice where the server performs a fork(2) and the client session
91 continues on the child process.
92 ::smptd::configure ?option value? ?option value ...?
94 Set configuration options for the SMTP server. Most values are
95 the name of a callback procedure to be called at various points
96 in the SMTP protocol. See the CALLBACKS section for details of
97 the procedures.
98 -validate_host proc
100 Callback to authenticate new connections based on the ip-
101 address of the client.
102 -validate_sender proc
104 Callback to authenticate new connections based on the
105 senders email address.
106 -validate_recipient proc
108 Callback to validate and authorize a recipient email
109 address
110 -deliverMIME proc
112 Callback used to deliver mail as a mime token created by
113 the tcllib mime package.
114 -deliver proc
116 Callback used to deliver email. This option has no effect
117 if the -deliverMIME option has been set.
118 ::smtpd::cget ?option?
120 If no option is specified the command will return a list of all
121 options and their current values. If an option is specified it
122 will return the value of that option.
123
125 validate_host callback
126 This procedure is called with the clients ip address as soon as
127 a connection request has been accepted and before any protocol
128 commands are processed. If you wish to deny access to a specific
129 host then an error should be returned by this callback. For
130 example:
131 proc validate_host {ipnum} {
134 if {[string match "192.168.1.*" $ipnum]} {
135 error "go away!"
136 }
137 }
138 If access is denied the client will receive a standard message
141 that includes the text of your error, such as:
142 550 Access denied: I hate you.
145 As per the SMTP protocol, the connection is not closed but we
148 wait for the client to send a QUIT command. Any other commands
149 cause a 503 Bad Sequence error.
150 validate_sender callback
152 The validate_sender callback is called with the senders mail
153 address during processing of a MAIL command to allow you to
154 accept or reject mail based upon the declared sender. To reject
155 mail you should throw an error. For example, to reject mail from
156 user "denied":
157 proc validate_sender {address} {
160 eval array set addr [mime::parseaddress $address]
161 if {[string match "denied" $addr(local)]} {
162 error "mailbox $addr(local) denied"
163 }
164 return
165 }
166 The content of any error message will not be passed back to the
169 client.
170 validate_recipient callback
172 The validate_recipient callback is similar to the vali‐
173 date_sender callback and permits you to verify a local mailbox
174 and accept mail for a local user address during RCPT command
175 handling. To reject mail, throw an error as above. The error
176 message is ignored.
177 deliverMIME callback
179 ] The deliverMIME callback is called once a mail message has
180 been successfully passed to the server. A mime token is con‐
181 structed from the sender, recipients and data and the users pro‐
182 cedure it called with this single argument. When the call
183 returns, the mime token is cleaned up so if the user wishes to
184 preserve the data she must make a copy.
185 proc deliverMIME {token} {
188 set sender [lindex [mime::getheader $token From] 0]
189 set recipients [lindex [mime::getheader $token To] 0]
190 set mail "From $sender [clock format [clock seconds]]"
191 append mail "\n" [mime::buildmessage $token]
192 puts $mail
193 }
194 deliver callback
197 The deliver callback is called once a mail message has been suc‐
198 cessfully passed to the server and there is no -deliverMIME
199 option set. The procedure is called with the sender, a list of
200 recipients and the text of the mail as a list of lines. For
201 example:
202 proc deliver {sender recipients data} {
205 set mail "From $sender [clock format [clock seconds]]"
206 append mail "\n" [join $data "\n"]
207 puts "$mail"
208 }
209 Note that the DATA command will return an error if no sender or
212 recipient has yet been defined.
213
215 ::smtpd::stopped
216 This variable is set to true during the ::smtpd::stop command to
217 permit the use of the vwait(n) command.
218
220 Written by Pat Thoyts mailto:patthoyts@users.sourceforge.net.
221
223 This software is distributed in the hope that it will be useful, but
224 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
225 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the file
226 "license.terms" for more details.
227
229 This document, and the package it describes, will undoubtedly contain
230 bugs and other problems. Please report such in the category smtpd of
231 the Tcllib SF Trackers [http://source‐
232 forge.net/tracker/?group_id=12883]. Please also report any ideas for
233 enhancements you may have for either package and/or documentation.
234
236 rfc 2821, rfc 821, services, smtp, smtpd, socket, vwait
237
239 Copyright (c) Pat Thoyts <patthoyts@users.sourceforge.net>
240smtpd 1.4 smtpd(n)