Read Me

Postfix DICT HTTP Howto

-------------------------------------------------------------------------------

Introduction

The Postfix http map type allows you to hook up Postfix to a http server with 
HTTP protocol, such as apache lighttpd nginx, etc. You need to write a 
CGI/FastCGI with C CPP Perl PHP etc, to complete the query from your 
proprietary database. You can specify multiple servers for the same http map, 
so that Postfix can switch to a good http server if one goes bad.


Building Postfix with Http support

Get postfix source code from:
    http://www.postfix.org/download.html

    tar xfz postfix-2.x.x.tar.gz
    cd postfix-2.x.x
    patch -p1 -d ./ < ../postfix-2.x.x_with_dict_http.patch

Then you can build Postfix from source code as described in the INSTALL document. 


Using HTTP map

Once Postfix is built with http support, you can specify a map type in main.cf
like this:

    alias_maps = http:/etc/postfix/http-aliases.cf

The file /etc/postfix/http-aliases.cf specifies lots of information telling
Postfix how to reference the http server. For a complete description, see
the http_table_sample.cf document.


PROTOCOL DESCRIPTION

The HTTP map class implements a very simple HTTP protocol: the client 
sends a request, and the server sends one reply. Requests and replies 
are sent as http header text, terminated by the double newline character. 
Request and reply parameters (see below).


REQUEST FORMAT

Each request is http header.
The lookup key is the value of key "POSTFIX-DICT-EMAIL" 
like this:

    GET /url_can_be_configured_by/http_table_sample.cf  HTTP/1.1
    POSTFIX-DICT-EMAIL: username@domain.com
    Keep-Alive: 300
    Connection: keep-alive
    Pragma: no-cache
    Cache-Control: no-cache


REPLY FORMAT

Each reply specifies a status code, error message and results data. 
Replies must be no longer than 4096 characters including the newline
terminator.
like this:

    HTTP/1.1 200 OK
    Server: xxxxxxxxxxxxxxx
    Date: Fri, 10 Dec 2000 00:00:00 GMT
    Connection: keep-alive
    Content-Length: 0
    POSTFIX-DICT-RETCODE: 200
    POSTFIX-DICT-RETMSG: 
    POSTFIX-DICT-RESULTS: separated by a space if multi-results


POSTFIX_DICT_RETCODE:
    2XX: The request was successful. The value of key 
         "POSTFIX_DICT_RESULTS" is results. If the requested 
         data does not exist, please let the result is empty.

    Other: This indicates an error condition. The value of key 
           "POSTFIX_DICT_RETMSG" describes the nature of the 
           problem. The client should retry the request later.

POSTFIX_DICT_RETMSG:
    As described the nature of the problem.
  
POSTFIX_DICT_RESULTS:
    The results of the query request data. If multiple results 
    let results separated by a space. If the requested data 
    does not exist, please let the result is empty.


SECURITY

Do not use HTTP lookup tables for security critical pur-
poses. The client-server connection is not protected and
the server is not authenticated.


Additional notes

The Http configuration interface setup allows for multiple http servers:
you can use one for a virtual table, one for an access table, and one for an
aliases table if you want.

Since sites that have a need for multiple mail exchangers may enjoy the
convenience of using a networked mailer database, but do not want to introduce
a single point of failure to their system, we've included the ability to have
Postfix reference multiple hosts for access to a single http map. This will
work if sites set up mirrored back-end databases on two or more http server 
hosts. Whenever queries fail with an error at one host, the rest of the hosts 
will be tried in random order. If no http server hosts are reachable, then 
mail will be deferred until at least one of those hosts is reachable.


Credits

    Xiaohua Jia
    xhjz@hotmail.com  
    Beijing, PRC 100013
    
    This project: 
        https://sourceforge.net/projects/postlookup-http/