Search:  
Gentoo Wiki

HOWTO_yaa


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc

Contents

Introduction

yaa! (yet another autoresponder) is a perl script for handling autoreplies written by Branko F. Gracnar. I came across this script when setting up a FreeBSD server. Soon I realized that there's almost no documentation out there, so I decided to quickly throw one together for the Gentoo wiki. Many of the problems I encountered when using yaa! can be transferred to Gentoo users using the same program, so if anyone wants to add Gentoo specific information, please do so.

Disclaimer: I, the first author (Cypres) am just a novice, so please do not hold me reponsible if you do something harmful to your system while following directions written in this howto.

The yaa! project can be found at Brane's homepage

First things first

Below is a list of the software I used to setup yaa! Since yaa! is a perl script, it will run on many platforms, so you should have no trouble setting it up on ie. Gentoo

Software used for this setup

yaa! is a Perl script, so you will of course need Perl, but you will also need a couple of Perl modules. Here is a list of the required modules borrowed from Brane's homepage

also used are:

What will be covered in this howto

What will not be covered in this howto

For all those sort of things, I recommend that you read genco's tutorial, also of course the Gentoo documentation on Postfix

Installing yaa!

Since yaa! is a Perl script there really isn't much installing about it.

Downloading yaa!

You should begin by going to: Brane's homepage and download yaa! I recommend yaa 0.3, since that is the one this howto is written for. Unpack the source as you normally would. I unpacked it in /usr/local/

# tar -xvjpf yaa-0.3.tar.bz2 -C /usr/local/

Perl modules

Now is a good time to check up on the Perl modules, since you can get into some nasty ambiguous errors if you don't get them right. Luckily there is a great utility for this purpose called CPAN If you followed the genco tutorial I linked to earlier then you should already be familiar with this utility. If not, here is "what's what".

Of course on Gentoo you would use emerge. "emerge -uva IO-stringy" is one of the required commands.

For Net::Server::Mail you want to emerge "g-cpan", and then "g-cpan -iv Net::Server::Mail", as it does not exist as a ebuild. With g-cpan you can easily install anything from CPAN.

If you use Perl 5.8 you must do something like this in order to utilize CPAN properly.

# export LANG=en_US
# perl -MCPAN -e shell
cpan> o conf prerequisites_policy ask

you will now be logged into cpan (possible after answering some questions) and are now ready to check for the required modules. Check for the required modules like this:

cpan> test Net::Server

Substitute test with install if any of them is missing, and make sure you got them all. CPAN could not find Carp::Heavy when I tried it, but yaa! is working fine without them, this is most likely because Carp::Heavy is included with Perl 5.8

Configuring yaa!

This is where the fun begins :)

Prerequisites to this section are:

MySQL table

When setting up your mysql table with information for yaa! you could set it up somewhat like this:

Code: setting up mysql table: autoresponder_data
CREATE TABLE `autoresponder_data` (
  `active` tinyint(1) NOT NULL default '0',
  `message` mediumtext NOT NULL,
  `subject` varchar(250) NOT NULL default '',
  `charset` varchar(250) NOT NULL default '',
  `forward` varchar(250) NOT NULL default '',
  `address` varchar(250) NOT NULL default '',
  `local_domains` varchar(250) NOT NULL default '',
  `tstart` int(32) NOT NULL default '0',
  `tfinish` int(32) NOT NULL default '0',
  PRIMARY KEY  (`address`),
  KEY `active` (`active`),
  KEY `tstart` (`tstart`,`tfinish`)
)

As you can see we will be creating a table which holds some vital data for yaa! to function. Configuing yaa! like this is very virtual hosting friendly, which is also the entire point of using yaa! since something similar to this could be done with ie, qmail or maildrop. The table itself is straightforward, please note however that you must specify a time for when autoreply should occur and when it should stop again with this setup.

If you don't have access to something like phpMyAdmin for entering the above you could save the sql command to a file and then execute it with the MySQL client. You will then need to do something like (if you saved it to autoresponder_data.sql and your database is called mail)

# mysql -u root -p mypassword mail < autoresponder_data.sql

yaa! is really flexible in its back-end implementation so the above is only a guideline, not a rule on how to do it.

yaa.conf

yaa! has excellent default settings, so this howto will cover only the essentials. For more advanced options take a look at the yaa.conf file distributed together with yaa!

File: yaa.conf

Daemon mode settings

$daemon = 1;
$daemon_lockfile = "/tmp/yaa.lock";
$daemon_pidfile = "/tmp/yaa.pid";
$daemon_tcpserver_loglevel = 4;

Since we will be running in daemon mode, the above is needed. Acturally you don't need to have a lock and pid file, but it is recommended.

yaa object settings

$duration_interval = -1;

This will disable the time check. When time check is enabled, yaa will not send out autoreplies to the same recipent more often than specified in this variable (default: 7200). This is both crucial in testing environments and production environments. I recommend you set this value to -1 until you're sure its running properly.

