Repository files navigation

Release: 2.4
Author: Vlad Seryakov (vlad@crystalballinc.com) Gustaf Neumann (neumann@wu-wien.ac.at)

The NaviServer SMTPD module implements the SMTP protocol and functionsas both an SMTP proxy and server. It provides an API for interactingwith the server directly via Tcl for e.g. sending mails andinteracting with the server. A typical setup uses a local Postfixinstallation as the relay for further message delivery. The modulefeatures built-in anti-spam and anti-virus capabilities which requirework to interact with newer releases of the external packages.

    A NaviServer (Sender) → B (nssmptd, 127.0.0.1:smtpdport) → C (relay, localhost:25)

• Compatibility: Compiles with Tcl versions 8.5, 8.6, and 9.0.
• Note: By default, anti-spam and anti-virus support are deactivated. They may require additional configuration or updates to work with current libraries.

• Overview
• Requirements
  • Anti-Spam Support
  • Anti-Virus Support
• Configuration
  • Basic Setup
  • Enabling Logging
  • Relay Authentication
• API Overview
• Usage Example
• License

This module acts as an intermediary SMTP server. It accepts messagesvia NaviServer or directly through its API and then forwards them to adesignated SMTP relay. This design enables integration with anti-spamand anti-virus tools, providing an additional layer of email security.

Install one of the following to enable anti-spam features:

• SpamAssassin:http://www.spamassassin.org/
• DSPAM:http://www.nuclearelephant.com/projects/dspam/
  Patched version:Download DSPAM 3.1.0 (Vlad)

Install one of the following to enable anti-virus features:

• ClamAV:http://www.clamav.net/
• Sophos SAVI:http://sophos.com

To enable the SMTPD module, add the following directives to yourNaviServer configuration file (e.g.,nsd.tcl) Load thenssmtpd.somodule within your server’smodules section and configure itssettings in a dedicated section:

