smtpd(n)

✨ smtpd — the Tcl SMTP Server Package (manual page smtpd(n), she's iconic) ✨

okay bestie, buckle up, we're doing smtpd(n) — the Tcl SMTP server implementation. yes, that smtpd(n). the manual name is literally smtpd and it lives in section n of the manual, iykyk 💅

---

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require smtpd ?1.6?

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

::smtpd::stop

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

::smptd::cget ?option?

---

🦋 DESCRIPTION 🦋

so the smtpd package hands you a simple, Tcl-only server library for the Simple Mail Transfer Protocol, exactly as described in RFC 821 (http://www.rfc-editor.org/rfc/rfc821.txt) and RFC 2821 (http://www.rfc-editor.org/rfc/rfc2821.txt). out of the box, the server binds to the default network address and the standard SMTP port, which is 25.

this package was designed to let you test Mail User Agent code from a developer's workstation. it does not attempt to deliver mail to your mailbox — not her job, not her problem. instead, you (the user of this package) are expected to write a procedure that gets called when mail arrives. once that procedure returns, the server has nothing further to do with the mail. it's giving "handoff, and then we don't speak again" 🫶

---

🔥 SECURITY 🔥

on Unix platforms, binding to the SMTP port requires root privileges. and honestly? i would not recommend running any script-based server as root unless there's some method for dropping root privileges immediately after the socket is bound. on Windows platforms, you don't need root or administrator privileges to bind low-numbered sockets — but security on those platforms is weak anyway, so 💀.

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 so many other well-tested, security-audited programs out there that can serve as mail servers for internet-connected hosts. love that for them, honestly.

---

🎀 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. those decisions belong to whichever application is using the package, and they're likely influenced by the set of servers that 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 — not this package, and not TLS itself. such a patch may be as simple as generally activating tls1 support, like 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 host's internet interface on the first available port. slay.

at present, the package only supports a single instance of an SMTP server. this could be changed if required, at the cost of making the package a little more complicated to read. if there's a good reason for running multiple SMTP services, then it'll only be necessary 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. that means either you should be running from within wish(1), or you should vwait(n) on the ::smtpd::stopped variable — which gets set when the server is stopped. no event loop, no vibes. periodt.

::smtpd::stop

halt the server and release the listening socket. if the server hasn't been started, then this command does nothing. the ::smtpd::stopped variable is set for use with vwait(n).

ngl, it should be noted that stopping the server does not disconnect any currently active sessions, because those are operating over an independent channel. only explicitly tracking and closing those 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 below for the details of those procedures. 👇

• -banner text — text of a custom banner message. the default banner is "tcllib smtpd 1.6". note that changing the banner does not affect the bracketing text in the full greeting, which prints 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 sender's 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 returns a list of all options and their current values. if an option is specified, it returns the value of that option. she's flexible like that 💅

---

🌈 CALLBACKS 🌈

validate_host callback

this procedure is called with the client's ip address as soon as a connection request has been accepted, and before any protocol commands are processed. if you want 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 — instead we wait for the client to send a QUIT command. any other commands cause a 503 Bad Sequence error. rude of them, but okay. 🙈

validate_sender callback

the validate_sender callback is called with the sender's mail address during processing of a MAIL command, to let you 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. so scream into the void, bestie, they won't hear it.

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 user's procedure is called with this single argument. when the call returns, the mime token is cleaned up — so if you wish to preserve the data, she must make a copy. no take-backs. 😭

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 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(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 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 the package and/or the documentation. we're listening, fr fr 🫶

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. (iykyk — it's right there.)

---

🍓 KEYWORDS 🍓

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

---

💖 CATEGORY 💖

Networking

---

👑 COPYRIGHT 👑

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

---

and that's the whole page, bestie! this was tcllib version 1.6, manual page smtpd(n) — no cap, that's the source and version right there, and the date is whatever your terminal feels like showing you. go forth and slay some SMTP. 💅✨🦋