How GNARWL worx
---------------

Gnarwl accepts mails by reading them through stdin. It then parses
the mail header looking for Subject:, To: and Cc:, copying all values,
found in these fields. After parsing the mailheader, gnarwl decides,
whether the mail should be replied to, or not. Afterwards, the read in mail
is silently dropped. Parsing of the mailheader is not case sensitive. An email 
may contain multiple recepients, in which case vacation messages will be sent
out for all of them (given they toggled their vacation flag in LDAP). Be
carefull with mailaddresses that are shared by several users, gnarwl 
won't do any checks here (actually it was implemented to check here,
but it didn't work and it was past midnight, so I ripped it out again ;-) ).
For example: assume, webmaster is forwarded to jane and joe, jane goes on
vacation, then everybody sending mail to webmaster will get a vacation from
jane. If this is of concern to you, use the blacklist facility (see below).


When gnarwl takes action
------------------------

In order for gnarwl to send out a vacation mail, the following prerequisites
must be fullfilled:

Mailheader:
- The header may not contain "Precedence: bulk" or "Precedence: junk"
  (to avoid replying to mailinglists)
- The header must include To: and From: fields. Note: we are talking
  mailheader To: and mailheader from:, not envelope to: and from: here!
- The header must not include: "To: undisclosed recepients:;"
- The header must be "well formed"
- The header my not specify more than mail_limit recepient addresses (this
  is to protect against DOS attacks, specifying thousands of recepients).

Database:
- Last action was taken db_expire hours ago. This is to prevent "mailloops".
  It is very important to have a reasonable value here. To give you the
  picture lets assume you set db_expire to 0, effectivly disabling this
  feature. Now one of your USERs subscribes to a mailinglist (ML). Then this 
  will happen (given, the mailinglist doesn't use "Precedence: bulk"):
  
  1. ML sends a mail to USER
  2. GNARWL sends VACATION to ML
  3. ML sends VACATION to anyone subscribed, including USER
  4. GNARWL receives VACATION from ML, and answers with a new VACATION to ML
  5. goto step 3 until either a) USER revokes his/her vacation or b) 
     the ML keeper kicks him/her of the ML for good (the later beeing more
     likely).
     
- The specified recepient mail address must not be on the blacklist.

Logging
-------

Gnarwl will log through syslogd  with the facility "mail". Use the -v switch
if you want verbose logging.


Files
---------

Assuming a default installation, gnarwl will use the following files:

/etc/gnarwl.cfg 
  the main config file (you might have guessed ;-) ).

/var/lib/gnarwl/blacklist.txt
  This files holds the mail addresses, gnarwl is never allowed to send
  vacation messages from (you should put system accounts like root or 
  webmaster herein). The format is one mail address per line, lines may be 
  commented out using a "#", you must put in the complete mailaddress (with 
  domain name), no substitution will be made. Also please don't put more
  than a dozen, or so entries in this file, it'll slow things down (the
  blacklist facility is anything but implemented effiently).

/var/lib/gnarwl/.forward
  Just a plain .forward file (actually to be used by your mailer)

/var/lib/gnarwl/db/*
  per mail account lockfiles (gdbm format). Here gnarwl will lock any
  vacaction message sent out (one file/mailaddress), to make sure it doesn't
  cause a mailloop (by sending away messages to a mailing list for example).
  It is save to delete these files if the corresponding mail recepient is
  not on vacation right now (to be more precise: just make sure, gnarwl is
  not processing the file you want to delete).


  
Vacation message
----------------

Gnarwl expects to read three attributes from LDAP, which are (by default)
called: vacationStart, vacationEnd and vacationInfo, all attributes are
formatfree strings. The content of vacationInfo is what is actually send
out, that is, piped through to sendmail and should therefore contain a
mailheader. Example (what vacationInfo should look like):

----<cut here>-----
From: $recepient\n
To: $sender\n
Subject: Re:$subject\n
\n
Hi,\n
I'm on vacation from $begin to $end.\n
---<paste here>------


As you see, gnarwl supports variables:

$recepient: The mailaddress found in the To: nad Cc: field of the original mail
$sender: The mailaddress found in the From: field of the original mail
$subject: The subject found in the $subject field of the original mail
$begin: The value of vacationStart
$end: The value of vacationEnd
\n : translates to newline. LDAP can't handle linefeeds directly (the only
 way to do this is by encoding the whole value in base64, which gnarwl does
 not understand, yet). So this is actually a dirty hack to get around the
 problem.
 