Dada Bridge - Discussion Lists and Email Sending from your Mail Reader

Dada Bridge

User Guide

The below documentation go into detail on how to install and configure Dada Bridge. A user guide for Dada Bridge is available in the Dada Mail Manual chapter, Using Dada Bridge:

http://dadamailproject.com/pro_dada/using_dada_bridge.html

Description

Dada Bridge is a plugin for Dada Mail that adds support to send email from your mail reader to a Dada Mail mailing list, both for announce-only tasks and discussion lists.

Dada Bridge allows you to do two things, fairly easily:

  • Set up an Announce-Only list.

    Dada Bridge allows you to send an email message to the List Email address, which will then be sent to your entire mailing list.

  • Set up a Discussion List.

    Anyone subscribed to your mailing list will be able send an email to the List Email Address, which will then be sent to the entire mailing list. Anyone else may reply to messages sent to the same mailing list.

There's some advantages to using Dada Bridge over more sophisticated programs:

Having solved these two problems also makes Dada Bridge potentially more secure to use and opens its use to a wider audience.

How does Dada Bridge work?

Many of Dada Bridge's concepts are slightly different than what you may be used to in traditional mailing lists:

  • Subscription/Unsubscription requests are handled via Dada Mail itself

    In other words, it's all web-based. There are currently no subscription mechanisms that use email commands.

  • A, "List Email" is just a POP3 email account.

    In Dada Mail, the List Email is the address you send to when you want to post a message to the list. This differs from the, List Owner email, which is the address that messages will be sent on behalf of (unless discussion lists are enabled).

    Usually in a mailing list manager, this address is created automatically by the program itself. In Dada Mail, you'll have to manually create the email (POP3) account and plug in the email address, POP3 server and username/password into Dada Mail.

    This allows anyone who can make POP3 accounts to have a discussion mailing list. You also have a whole lot of flexibility when it comes to what the List Email can be.

    In normal use, Dada Bridge will check this account and deliver any messages it finds accordingly. When in normal use, do not check this account yourself.

Requirements

Recommendations

  • Setup Dada Mail using the SQL Backend.

    Multipart messages, attachments and inline embedded images will work very well if you use the SQL Backend.

  • Disable Javascript in Archived Messages

    In Dada Mail's List control panel under, Message Archives - # Advanced Archive Options, check the option, Disable Javascript in Archived Messages . This will prevent exploitations embedded in messages sent to the mailing list when viewed in Dada Mail's own archives. Along with Javascript, this option will strip out: embed, object, frame, iframe, and meta tags.

    This feature does require the use of a CPAN module called, HTML::Scrubber, which you may have to install yourself:

    http://search.cpan.org/dist/HTML-Scrubber/

    If you do not have this available, I do urgently suggest you do not use archiving for discussion lists.

Obtaining The Plugin

Dada Bridge is located in the, dada/plugins directory of the Dada Mail distribution, under the name: dada_bridge.pl

Installation

This plugin can be installed during a Dada Mail install/upgrade, using the included installer that comes with Dada Mail. The below installation instructions go through how to install the plugin manually.

If you install the plugin using the Dada Mail installer, you will still have set the cronjob manually, which is covered below.

Lightning Configuration/Installation Instructions

Configuration/Installation Screencasts

Configuring and Installing (and Using) Dada Bridge is covered in two screencasts:

Part 1

http://www.youtube.com/watch

Part 2

http://www.youtube.com/watch

Installation

Before we get into installation, here's how Dada Bridge is used:

One part of Dada Bridge is run as a Dada Mail plugin - you'll have to log into your list before you're able to make any changes to its settings.

The second part of Dada Bridge is the part that actually looks for any new mail to be examined and hopefully, broadcasted and sent out to your list. This part of Dada Bridge is usually run via a cronjob.

There's a few ways that Dada Bridge can do the second part, and we'll go in detail on how to set up both ways.

Configuring Dada Bridge's Plugin Side

#1 Change the permissions of the, dada_bridge.pl script to, "755"

