lib/Exim/Grey.pm
changeset 67 da29842506b4
parent 66 16b4815a6a15
child 68 8bc711bdd180
equal deleted inserted replaced
66:16b4815a6a15 67:da29842506b4
     1 package Exim::Grey;
     1 package Exim::Grey;
       
     2 # for usage please see at the end
     2 
     3 
     3 use strict;
     4 use strict;
     4 use warnings;
     5 use warnings;
     5 use base 'Exporter';
     6 use base 'Exporter';
     6 use Carp;
     7 use Carp;
    18 # But we need locking! DB_File::Lock isn't part of the corelist.
    19 # But we need locking! DB_File::Lock isn't part of the corelist.
    19 use DB_File::Lock;
    20 use DB_File::Lock;
    20 
    21 
    21 my %DEFAULT = (
    22 my %DEFAULT = (
    22     delay => 600,
    23     delay => 600,
    23     db    => "seen",
    24     db    => 'seen',
    24 );
    25 );
    25 
    26 
    26 sub unseen;
    27 sub unseen;
    27 
    28 
    28 # some helper functions
    29 # some helper functions
    29 sub getDBDir();
    30 sub getDBDir();
    30 sub findExim(;$);
    31 sub findExim(;$);
    31 sub connectDB($$);
    32 sub connectDB($$);
    32 sub getDefault() { %DEFAULT }
    33 sub getDefault() { %DEFAULT }
    33 
    34 
    34 # Usage:
    35 
    35 # 	${perl{unseen}{KEY}}
       
    36 # 	${perl{unseen}{KEY}{600}}
       
    37 # 	${perl{unseen}{KEY}{600}{seen}}
       
    38 # 	${perl{unseen}{KEY}{600}{$spool_directory/grey/seen}}
       
    39 #
       
    40 # With KEY being something to identify the second delivery attempt
       
    41 # I recommend using <$sender_address>:<$local_part@$domain>
       
    42 #
       
    43 # If KEY has a /... suffix, this suffix is used for auto-whitelisting.
       
    44 # I recommend using $sender_host_address.
       
    45 #
       
    46 # defer  condition = ${perl{unseen}{<$sender_address>:<$local_part@$domain>/$sender_host_address}}
       
    47 #
       
    48 # record structure: key:   item\0
       
    49 #                   value: timestamp(creation) timestamp(usage)[ auto]\0
       
    50 # (This way we're compatible with ${lookup{...}dbm{...}})
       
    51 #
       
    52 # dbm file is relativ to $spool_directory/grey, EXCEPT its name
    36 # dbm file is relativ to $spool_directory/grey, EXCEPT its name
    53 # starts with "./" or "/".
    37 # starts with "./" or "/".
    54 
    38 
    55 sub unseen {
    39 sub unseen {
    56     my $item   = shift;
    40     my $item   = shift;
   201     die "Can't connect to database driver";
   185     die "Can't connect to database driver";
   202 }
   186 }
   203 
   187 
   204 1;
   188 1;
   205 
   189 
       
   190 __END__
       
   191 =head1 NAME
       
   192 
       
   193  Exim::Grey
       
   194 
       
   195 =head1 SYNOPSIS
       
   196 
       
   197  perl_startup use Exim::Grey qw(unseen);
       
   198  ...
       
   199  acl rcpt
       
   200     defer condition = ${perl{unseen}{<$sender_address>:<$local_part@$domain>}}
       
   201 
       
   202 =head1 DESCRIPTION
       
   203 
       
   204 This is a module to be loade by Exim, the MTA. On request it exports
       
   205 a single function C<unseen()>. This function may be used in the ACL section
       
   206 to support greylisting.
       
   207 
       
   208 =head1 FUNCTIONS
       
   209 
       
   210 =over
       
   211 
       
   212 =item scalar B<unseen>(I<key>, I<delay>, I<db>)
       
   213 
       
   214 This function returns I<true> if the key is already known in the I<db> database
       
   215 for the minimum I<delay> time. (Note: The database may be cleaned regularly by
       
   216 the compangion L<exigrey> tool.)
       
   217 
       
   218 The I<key> is mandotory, the default I<delay> is 600 seconds and the default I<db>
       
   219 is called F<seen>.
       
   220 
       
   221 I<Key> may contain a suffix, separated with '/'. This suffix is used for
       
   222 automatic whitelisting.
       
   223 
       
   224 =back
       
   225 
       
   226 =head1 INTERNALS
       
   227 
       
   228 =head2 Format of the database
       
   229 
       
   230 The record structure is
       
   231 
       
   232  key:   item\0
       
   233  value: timestamp(creation) timestamp(usage) counter[ flags]\0
       
   234 
       
   235 This way we are compatible with ${lookup{...}dbm{...}}
       
   236 
       
   237 =head1 FILES
       
   238 
       
   239 The database files are placed in C<$spool_directory/grey/>.
       
   240 
       
   241 =head1 SEE ALSO
       
   242 
       
   243 The companion tool L<exigrey> should be used for inspection and manipulation
       
   244 of the database.
       
   245 
       
   246 =cut
       
   247 
   206 # vim:aw et sw=4 ts=4:
   248 # vim:aw et sw=4 ts=4: