LOGLEVELS.TXT
Document Version: 2004-09-27

SpamBouncer documentation for how to use
the loglevels variables inside SpamBouncer
procmail recipes.

Shorthand Logflags:

 SBLOG="[Shorthand Logflags]-[Log message]"
 INCLUDERC=${SBDIR}/functions/loglevel.rc

Verbose logflags:

 SBLOGFLAGS="[Verbose Logflags]"
 SBLOG="[Log message]"
 INCLUDERC=${SBDIR}/functions/loglevel.rc

The logflags are optional. If left unset, then the text assigned to the
SBLOG variable will be sent to the SBLOGFILE.

Important: Shorthand logflags will take precedence over the
           Verbose logflags if both are present.

Files used by this set of procmail recipes:

 functions/initloglevel.rc   (Must be called before first use of loglevel.rc)

 functions/loglevel.rc        Called as needed throughout the SpamBouncer's
                              recipes


 functions/loghandler.rc      Low level function called by loglevel.rc only.

 functions/logfile.rc         Low level function called by loghandler.rc only.


New Internal SpamBouncer variables used by this set of procmail recipes
SBLOGFLAGS, SBLOGSTYLE, SBLOGNUMBER, SBLOGTYPE, SBLOGTYPETEXT, SBLOG, SBMESSAGEID

Existing SpamBouncer variables used by this set of procmail recipes
SBDIR, SBHEADERS, ECHO, DATE, HOST, TEST, FORMAIL, LOGFILE

User settable variables used by this set of procmail recipes
SBHEADERS, SBLOGFILE, SBLOGLEVEL, SBDIR, ECHO, TEST, FORMAIL, LOGFILE

Where:

 SBHEADERS=BRIEF|COMPLETE

 SBLOGFILE=/path/to/spambouncer/logfile
  SBLOGFILE=INTERNAL
  SBLOGFILE=${HOME}/sblogfile

  - defaults to INTERNAL if left unset by the user.
    If set to INTERNAL, then SBLOGFILE information
    will be redirected to the procmail LOGFILE

 LOGFILE=/path/to/ProcmailLogfile
  LOGFILE=${HOME}/mail/log

  - If left unset by the user, then any log information may be lost.

 SBLOGLEVEL=[0-9]
  - Level at which messages should be recorded in the SBLOGFILE
    SBLOGLEVEL=0  Don't log anything.
    SBLOGLEVEL=3  Default. Similar to SBHEADERS=COMPLETE
                  will direct the log messages to the SBLOGFILE
    SBLOGLEVEL=9  Log everyting. Sutable for Debugging.

 SBDIR=/path/to/spambouncer

  Examples:
   SBDIR=${HOME}/sb
   SBDIR=/usr/local/spambouncer

 ECHO, TEST, FORMAIL 
  - are defined by the SpamBouncer with reasonable defaults, but
    can be set by the user as well.

