.\" -*- nroff -*-
.\" Copyright (C) 2001 Pat Thoyts <patthoyts@users.sourceforge.net>
.\" 
.\" RCS: @(#) $Id$
.\" 
.so man.macros
.TH smtpd n 1.0 smtpd "Tcl SMTP Server Package"
.BS
.\" The CW macros give us Constant Width fonts for formatting code.
.de CW
\&\f(CW\\$*\fR
..
.de CWS
\&\f(CW\s-1\\$*\s0\fR
..
.\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
smtpd \- Tcl SMTP server implementation
.SH SYNOPSIS
\fBpackage require Tcl 8.3\fR
.sp
\fBpackage require smtpd ?1.0?\fR
.sp
\fB::smtpd::start\fR \fR?\fImyaddr\fR?\fR \fR?\fIport\fR?\fR
.sp
\fB::smtpd::stop\fR
.sp
\fB::smptd::configure\fR \fR?\fIoption\fR \fIvalue\fR?\fR \fR?\fIoption\fR \fIvalue\fR \fI...\fR?\fR
.sp
\fB::smtpd::cget\fR \fR?\fIoption\fR
.sp
.BE
.SH DESCRIPTION
.PP
The \fBsmtpd\fR package provides a simple Tcl-only server library for
the Simple Mail Transfer Protocol as described in RFC 821 and RFC 2821.
By default the server will bind to the default network address and the
standard SMTP port (25). 
.SH COMMANDS
.TP
\fB::smtpd::start\fR \fR?\fImyaddr\fR?\fR \fR?\fIport\fR?\fR
Start the service listening on \fIport\fR or the default port 25. If
\fImyaddr\fR 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.
.TP
\fB::smtpd::stop\fR
Halt the server and release the listening socket. If the server has
not been started then do nothing.
.TP
\fB::smptd::configure\fR \fR?\fIoption\fR \fIvalue\fR?\fR
\fR?\fIoption\fR \fIvalue\fR \fI...\fR?\fR
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.
.RS
.TP
\fB-validate_host proc\fR
Callback to authenticate new connections based on the ip-address of the
client.
.TP
\fB-validate_sender proc\fR
Callback to authenticate new connections based on the senders email address.
.TP
\fB-validate_recipient proc\fR
Callback to validate and authorize a recipient email address
.TP
\fB-deliver proc\fR
Callback used to deliver email.
.RE
.TP
.SH CALLBACKS
.TP
\fBvalidate_host callback\fR
This procedure is called with the clients ip address. If you wish to
deny access then an error should be returned. For example:
.br
\f(CWproc validate_host {ipnum} {
  if {[string match "192.168.1.*" $ipnum]} {
    error "go away!"
  }
}
\fR
.TP
\fBvalidate_sender callback\fR
The validate_sender callback is called with the senders mail address
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":
.br
\f(CWproc validate_sender {address} {
  eval array set addr \\
       [mime::parseaddress $address]
  if {[string match "denied" $addr(local)]} {
       error "mailbox $addr(local) denied"
  }
  return    
}
\fR
.TP
\fBvalidate_recipient callback\fR
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. To reject mail, throw an error as above.
.TP
\fBdeliver callback\fR
The deliver callback is called once a mail message has been
successfully passed to the server. The procedure is called with the
sender, a list of recipients and the text of the mail as a list of
lines. For example:
\f(CWproc deliver {sender recipients data} {
  set mail "From $saddr(address) \\
             [clock format [clock seconds]]"
  append mail "\\n" [join $data "\\n"]
  puts "$mail"
}
\fR
.RE
.\".TP
.\".SH VARIABLES
.\".TP
.\"\fB::smtpd::postmaster\fR
.\"The e-mail address of the person that is the contact for the server.
.SH BUGS
There are no bugs \(em yet.
.SH AUTHOR
Written by Pat Thoyts <patthoyts@users.sourceforge.net>
.SH COPYRIGHT
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.
.SH KEYWORDS
smtpd, smtp, services, RFC 821, RFC 2821