Find the dada_bridge.pl script in your dada/plugins directory. Change its permissions to, 755

#2 Configure your outside config file (.dada_config)

You'll most likely want to edit your outside config file (.dada_config) so that it shows Dada Bridge in the left-hand menu, under the, Plugins heading.

First, see if the following lines are present in your .dada_config file:

 # start cut for list control panel menu
 =cut
 =cut
 # end cut for list control panel menu

If they are, remove them.

Then, find these lines:

 #                                      {-Title      => 'Discussion Lists',
 #                                       -Title_URL  => $PLUGIN_URL."/dada_bridge.pl",
 #                                       -Function   => 'dada_bridge',
 #                                       -Activated  => 1,
 #                                      },

Uncomment the lines, by taking off the, "#"'s:

                                        {-Title      => 'Discussion Lists',
                                         -Title_URL  => $PLUGIN_URL."/dada_bridge.pl",
                                         -Function   => 'dada_bridge',
                                         -Activated  => 1,
                                        },

Save your .dada_config file.

You can now log into your List Control Panel and under the, plugins heading you should now see a linked entitled, "Discussion lists". Clicking that will allow you to set up your list to receive mail from a mail reader.

Messages will not yet be received and sent out via Dada Bridge.

For that to happen - two things will have to be configured. The first is setting up the List Email - that's done in the control panel for the plugin itself and should (hopefully) be self-explanitory.

The second is to set up the cronjob and that's what we'll talk about next:

Configuring the Cronjob to Automatically Run Dada Bridge

We're going to assume that you already know how to set up the actual cronjob, but we'll be explaining in depth on what the cronjob you need to set is.

Setting the cronjob

Generally, setting the cronjob to have Dada Bridge run automatically just means that you have to have a cronjob access a specific URL. The URL looks something like this:

 http://example.com/cgi-bin/dada/plugins/dada_bridge.pl?run=1&verbose=1

Where, http://example.com/cgi-bin/dada/plugins/dada_bridge.pl is the URL to your copy of dada_bridge.pl

You'll see the specific URL used for your installation of Dada Mail in the web-based control panel for Dada Bridge, under the fieldset legend, Manually Run Dada Bridge. under the heading, Manual Run URL:

This will have Dada Bridge check any awaiting messages.

You may have to look through your hosting account's own FAQ, Knowledgebase and/or other docs to see exactly how you invoke a URL via a cronjob.

A Pretty Good Guess of what the entire cronjob should be set to is located in the web-based crontrol panel for Dada Bridge, under the fieldset legend, Manually Run Dada Bridge, under the heading, curl command example (for a cronjob):

From my testing, this should work for most Cpanel-based hosting accounts.

Here's the entire cronjob explained:

In this example, I'll be running the script every 5 minutes ( */5 * * * * ) - tailor to your taste.

        */5 * * * * /usr/local/bin/curl -s --get --data run=1\;verbose=0\; --url http://example.com/cgi-bin/dada/plugins/dada_bridge.pl

Disallowing running Dada Bridge manually (via URL)

If you DO NOT want to use this way of invoking the program to check awaiting messages and send them out, make sure to set the plugin config variable (which we'll cover below) Allow_Manual_Run to, 0.

Security Concerns "Manual_Run_Passcode"

Running the plugin like this is somewhat risky, as you're allowing an anonymous web browser to run the script in a way that was originally designed to only be run either after successfully logging into the list control panel, or, when invoking this script via the command line.

If you'd like, you can set up a simple Passcode, to have some semblence of security over who runs the program. Do this by setting the, plugin config (again, we'll cover plugin configs, below), Manual_Run_Passcode to a password-like string:

        Manual_Run_Passcode                 => 'sneaky',

In this example, you'll then have to change the URL in these examples to:

 http://example.com/cgi-bin/dada/plugins/dada_bridge.pl?run=1&passcode=sneaky

Other options you may pass

