Scroll to navigation

smtpd(3tcl) Tcl SMTP Server Package smtpd(3tcl) 





NAME


smtpd - Tcl SMTP server implementation






SYNOPSIS


package require Tcl 8.3


package require smtpd ?1.5?


::smtpd::start ?myaddr? ?port?


::smtpd::stop


::smptd::configure ?option value?
    ?option value ...?


::smtpd::cget ?option?










DESCRIPTION


The smtpd package provides a simple Tcl-only server library
    for the Simple Mail Transfer Protocol as described in RFC 821
    (http://www.rfc-editor.org/rfc/rfc821.txt) and RFC 2821
    (http://www.rfc-editor.org/rfc/rfc2821.txt). By default the server
    will bind to the default network address and the standard SMTP port
  (25).


This package was designed to permit testing of Mail User Agent
    code from a developers workstation. It does not attempt to deliver mail
    to your mailbox. Instead users of this package are expected to write a
    procedure that will be called when mail arrives. Once this procedure
    returns, the server has nothing further to do with the mail.






SECURITY


On Unix platforms binding to the SMTP port requires root
    privileges. I would not recommend running any script-based server as root
    unless there is some method for dropping root privileges immediately after
    the socket is bound. Under Windows platforms, it is not necessary to have
    root or administrator privileges to bind low numbered sockets. However,
    security on these platforms is weak anyway.


In short, this code should probably not be used as a permanently
    running Mail Transfer Agent on an Internet connected server, even though we
    are careful not to evaluate remote user input. There are many other well
    tested and security audited programs that can be used as mail servers for
    internet connected hosts.






TLS SECURITY CONSIDERATIONS


This package uses the TLS package to handle the security
    for https urls and other socket connections.


Policy decisions like the set of protocols to support and what
    ciphers to use are not the responsibility of TLS, nor of this package
    itself however. Such decisions are the responsibility of whichever
    application is using the package, and are likely influenced by the set of
    servers the application will talk to as well.


For example, in light of the recent POODLE attack
    [http://googleonlinesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-ssl-30.html]
    discovered by Google many servers will disable support for the SSLv3
    protocol. To handle this change the applications using TLS must be
    patched, and not this package, nor TLS itself. Such a patch may be as
    simple as generally activating tls1 support, as shown in the example
    below.






    package require tls


    tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol


    ... your own application code ...









COMMANDS



  
::smtpd::start ?myaddr? ?port?

  
Start the service listening on port or the default port 25. If
      myaddr is given as a domain-style name or numerical dotted-quad IP
      address then the server socket will be bound to that network interface. By
      default the server is bound to all network interfaces. For example:
    

  








  set sock [::smtpd::start [info hostname] 0]





will bind to the hosts internet interface on the first available
    port.


At present the package only supports a single instance of a SMTP
    server. This could be changed if required at the cost of making the package
    a little more complicated to read. If there is a good reason for running
    multiple SMTP services then it will only be necessary to fix the
    options array and the ::smtpd::stopped variable usage.


As the server code uses fileevent(3tcl) handlers to process
    the input on sockets you will need to run the event loop. This means either
    you should be running from within wish(1) or you should
    vwait(3tcl) on the ::smtpd::stopped variable which is set when
    the server is stopped.



  
::smtpd::stop

  
Halt the server and release the listening socket. If the server has not
      been started then this command does nothing. The ::smtpd::stopped
      variable is set for use with vwait(3tcl).
    
It should be noted that stopping the server does not
        disconnect any currently active sessions as these are operating over an
        independent channel. Only explicitly tracking and closing these
        sessions, or exiting the server process will close down all the running
        sessions. This is similar to the usual unix daemon practice where the
        server performs a fork(2) and the client session continues on the
        child process.

  

  
::smptd::configure ?option value? ?option
    value ...?

  
Set configuration options for the SMTP server. Most values are the name of
      a callback procedure to be called at various points in the SMTP protocol.
      See the CALLBACKS section for details of the procedures.







  
  
Text of a custom banner message. The default banner is "tcllib smtpd
      1.5". Note that changing the banner does not affect the bracketing
      text in the full greeting, printing status 220, server-address, and
      timestamp.

  

  
Callback to authenticate new connections based on the ip-address of the
      client.

  

  
Callback to authenticate new connections based on the senders email
      address.

  

  
Callback to validate and authorize a recipient email address

  

  
Callback used to deliver mail as a mime token created by the tcllib
      mime package.

  

  
Callback used to deliver email. This option has no effect if the
      -deliverMIME option has been set.







  
::smtpd::cget ?option?

  
If no option is specified the command will return a list of all
      options and their current values. If an option is specified it will return
      the value of that option.








CALLBACKS



  

  
This procedure is called with the clients ip address as soon as a
      connection request has been accepted and before any protocol commands are
      processed. If you wish to deny access to a specific host then an error
      should be returned by this callback. For example:
    

  








 proc validate_host {ipnum} {


    if {[string match "192.168.1.*" $ipnum]} {


       error "go away!"


    }


 }





If access is denied the client will receive a standard message
    that includes the text of your error, such as:








 550 Access denied: I hate you.





As per the SMTP protocol, the connection is not closed but we wait
    for the client to send a QUIT command. Any other commands cause a 503 Bad
    Sequence error.



  

  
The validate_sender callback is called with the senders mail address
      during processing of a MAIL command to allow you to accept or reject mail
      based upon the declared sender. To reject mail you should throw an error.
      For example, to reject mail from user "denied":
    

  








 proc validate_sender {address} {


    eval array set addr [mime::parseaddress $address]


    if {[string match "denied" $addr(local)]} {


         error "mailbox $addr(local) denied"


    }


    return


 }





The content of any error message will not be passed back to the
    client.



  

  
The validate_recipient callback is similar to the validate_sender callback
      and permits you to verify a local mailbox and accept mail for a local user
      address during RCPT command handling. To reject mail, throw an error as
      above. The error message is ignored.

  

  
The deliverMIME callback is called once a mail message has been
      successfully passed to the server. A mime token is constructed from the
      sender, recipients and data and the users procedure it called with this
      single argument. When the call returns, the mime token is cleaned up so if
      the user wishes to preserve the data she must make a copy.
    

  








 proc deliverMIME {token} {


     set sender [lindex [mime::getheader $token From] 0]


     set recipients [lindex [mime::getheader $token To] 0]


     set mail "From $sender [clock format [clock seconds]]"


     append mail "\n" [mime::buildmessage $token]


     puts $mail


 }






  

  
The deliver callback is called once a mail message has been successfully
      passed to the server and there is no -deliverMIME option set. The
      procedure is called with the sender, a list of recipients and the text of
      the mail as a list of lines. For example:
    

  








 proc deliver {sender recipients data} {


    set mail "From $sender  [clock format [clock seconds]]"


    append mail "\n" [join $data "\n"]


    puts "$mail"


 }





Note that the DATA command will return an error if no sender or
    recipient has yet been defined.






VARIABLES



  
::smtpd::stopped

  
This variable is set to true during the ::smtpd::stop
      command to permit the use of the vwait(3tcl) command.








AUTHOR


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






LICENSE


This software is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the file
    "license.terms" for more details.






BUGS, IDEAS, FEEDBACK


This document, and the package it describes, will undoubtedly
    contain bugs and other problems. Please report such in the category
    smtpd of the Tcllib Trackers
    [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for
    enhancements you may have for either package and/or documentation.


When proposing code changes, please provide unified diffs,
    i.e the output of diff -u.


Note further that attachments are strongly preferred over
    inlined patches. Attachments can be made by going to the Edit form of
    the ticket immediately after its creation, and then using the left-most
    button in the secondary navigation bar.






KEYWORDS


rfc 2821, rfc 821, services, smtp, smtpd, socket, vwait






CATEGORY


Networking






COPYRIGHT


Copyright (c) Pat Thoyts <patthoyts@users.sourceforge.net>








  

    1.5
    tcllib