ns_section ns/server/${server}/modules {  ns_param nssmtpd${home}/bin/nssmtpd.so}ns_section ns/server/${server}/module/nssmtpd {## Networking settings#  ns_param port         2525  ns_param address      127.0.0.1  ns_param relay        localhost:25  ns_param relaydomains"localhost domain.com"  ns_param localdomains"localhost domain.com"  ns_param spamd        localhost## Tcl callback definitions#  ns_param initproc     smtpd::init  ns_param rcptproc     smtpd::rcpt  ns_param dataproc     smtpd::data  ns_param errorproc    smtpd::error# For STARTTLS functionality  ns_param certificate"pathToYourCertificateChainFile.pem"  ns_param cafile""  ns_param capath""  ns_param ciphers"ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305"}

For secure communication via STARTTLS and to enable logging, add theseparameters to thenssmtpd section.

ns_section ns/server/${server}/module/nssmtpd {# ...# For logging "ns_smtpd send ..." operations  ns_param logging    on           ;# default: off# ns_param logfile ${logroot}/smtpsend.log  ns_param logrollfmt %Y-%m-%d     ;# format appended to log filename# ns_param logmaxbackup 100       ;# max number of backup log files# ns_param logroll true           ;# enable automatic log rolling# ns_param logrollonsignal true   ;# roll logs on SIGHUP# ns_param logrollhour 0          ;# specify the hour to roll logs# ...}

Therelay parameter defines the SMTP server responsible for messagedelivery. When using port25, the relay server is assumed to acceptmessages without requiring further authentication. However, if youconfigure the relay to use port587, the module supports PLAINpassword authentication. In this scenario, ensure that:

• The relay server supports STARTTLS.
• NaviServer and this module are compiled with OpenSSL support.

The URL format is intentionally designed to accommodate additionalauthentication methods in the future. An example (with placeholdersin uppercase):

ns_section ns/server/${server}/module/nssmtpd {# ...  ns_param relay plain://USER:PWD@MAILHOST:587# ...}

Note that the USER:PWD infomation is passed in the "userinfo" part ofthe URL (as defined in RFC 3207). To guarantee URL parsing, USER:PWDhas to be percent-encoded. This can be done e.g. with the NaviServercommandns_urlencode -part oauth1 $credentials.

Note: The username and password (USER:PWD) are included in theURL's "userinfo" segment, as defined by RFC 3207. To ensure correctURL parsing, these credentials must be percent-encoded. For example,you can use the NaviServer commandns_urlencode -part oauth1 $credentialsto perform this encoding.

Security Note: Be cautious when embedding credentials inconfiguration files. To protect sensitive information, restrict filepermissions for the configuration file, verify user permissions on thehost machine, or consider using environment variables or readingcredentials from a secured file. Keep in mind that arbitrary Tclcommands can be executed from within the configuration file.

The module is managed via a single Tcl command,ns_smtpd, whichprovides an extensive set of operations for interacting with the SMTPserver. Below is a summary of available commands:

• General Commands:
  • ns_smtpd flag /name/
  • ns_smtpd send /sender_email/ /rcpt_email/ /data_varname/ ?server? ?port?
• Relay Management:
  • ns_smtpd relay add /domain/
  • ns_smtpd relay check /address/
  • ns_smtpd relay clear
  • ns_smtpd relay del /domain/
  • ns_smtpd relay get
  • ns_smtpd relay set /relay/ ?relay? ...
• Local Domains/IPs:
  • ns_smtpd local add /domain|ipaddr|
  • ns_smtpd local check /ipaddr|
  • ns_smtpd local clear
  • ns_smtpd local del /domain|ipaddr|
  • ns_smtpd local get
  • ns_smtpd local set /ipaddr/ ?ipaddr? ...
• Data Encoding/Decoding:
  • ns_smtpd encode /base64|hex|qprint/ /text/
  • ns_smtpd decode /base64|hex|qprint/ /text/
• Validation and Versioning:
  • ns_smtpd checkemail /email/    (Returns a valid email in the form name@domain)
  • ns_smtpd checkdomain /domain/
  • ns_smtpd virusversion    (Returns anti-virus tool version)
  • ns_smtpd spamversion    (Returns anti-spam tool version)
• Spam and Virus Checks:
  • ns_smtpd checkspam /message/ ?email?
  • ns_smtpd trainspam 1|0 /email/ /message/ ?signature? ?mode? ?source?
  • ns_smtpd checkvirus /data/
• Session and Message Handling:
  • ns_smtpd sessions
  • ns_smtpd gethdr /name/
  • ns_smtpd gethdrs ?name?
  • ns_smtpd getbody
  • ns_smtpd getfrom
  • ns_smtpd getfromdata
  • ns_smtpd setfrom /address/
  • ns_smtpd setfromdata /data/
  • ns_smtpd getrcpt ?address|index?
  • ns_smtpd getrcptdata ?address|index?
  • ns_smtpd addrcpt /address/ ?flags? ?data?
  • ns_smtpd setrcptdata /address|index/ /data/
  • ns_smtpd delrcpt /address|index/
  • ns_smtpd setflag /address|index/ /flag/
  • ns_smtpd unsetflag /address|index/ /flag/
  • ns_smtpd getflag ?address|index?
  • ns_smtpd setreply /reply/
  • ns_smtpd getline
  • ns_smtpd dump /filename/

The provided source code of the Tcl files provide more details aboutusing the API.

Once configured, the SMTPD module will act as an SMTP server, forwarding messages to the relay specified by therelay parameter. Additionally, you can interact with it via thens_smtpd command to perform actions such as sending mail, checking spam/virus status, and managing session data.

For example, to send an email using the API:

set message"From: sender@example.comTo: recipient@example.comDate:[ns_httptime [clock seconds]]Subject: TestmailThis is a test mail!"ns_smtpd send sender@example.com recipient@example.com message localhost 25

This command will deliver the message to the configured SMTP relay,applying potentially anti-spam or anti-virus checks along the way.

This project is licensed under the Mozilla Public License.

• Vlad Seryakov –vlad@crystalballinc.com
• Gustaf Neumann –neumann@wu-wien.ac.at