modules/og2list/mail-in.txt

NAME
    mail-in.pl - incoming mail handler for og2list.module

Synopsis
    "mail-in.pl [-d] -f sender -t recipient"

Description
    mail-in.pl expects a mail message conforming to RfC 2822 and possibly
    containing one or more MIME parts conforming to RfC 2046ff. to be fed to
    its standard input. In the default mode of operation, it is intended to
    be run from a mail transfer agent.

    Both sender and recipient parameters are mandatory.

    If the -d ("debug") switch is set, the processed message body, along
    with some pseudo headers, is printed to standard output, instead of
    being queued. It is UTF-8 encoded.

TODO's, incorrectly/incompletely implemented issues
    * Determining sender and recipient(s) from headers that might have been
    inserted by MTA

Integration into MTA setup (Exim 4.x)
    Global
        The global section of Exim's configuration file is the place to
        define variables and installation-specific parameters such as the
        SQL location below.

        See Section 9.21 of the Exim specification for details.

        The user/group ID and the home directory need not match any other
        user account on the system, in particular not the webserver's or the
        web application's user. mail-in.pl only needs to access its
        configuration file and the og2list_* tables in the SQL database for
        which the credentials are stored in the configuration file.

          OG2LIST_HOME = /home/og2list
          OG2LIST_UID  = og2list
          OG2LIST_GID  = og2list

          hide mysql_servers = localhost/drupal/dbuser/dbpass

    Router
        Routers are rules that determine how a destination address should be
        handled. The following piece of code assigns addresses to a
        transport rule called og2list_transport which is defined below.

        Note that the since Routers are evaluated one after anotehr, their
        order in the configuration file will most likely affect overall
        behavior.

        See section 3.8 of the Exim specification for details.

          og2list:
            debug_print "R: og2list from $return_path \
              for $local_part@$domain"
            driver = accept
            transport = og2list_transport
            condition = ${lookup mysql{SELECT 1 FROM og2list_groups \
                                       WHERE recipient \
                                       LIKE '$local_part'} \
                                 {$value} \
                                 fail}

        If Exim has been built without MySQL support, the following
        condition statement should work:

            condition = ${run{/path/to/valid-recipient.pl $local_part@$domain}{1}{0}}

        It is possible to use the "domains" statement to restrict the
        domains for which the og2list is actually tried (see Exim
        specification, chapter 15 for details).

        "abuse"(RfC2142), "postmaster"(RfC2821) and other essential
        local parts should be handled by a router which precedes the
        og2list router. The system_aliases router that is part of
        Exim's default configuration file is a good place for this.

    Transport
        Transports are the rules that determine by what means a message
        should be delivered that has been assigned to this transport by a
        router.

          og2list_transport:
            debug_print "T: og2list_transport from \
              $return_path for $local_part@$domain"
            driver = pipe
            freeze_exec_fail
            log_output
            command = OG2LIST_HOME/mail-in.pl \
              -f $return_path -t $local_part@$domain
            current_directory = OG2LIST_HOME
            user = OG2LIST_UID
            group = OG2LIST_GID