autoreponse settings

$mail_sending_method = "smtp";
$smtp_server = "localhost";

This is where you set up your smtp server. It's also possible to use the sendmail binary, but a combination of sendmail binary and daemon mode is said to have ill effects. The settings above is btw. default.


lookup map settings

$lookup_maps = {
         'my_sql_map' => {
                'driver' => 'SQL',
                'sql_dsn' => 'dbi:mysql:database=mail;host=localhost',
                'sql_username' => "myusername",
                'sql_password' => "mypassword",
                'sql_select' => "select active,message,subject,charset,forward,local_domains
                                from autoresponder_data where address = %m and active='1' and
                                tstart <= UNIX_TIMESTAMP() and tfinish >= UNIX_TIMESTAMP()",
        },
};

This is where you specify which driver you will be using for database connectivity, and set your username and password needed to login. Use of other databases is possible, you just need a Perl DBD:: module, and then read the yaa.conf.sample for some tweaking.

$lookup_map_query_order = {
        active => [
                'my_sql_map:active'
        ],
        subject => [
                'my_sql_map:subject'
        ],
        message => [
                'my_sql_map:message'
        ],
        charset => [
                'my_sql_map:charset'
        ],
        forward => [
                'my_sql_map:forward'
        ],
        rewrite_sender => [
                #empty
        ],
        rewrite_recipient => [
                #empty
        ],
        'local_domains' => [
                'my_sql_map:local_domains'
        ],
};

This is where you set up the usage of the lookup maps. You can apply any number of combinations of lookup maps, but this is what's needed for basic settings. The local_domains lookup map is really important. You will need to have autoreply.mydomain.tld in this variable.

#die "You haven't edit configuration file, have you?:))";

Remember to comment the line at the very bottom, or yaa! will just quit.

This will set up yaa! for usage with the MySQL table mentioned earlier, and turn on debugging features. For extra verbosity do something like this:

# export YAA_DEBUG=1

Afterwards, start yaa. This will give you a lot of debuggig messages, but is very useful when debugging yaa!, since you can spend a lot of time pondering why yaa! isn't sending any email for example.

Postfix with Virtual Host config

You will need to make sure that Postfix delivers incoming mail to your inbox (through ie. maildrop) and forwards it to yaa! This howto assumes that you are using Postfix with a virtual host setup. If not, yaa! should work just as fine, but the setup described in this howto might need some tweaking.

All that really needs to be done here is delivering the mail to both your mailagent and yaa! This is done by adding an entry to your postfix virtual table:

INSERT INTO `postfix_virtual` (`email`, `destination`)
VALUES ('myaddress@mydomain.tld', 'myaddress@mydomain.tld, myaddress@autoreply.mydomain.tld');

You will also need to add a transport entry, that will make sure that mail for autoreply.mydomain.tld will arrive at yaa!.

INSERT INTO `postfix_transport` (`domain`, `destination`)
VALUES ('autoreply.mydomain.tld', 'yaa:127.0.0.1:40000');

This assumes that you are running yaa! as a local SMTP service with port 40000. You can also opt to use LMTP instead, that is however at the moment beyond the scope of this howto.


Finally, make sure you add the following line at the end of /etc/postfix/master.cf:

Note: yaa unix - - y - - smtp

.. And then Restart Postfix. Also be sure that your iptables (or other firewall) script isn't blocking Port 40000.
-Added by Ghostbear, 14 Nov 07

Starting for the first time

So you have made it this far. Now the hours of debugging your setup can begin ;)

The first you will do is go ahead and start yaa, for now we will be starting it manually.

# /usr/local/yaa-0.3/bin/yaa.pl --action=start

The '--action=start' will start yaa! in daemon mode. You can also use '--action=stop' and '--action=status'. Remember to restart yaa! after a change to its configuration file.

You will of course need to add an entry to the autoresponder_data table before yaa! will send any autoreplies to you. You can use the following as a template.

INSERT INTO `autoresponder_data` VALUES (1, 'I\'m Gone',
 '', 'ISO-8859-1', '', 'myadress@autoreply.mydomain.tld',
 'autoreply.mydomain.tld', UNIX_TIMESTAMP(), UNIX_TIMESTAMP() + 14400 );

Please note that the subject field is empty. This will cause yaa! to prefix the original message subject with "Re:". Also note that the domain autoreply.mydomain.tld must be selected to match the transport table.

Try sending a mail to the autoreply enabled address, and check your inbox. Also take a look in /var/log/maillog and /var/log/messages for any relevant debugging messages.

If you get stuck

You can take a look at the yaa! mailing lists archives for additional information. Here is a couple of things i found useful for debugging yaa!

# telnet localhost 40000

If you have yaa! running as an SMTP service, you can connect to it via telnet. It should greet you with a welcome message, which is a great way of knowing if the application is running.

# ls /tmp/yaa*