You can control quite a few things by setting variables right in the query string:

  • passcode

    As mentioned above, the Manual_Run_Passcode allows you to set some sort of security while running in this mode. Passing the actual password is done in the query string:

     http://example.com/cgi-bin/dada/plugins/dada_bridge.pl?run=1&passcode=sneaky
  • verbose

    By default, you'll receive the a report of how Dada Bridge is doing downloading awaiting messages, validating them and sending them off.

    This is sometimes not so desired, especially in a cron environment, since all this informaiton will be emailed to you (or someone) everytime the script is run. You can run Dada Bridge with a cron that looks like this:

     */5 * * * * /usr/local/bin/curl -s --get --data run=1 --url http://example.com/cgi-bin/dada/plugins/dada_bridge.pl >/dev/null 2>&1

    The, >/dev/null 2>&1 line throws away any values returned.

    Since all the information being returned from the program is done sort of indirectly, this also means that any problems actually running the program will also be thrown away.

    If you set verbose to, 0, under normal operation, Dada Bridge won't show any output, but if there's a server error, you'll receive an email about it. This is probably a good thing. Example:

     * * * * * /usr/local/bin/curl -s --get --data run=1\;verbose=0 --url http://example.com/cgi-bin/dada/plugins/dada_bridge.pl
  • test

    Runs Dada Bridge in test mode by checking the messages awaiting and parsing them, but not actually carrying out any sending.

Notes on Setting the Cronjob for curl

You may want to check your version of curl and see if there's a speific way to pass a query string. For example, this:

 */5 * * * * /usr/local/bin/curl -s http://example.com/cgi-bin/dada/plugins/dada_bridge.pl?run=1&passcode=sneaky

Doesn't work for me.

I have to use the --get and --data flags, like this:

 */5 * * * * /usr/local/bin/curl -s --get --data run=1\;passcode=sneaky --url http://example.com/cgi-bin/dada/plugins/dada_bridge.pl

my query string is this part:

 run=1\;passcode=sneaky

And also note I had to escape the, ; character. You'll probably have to do the same for the & character.

Finally, I also had to pass the actual URL of the plugin using the --url flag.

Command Line Interface

There's a slew of optional arguments you can give to this script. To use Dada Bridge via the command line, first change into the directory that Dada Bridge resides in, and issue the command:

 ./dada_bridge.pl --help

Command Line Interface for Cronjobs:

You can also invoke dada_bridge.pl from the command line interface for cronjobs. The secret is to actually have two commands in one. The first command changes into the same directory as the dada_bridge.pl script, the second invokes the script with the paramaters you'd like.

For example:

 */5 * * * * cd /home/myaccount/cgi-bin/dada/plugins; /usr/bin/perl ./dada_bridge.pl  >/dev/null 2>&1

Where, /home/myaccount/cgi-bin/dada/plugins is the full path to the directory the dada_bridge.pl script is located.

Remember to enable sending using this method!

By default, the ability for dada_bridge.pl to send and receive messages is disabled on a per-list basis. To enable sending, log into your list control panel and go to the dada_bridge.pl admin screen.

Uncheck:

 Disable sending using this method

And you're off to the races.

Plugin Configuration Settings

The below settings are available to you, if you wish to further configure the plugin. You'll find the settings within the plugin itself - look at the top of the, dada_bridge.pl script.

BUT, we suggest that you set these plugin config settings in your outside config file (.dada_config).

First, search and see if the following lines are present in your .dada_config file:

 # start cut for plugin configs
 =cut
 =cut
 # end cut for plugin configs

If they are present, remove them.

You can then configure the plugin variables on these lines:

        Dada_Bridge => {
                Plugin_Name                         => undef,
                Plugin_URL                          => undef,
                Allow_Manual_Run                    => undef,
                Manual_Run_Passcode                 => undef,
                MessagesAtOnce                      => undef,
                Soft_Max_Size_Of_Any_Message        => undef,
                Max_Size_Of_Any_Message             => undef,
                Allow_Open_Discussion_List          => undef,
                Room_For_One_More_Check             => undef,
                Enable_POP3_File_Locking            => undef,
                Check_List_Owner_Return_Path_Header => undef,
                Check_Multiple_Return_Path_Headers  => undef,
        },

