Patch title: Release 85 bulk changes
Abstract:
File: /pliant/protocol/smtp/index.page
Key:
    Removed line
    Added line
title "The Pliant SMTP server"
center highlight:"broken since release 26"


header "The Pliant SMTP server design"

image "/pliant/welcome/image/mail.jpeg" right
  [The Pliant SMTP server has been design with deap layering in mind. ]
  [Rather than providing a straight forward to use server, the Pliant SMTP server deals with all SMTP protocol related mess, but let you decide on your own (through a configuration file which is a true Pliant program) what messages you will accept or reject, and where your're going to store them or forward them.] ; eol
box right
  image "/pliant/welcome/image/mail.jpeg"
[The Pliant SMTP server has been design with deap layering in mind. ]
[Rather than providing a straight forward to use server, the Pliant SMTP server deals with all SMTP protocol related mess, but let you decide on your own (through a configuration file which is a true Pliant program) what messages you will accept or reject, and where your're going to store them or forward them.] ; eol

para
  [If you expect a ready to use SMTP server, you need both the Pliant SMTP server and a sample] ; fixed [ /etc/pliant/mail ] ; [or] ; fixed [ /pliant_security/mail ] ; [file (see samples below).]


header "Running the Pliant SMTP server"

[The simplest way to start Pliant SMTP server is to type in the following command at the shell prompt:]
listing
  pliant module /pliant/protocol/smtp/server.pli command smtp_server
[If everything works fine, you should get a message:] ; eol
fixed [SMTP server is running on TCP port 25.] ; eol
[and the program should not stop.] ; eol
[If the program stoped (you get back to the prompt), you probably have another SMTP server already running, or your TCP/IP layer is not configured properly at operating system level. ]
[On a Unix system, you may also not be able to start the SMTP server if you don't have 'root' rights.]


section "security"
header "Security"

para
  [The Pliant confidential configurations files can be stored in] ; fixed [ /pliant_security/ ] ; [or] ; fixed [ /etc/pliant/ ] ; [directory (these paths refer to the operating system root, not to Pliant root).] ; eol
  [The default access control files for the SMTP server is named] ; fixed [ mail] ; [.] ; eol
  [The access control control file is a pliant program that decides if the submitted mail is accepted, and where it must be stored. ]

[This is a sample control file that you could store in] ; fixed [ /pliant_security/mail ] ; [or] ; fixed [ /etc/pliant/mail] ; [:]
listing
  constant mycorp_domain "mycorp.com"
  constant mycorp_ip "10.0.0.0/255.0.0.0"
  constant mycorp_mails_path "/mycorp/mail/"
  if stage=stage_to
    if (to parse any:(var Str user) "@" any:(var Str domain)) and domain=mycorp_domain
      # the mail is for a user inside our domain
      if (file_query mycorp_mails_path+user+"/" standard)=defined and user<>"forward" and user<>"archive"
        # the mailbox directory exists   
        store mycorp_mails_path+user+"/"
        # we also have a mail archives directory
        archive mycorp_mails_path+"archive/"+(string received_on:year)+(right (string received_on:month) 2 "0")+"/"+(right (string received_on:day) 2 "0")+"/"
      else
        reject "There is no "+to+" mailbox here"
    else
      # the mail is for a user outside our domain
      if (ip is_inside_ip_domain mycorp_ip) or (ip is_inside_ip_domain "127.0.0.0/255.255.255.0")
        # the client was in our domain, so we are not an open relay
        forward mycorp_mails_path+"forward/"
      else
        reject "This is not an open relay"

para
  [The control function is called saveral times while the client provides informations to the server.]
  [If the mail has several recipients, the control function will be called several times with stage=stage_to.]

  table columns 2
    cell [stage_open] ; cell [The TCP connection has been etablished but no information has been sent or received yet.]
    cell [stage_helo] ; cell [The SMTP server sent the welcome message, and the client answered through a 'HELO' command.]
    cell [stage_from] ; cell [The SMTP server is trying to send a new mail: it provided the 'MAIL FROM' command.]
    cell [stage_to] ; cell [It also provided the 'RCPT TO' command.]
    cell [stage_header] ; cell [The header of the message has been received by the SMTP server.]
    cell [stage_body] ; cell [All the message has been received by the SMTP server: if we don't reject, then the client will assume that we accepted the message.]
  [Please notice that 'stage_helo' and 'stage_from' may never be executed because if the client does not provide it's identity and the message has no sender.]

[These are the variables and instructions that you may use in the messages filter function:]
table columns 3
  cell
    bold [variable]
  cell
    bold [minimal stage]
  cell
    bold [meaning]
  cell
    fixed [stage]
  cell
    void
  cell
    [The current stage, so tells you which variables are meaningfull.]
  cell
    fixed [ip]
  cell
    [stage_open]
  cell
    [The IP address of the client.]
  cell
    fixed [name]
  cell
    [stage_helo]
  cell
    [The name provided by the client through HELO SMTP protocol instruction.]
  cell
    fixed [received_on]
  cell
    [stage_open]
  cell
    [The date and time the SMTP client started sending the message.]
  cell
    fixed [mailfrom]
  cell
    [stage_from]
  cell
    [The sender mailbox as provided through the MAIL FROM SMTP protocol instruction.] ; eol
    [A sample value is:] ; fixed [ Mr Somebody <somebody@somewhere.com>]
  cell
    fixed [from]
  cell
    [stage_from]
  cell
    [The sender stripped mailbox.] ; eol
    [A sample value is:] ; fixed [ somebody@somewhere.com]
  cell
    fixed [mailto]
  cell
    [stage_to]
  cell
    [The target mailbox as provided through the RCPT TO SMTP protocol instruction.] ; eol
    [A sample value is:] ; fixed [ Mr Somebody <somebody@somewhere.com>]
  cell
    fixed [to]
  cell
    [stage_to]
  cell
    [The recipient stripped mailbox.] ; eol
    [A sample value is:] ; fixed [ somebody@somewhere.com]
  cell
    fixed [hidden_to]
  cell
    [stage_header]
  cell
    [The list of all the recipients that are not listed in the message header.] ; eol
    [This field type is 'List' and each element in the list has 'Str' type.]
  cell
    fixed [data]
  cell
    [stage_header / stage_body]
  cell
    [The stream containing the message.] ; eol
    [At stage=stage_header, only the mail header has been received, but at stage=stage_body, all the mail has been received.]
  cell
    fixed [store ] ; italic [path]
  cell
    void
  cell
    [The mail will be stored in the provided path.] ; eol
    [The path is generally the path of the recipient user mailbox.]
  cell
    fixed [archive ] ; italic [path]
  cell
    void
  cell
    [Same as 'store', but the path is one where several mailboxes are replicated for later searching.]
  cell
    fixed [exclude ] ; italic [path]
  cell
    void
  cell
    [Do not store the mail in the provided path.]
    [This enables to forbid mails from or to some confidential mailboxes to be stored in archives.]
  cell
    fixed [reject ] ; italic [message]
  cell
    void
  cell
    [Reject the mail with ] ; italic [message] ; [ being the one line explanation sent with the error code to the SMTP client.]


header "More details about Pliant SMTP server internals"

table columns 2 border 0
  cell
    link "server.pli" "server.pli"
  cell
    [contains the part of the SMTP server that will receive incoming mails and store them in mailboxes or forward queues.]
  cell
    link "forward.pli" "forward.pli"
  cell
    [contains the part of the SMTP server that will forward messages in send queues.]


header "The Pliant SMTP server implementation status"

  [The current status of the SMTP server is described in the ]
  link "SMTP server" "/pliant/welcome/project/smtp"
  [ section of the ]
  link "Pliant overall project" "/pliant/welcome/project/"
  [.]