Integration into MTA setup (Postfix 2.x)
    Integrating the mail-in.pl into Postfix is best done via a 'transport'.
    You will need to dedicate a complete domain or subdomain for that
    purpose. Think of it as a special purpose domain like
    lists.workaround.org where all accounts have a special meaning. The
    domain might well be a subdomain of another domain.

    main.cf
    The '/etc/postfix/main.cf' is Postfix' main configuration file. First
    you need to define the domain (as mentioned above) here as a relay
    domain:

      relay_domains = drupal.workaround.org

    If you already have relay domains configured here then just add the
    domain.

    transport
    As written initially the mail-in.pl will be used as a 'transport'.
    Transports are defined in '/etc/postfix/transport'. Just add this line
    forwarding the domain to the 'drupal:' service:

      drupal.workaround.org drupal:

    It's strongly recommended that you also add these two lines:

      abuse@drupal.workaround.org local:
      postmaster@drupal.workaround.org local:

    These forward all mails to the given email addresses to the aliases
    'abuse' and 'postmaster' that you probably already have set up in your
    '/etc/aliases' file. Every domain needs to have a person reading those
    two accounts to deal with technical mail problems or spamming attacks.

    Then usually you "hash" these files. Try 'postconf transport_maps' and
    see if the result looks like 'hash:/etc/postfix/transport'. After
    changing the '/etc/postfix/transport' file run 'postmap
    /etc/postfix/transport' and the file '/etc/postfix/transport.db' will be
    updated.

    master.cf
    Now that you told Postfix to send all mails for your special domain to
    the 'drupal:' transport you finally need to define this transport. Add
    the following lines to your '/etc/postfix/master.cf' file:

      drupal  unix  -       n       n       -       -       pipe
        flags=DRhu user=www-data argv=/path/modules/og/og2list/mail-in.pl \
                    -f ${sender} -t ${recipient}

    (Note: the first line needs to start at column 0 in your configuration
    file. Indent the next line by whitespace.)

    Restart Postfix
    Finally restart the Postfix service ('postfix reload') and try a
    'postfix check' to see whether you made any major mistakes. No output
    means that everything is well.

    Try it
    After you created a group in drupal you should be able to send mail to
    the alias you defined. Sending a mail to testgroup@drupal.workaround.org
    should create a log entry like this in your /var/log/mail.log (or
    wherever your syslog daemon writes the mail logs to):

    Apr 21 22:12:51 torf postfix/pipe[17969]: 99462FFF2:
    to=<testgroup@drupal.workaround.org>, relay=drupal, delay=1, status=sent
    (drupal.workaround.org)

Unfinished work, TODO's
    Distinguish between temporary and fatal error return codes
    ...

License
    mail-in.pl, mail handler that accepts one mail from STDIN and queues it
    to be processed by the og2list Drupal module.

    Copyright (C) 2006 Hilko Bengen

    This program is free software; you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation; either version 2 of the License, or (at your
    option) any later version.

    This program 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 GNU General
    Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