Plugin_Name

The name of the plugin. By default, Dada Bridge.

Plugin_URL

Sometimes, the plugin has a hard time guessing what its own URL is. If this is happening, you can manually set the URL of the plugin in Plugin_URL.

Allow_Manual_Run

Allows you to invoke the plugin to check and send awaiting messages via a URL.

Manual_Run_Passcode

Allows you to set a passcode if you want to allow manually running the plugin.

MessagesAtOnce

You can specify how many messages you want to have the program actually handle per execution of the script by changing the, MessagesAtOnce variable. By default, it's set conservatively to, 1.

Soft_Max_Size_Of_Any_Message

Like its brethren, Max_Size_Of_Any_Message Soft_Max_Size_Of_Any_Message sets the maximum size of a message that's accepted, but If the message falls between, Soft_Max_Size_Of_Any_Message and, Max_Size_Of_Any_Message a, "Your email message is too big!" email message will be sent to the original poster.

Set the size in octects.

Max_Size_Of_Any_Message

Sets a hard limit on how large a single message can actually be, before you won't allow the message to be processed. If a message is too large, it'll be simple deleted. A warning will be written in the error log, but the original sender will not be notified.

Allow_Open_Discussion_List

If set to, 1 a new option will be available in Dada Bridge's list control panel to allow you to have a discussion list that anyone can send messages to.

Room_For_One_More_Check

Room_For_One_More_Check looks to see how many mass mailings are currently happening. If its at or above the limit set in $MAILOUT_AT_ONCE_LIMIT, Dada Bridge will not attempt to look for and (possibly) create another mass mailing to join the queue.

Enable_POP3_File_Locking

Enable_POP3_File_Locking. Sometimes, the pop3 locking stuff in Dada Mail simply goes haywire and you get deadlocks. Setting this configuration to, 0 stops that.

Check_List_Owner_Return_Path_Header

When testing the validity of a received message, Dada Mail will look to see if the, Return-Path header matches what's set in the, From header. If they do not match, this test fails and the message will be rejected. Setting, Check_List_Owner_Return_Path_Header will disable this test.

Check_Multiple_Return_Path_Headers

Check_Multiple_Return_Path_Headers is another validity test for received messages. This time, the message is looked to see if it has more than one Return-Path header. If it does, it is rejected. If you set, Check_Multiple_Return_Path_Headers to, 0, this test will be disabled.

DEBUGGING

This plugin, much more so than the main Dada Mail program is a bit finicky, since you have to rely on getting a successful connection to your POP3 server and also be able to run the program via a cronjob.

Debugging your POP3 account information

The easiest way to debug your POP3 account info is to actually test it out.

If you have a command line, drop into it and connect to your POP3 server, like so:

 prompt:]telnet pop3.example.com 110
 Trying 12.123.123.123...
 Connected to pop3.example.com.
 Escape character is '^]'.
 +OK <37892.1178250885@hedwig.summersault.com>
 user user%example.com
 +OK 
 pass sneaky
 +OK 
 list

In the above example, pop3.example.com is your POP3 server. You'll be typing in:

  user user%example.com

and:

  pass sneaky

(changing them to their real values) when prompted. This is basically what dada_bridge.pl does itself.

If you don't have a command line, try adding an account in a desktop mail reader. If these credentials work there, they'll most likely work for dada_bridge.pl.

If your account information is correct and also logs in when you test the pop3 login information through dada_bridge.pl yourself, check to see if there isn't an email filter attached the account that looks at messages before they're delivered to the POP3 Mailbox and outright deletes messages because it triggered a flag.

This could be the cause of mysterious occurences of messages never reaching the POP3 Mailbox.

COPYRIGHT

Copyright (c) 1999 - 2012 Justin Simoni All rights reserved.

LICENSE

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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Loading