2 # $Cambridge: exim/src/src/exipick.src,v 1.2 2004/11/12 12:01:52 ph10 Exp $
4 # This variable should be set by the building process to Exim's spool directory.
5 my $spool = 'SPOOL_DIRECTORY';
10 my($p_name) = $0 =~ m|/?([^/]+)$|;
11 my $p_version = "20041110.0";
12 my $p_usage = "Usage: $p_name [--help|--version] (see --help for details)";
14 Copyright (c) 2003-2004 John Jetmore <jj33\@pobox.com>
16 This program is free software; you can redistribute it and/or modify
17 it under the terms of the GNU General Public License as published by
18 the Free Software Foundation; either version 2 of the License, or
19 (at your option) any later version.
21 This program is distributed in the hope that it will be useful,
22 but WITHOUT ANY WARRANTY; without even the implied warranty of
23 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
24 GNU General Public License for more details.
26 You should have received a copy of the GNU General Public License
27 along with this program; if not, write to the Free Software
28 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
30 ext_usage(); # before we do anything else, check for --help
32 Getopt::Long::Configure("bundling_override");
34 'spool:s' => \$G::spool, # exim spool dir
35 'bp' => \$G::mailq_bp, # List the queue (noop - default)
36 'bpa' => \$G::mailq_bpa, # ... with generated address as well
37 'bpc' => \$G::mailq_bpc, # ... but just show a count of messages
38 'bpr' => \$G::mailq_bpr, # ... do not sort
39 'bpra' => \$G::mailq_bpra, # ... with generated addresses, unsorted
40 'bpru' => \$G::mailq_bpru, # ... only undelivered addresses, unsorted
41 'bpu' => \$G::mailq_bpu, # ... only undelivered addresses
42 'and' => \$G::and, # 'and' the criteria (default)
43 'or' => \$G::or, # 'or' the criteria
44 'f:s' => \$G::qgrep_f, # from regexp
45 'r:s' => \$G::qgrep_r, # recipient regexp
46 #'s:s' => \$G::qgrep_s, # match against size field
47 'y:s' => \$G::qgrep_y, # message younger than (secs)
48 'o:s' => \$G::qgrep_o, # message older than (secs)
49 'z' => \$G::qgrep_z, # frozen only
50 'x' => \$G::qgrep_x, # non-frozen only
51 'c' => \$G::qgrep_c, # display match count
52 'l' => \$G::qgrep_l, # long format (default)
53 'i' => \$G::qgrep_i, # message ids only
54 'b' => \$G::qgrep_b, # brief format
55 'flatq' => \$G::flatq, # brief format
56 'caseful' => \$G::caseful, # in '=' criteria, respect case
57 'caseless'=> \$G::caseless, # ...ignore case (default)
58 'show-vars:s' => \$G::show_vars, # display the contents of these vars
59 'show-rules' => \$G::show_rules # display compiled match rules
62 push(@ARGV, "\$sender_address =~ /$G::qgrep_f/") if ($G::qgrep_f);
63 push(@ARGV, "\$recipients =~ /$G::qgrep_r/") if ($G::qgrep_r);
64 push(@ARGV, "\$message_age < $G::qgrep_y") if ($G::qgrep_y);
65 push(@ARGV, "\$message_age > $G::qgrep_o") if ($G::qgrep_o);
66 push(@ARGV, "\$deliver_freeze") if ($G::qgrep_z);
67 push(@ARGV, "!\$deliver_freeze") if ($G::qgrep_x);
68 $G::mailq_bp = $G::mailq_bp; # shut up -w
69 $G::and = $G::and; # shut up -w
71 $G::caseless = $G::caseful ? 0 : 1; # nocase by default, case if both used
72 $spool = $G::spool if ($G::spool);
73 my $count_only = 1 if ($G::mailq_bpc || $G::qgrep_c);
74 my $unsorted = 1 if ($G::mailq_bpr || $G::mailq_bpra || $G::mailq_bpru);
75 my $msg = get_all_msgs($spool, $unsorted);
76 my $crit = process_criteria(\@ARGV);
77 my $e = Exim::SpoolFile->new();
78 my $tcount = 0 if ($count_only);
79 my $mcount = 0 if ($count_only);
80 $e->set_spool($spool);
81 $e->set_undelivered_only(1) if ($G::mailq_bpru || $G::mailq_bpu);
82 $e->set_show_generated(1) if ($G::mailq_bpa || $G::mailq_bpra);
83 $e->output_long() if ($G::qgrep_l);
84 $e->output_idonly() if ($G::qgrep_i);
85 $e->output_brief() if ($G::qgrep_b);
86 $e->output_flatq() if ($G::flatq);
87 $e->set_show_vars($G::show_vars) if ($G::show_vars);
90 foreach my $m (@$msg) {
91 next if (scalar(keys(%$G::msg_ids)) && !$G::or
92 && !$G::msg_ids->{$m->{message}});
93 if (!$e->parse_message($m->{message})) {
94 warn "Couldn't parse $m->{message}: ".$e->error()."\n";
100 foreach my $c (@$crit) {
101 my $var = $e->get_var($c->{var});
102 my $ret = eval($c->{cmp});
104 print STDERR "Error in eval '$c->{cmp}': $@\n";
108 if ($G::or) { last(CRITERIA); }
109 else { next(CRITERIA); }
111 if ($G::or) { next(CRITERIA); }
115 next(MSG) if (scalar(@$crit) > 0 && !$match);
120 $e->print_message(\*STDOUT);
126 } elsif ($G::qgrep_c) {
127 print "$mcount matches out of $tcount messages\n";
132 sub process_criteria {
138 foreach my $t ('@') { s/$t/\\$t/g; } # '$'
139 if (/^(.*?)\s+(<=|>=|==|!=|<|>)\s+(.*)$/) {
140 #print STDERR "found as integer\n";
141 my $v = $1; my $o = $2; my $n = $3;
142 if ($n =~ /^([\d\.]+)M$/) { $n = $1 * 1024 * 1024; }
143 elsif ($n =~ /^([\d\.]+)K$/) { $n = $1 * 1024; }
144 elsif ($n =~ /^([\d\.]+)B?$/) { $n = $1; }
145 elsif ($n =~ /^([\d\.]+)d$/) { $n = $1 * 60 * 60 * 24; }
146 elsif ($n =~ /^([\d\.]+)h$/) { $n = $1 * 60 * 60; }
147 elsif ($n =~ /^([\d\.]+)m$/) { $n = $1 * 60; }
148 elsif ($n =~ /^([\d\.]+)s?$/) { $n = $1; }
150 print STDERR "Expression $_ did not parse: numeric comparison with ",
155 push(@c, { var => lc($v), cmp => "(\$var $o $n) ? 1 : 0" });
156 } elsif (/^(.*?)\s+(=~|!~)\s+(.*)$/) {
157 #print STDERR "found as string regexp\n";
158 push(@c, { var => lc($1), cmp => "(\"\$var\" $2 $3) ? 1 : 0" });
159 } elsif (/^(.*?)\s+=\s+(.*)$/) {
160 #print STDERR "found as bare string regexp\n";
161 my $case = $G::caseful ? '' : 'i';
162 push(@c, { var => lc($1), cmp => "(\"\$var\" =~ /$2/$case) ? 1 : 0" });
163 } elsif (/^(.*?)\s+(eq|ne)\s+(.*)$/) {
164 #print STDERR "found as string cmp\n";
165 my $var = lc($1); my $op = $2; my $val = $3;
166 push(@c, { var => $var, cmp => "(\"\$var\" $op \"$val\") ? 1 : 0" });
167 if ($var eq 'message_id' && $op eq "eq") {
168 #print STDERR "short circuit @c[-1]->{cmp} $val\n";
169 $G::msg_ids->{$val} = 1;
171 } elsif (/^(!)?(\S+)$/) {
172 #print STDERR "found as boolean\n";
173 push(@c, { var => lc($2), cmp => "($1\$var) ? 1 : 0" });
175 print STDERR "Expression $_ did not parse\n";
182 if ($G::show_rules) { foreach (@c) { print "$_->{var}\t$_->{cmp}\n"; } }
188 my $d = shift() . '/input';
192 opendir(D, "$d") || die "Couldn't opendir $d: $!\n";
193 foreach my $e (grep !/^\./, readdir(D)) {
194 if ($e =~ /^[a-zA-Z0-9]$/) {
195 opendir(DD, "$d/$e") || next;
196 foreach my $f (grep !/^\./, readdir(DD)) {
197 push(@m, { message => $1, path => "$e/$1" }) if ($f =~ /^(.{16})-H$/);
200 } elsif ($e =~ /^(.{16})-H$/) {
201 push(@m, { message => $1, path => $1 });
206 return($u ? \@m : [ sort { $a->{message} cmp $b->{message} } @m ]);
211 package Exim::SpoolFile;
213 $Exim::SpoolFile::ACL_C_MAX = 10;
214 #$Exim::SpoolFile::ACL_M_MAX = 10;
219 bless($self, $class);
221 $self->{_spool_dir} = '';
222 $self->{_undelivered_only} = 0;
223 $self->{_show_generated} = 0;
224 $self->{_output_long} = 1;
225 $self->{_output_idonly} = 0;
226 $self->{_output_brief} = 0;
227 $self->{_output_flatq} = 0;
228 $self->{_show_vars} = {};
237 $self->{_output_long} = 1;
238 $self->{_output_idonly} = 0;
239 $self->{_output_brief} = 0;
240 $self->{_output_flatq} = 0;
246 $self->{_output_long} = 0;
247 $self->{_output_idonly} = 1;
248 $self->{_output_brief} = 0;
249 $self->{_output_flatq} = 0;
255 $self->{_output_long} = 0;
256 $self->{_output_idonly} = 0;
257 $self->{_output_brief} = 1;
258 $self->{_output_flatq} = 0;
264 $self->{_output_long} = 0;
265 $self->{_output_idonly} = 0;
266 $self->{_output_brief} = 0;
267 $self->{_output_flatq} = 1;
274 foreach my $v (split(/\s*,\s*/, $s)) {
275 $self->{_show_vars}{$v}++;
279 sub set_show_generated {
281 $self->{_show_generated} = shift;
284 sub set_undelivered_only {
286 $self->{_undelivered_only} = shift;
291 return $self->{_error};
296 $self->{_error} = shift;
303 $self->{_error} = '';
304 $self->{_delivered} = 0;
305 $self->{_message} = '';
309 $self->{_numrecips} = 0;
310 $self->{_udel_tree} = {};
311 $self->{_del_tree} = {};
312 $self->{_recips} = {};
321 $self->{_message} = shift || return(0);
322 return(0) if (!$self->{_spool_dir});
323 if (!$self->_find_path()) {
324 # assume the message was delivered from under us and ignore
325 $self->{_delivered} = 1;
328 $self->_parse_header() || return(0);
336 return(0) if (!$self->{_message});
337 return(0) if (!$self->{_spool_dir});
339 foreach my $f ('', substr($self->{_message}, 5, 1).'/') {
340 if (-f $self->{_spool_dir} . "/input/$f" . $self->{_message} . '-H') {
341 $self->{_path} = $self->{_spool_dir} . "/input/$f";
350 $self->{_spool_dir} = shift;
353 # accepts a variable with or without leading '$' or trailing ':'
362 if ($var eq 'message_body' && !$self->{_vars}{message_body});
364 return $self->{_vars}{$var};
369 my $f = $self->{_path} . '/' . $self->{_message} . '-D';
371 open(I, "<$f") || return($self->_error("Couldn't open $f: $!"));
373 return(0) if ($self->{_message}.'-D' ne $_);
375 $self->{_vars}{message_body} = join('', <I>);
377 $self->{_vars}{message_body} =~ s/\n/ /g;
378 $self->{_vars}{message_body} =~ s/\000/ /g;
384 my $f = $self->{_path} . '/' . $self->{_message} . '-H';
386 open(I, "<$f") || return($self->_error("Couldn't open $f: $!"));
388 return(0) if ($self->{_message}.'-H' ne $_);
389 $self->{_vars}{message_id} = $self->{_message};
393 return(0) if (!/^(\S+)\s(\d+)\s(\d+)$/);
394 $self->{_vars}{originator_login} = $1;
395 $self->{_vars}{originator_uid} = $2;
396 $self->{_vars}{originator_gid} = $3;
400 return(0) if (!/^<(.*)>$/);
401 $self->{_vars}{sender_address} = $1;
402 $self->{_vars}{sender_address_domain} = $1;
403 $self->{_vars}{sender_address_local_part} = $1;
404 $self->{_vars}{sender_address_domain} =~ s/^.*\@//;
405 $self->{_vars}{sender_address_local_part} =~ s/^(.*)\@.*$/$1/;
409 return(0) if (!/^(\d+)\s(\d+)$/);
410 $self->{_vars}{received_time} = $1;
411 $self->{_vars}{warning_count} = $2;
412 $self->{_vars}{message_age} = time() - $self->{_vars}{received_time};
416 if (/^(-\S+)\s*(.*$)/) {
419 if ($tag eq '-acl') {
421 return(0) if ($arg !~ /^(\d+)\s(\d+)$/);
422 if ($1 < $Exim::SpoolFile::ACL_C_MAX) {
425 $t = "acl_m" . ($1 - $Exim::SpoolFile::ACL_C_MAX);
427 read(I, $self->{_vars}{$t}, $2+1) || return(0);
428 chomp($self->{_vars}{$t});
429 } elsif ($tag eq '-local') {
430 $self->{_vars}{sender_local} = 1;
431 } elsif ($tag eq '-localerror') {
432 $self->{_vars}{local_error_message} = 1;
433 } elsif ($tag eq '-local_scan') {
434 $self->{_vars}{local_scan_data} = $arg;
435 } elsif ($tag eq '-host_lookup_failed') {
436 $self->{_vars}{host_lookup_failed} = 1;
437 } elsif ($tag eq '-body_linecount') {
438 $self->{_vars}{body_linecount} = $arg;
439 } elsif ($tag eq '-frozen') {
440 $self->{_vars}{deliver_freeze} = 1;
441 $self->{_vars}{deliver_frozen_at} = $arg;
442 } elsif ($tag eq '-deliver_firsttime') {
443 $self->{_vars}{deliver_firsttime} = 1;
444 $self->{_vars}{first_delivery} = 1;
445 } elsif ($tag eq '-manual_thaw') {
446 $self->{_vars}{deliver_manual_thaw} = 1;
447 $self->{_vars}{manually_thawed} = 1;
448 } elsif ($tag eq '-auth_id') {
449 $self->{_vars}{authenticated_id} = $arg;
450 } elsif ($tag eq '-auth_sender') {
451 $self->{_vars}{authenticated_sender} = $arg;
452 } elsif ($tag eq '-sender_set_untrusted') {
453 $self->{_vars}{sender_set_untrusted} = 1;
454 } elsif ($tag eq '-tls_certificate_verified') {
455 $self->{_vars}{tls_certificate_verified} = 1;
456 } elsif ($tag eq '-tls_cipher') {
457 $self->{_vars}{tls_cipher} = $arg;
458 } elsif ($tag eq '-tls_peerdn') {
459 $self->{_vars}{tls_peerdn} = $arg;
460 } elsif ($tag eq '-host_address') {
461 $self->{_vars}{sender_host_port} = $self->_get_host_and_port(\$arg);
462 $self->{_vars}{sender_host_address} = $arg;
463 } elsif ($tag eq '-interface_address') {
464 $self->{_vars}{interface_port} = $self->_get_host_and_port(\$arg);
465 $self->{_vars}{interface_address} = $arg;
466 } elsif ($tag eq '-host_auth') {
467 $self->{_vars}{sender_host_authenticated} = $arg;
468 } elsif ($tag eq '-host_name') {
469 $self->{_vars}{sender_host_name} = $arg;
470 } elsif ($tag eq '-helo_name') {
471 $self->{_vars}{sender_helo_name} = $arg;
472 } elsif ($tag eq '-ident') {
473 $self->{_vars}{sender_ident} = $arg;
474 } elsif ($tag eq '-received_protocol') {
475 $self->{_vars}{received_protocol} = $arg;
476 } elsif ($tag eq '-N') {
477 $self->{_vars}{dont_deliver} = 1;
478 } elsif ($tag eq '-body_zerocount') {
479 $self->{_vars}{body_zerocount} = $arg;
480 } elsif ($tag eq '-allow_unqualified_recipient') {
481 $self->{_vars}{allow_unqualified_recipient} = 1;
482 } elsif ($tag eq '-allow_unqualified_sender') {
483 $self->{_vars}{allow_unqualified_sender} = 1;
485 # unrecognized tag, save it for reference
486 $self->{$tag} = $arg;
493 # when we drop out of the while loop, we have the first line of the
494 # delivered tree in $_
498 } elsif ($_ =~ s/^[YN][YN]\s+//) {
499 $self->{_del_tree}{$_} = 1;
504 } while ($_ !~ /^\d+$/);
506 $self->{_numrecips} = $_;
507 $self->{_vars}{recipients_count} = $self->{_numrecips};
508 for (my $i = 0; $i < $self->{_numrecips}; $i++) {
512 if (/^(.*)\s\d+,(\d+),\d+$/) {
513 #print STDERR "exim3 type (untested): $_\n";
514 $self->{_recips}{$1} = { pno => $2 };
516 } elsif (/^(.*)\s(\d+)$/) {
517 #print STDERR "exim4 original type (untested): $_\n";
518 $self->{_recips}{$1} = { pno => $2 };
520 } elsif (/^(.*)\s(.*)\s(\d+),(\d+)#1$/) {
521 #print STDERR "exim4 new type #1 (untested): $_\n";
522 return($self->_error("incorrect format: $_")) if (length($2) != $3);
523 $self->{_recips}{$1} = { pno => $4, errors_to => $2 };
525 } elsif (/^.*#(\d+)$/) {
526 print STDERR "exim4 #$1 style (unimplemented): $_\n";
527 $self->_error("exim4 #$1 style (unimplemented): $_");
529 #print STDERR "default type: $_\n";
530 $self->{_recips}{$_} = {};
533 $self->{_udel_tree}{$addr} = 1 if (!$self->{_del_tree}{$addr});
535 $self->{_vars}{recipients} = join(', ', keys(%{$self->{_recips}}));
536 $self->{_vars}{recipients_del} = join(', ', keys(%{$self->{_del_tree}}));
537 $self->{_vars}{recipients_undel} = join(', ', keys(%{$self->{_udel_tree}}));
538 $self->{_vars}{recipients_undel_count} = scalar(keys(%{$self->{_udel_tree}}));
539 $self->{_vars}{recipients_del_count} = 0;
540 foreach my $r (keys %{$self->{_del_tree}}) {
541 next if (!$self->{_recips}{$r});
542 $self->{_vars}{recipients_del_count}++;
547 return(0) if (!/^$/);
549 # start reading headers
550 while (read(I, $_, 3) == 3) {
552 return(0) if (!length($t));
553 while ($t =~ /^\d$/) {
557 # ok, right here $t contains the header flag and $_ contains the number of
558 # bytes to read. If we ever use the header flag, grab it here.
559 $self->{_vars}{message_size} += $_ if ($t ne '*');
560 $t = getc(I); # strip the space out of the file
562 return(0) if (read(I, $_, $bytes) != $bytes);
563 chomp(); # may regret this later
564 # build the $header_ variable, following exim's rules (sort of)
565 if (/^([^ :]+):(.*)$/s) {
566 my $v = "header_" . lc($1);
570 $self->{_vars}{$v} .= (defined($self->{_vars}{$v}) ? "\n" : '') . $d;
571 $self->{_vars}{received_count}++ if ($v eq 'header_received');
573 # push header onto $message_headers var, following exim's rules
574 $self->{_vars}{message_headers} .=
575 (defined($self->{_vars}{message_headers}) ? "\n" : '') . $_;
579 if (length($self->{_vars}{"header_reply-to"}) > 0) {
580 $self->{_vars}{reply_address} = $self->{_vars}{"header_reply-to"};
582 $self->{_vars}{reply_address} = $self->{_vars}{header_from};
585 $self->{_vars}{message_body_size} =
586 (stat($self->{_path}.'/'.$self->{_message}.'-D'))[7] - 19;
587 if ($self->{_vars}{message_body_size} < 0) {
588 $self->{_vars}{message_size} = 0;
590 $self->{_vars}{message_size} += $self->{_vars}{message_body_size} + 1;
596 # mimic exim's host_extract_port function - receive a ref to a scalar,
597 # strip it of port, return port
598 sub _get_host_and_port {
600 my $host = shift; # scalar ref, be careful
602 if ($$host =~ /^\[([^\]]+)\](?:\:(\d+))?$/) {
605 } elsif ($$host =~ /^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})(?:\.(\d+))?$/) {
608 } elsif ($$host =~ /^([\d\:]+)(?:\.(\d+))?$/) {
618 my $fh = shift || \*STDOUT;
619 return if ($self->{_delivered});
621 if ($self->{_output_idonly}) {
622 print $fh $self->{_message}, "\n";
626 if ($self->{_output_long} || $self->{_output_flatq}) {
627 my $i = int($self->{_vars}{message_age} / 60);
629 $i = int(($i+30)/60);
630 if ($i > 72) { printf $fh "%2dd ", int(($i+12)/24); }
631 else { printf $fh "%2dh ", $i; }
632 } else { printf $fh "%2dm ", $i; }
634 $i = $self->{_vars}{message_size};
635 if ($i == 0) { $i = " "; }
636 elsif ($i < 1024) { $i = sprintf("%5d", $i); }
637 elsif ($i < 10*1024) { $i = sprintf("%4.1fK", $i / 1024); }
638 elsif ($i < 1024*1024) { $i = sprintf("%4dK", ($i+512)/1024); }
639 elsif ($i < 10*1024*1024) { $i = sprintf("%4.1fM", $i/(1024*1024)); }
640 else { $i = sprintf("%4dM", ($i + 512 * 1024)/(1024*1024)); }
643 print $fh "$self->{_message} ";
644 print $fh "From: " if ($self->{_output_brief});
645 print $fh "<$self->{_vars}{sender_address}>";
647 if ($self->{_output_long}) {
648 print $fh " ($self->{_vars}{originator_login})"
649 if ($self->{_vars}{sender_set_untrusted});
651 # XXX exim contains code here to print spool format errors
652 print $fh " *** frozen ***" if ($self->{_vars}{deliver_freeze});
655 foreach my $v (keys(%{$self->{_show_vars}})) {
656 printf $fh " %25s = '%s'\n", $v, $self->get_var($v);
659 foreach my $r (keys %{$self->{_recips}}) {
660 next if ($self->{_del_tree}{$r} && $self->{_undelivered_only});
661 printf $fh " %s %s\n", $self->{_del_tree}{$r} ? "D" : " ", $r;
663 if ($self->{_show_generated}) {
664 foreach my $r (keys %{$self->{_del_tree}}) {
665 next if ($self->{_recips}{$r});
666 printf $fh " +D %s\n", $r;
669 } elsif ($self->{_output_brief}) {
671 foreach my $r (keys %{$self->{_recips}}) {
672 next if ($self->{_del_tree}{$r});
675 print $fh " To: ", join(';', @r);
676 } elsif ($self->{_output_flatq}) {
677 print $fh " *** frozen ***" if ($self->{_vars}{deliver_freeze});
679 foreach my $r (keys %{$self->{_recips}}) {
680 next if ($self->{_del_tree}{$r});
683 print $fh " ", join(' ', @r);
692 foreach my $k (sort keys %$self) {
693 my $r = ref($self->{$k});
695 printf "%20s <<EOM\n", $k;
696 print @{$self->{$k}}, "EOM\n";
697 } elsif ($r eq 'HASH') {
698 printf "%20s <<EOM\n", $k;
699 foreach (sort keys %{$self->{$k}}) {
700 printf "%20s %s\n", $_, $self->{$k}{$_};
704 printf "%20s %s\n", $k, $self->{$k};
712 if ($ARGV[0] =~ /^--help$/i) {
714 $ENV{PATH} .= ":" unless $ENV{PATH} eq "";
715 $ENV{PATH} = "$ENV{PATH}$Config::Config{'installscript'}";
716 #exec("perldoc", "-F", "-U", $0) || exit 1;
717 $< = $> = 1 if ($> == 0 || $< == 0);
718 exec("perldoc", $0) || exit 1;
720 %Config::Config = ();
721 } elsif ($ARGV[0] =~ /^--version$/i) {
722 print "$p_name version $p_version\n\n$p_cp\n";
734 exipick - display messages from Exim queue based on a variety of criteria
738 exipick [--help|--version] | [-spool <spool>] [-and|-or] [-bp|-bpa|-bpc|-bpr|-bpra|-bpru|-bpu] [<criterion> [<criterion> ...]]
742 exipick is designed to display the contents of a Exim mail spool based on user-specified criteria. It is designed to mimic the output of 'exim -bp' (or any of the other -bp* options) and Exim's spec.txt should be used to learn more about the exact format of the output. The criteria are formed by creating comparisons against characteristics of the messages, for instance message_size, sender_helo_name, or message_headers.
750 The path to exim's spool directory. In general usage you should set the $spool variable in the script to your site's main spool directory, but this option is useful for alternate installs, or installs on NFS servers, etc.
754 A message will be displayed only if it matches all of the specified criteria. This is the default.
758 A message will be displayed if it matches any of the specified criteria.
762 By default criteria using the '=' operator are caseless. Specifying this option make them respect case.
764 =item The -bp* options all control how much information is displayed and in what manner. They all match the functionality of the options of the same name in Exim. Briefly:
766 =item -bp display the matching messages in 'mailq' format.
768 =item -bpa ... with generated addresses as well.
770 =item -bpc ... just show a count of messages.
772 =item -bpr ... do not sort.
774 =item -bpra ... with generated addresses, unsorted.
776 =item -bpru ... only undelivered addresses, unsorted.
778 =item -bpu ... only undelivered addresses.
780 Please see Exim's spec.txt for details on the format and information displayed with each option.
782 =item The following options are included for compatibility with the 'exiqgrep' utility:
784 =item -f <regexp> Same as '$sender_address = <regexp>'
786 =item -r <regexp> Same as '$recipients = <regexp>'
788 =item -y <seconds> Same as '$message_age < <seconds>'
790 =item -o <seconds> Same as '$message_age > <seconds>'
792 =item -z Same as '$deliver_freeze'
794 =item -x Same as '!$deliver_freeze'
796 =item -c Display count of matches only
798 =item -l Display in long format (default)
800 =item -i Display message IDs only
802 =item -b Display brief format only
804 Please see the 'exiqgrep' documentation for more details on the behaviour and output format produced by these options
808 The criteria are used to determine whether or not a given message should be displayed. The criteria are built using variables containing information about the individual messages (see VARIABLES section for list and descriptions of available variables). Each criterion is evaluated for each message in the spool and if all (by default) criteria match or (if -or option is specified) any criterion matches, the message is displayed. See VARIABLE TYPES for explanation of types of variables and the evaluations that can be performed on them and EXAMPLES section for complete examples.
810 The format of a criterion is explained in detail below, but a key point to make is that the variable being compared must always be on the left side of the comparison.
812 If no criteria are provided all messages in the queue are displayed (in this case the output of exipick should be identical to the output of 'exim -bp')
824 =head1 VARIABLE TYPES
826 Although there are variable types defined, they are defined only by the type of data that gets put into them. They are internally typeless. Because of this it is perfectly legal to perform a numeric comparison against a string variable, although the results will probably be meaningless.
832 Variable of the numeric type can be of integer or float. Valid comparisons are <, <=, >, >=, ==, and !=.
834 The numbers specified in the criteria can have a suffix of d, h, m, s, M, K, or B, in which case the number will be mulitplied by 86400, 3600, 60, 1, 1048576, 1024, or 1 respectively. These suffixes are case sensitive. While these are obviously designed to aid in date and size calculations, they are not restricted to variables of their respective types.
838 Variables of the boolean type are very easy to use in criteria. The format is either the variable by itself or the variable negated with a ! sign. For instance, 'deliver_freeze' matches if the message in question is frozen, '!deliver_freeze' matches if message is not frozen.
842 String variables are basically defined as those that are neither numeric nor boolean and can contain any data. There are several types of comparisons that can be made against string variables. With the exception of '=', the operators all match the functionality of the like-named perl operators.
844 The simplest form is a bare string regular expression, represented by the operator '='. The value used for the comparison will be evaluated as a regular expression and can be as simple or as complex as desired. For instance 'sender_helo_name = example' on the simple end or 'sender_helo_name = ^aol\.com$' on the more complex end. This comparison is caseless by default. See --caseful option.
846 Slightly more complex is the string comparison with the operators 'eq' and 'ne' for equal and not equal, respectively. 'sender_helo_name eq hotmail.com' is true for messages with the exact helo string "hotmail.com", while 'sender_helo_name ne hotmail.com' is true for any message any helo string other than hotmail.com.
848 The most complex and the most flexible format are straight regular expressions with the operators =~ and !~. The value in the criteria is expected to be a correctly formatted perl regular expression B<including the regexp delimiters (usually //)>. The criterion 'sender_helo_name !~ /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/' matches for any message which does not have an IP address for its helo string.
854 With a few exceptions the available variables match Exim's internal expansion variables in both name and exact contents. There are a few notable additions and format deviations which are noted below. Although a brief explanation is offered below, Exim's spec.txt should be consulted for full details. It is important to remember that not every variable will be defined for every message. For example, sender_host_port is not defined for messages not received from a remote host.
856 In the list below, '.' denotes standard messages with contents matching Exim's variable, '#' denotes standard variables with non-standard contents, and '+' denotes a non-standard variable.
858 =head2 Boolean variables
862 =item + allow_unqualified_recipient
864 TRUE if unqualified recipient addresses are permitted in header lines.
866 =item + allow_unqualified_sender
868 TRUE if unqualified sender addresses are permitted in header lines.
870 =item + deliver_freeze
872 TRUE if the message is frozen.
874 =item . first_delivery
876 TRUE if the message has not been deferred.
878 =item . manually_thawed
880 TRUE when the message has been manually thawed.
884 TRUE if, under normal circumstances, Exim will not try to deliver the message.
886 =item . host_lookup_failed
888 TRUE if there was an attempt to look up the host's name from its IP address, but the attempt failed.
890 =item + local_error_message
892 TRUE if the message is a locally-generated error message.
896 TRUE if the message was locally generated.
898 =item + sender_set_untrusted
900 TRUE if the envelope sender of this message was set by an untrusted local caller.
902 =item . tls_certificate_verified
904 TRUE if a TLS certificate was verified when the message was received.
908 =head2 Numeric variables
912 =item . body_linecount
914 The number of lines in the message's body.
916 =item . body_zerocount
918 The number of binary zero bytes in the message's body.
920 =item + deliver_frozen_at
922 The epoch time at which message was frozen.
924 =item . interface_port
926 The local port number if network-originated messages.
930 The number of seconds since the message was received.
932 =item . message_body_size
934 The size of the body in bytes.
938 The size of the message in bytes.
940 =item . originator_gid
942 The group id under which the process that called Exim was running as when the message was received.
944 =item . originator_uid
946 The user id under which the process that called Exim was running as when the message was received.
948 =item . received_count
950 The number of Received: header lines in the message.
952 =item + received_time
954 The epoch time at which the message was received.
956 =item . recipients_count
958 The number of envelope recipients for the message.
960 =item + recipients_del_count
962 The number of envelope recipients for the message which have already been delivered. Note that this is the count of original recipients to which the message has been delivered. It does not include generated addresses so it is possible that this number will be less than the number of addresses in the recipients_del string.
964 =item + recipients_undel_count
966 The number of envelope recipients for the message which have not yet been delivered.
968 =item . sender_host_port
970 The port number that was used on the remote host for network-originated messages.
972 =item + warning_count
974 The number of delay warnings which have been sent for this message.
978 =head2 String variables
982 =item . acl_c0-acl_c9, acl_m0-acl_m9
984 User definable variables.
986 =item . authenticated_id
988 Optional saved information from authenticators, or the login name of the calling process for locally submitted messages.
990 =item . authenticated_sender
992 The value of AUTH= param for smtp messages, or a generated value from the calling processes login and qualify domain for locally submitted messages.
996 The value of the same named message header, for example header_to or header_reply-to. These variables are really closer to Exim's rheader_* variables, with the exception that leading and trailing space is removed.
998 =item . interface_address
1000 The address of the local IP interface for network-originated messages.
1002 =item . local_scan_data
1004 The text returned by the local_scan() function when a message is received.
1006 =item # message_body
1008 The message's body. Unlike Exim's variable of the same name, this variable contains the entire message body. The logic behind this is that the message body is not read unless it is specifically referenced, so under normal circumstances it is not a penalty, but when you need the entire body you need the entire body. Like Exim's copy, newlines and nulls are replaced by spaces.
1010 =item . message_headers
1012 A concatenation of all the header lines except for lines added by routers or transports.
1016 The unique message id that is used by Exim to identify the message.
1018 =item + originator_login
1020 The login of the process which called Exim.
1022 =item . received_protocol
1024 The name of the protocol by which the message was received.
1028 The list of envelope recipients for a message. Unlike Exim's version, this variable always contains every envelope recipient of the message. The recipients are separated by a comma and a space.
1030 =item + recipients_del
1032 The list of delivered envelope recipients for a message. This non-standard variable is in the same format as recipients and contains the list of already-delivered recipients including any generated addresses.
1034 =item + recipients_undel
1036 The list of undelivered envelope recipients for a message. This non-standard variable is in the same format as recipients and contains the list of undelivered recipients.
1038 =item . reply_address
1040 The contents of the Reply-To: header line if one exists and it is not empty, or otherwise the contents of the From: header line.
1042 =item . sender_address
1044 The sender's address that was received in the message's envelope. For bounce messages, the value of this variable is the empty string.
1046 =item . sender_address_domain
1048 The domain part of sender_address.
1050 =item . sender_address_local_part
1052 The local part of sender_address.
1054 =item . sender_helo_name
1056 The HELO or EHLO value supplied for smtp or bsmtp messages.
1058 =item . sender_host_address
1060 The remote host's IP address.
1062 =item . sender_host_authenticated
1064 The name of the authenticator driver which successfully authenticated the client from which the message was received.
1066 =item . sender_host_name
1068 The remote host's name as obtained by looking up its IP address.
1070 =item . sender_ident
1072 The identification received in response to an RFC 1413 request for remote messages, the login name of the user that called Exim for locally generated messages.
1076 The cipher suite that was negotiated for encrypted SMTP connections.
1080 The value of the Distinguished Name of the certificate if Exim is configured to request one.
1088 =item exipick 'deliver_freeze'
1090 Display only frozen messages.
1092 =item exipick 'received_protocol eq asmtp' 'message_age < 20m'
1094 Display only messages wich were delivered over an authenticated smtp session in the last 20 minutes.
1096 =item exipick -bpc 'message_size > 200K'
1098 Display a count of messages in the queue which are over 200 kilobytes in size.
1100 =item exipick -or 'sender_helo_name =~ /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/' 'sender_helo_name = _'
1102 Display message which have a HELO string which either is an IP address or contains an underscore.
1108 None that I know of, except an Exim installation. Your life will also be a lot easier if you set $spool at the top of the script to your install's spool directory.
1110 =head1 ACKNOWLEDGEMENTS
1112 Although I conceived of the concept for this program independently, the name 'exipick' was taken from the Exim WishList and was suggested by Jeffrey Goldberg.
1114 Thank you to Philip Hazel for writing Exim. Of course this program exists because of Exim, but more specifically the message parsing code is based on Exim's and some of this documentation was copy/pasted from Exim's.
1120 =item EMAIL: proj-exipick@jetmore.net
1122 =item HOME: jetmore.org/john/code/#exipick