PicLan-IP SMTP/POP3 Mail Server Configuration

This documentation is for PicLan-IP build 2.0.0(135) and later. A number of configuration parameters for email functions have changed as of this release.

The PicLan-IP mail server functions can be used to:

Send mail to other SMTP mail servers
Receive mail from other SMTP mail servers
Receive and relay mail from other SMTP mail servers
Allow users access to mail accounts over POP3 connections

Each of these functions requires different configuration information.

Configuration Outbound SMTP Mail Services

In order for the PicLan-IP mail server to successfully send internet mail to other SMTP mail servers, you must configuration your network with the following elements:

Configuring the PicLan-IP Mail Server for Outbound SMTP

In order to use outbound SMTP services, you must first decide whether the PicLan-IP mail server will directly send mail to it's destination or use a relay for this purpose. If PicLan-IP sends the mail directly, then PicLan-IP is responsible for all message retry logic, DNS lookups, MX record decodes, and other mail operations. If you configure the PicLan-IP mail server to send all mail to a relay SMTP server, then the relay server takes over the responsibility for message retry logic, DNS lookups, ets.

Configuring PicLan-IP to send mail directly

This configuration requires the following fields in the PLIP.CTRL CONFIG item:

Parameter	Format	Description	Default
`DNS`	...	You must configure DNS parameter fields in order to have PicLan-IP send mail directly.	none
`LOCAL HOST NAME=`	system name (mail.modsoft.com)	The name of the PicLan-IP system.	none

Configuring PicLan-IP to send mail through a relay

This configuration requires the following fields in the PLIP.CTRL CONFIG item:

Parameter	Format	Description	Default
`OBSOLETE MAIL HOST=`	IP address or system name	This configuration parameter is now a part of the EMAIL,ROUTE file. The name or IP address of the mail relay host. If you specify a name, then you must configure DNS parameter fields in order to have PicLan-IP send mail directly.	none

Configuring other PicLan-IP send mail parameters

There are a number of additional parameters that are used by the mail send operations. These are included in the PLIP.CTRL CONFIG item as:

Parameter	Format	Description	Default
`MAIL TIMEOUT=`	hh:mm:ss	The amount of time that the mail server will wait for any single response from a destination server.	10 minutes
`MAIL LONG TIMEOUT=`	hh:mm:ss	The total amount of time that the mail server will take sending to a single SMTP address	20 minutes
`MAIL CONN OUT=`	##	The total number of simultanious network SMTP connections that the mail server will make concurrently.	20
`MAIL RETRY TIME=`	hh:mm:ss	The amount of time between retries of outbound mail messages	20 minutes
`MAIL WARN TIME=`	hh:mm:ss	The amount of time before a non-delivered mail warning message is sent to the sender.	24 hours (1 day)
`MAIL MAX TIME=`	hh:mm:ss	The amount of time before a message is discarded and a mail failure message is send to the sender	120 hours (5 days)
`MAIL WARN MAX=`	hh:mm:ss	The maximum amount of time that a mail warning or failure return message is retried	6 hours
`MAIL MAX HOPS=`	##	The maximum number of hops that a message can forward through before being discarded.	20

Configuring Inbound SMTP Mail Services

Inbound SMTP mail services require that you configure the PicLan-IP software so is listens for inbound SMTP connections and that it knows what to do with inbound mail messages as they arrive.

Configuring SMTP Listens

An SMTP listen is configured with a line in the PLIP.CTRL CONFIG item:

SMTP LISTEN=*:25

This will setup an SMTP listen for the default IP address for the PicLan-IP host on TCP port 25 (which is the default for SMTP).

SMTP Routing Concepts

In general, there are three actions that can be taken when an inbound message arrives:

The message can be refused.
The message can be filed in a mailbox for later retrieval either by a Pick application program or by a POP3 client.
The message can be forwarded to another system and/or email address.

PicLan-IP allows you to file and forward messages multiple times. This allows you to distribute mail to multiple local and remote mailboxes.

Configuring Inbound SMTP Routing Rules

PicLan-IP decided what to do with inbound SMTP mail messages based on routing rules that are stored in the file EMAIL,ROUTE. This file can have routing rule items with three possible item-id formats:

user@domain
*@domain
*@*

All items in this file are stored with lowercase item-ids. You can create as many routing rule items in this file as you wish. When an inbound message arrives, the destination address of the message is used to read routing rule items from the EMAIL,ROUTE file. The order that routing rules are read is:

The entire email message in the form "user@domain" is read first.
If the specific user is not found, then "*@domain" is read to handle unknown users at a particular domain.
If the domain is not found, then "*@*" is read to handle general message forwarding.

What an Inbound SMTP Routing Rule Looks Like

Inbound SMTP routine rules are multi-line text items that the PicLan-IP mail server uses to determine where a message will go. A simple example would be to file a message in a mailbox.

    doug@modsoft.com
001 MAILBOX DOUG

The single line MAILBOX ... specifies that inbound messages to "doug@modsoft.com" should be saved in a mailbox named "DOUG". If you wish to create email addresses that go to multiple local mailboxes, you could use a mailbox like:

    maillist@modsoft.com
001 MAILBOX JOHN
002 MAILBOX GEORGE
003 MAILBOX JERRY
004 MAILBOX SAMANTHA

Inbound SMTP rules can also be used to cause messages to be forwarded to other SMTP mail host systems:

    george@modsoft.com
001 FWD george@piclan.com FWD.PARAMETERS

The FWD.PARAMETER can consist of the following strings:

MX - Forward based on DNS MX record lookups
###.###.###.### - Forward to a specific SMTP host by IP address

You may also specify several IP addresses seperated by spaces. In this case, PicLan-IP will load-share outbound mail messages between the specified servers.

This can be used either seperately or in conjunction with local mailboxes:

    george@modsoft.com
001 FWD george@piclan.com MX
002 MAILBOX GEORGE

These routing rules are typically used for specific mailbox destinations. If you wish to accept inbound messages for generic addresses, then additional rules are often used to control mail relaying and access:

    *@*
001 ALLOW 207.215.231.0 255.255.255.0
002 FWD *@* MX

The ALLOW keyword provides a mechanism to refuse forwarded mail except from your local users. You specify what is a local user by supplying an IP network and sub-net mask. This example would allow forwarding from users with IP addresses from 207.215.231.0 thru 207.215.231.255. If you have multiple local network address ranges, then you can specify multiple ALLOW lines. If an inbound mail message comes from an address that is not allowed, then a "550 we do not forward" error will be generated and the mail message will be refused.

The reason that you setup a general *@* record is to allow email client applications like Pegasus and Eudora to send mail using the PicLan-IP mail server as the sending SMTP server. The reason that you want to restrict mail forwarding is to prevent bulk emailers from using your mail server to send their email messages over the internet using your bandwidth instead of their bandwidth.

Setting up Mailboxes

If you wish to store mail locally on the MultiValue host system, you will need to setup mailboxes for each user that is to receive mail. Mailboxes are setup in the EMAIL,MAILBOX file. This file has the format:

Attribute Number	Attribute Name	Description
`Item ID`		The name of the mailbox. Mailboxes should be upper-case only.
`001`	POP3 Password	The password required for POP3 access to the mailbox. If you do not specify a POP3 password, then the mail will not be accessible over POP3. Passwords are case sensitive
`002`	Max Messages	The maximum number of message allowed to be stored in the mailbox. A null entry allows unlimited storage. (not currently implemented)
`003`	Max Message Size	The maximum total size of messages allowed to be stored in the mailbox. A null entry allows unlimited storage. (not currently implemneted)
`004`	Event Subroutine Name	The name of a subroutine that will be called when a message arrives. A single parameter with the message ID number is passed to the subroutine.
`005`	Event TCL Command	A TCL command that is executed when a message arrives. A single parameter with the message ID number is appended to the TCL command.

`...`		Attributes above 11 are for the internal use of the PicLan-IP mail server and should not be modified manually
`011`	List of messages in Mailbox	A multi-value list of message IDs currently stored for this mailbox.
`012`	List of message sizes in Mailbox	A multi-value list of message sizes currently stored for this mailbox.
`013`	Total size of messages in Mailbox	The total size in bytes of messages stored in this mailbox.
`014`	Lock Handle	A handle that indicates that the mailbox is "locked" by POP3.

At a minimum, the EMAIL,MAILBOX file must have an empty item for each mailbox in use.

As of build 113, some email functions are not implemented, so not all of the above elements may be active.

Setting up POP3 Access

If you wish to allow users to access their mailboxes via POP3, you need to setup a POP3 listen line in PLIP.CTRL CONFIG as:

POP3 LISTEN=*:110

This will setup a POP3 listen on the default IP address and TCP port 110 (which is the default for POP3). POP3 users will then be able to access any mailbox with a POP3 password.