User:Austin J. Che/Extensions/Wikilist

From OpenWetWare

< User:Austin J. Che | Extensions(Difference between revisions)
Jump to: navigation, search
Current revision (18:30, 17 November 2007) (view source)
 
(7 intermediate revisions not shown.)
Line 5: Line 5:
To send an email, you can go to the special page [[Special:Wikilist]] and enter the name of a page. A direct link to email members of a page is of the form <nowiki>[[Special:Wikilist/Pagename]]</nowiki>
To send an email, you can go to the special page [[Special:Wikilist]] and enter the name of a page. A direct link to email members of a page is of the form <nowiki>[[Special:Wikilist/Pagename]]</nowiki>
-
In addition, the To address of the message is a real email address so that the email can be replied to by anyone using any email client (see technical details).
+
In addition, the To address of the message is a real email address so that the email can be replied to by anyone using any email client. An arbitrary page is used as an mailing list by using its article ID so an email address looks like 12345@mail.domain.com. To make a more human readable list, pages under a defined namespace e.g. "List" can be used. Thus, foo@mail.domain.com will use the page at List:foo.
 +
 
 +
Note that page names on the wiki are much more relaxed than allowed email addresses. For the named form for lists, it is up to users to create valid pages that mail servers will accept as valid email addresses. Recommendations:
 +
