1smtpd(n)                    Tcl SMTP Server Package                   smtpd(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       smtpd - Tcl SMTP server implementation
9

SYNOPSIS

11       package require Tcl  8.3
12
13       package require smtpd  ?1.4?
14
15       ::smtpd::start ?myaddr? ?port?
16
17       ::smtpd::stop
18
19       ::smptd::configure ?option value? ?option value ...?
20
21       ::smtpd::cget ?option?
22
23_________________________________________________________________
24

DESCRIPTION

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
32       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

SECURITY

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
46       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

COMMANDS

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
60
61                set sock [::smtpd::start [info hostname] 0]
62
63
64              will bind to the hosts internet interface on the first available
65              port.
66
67              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
74              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
80       ::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
85              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
93       ::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
99              -validate_host proc
100                     Callback to authenticate new connections based on the ip-
101                     address of the client.
102
103              -validate_sender proc
104                     Callback to authenticate new  connections  based  on  the
105                     senders email address.
106
107              -validate_recipient proc
108                     Callback  to  validate  and  authorize  a recipient email
109                     address
110
111              -deliverMIME proc
112                     Callback used to deliver mail as a mime token created  by
113                     the tcllib mime package.
114
115              -deliver proc
116                     Callback used to deliver email. This option has no effect
117                     if the -deliverMIME option has been set.
118
119       ::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

CALLBACKS

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
132
133               proc validate_host {ipnum} {
134                  if {[string match "192.168.1.*" $ipnum]} {
135                     error "go away!"
136                  }
137               }
138
139
140              If access is denied the client will receive a  standard  message
141              that includes the text of your error, such as:
142
143
144               550 Access denied: I hate you.
145
146
147              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
151       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
158
159               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
167
168              The  content of any error message will not be passed back to the
169              client.
170
171       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
178       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
186
187               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
195
196       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
203
204               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
210
211              Note  that the DATA command will return an error if no sender or
212              recipient has yet been defined.
213

VARIABLES

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

AUTHOR

220       Written by Pat Thoyts mailto:patthoyts@users.sourceforge.net.
221

LICENSE

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

BUGS, IDEAS, FEEDBACK

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

KEYWORDS

236       rfc 2821, rfc 821, services, smtp, smtpd, socket, vwait
237
239       Copyright (c) Pat Thoyts <patthoyts@users.sourceforge.net>
240
241
242
243
244smtpd                                 1.4                             smtpd(n)
Impressum