smtpd(n)						      Tcl SMTP Server Package							  smtpd(n)

__________________________________________________________________________________________________________________________________________________

NAME

       smtpd - Tcl SMTP server implementation

SYNOPSIS

       package require Tcl  8.3

       package require smtpd  ?1.4?

       ::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  net-
       work 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.

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  neces-
	      sary to fix the options array and the ::smtpd::stopped variable usage.

	      As the server code uses fileevent(n) 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(n) 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(n).

	      It should be noted that stopping the server does not disconnect any currently active sessions as these are operating over  an  inde-
	      pendent  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.

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

	      -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 com-
	      mands 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.

       validate_sender callback
	      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.

       validate_recipient callback
	      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.

       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 "
" [mime::buildmessage $token]
		   puts $mail
	       }

       deliver callback
	      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 "
" [join $data "
"]
		  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(n) 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 "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  SF	Trackers [http://sourceforge.net/tracker/?group_id=12883].  Please also report any ideas for enhancements you may have for
       either package and/or documentation.

KEYWORDS

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

COPYRIGHT

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

smtpd									1.4								  smtpd(n)