* names should be all lowercase (first letter may be uppercased automatically by wiki but that's fine)
 +
* only use alphanumeric, -, _ characters and keep it less than 50 characters
 +
** The RFC says that the local part before the @ can be a max of 64 chars, but I wouldn't push it
==Technical Details==
==Technical Details==
 +
The basic logic of mail delivery:
 +
* The internal wiki article ID or page name under a specific namespace uniquely identifies a list.
 +
* This allows us to create list addresses of the form wikilist+listID@real.domain.
 +
* In addition, with clean addresses, listID@some.domain redirects to the above.
 +
* When someone goes to the Special:Wikilist page, a single email is sent to the list address above.
 +
* When a message is received by the mail server at the list address (either from someone's email client or from the wiki), the mail is directed to local user wikilist.
 +
* User (or alias) wikilist runs procmail with the listID as the first argument.
 +
* The user's procmailrc passes the listID to the wikilist.php script.
 +
* wikilist.php looks up the list and extracts the list recipients.
 +
* The message is resent via the local mailer to the list recipients.
 +
 +
===Installation===
There are three files for installation:
There are three files for installation:
-
# SpecialWikilist.php (main file that mainly creates the Special page)
+
# SpecialWikilist.php (creates the Special page on the wiki)
# wikilist.php (designed to be run from the command line and resends email to a list)
# wikilist.php (designed to be run from the command line and resends email to a list)
# wikilist.procmailrc (a procmail script whose main job is to call wikilist.php)
# wikilist.procmailrc (a procmail script whose main job is to call wikilist.php)
-
SpecialWikilist.php should be installed in the wiki extensions directory and require'd from LocalSettings.php. In addition, the variable $wgWikilistEmailHost must be set to the name of your email host name. It is probably easiest if the email host is the same physical machine as your wiki server unless your email server has access to the wiki database to look up the members of the list.
+
SpecialWikilist.php should be installed in the wiki extensions directory and require'd from LocalSettings.php.  
-
Your MTA must support plus addressing (where user+foo@domain is sent to user and the extra foo is ignored). Some mailers use '-' instead of '+' which is fine if you set $wgWikilistMailExtension to something other than the default of '+'. The other variable to be aware of is $wgWikilistEmailUser which is by default 'wikilist' and will be the user part of the email address. Some example setups that I've tried are:
+
Make sure the user running procmail has read permissions on wikilist.php and LocalSettings.php (can be user wikilist, nobody, or something else depending on your setup). The procmailrc file permissions need to be set carefully. The easiest permissions are to set the owner of the directory and .procmailrc to root, make it world readable, and only user writable.
-
* Postfix: add to /etc/aliases <tt>wikilist: "|/path/to/procmail -m /path/to/wikilist.procmailrc $EXTENSION"</tt>
+
===Configuration===
-
** When mail comes for wikilist+extension@domain, postfix will automatically pass the extension to the procmail script using the variable $EXTENSION
+
Configuration variables (in LocalSettings.php):
-
* Sendmail: local delivery should be set up to go through procmail. A user called wikilist should be created in /etc/passwd with some new home directory. Move the wikilist.procmailrc to this new directory, rename it .procmailrc, and set the right permissions. The easiest permissions are to set the owner of the directory and .procmailrc to root, make it world readable, and only user writable.
+
* $wgWikilistEmailHost: email host. Default none and this MUST be set.
 +
** It is probably easiest if the email host is the same physical machine as your wiki server unless your email server has access to the wiki database to look up the members of the list. Note that if you will use the clean form of email addresses, i.e. anything@mail.domain.com can be a wiki list, then it is recommended to use a virtual mail domain that has no other real addresses. You CAN use the same domain as your normal email host, but users on the wiki will need to know what local addresses exist and cannot be used for a wikilist.
 +
* $wgExtraNamespaces: add new namespace if you wish, although you can use an existing one like the main namespace
 +
* $wgWikilistNamespace: The namespace to use for named lists. Default NS_MAIN.
 +
* $wgWikilistEmailPrefix: this will be prefixed to the email address. Default is none and you only need to set this when not using clean addresses.
 +
Some paths may need to be updated at the top of the wikilist.procmailrc and wikilist.php files (for example the path to php and sendmail). The procmailrc file will also likely need to be changed for your local system configuration. The example procmailrc file takes into account the virtual email host domain which you are unlikely to need (the configuration is for openwetware that has many subwikis).
-
Some paths may need to be updated at the top of the wikilist.procmailrc and wikilist.php files (for example the path to php and sendmail). Also, make sure the user running procmail has read permissions on wikilist.php and LocalSettings.php (can be user wikilist, nobody, or something else depending on your setup).
+
===Normal Addressing===
-
The basic logic of mail delivery:
+
Note: there are probably other ways of implementing this delivery with your MTA. This is just one way I know works. The end goal is to call wikilist.php with the name/ID of the list when emails come in. Let me know if there are alternative or simpler ways.
-
* We use the internal wiki article ID to uniquely represent every page.
+
-
* This ID allows us to create arbitrary list addresses of the form wikilist+ID@domain.
+
-
* When someone goes to the Special page, a single email is sent to the list address above.
+
-
* When a message is received by the mail server at the list address (either from someone's email client or from the Special page on the wiki), the mail is directed to user wikilist.
+
-
* User (or alias) wikilist runs procmail with the list ID as the first argument.
+
-
* The user's procmailrc passes the list ID to the wikilist.php script.
+
-
* wikilist.php looks up the list ID and extracts the list recipients.
+
-
* The message is resent via the local mailer to the list recipients.
+
 +
Your MTA must support plus addressing (where user+foo@domain is sent to user and the extra foo is ignored). Some mailers use '-' instead of '+' which is fine. Set $wgWikilistEmailPrefix to what should be added before the list name (e.g. "wikilist+"). This will make the address for list foo be wikilist+foo@real.domain.
 +
 +
* Postfix: see example below.
 +
* Sendmail: local delivery should be set up to go through procmail. A user called wikilist should be created in /etc/passwd with some new home directory. Move the wikilist.procmailrc to this new directory, rename it .procmailrc, and set the right permissions.
 +
 +
===Clean Addresses===
 +
To allow list@some.domain work, we redirect all such addresess to the wikilist+list@real.domain set up above. This depends on your MTA. An example for Postfix is below.
 +
 +
===Example config with Postfix with a virtual mail domain===
 +
LocalSettings.php:
 +
<pre>
 +
define('NS_LIST', 100);
 +
define('NS_LIST_TALK', 101);
 +
$wgExtraNamespaces = array(NS_LIST => "List", NS_LIST_TALK => "List talk");
 +
$wgWikilistNamespace = NS_LIST;
 +
$wgWikilistEmailHost = "lists.openwetware.org";
 +
</pre>
 +
 +
/etc/aliases:
 +
<pre>wikilist: "|/path/to/procmail -m /path/to/wikilist.procmailrc $EXTENSION"</pre>
 +
main.cf:
 +
<pre>
 +
mydestination = (includes openwetware.org but not lists.openwetware.org)
 +
virtual_alias_maps = regexp:/etc/postfix/virtual
 +
virtual_alias_domains = hash:/etc/postfix/virtual_domains
 +
</pre>
 +
/etc/postfix/virtual_domains:
 +
<pre>
 +
# right hand side doesn't matter
 +
lists.openwetware.org OK
 +
</pre>
 +
/etc/postfix/virtual:
 +
<pre>
 +
/(.*)@lists.openwetware.org/ wikilist+$1@openwetware.org
 +
</pre>
 +
 +
===Example config with Postfix using one mail domain===
 +
LocalSettings.php:
 +
<pre>
 +
define('NS_LIST', 100);
 +
define('NS_LIST_TALK', 101);
 +
$wgExtraNamespaces = array(NS_LIST => "List", NS_LIST_TALK => "List talk");
 +
$wgWikilistNamespace = NS_LIST;
 +
$wgWikilistEmailHost = "lists.openwetware.org";
 +
</pre>
 +
 +
/etc/aliases:
 +
<pre>wikilist: "|/path/to/procmail -m /path/to/wikilist.procmailrc $EXTENSION"</pre>
 +
main.cf:
 +
<pre>
 +
luser_relay = wikilist+$local@$domain
 +
# the following is required for luser_relay to work
 +
local_recipient_maps =
 +
</pre>
----
----
-
Send bugs and comments to [[Austin Che]]. Other extensions including sources can be found at [[../]].
+
Send bugs and comments to [[Austin Che]]. Other extensions including sources can be found at [[../]].
 +
 
 +
[[Category:Extensions]]

Current revision

Contents

Usage

This extension allows any wiki page to be used as an email list. All links on a page of the form [[User:username]] (such as that formed by signing a page) are used as the members of the list. Duplicates are removed. Emails are sent to the user address stored in the wiki and only if emails are enabled from other users (under user preferences).

To send an email, you can go to the special page Special:Wikilist and enter the name of a page. A direct link to email members of a page is of the form [[Special:Wikilist/Pagename]]

In addition, the To address of the message is a real email address so that the email can be replied to by anyone using any email client. An arbitrary page is used as an mailing list by using its article ID so an email address looks like 12345@mail.domain.com. To make a more human readable list, pages under a defined namespace e.g. "List" can be used. Thus, foo@mail.domain.com will use the page at List:foo.

Note that page names on the wiki are much more relaxed than allowed email addresses. For the named form for lists, it is up to users to create valid pages that mail servers will accept as valid email addresses. Recommendations:

  • names should be all lowercase (first letter may be uppercased automatically by wiki but that's fine)
  • only use alphanumeric, -, _ characters and keep it less than 50 characters
    • The RFC says that the local part before the @ can be a max of 64 chars, but I wouldn't push it

Technical Details

The basic logic of mail delivery:

  • The internal wiki article ID or page name under a specific namespace uniquely identifies a list.
  • This allows us to create list addresses of the form wikilist+listID@real.domain.
  • In addition, with clean addresses, listID@some.domain redirects to the above.
  • When someone goes to the Special:Wikilist page, a single email is sent to the list address above.
  • When a message is received by the mail server at the list address (either from someone's email client or from the wiki), the mail is directed to local user wikilist.
  • User (or alias) wikilist runs procmail with the listID as the first argument.
  • The user's procmailrc passes the listID to the wikilist.php script.
  • wikilist.php looks up the list and extracts the list recipients.
  • The message is resent via the local mailer to the list recipients.

Installation

There are three files for installation:

  1. SpecialWikilist.php (creates the Special page on the wiki)
  2. wikilist.php (designed to be run from the command line and resends email to a list)
  3. wikilist.procmailrc (a procmail script whose main job is to call wikilist.php)

SpecialWikilist.php should be installed in the wiki extensions directory and require'd from LocalSettings.php.

Make sure the user running procmail has read permissions on wikilist.php and LocalSettings.php (can be user wikilist, nobody, or something else depending on your setup). The procmailrc file permissions need to be set carefully. The easiest permissions are to set the owner of the directory and .procmailrc to root, make it world readable, and only user writable.

Configuration

Configuration variables (in LocalSettings.php):

  • $wgWikilistEmailHost: email host. Default none and this MUST be set.
    • It is probably easiest if the email host is the same physical machine as your wiki server unless your email server has access to the wiki database to look up the members of the list. Note that if you will use the clean form of email addresses, i.e. anything@mail.domain.com can be a wiki list, then it is recommended to use a virtual mail domain that has no other real addresses. You CAN use the same domain as your normal email host, but users on the wiki will need to know what local addresses exist and cannot be used for a wikilist.
  • $wgExtraNamespaces: add new namespace if you wish, although you can use an existing one like the main namespace
  • $wgWikilistNamespace: The namespace to use for named lists. Default NS_MAIN.
  • $wgWikilistEmailPrefix: this will be prefixed to the email address. Default is none and you only need to set this when not using clean addresses.

Some paths may need to be updated at the top of the wikilist.procmailrc and wikilist.php files (for example the path to php and sendmail). The procmailrc file will also likely need to be changed for your local system configuration. The example procmailrc file takes into account the virtual email host domain which you are unlikely to need (the configuration is for openwetware that has many subwikis).

Normal Addressing

Note: there are probably other ways of implementing this delivery with your MTA. This is just one way I know works. The end goal is to call wikilist.php with the name/ID of the list when emails come in. Let me know if there are alternative or simpler ways.

Your MTA must support plus addressing (where user+foo@domain is sent to user and the extra foo is ignored). Some mailers use '-' instead of '+' which is fine. Set $wgWikilistEmailPrefix to what should be added before the list name (e.g. "wikilist+"). This will make the address for list foo be wikilist+foo@real.domain.

  • Postfix: see example below.
  • Sendmail: local delivery should be set up to go through procmail. A user called wikilist should be created in /etc/passwd with some new home directory. Move the wikilist.procmailrc to this new directory, rename it .procmailrc, and set the right permissions.

Clean Addresses

To allow list@some.domain work, we redirect all such addresess to the wikilist+list@real.domain set up above. This depends on your MTA. An example for Postfix is below.

Example config with Postfix with a virtual mail domain

LocalSettings.php:

define('NS_LIST', 100);
define('NS_LIST_TALK', 101);
$wgExtraNamespaces = array(NS_LIST => "List", NS_LIST_TALK => "List talk");
$wgWikilistNamespace = NS_LIST;
$wgWikilistEmailHost = "lists.openwetware.org";

/etc/aliases:

wikilist: "|/path/to/procmail -m /path/to/wikilist.procmailrc $EXTENSION"

main.cf:

mydestination = (includes openwetware.org but not lists.openwetware.org)
virtual_alias_maps = regexp:/etc/postfix/virtual
virtual_alias_domains = hash:/etc/postfix/virtual_domains

/etc/postfix/virtual_domains:

# right hand side doesn't matter
lists.openwetware.org OK

/etc/postfix/virtual:

/(.*)@lists.openwetware.org/ wikilist+$1@openwetware.org

Example config with Postfix using one mail domain

LocalSettings.php:

define('NS_LIST', 100);
define('NS_LIST_TALK', 101);
$wgExtraNamespaces = array(NS_LIST => "List", NS_LIST_TALK => "List talk");
$wgWikilistNamespace = NS_LIST;
$wgWikilistEmailHost = "lists.openwetware.org";

/etc/aliases:

wikilist: "|/path/to/procmail -m /path/to/wikilist.procmailrc $EXTENSION"

main.cf:

luser_relay = wikilist+$local@$domain
# the following is required for luser_relay to work
local_recipient_maps =

Send bugs and comments to Austin Che. Other extensions including sources can be found at User:Austin J. Che/Extensions.

Personal tools