1	NAME
2	mail-in.pl - incoming mail handler for og2list.module
3
4	Synopsis
5	"mail-in.pl [-d] -f sender -t recipient"
6
7	Description
8	mail-in.pl expects a mail message conforming to RfC 2822 and possibly
9	containing one or more MIME parts conforming to RfC 2046ff. to be fed to
10	its standard input. In the default mode of operation, it is intended to
11	be run from a mail transfer agent.
12
13	Both sender and recipient parameters are mandatory.
14
15	If the -d ("debug") switch is set, the processed message body, along
16	with some pseudo headers, is printed to standard output, instead of
17	being queued. It is UTF-8 encoded.
18
19	TODO's, incorrectly/incompletely implemented issues
20	* Determining sender and recipient(s) from headers that might have been
21	inserted by MTA
22
23	Integration into MTA setup (Exim 4.x)
24	Global
25	The global section of Exim's configuration file is the place to
26	define variables and installation-specific parameters such as the
27	SQL location below.
28
29	See Section 9.21 of the Exim specification for details.
30
31	The user/group ID and the home directory need not match any other
32	user account on the system, in particular not the webserver's or the
33	web application's user. mail-in.pl only needs to access its
34	configuration file and the og2list_* tables in the SQL database for
35	which the credentials are stored in the configuration file.
36
37	OG2LIST_HOME = /home/og2list
38	OG2LIST_UID = og2list
39	OG2LIST_GID = og2list
40
41	hide mysql_servers = localhost/drupal/dbuser/dbpass
42
43	Router
44	Routers are rules that determine how a destination address should be
45	handled. The following piece of code assigns addresses to a
46	transport rule called og2list_transport which is defined below.
47
48	Note that the since Routers are evaluated one after anotehr, their
49	order in the configuration file will most likely affect overall
50	behavior.
51
52	See section 3.8 of the Exim specification for details.
53
54	og2list:
55	debug_print "R: og2list from $return_path \
56	for $local_part@$domain"
57	driver = accept
58	transport = og2list_transport
59	condition = ${lookup mysql{SELECT 1 FROM og2list_groups \
60	WHERE recipient \
61	LIKE '$local_part'} \
62	{$value} \
63	fail}
64
65	If Exim has been built without MySQL support, the following
66	condition statement should work:
67
68	condition = ${run{/path/to/valid-recipient.pl $local_part@$domain}{1}{0}}
69
70	It is possible to use the "domains" statement to restrict the
71	domains for which the og2list is actually tried (see Exim
72	specification, chapter 15 for details).
73
74	"abuse"(RfC2142), "postmaster"(RfC2821) and other essential
75	local parts should be handled by a router which precedes the
76	og2list router. The system_aliases router that is part of
77	Exim's default configuration file is a good place for this.
78
79	Transport
80	Transports are the rules that determine by what means a message
81	should be delivered that has been assigned to this transport by a
82	router.
83
84	og2list_transport:
85	debug_print "T: og2list_transport from \
86	$return_path for $local_part@$domain"
87	driver = pipe
88	freeze_exec_fail
89	log_output
90	command = OG2LIST_HOME/mail-in.pl \
91	-f $return_path -t $local_part@$domain
92	current_directory = OG2LIST_HOME
93	user = OG2LIST_UID
94	group = OG2LIST_GID
95
96	Integration into MTA setup (Postfix 2.x)
97	Integrating the mail-in.pl into Postfix is best done via a 'transport'.
98	You will need to dedicate a complete domain or subdomain for that
99	purpose. Think of it as a special purpose domain like
100	lists.workaround.org where all accounts have a special meaning. The
101	domain might well be a subdomain of another domain.
102
103	main.cf
104	The '/etc/postfix/main.cf' is Postfix' main configuration file. First
105	you need to define the domain (as mentioned above) here as a relay
106	domain:
107
108	relay_domains = drupal.workaround.org
109
110	If you already have relay domains configured here then just add the
111	domain.
112
113	transport
114	As written initially the mail-in.pl will be used as a 'transport'.
115	Transports are defined in '/etc/postfix/transport'. Just add this line
116	forwarding the domain to the 'drupal:' service:
117
118	drupal.workaround.org drupal:
119
120	It's strongly recommended that you also add these two lines:
121
122	abuse@drupal.workaround.org local:
123	postmaster@drupal.workaround.org local:
124
125	These forward all mails to the given email addresses to the aliases
126	'abuse' and 'postmaster' that you probably already have set up in your
127	'/etc/aliases' file. Every domain needs to have a person reading those
128	two accounts to deal with technical mail problems or spamming attacks.
129
130	Then usually you "hash" these files. Try 'postconf transport_maps' and
131	see if the result looks like 'hash:/etc/postfix/transport'. After
132	changing the '/etc/postfix/transport' file run 'postmap
133	/etc/postfix/transport' and the file '/etc/postfix/transport.db' will be
134	updated.
135
136	master.cf
137	Now that you told Postfix to send all mails for your special domain to
138	the 'drupal:' transport you finally need to define this transport. Add
139	the following lines to your '/etc/postfix/master.cf' file:
140
141	drupal unix - n n - - pipe
142	flags=DRhu user=www-data argv=/path/modules/og/og2list/mail-in.pl \
143	-f ${sender} -t ${recipient}
144
145	(Note: the first line needs to start at column 0 in your configuration
146	file. Indent the next line by whitespace.)
147
148	Restart Postfix
149	Finally restart the Postfix service ('postfix reload') and try a
150	'postfix check' to see whether you made any major mistakes. No output
151	means that everything is well.
152
153	Try it
154	After you created a group in drupal you should be able to send mail to
155	the alias you defined. Sending a mail to testgroup@drupal.workaround.org
156	should create a log entry like this in your /var/log/mail.log (or
157	wherever your syslog daemon writes the mail logs to):
158
159	Apr 21 22:12:51 torf postfix/pipe[17969]: 99462FFF2:
160	to=<testgroup@drupal.workaround.org>, relay=drupal, delay=1, status=sent
161	(drupal.workaround.org)
162
163	Unfinished work, TODO's
164	Distinguish between temporary and fatal error return codes
165	...
166
167	License
168	mail-in.pl, mail handler that accepts one mail from STDIN and queues it
169	to be processed by the og2list Drupal module.
170
171	Copyright (C) 2006 Hilko Bengen
172
173	This program is free software; you can redistribute it and/or modify it
174	under the terms of the GNU General Public License as published by the
175	Free Software Foundation; either version 2 of the License, or (at your
176	option) any later version.
177
178	This program is distributed in the hope that it will be useful, but
179	WITHOUT ANY WARRANTY; without even the implied warranty of
180	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
181	Public License for more details.
182
183	You should have received a copy of the GNU General Public License along
184	with this program; if not, write to the Free Software Foundation, Inc.,
185	51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
186