smtpd(3)



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-edi-
       tor.org/rfc/rfc2821.txt).  By default the server will bind to  the  de-
       fault 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  run-
       ning  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 applica-
       tion 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://googleonli-
       nesecurity.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  inter-
              faces. 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 in-
              dependent 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 prac-
              tice  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.

              -banner text
                     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.

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

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

              -validate_recipient proc
                     Callback to validate and authorize a recipient email  ad-
                     dress

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

              -deliver proc
                     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
       validate_host callback
              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  ex-
              ample:

               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 in-
       cludes 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.

       validate_sender callback
              The validate_sender callback is called with the senders mail ad-
              dress 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.

       validate_recipient callback
              The  validate_recipient  callback  is  similar  to   the   vali-
              date_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.

       deliverMIME callback
              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
               }

       deliver callback
              The deliver callback is called once a mail message has been suc-
              cessfully passed to the server and there is no -deliverMIME  op-
              tion set. The procedure is called with the sender, a list of re-
              cipients and the text of the mail as a list of lines. For  exam-
              ple:

               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 recipi-
       ent 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  MER-
       CHANTABILITY  or  FITNESS  FOR  A PARTICULAR PURPOSE. See the file "li-
       cense.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 out-
       put 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>

tcllib                                1.5                          smtpd(3tcl)

Man(1) output converted with man2html
list of all man pages