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

- NAME Dada Bridge
- Obtaining The Program
- DESCRIPTION
- Intended Audience
- How does dada_bridge.pl work?
- REQUIREMENTS
- RECOMMENDATIONS
- Lightning Configuration/Installation Instructions
- INSTALLATION

- Configuring dada_bridge.pl's Plugin Side
- #1 Upload into the plugins directory
- #2 Configure the Config.pm file

- Configurating the Cronjob to Automatically Run Dada Bridge

- Setting the cronjob

- $Plugin_Config->{Allow_Manual_Run}

- Security Concerns and $Plugin_Config->{Manual_Run_Passcode}

- Other options you may pass
- Notes on Setting the Cronjob for curl

- Command Line Interface

- Command Line Interface for Cronjobs:
- #1 Change the lib path
- #2 Set the cron job

- Remember to enable sending using this method!
- Misc. Options

- $Plugin_Config->{Plugin_URL}
- $Plugin_Config->{Allow_Manual_Run}
- $Plugin_Config->{Manual_Run_Passcode}
- $Plugin_Config->{MessagesAtOnce}
- $Plugin_Config->{Max_Size_Of_Any_Message}
- $Moderation_Msg
- $Rejection_Message

- DEBUGGING

- Debugging your POP3 account information

- COPYRIGHT
- LICENSE

# NAME Dada Bridge

# Obtaining The Program

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

# DESCRIPTION

Dada Bridge is a program created to allow the support of sending email from your mail reader to a Dada Mail list, both for announce-only tasks and discussion lists.

# Intended Audience

Before I get asked the inevitable question, ``why did you reinvent another wheel?'', here's my response:

dada_bridge.pl, along with Dada Mail is not meant to be a replacement for similar systems, such as Mailman or Majordomo. dada_bridge.pl is a much simpler program with far fewer features then either of these two programs.

As with most of Dada Mail, the primary goals are usability and... well - style!

dada_bridge.pl does solve a few problems with trying to use similar programs -

- You do NOT need root access to the server to install the program, or setup the list address
- You do NOT need to use an alias to a script to use dada_bridge.pl

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

# How does dada_bridge.pl work?

Many of dada_bridge.pl'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, a ``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: not so in Dada Mail - you'll have to manually create the email (POP3) account and plug in the email, pop3 server and username/password into Dada Mail.

  This sounds like a step backward, but it 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.pl will check this account and route any messages it finds accordingly. When in normal use, do not check this account yourself.

Saying all this, dada_bridge.pl's niche is probably with small to medium sized lists. This program has not been tested with lists larger than a few hundred, so your mileage may vary.

The other thing you may want to take into consideration is the lack of proper threading in Dada Mail's web-based archives. At the moment, archives are only sorted by date.

This may/may not be a deal breaker, but also take into consideration that the displaying of complex email messages is usually actually better in Dada Mail than most other mail archive viewing programs.

One more thing to take into consideration is that there is currently no filter in place to reject messages based on size or type. There is a way currently to strip messages with attachments of a certain file ending or mime-type.

These two issues may be at least partly worked around using the preferences of your POP email account. Many services will at least allow you to set a per-mailbox limit, or even a per-message limit for size.

As for content, Dada Mail is currently completely MIME-aware and will accept anything it can parse, which means, multipart messages, attachments, inline embedded images - the works.

For a stopgap solution to the last issues, you may look into a mail filtering program like Procmail, which can be configured to death.

# REQUIREMENTS

- Familiarity with setting cron jobs

  If you do not know how to set up a cron job, attempting to set one up for Dada Bridge will result in much aggravation. Please read up on the topic before attempting!

- a free POP3 account for each list.
- Ability to set cron jobs

# RECOMMENDATIONS

- Shell Access to Your Hosting Account

  Shell Access is sometimes required to set up a cronjob, using the:

       crontab -e

  command. You may also be able to set up a cron tab using a web-based control panel tool, like Cpanel.

  Shell access also facilitates testing of the program.

- Use the *SQL backend for Archives

  if not for subscribers as well.

  Multipart messages, attachments and inline embedded images will work very well if you use the *SQL backend for Archives. They may not work at all if you don't.

  Since you don't have any control over the type of messages being sent using dada_bridge.pl, I would use the *SQL backend for Archives.

  For the same reason, I also and cannot stress enough that you check,

  Disable Embedded JavaScript in Archived Messages

  In Dada Mail's List control panel under, Manage Archives - Archive Options - Advanced. This will prevent exploitations embedded in messages sent to the 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.

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