How to use the Verbose and Shorthand log flags:

 Verbose:
 SBLOGFLAGS="SBLOGSTYLE SBLOGNUMBER SBLOGTYPE"
 SBLOG="Text to Log"

 Shorthand:
 SBLOG="SNT-Text to Log"
  where: S=SBLOGSTYLE, N=SBLOGNUMBER, T=SBLOGTYPE

 "SBLOGSTYLE=(ALWAYS|BRIEF|COMPLETE|LOG)" match vs SBHEADERS set by user.
 "Shorthand   A      B     C        L   "
 "Verbose     ALWAYS BRIEF COMPLETE LOG "

 - If SBLOGSTYLE is set to ALWAYS, then the SBHEADERS setting will be ignored.
   and the SBLOG entry will always be sent to the log and appended to the
   email as an X-SBxxxx: header if valid SBLOGTYPE is set.

 - If SBLOGSTYLE is set to LOG, then the SBLOG entry will be sent only to the
   SBLOGFILE if the SBLOGNUMBER is greater than or equal to SBLOGLEVEL and 
   will not appended as an X-SBxxxx: header to any email.

 - If SBLOGSTYLE is set to BRIEF or COMPLETE then an X-SBxxxx: header will be
   added to the email if the SBHEADERS matches the SBLOGSTYLE. Also the SBLOG
   text will be sent to the SBLOGFILE if the SBLOGNUMBER is greater than or 
   equal to the SBLOGLEVEL.

 "SBLOGNUMBER=[0-9]" match vs SBLOGLEVEL set by user.

 - SBLOGNUMBER is compared to the SBLOGLEVEL setting. If SBLOGNUMBER is greater
   than or equal to SBLOGLEVEL, the SBLOG text will be sent to the SBLOGFILE.
   If SBLOGNUMBER is less than SBLOGLEVEL, the SBLOG text will not be logged
   to the SBLOGFILE, however, it may still be appended to the email as an
   X-SBxxxx: header, if SBHEADERS matches the SBLOGSTYLE, or if SBLOGSTYLE is 
   set to ALWAYS.

 "SBLOGTYPE=(RULE|STOP|PASS|NOTE|CLASS|SCORE|LOG)" how to output the message. As an X-SBrule:, X-SBNote:, ... etc
 "Shorthand  R    S    P    N    C       O   L   "
 "Verbose    RULE STOP PASS NOTE CLASS SCORE LOG "

 - SBLOGTYPE will specify the type of X-SBxxxx: header to add, where
   R=X-SBRule:
   S=X-SBStop:
   P=X-SBPass:
   N=X-SBNote:
   C=X-SBClass:
   O=X-SBScore:
   L=Nothing - no X header is needed. 
      When SBLOGTYPE is set to LOG, the SBLOG text is sent only to the SBLOGFILE.
      If no SBLOGTYPE Flag is set, the flag will default to type LOG


Examples:

Apply an SBLOG message to the email as an
X-SBRule: message, and echo to the SBLOGFILE
if SBLOGNUMBER is greater than or equal to SBLOGLEVEL

-----

Shorhand method:

 SBLOG="B2R-Some Breif Log Rule Message"
 INCLUDERC=${SBDIR}/functions/loglevel.rc

Verbose method:

 SBLOGFLAGS="BRIEF 2 RULE"
 SBLOG="Some brief log rule message"
 INCLUDERC=${SBDIR}/functions/loglevel.rc

------

Apply an SBLOG message to the email as an
X-SBNote: message, and echo to the SBLOGFILE
if SBLOGNUMBER is greater than or equal to SBLOGLEVEL

Shorthand method:

 SBLOG="C3N-Some Complete Log Note Message"
 INCLUDERC=${SBDIR}/functions/loglevel.rc

Verbose method:

 SBLOGFLAGS="COMPLETE 3 NOTE"
 SBLOG="Some complete log note message"
 INCLUDERC=${SBDIR}/functions/loglevel.rc

-----

Send an SBLOG message to the SBLOGFILE
without adding any X-SBxxxx: headers
to the email.

Shorthand method:
 SBLOG="L3-Message to send to the SBLOGFILE"
 INCLUDERC=${SBDIR}/functions/loglevel.rc

Verbose method:
 SBLOGFLAGS="LOG 3"
 SBLOG="Message to send to the SBLOGFILE"
 INCLUDERC=${SBDIR}/functions/loglevel.rc

-----

Author: Garen Erdoisa <scamper@trisk.com>
Copyright 2004 by Garen Erdoisa All Rights Reserved
Licence: GNU GPL

Intended use and Disclaimer statement:

This document and the files referred to by this document
were written specifically for internal use by the SpamBouncer
which is a set of procmail recipes used for filtering 
spam email messages.

see URL: http://www.spambouncer.org

Use with any other application or set of applications
will probabally not work  without some re-writes of the
code as a stand alone module.

Send bug reports related to the files mentioned in this document 
to: 

  Garen Erdoisa <scamper@trisk.com> 

Please only send such reports if they are related to a released 
copy of the SpamBouncer, and please specify the SpamBouncer version 
you using along with your report.  

Please do not bother the author with bug reports related to any 
re-writes or other use of this code with other applications.