When yaa! is running as daemon mode you should see a couple of files, among others yaa.pid && yaa.lock. They should both exist. yaa! won't start if there is a left over yaa.lock file, eventhough yaa.pid is gone and yaa! isn't running.

# kill `cat /tmp/yaa.pid`

This will read the pid stored in /tmp/yaa.pid and kill it. Useful if yaa! won't do it for you.

# killall perl5.8.7

This will kill yaa!'s main process, and possibly any other running perl scripts. When yaa! won't start, this could be because either yaa.lock exists or another (yaa!) process has allready snatched port 40000.

Happy debugging...

Hacks and Fixes

I have noticed some strange behavior with yaa! Luckily yaa! is a perl script, so its even easier to fix this on the fly. I had to make some changes to the yaa! script in order to fix a few, what I would call bugs.

Recipient not found when using strange chars in "From" name

in file /usr/lib/perl5/Yaa/Message.pm you'll se something like this around "sub _parse_header_to {"

             if ($item =~ m/^['"]?([\w\.\=\-\?\ ]+)["']? <([a-z0-9\._-]+)@([a-z0-9\._-]+)\.([a-z]{2,4})>$/i) {
                       $addr = $2 . "@" . $3 . "." . $4;
                       $name = $1;
            }
               elseif ($item =~ m/^<([a-z0-9\._-]+)@([a-z0-9\._-]+)\.([a-z]{2,4})>$/) {
                       $addr = $1 . "@" . $2 . "." . $3;
               }
               elsif ($item =~ m/^([a-z0-9\._-]+)@([a-z0-9\._-]+)\.([a-z]{2,4})$/) {
                       $addr = $1 . "@" . $2 . "." . $3;
               }


i suggest you to change this to:

               #if ($item =~ m/^['"]?([\w\.\=\-\?\ ]+)["']? <([a-z0-9\._-]+)@([a-z0-9\._-]+)\.([a-z]{2,4})>$/i) {
               #       $addr = $2 . "@" . $3 . "." . $4;
               #       $name = $1;
               #}
               if ($item =~ m/.+<([a-z0-9\._-]+)@([a-z0-9\._-]+)\.([a-z]{2,4})>$/i) {
                       $addr = $1 . "@" . $2 . "." . $3;
               }
               elsif ($item =~ m/^([a-z0-9\._-]+)@([a-z0-9\._-]+)\.([a-z]{2,4})$/i) {
                       $addr = $1 . "@" . $2 . "." . $3;
               }


As you cant see these minor changes (/i and commenting out first if) gives you proper handling of all chars in From field eg. "&" sign will be properly handled.

Charset applied to subject cause strange mails

When all the debugging was done, yaa! sent some strange emails, with non-regonizable characters in the subject field. This caused strange behavior with Gmail and Thunderbird. The message looked somewhat like this:

snip
Auto-Submitted: auto-replied
Precedence: bulk
Subject: =?iso-8859-1?Q?Re: test of yaa=

?=
MIME-Version: 1.0
Content-Type: text/plain;
        charset="iso-8859-1"
Content-Transfer-Encoding: Quoted-Printable

Hello world
snip

This was of course done to apply the charset to the subject as well as the body. There is a simple way of fixing this by editing a file in the yaa! script. And here is a nice patch for you.

File: email_subject.patch
--- Autoresponse.pm     2004-08-19 20:35:28.000000000 +0200
+++ Autoresponse.pm     2005-07-14 13:16:03.000000000 +0200
@@ -182,7 +182,11 @@
        push(@headers, "Precedence: bulk");

        # Subject
-       push(@headers, "Subject: =?" . (($self->{charset}) ? $self->{charset} : $self->{default_charset}) . "?Q?" . encode_qp($subject) . "?=");
+       #
+       # Fixes the strange subjects that email clients don't understand
+       # (second argument on encode_qp should be "")
+       push(@headers, "Subject: =?" . (($self->{charset}) ? $self->{charset} : $self->{default_charset}) . "?Q?" . encode_qp($subject,"") . "?=");


        # Content Type
        push(@headers, "MIME-Version: 1.0");

Usage: Save it to a file and do something like this:

# cd /usr/local/yaa-0.3/lib/
# patch -p0 <email-subject.patch

Final thoughts

yaa! is a great script, but it has almost no documentation available at the time of writing. This makes debugging very hard, and configuring even harder. Also there are some features that would come in handy, should yaa! reach a high level of distribution. An autostart script would be a really nice feature in yaa! (using FreeBSD), but unfortunaly getting yaa! to autostart is troublesome. Hopefully this will be fixed in a future version, and someone with proper knowledge of FreeBSD rc.scripts will write one. An yaa! ebuild in portage would also be appreciated, so there is plenty of community work to be done with yaa!

Retrieved from "http://www.gentoo-wiki.info/Yaa%21"

Last modified: Fri, 05 Sep 2008 10:00:00 +0000 Hits: 15,462