# Lightning Configuration/Installation Instructions

To get to the point:

- Upload the dada_bridge.pl script into the cgi-bin/dada/plugins directory (if it's not already there)
- chmod 755 the dada_bridge.pl script
- run the plugin via a web browser.
- Set the cronjob

Below is the detailed version of the above:

# 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.pl's Plugin Side

## #1 Upload into the plugins directory

We're assuming your cgi-bin looks like this:

     /home/account/cgi-bin/dada

and inside the dada directory is the mail.cgi file and the DADA (uppercase) directory. Make a new directory in the dada directory called, plugins (if it's not already there).

If not already there, upload your copy of dada_bridge.pl into that plugins directory. chmod 755 dada_bridge.pl

## #2 Configure the Config.pm file

This plugin will give you a new menu item in your list control panel. Tell Dada Mail to make this menu item by tweaking the Config.pm file. Find these lines in the Config.pm file:

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

Uncomment it (take off the ``#'''s)

Save the Config.pm file.

You're basically done configurating the Dada Bridge plugin.

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:

# Configurating 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 thing explained:

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

- Using Curl:

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

- Using Curl, a few more options (we'll cover those in just a bit):

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

### $Plugin_Config->{Allow_Manual_Run}

If you DO NOT want to use this way of invoking the program to check awaiting messages and send them out, make sure to change the variable, $Plugin_Config-{Allow_Manual_Run}> to, 0:

     $Plugin_Config->{Allow_Manual_Run}    = 0;

at the top of the dada_bridge.pl script. If this variable is not set to, 1 this method will not work.

## Security Concerns and $Plugin_Config->{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-{Manual_Run_Passcode}` variable in the dada_bridge.pl source itself.

If you set the variable like so:

        $Plugin_Config->{Manual_Run_Passcode} = 'sneaky';

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 `$Plugin_Config-{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:

One reason that the web-based way of running the cronjob is better, is that it doesn't involve reconfiguring the plugin, every time you upgrade. This makes the web-based invoking a bit more convenient.

## #1 Change the lib path

You'll need to explicitly state where both the:

- Absolute Path to the site-wide Perl libraries
- Absolute Path of the local Dada Mail libraries

I'm going to rush through this, since if you want to run Dada Bridge this way you probably know the terminology, but:

This script will be running in a different environment and from a different location than what you'd run it as, when you visit it in a web-browser. It's annoying, but one of the things you have to do when running a command line script via a cronjob.

As an example: `use lib qw()` lines probably look like:

     use lib qw(

     ../
     ../DADA/perllib
     ../../../../perl
     ../../../../perllib

     );

To this list, you'll want to append your site-wide Perl Libraries and the path to the Dada Mail libraries.

If you don't know where your site-wide Perl libraries are, try running this via the command line:

     perl -e 'print $_ ."\n" foreach @INC';

If you do not know how to run the above command, visit your Dada Mail in a web browser, log into your list and on the left hand menu and: click, About Dada Mail

Under Script Information, click the, +/- More Information link and under the, Perl Library Locations, select each point that begins with a, ``/'' and use those as your site-wide path to your perl libraries.

## #2 Set the cron job

Cron Jobs are scheduled tasks. We're going to set a cron job to test for new messages every 5 minutes. Here's an example cron tab:

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

Where, /home/myaccount/cgi-bin/dada/plugins/dada_bridge.pl is the full path to the script we just configured.

# 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.

# Misc. Options

## $Plugin_Config->{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_Config-{Plugin_URL}>

## $Plugin_Config->{Allow_Manual_Run}

Allows you to invoke the plugin to check and send awaiting messages via a URL. See, ``The Easy Way'' cronjob setting up docs, above.

## $Plugin_Config->{Manual_Run_Passcode}

Allows you to set a passcode if you want to allow manually running the plugin. See, ``Tehe Easy Way'' cronjob setting up docs, above.

## $Plugin_Config->{MessagesAtOnce}

You can specificy how many messages you want to have the program actually handle per execution of the script by changing the, $Plugin_Config-{MessagesAtOnce}> variable in the source of the script itself. By default, it's set conservatively to, 1.

## $Plugin_Config->{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.

## $Moderation_Msg

The text of the email message that gets sent out to the list owner, when they receive an email message that requires moderation.

## $Rejection_Message

The text of the email message that gets sent out to the subscriber who has a email message sent to the list that was rejected during moderation.

# 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) 2004 - 2008 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.