rt/bin/rt-mailgate.in

   1 #!@PERL@ -w
   2 # {{{ BEGIN BPS TAGGED BLOCK
   3 #
   4 # COPYRIGHT:
   5 #
   6 # This software is Copyright (c) 1996-2004 Best Practical Solutions, LLC
   7 #                                          <jesse@bestpractical.com>
   8 #
   9 # (Except where explicitly superseded by other copyright notices)
  10 #
  11 #
  12 # LICENSE:
  13 #
  14 # This work is made available to you under the terms of Version 2 of
  15 # the GNU General Public License. A copy of that license should have
  16 # been provided with this software, but in any event can be snarfed
  17 # from www.gnu.org.
  18 #
  19 # This work is distributed in the hope that it will be useful, but
  20 # WITHOUT ANY WARRANTY; without even the implied warranty of
  21 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  22 # General Public License for more details.
  23 #
  24 # You should have received a copy of the GNU General Public License
  25 # along with this program; if not, write to the Free Software
  26 # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  27 #
  28 #
  29 # CONTRIBUTION SUBMISSION POLICY:
  30 #
  31 # (The following paragraph is not intended to limit the rights granted
  32 # to you to modify and distribute this software under the terms of
  33 # the GNU General Public License and is only of importance to you if
  34 # you choose to contribute your changes and enhancements to the
  35 # community by submitting them to Best Practical Solutions, LLC.)
  36 #
  37 # By intentionally submitting any modifications, corrections or
  38 # derivatives to this work, or any other work intended for use with
  39 # Request Tracker, to Best Practical Solutions, LLC, you confirm that
  40 # you are the copyright holder for those contributions and you grant
  41 # Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
  42 # royalty-free, perpetual, license to use, copy, create derivative
  43 # works based on those contributions, and sublicense and distribute
  44 # those contributions and any derivatives thereof.
  45 #
  46 # }}} END BPS TAGGED BLOCK
  47
  48 =head1 NAME
  49
  50 rt-mailgate - Mail interface to RT3.
  51
  52 =begin testing
  53
  54 use RT::I18N;
  55
  56 # Make sure that when we call the mailgate wrong, it tempfails
  57
  58 ok(open(MAIL, "|@RT_BIN_PATH@/rt-mailgate --url http://bad.address"), "Opened the mailgate - The error below is expected - $@");
  59 print MAIL <<EOF;
  60 From: root\@localhost
  61 To: rt\@example.com
  62 Subject: This is a test of new ticket creation
  63
  64 Foob!
  65 EOF
  66 close (MAIL);
  67
  68 # Check the return value
  69 is ( $? >> 8, 75, "The error message above is expected The mail gateway exited with a failure. yay");
  70
  71
  72 # {{{ Test new ticket creation by root who is privileged and superuser
  73
  74 ok(open(MAIL, "|@RT_BIN_PATH@/rt-mailgate  --debug --url http://localhost".$RT::WebPath."/ --queue general --action correspond"), "Opened the mailgate - $@");
  75 print MAIL <<EOF;
  76 From: root\@localhost
  77 To: rt\@example.com
  78 Subject: This is a test of new ticket creation
  79
  80 Blah!
  81 Foob!
  82 EOF
  83 close (MAIL);
  84
  85 #Check the return value
  86 is ($? >> 8, 0, "The mail gateway exited normally. yay");
  87
  88 use RT::Tickets;
  89 my $tickets = RT::Tickets->new($RT::SystemUser);
  90 $tickets->OrderBy(FIELD => 'id', ORDER => 'DESC');
  91 $tickets->Limit(FIELD => 'id', OPERATOR => '>', VALUE => '0');
  92 my $tick = $tickets->First();
  93 ok (UNIVERSAL::isa($tick,'RT::Ticket'));
  94 ok ($tick->Id, "found ticket ".$tick->Id);
  95 ok ($tick->Subject eq 'This is a test of new ticket creation', "Created the ticket");
  96
  97 # }}}
  98
  99
 100 # {{{This is a test of new ticket creation as an unknown user
 101
 102 ok(open(MAIL, "|@RT_BIN_PATH@/rt-mailgate --url http://localhost".$RT::WebPath."/ --queue general --action correspond"), "Opened the mailgate - $@");
 103 print MAIL <<EOF;
 104 From: doesnotexist\@example.com
 105 To: rt\@example.com
 106 Subject: This is a test of new ticket creation as an unknown user
 107
 108 Blah!
 109 Foob!
 110 EOF
 111 close (MAIL);
 112 #Check the return value
 113 is ($? >> 8, 0, "The mail gateway exited normally. yay");
 114
 115 $tickets = RT::Tickets->new($RT::SystemUser);
 116 $tickets->OrderBy(FIELD => 'id', ORDER => 'DESC');
 117 $tickets->Limit(FIELD => 'id' ,OPERATOR => '>', VALUE => '0');
 118 $tick = $tickets->First();
 119 ok ($tick->Id, "found ticket ".$tick->Id);
 120 ok ($tick->Subject ne 'This is a test of new ticket creation as an unknown user', "failed to create the new ticket from an unprivileged account");
 121 my $u = RT::User->new($RT::SystemUser);
 122 $u->Load('doesnotexist@example.com');
 123 ok( $u->Id == 0, " user does not exist and was not created by failed ticket submission");
 124
 125
 126 # }}}
 127
 128 # {{{ now everybody can create tickets.  can a random unkown user create tickets?
 129
 130 my $g = RT::Group->new($RT::SystemUser);
 131 $g->LoadSystemInternalGroup('Everyone');
 132 ok( $g->Id, "Found 'everybody'");
 133
 134 my ($val,$msg) = $g->PrincipalObj->GrantRight(Right => 'CreateTicket');
 135 ok ($val, "Granted everybody the right to create tickets - $msg");
 136
 137 sleep(60); # gotta sleep so the remote process' ACL cache times out
 138
 139 ok(open(MAIL, "|@RT_BIN_PATH@/rt-mailgate --url http://localhost".$RT::WebPath."/ --queue general --action correspond"), "Opened the mailgate - $@");
 140 print MAIL <<EOF;
 141 From: doesnotexist\@example.com
 142 To: rt\@example.com
 143 Subject: This is a test of new ticket creation as an unknown user
 144
 145 Blah!
 146 Foob!
 147 EOF
 148 close (MAIL);
 149 #Check the return value
 150 is ($? >> 8, 0, "The mail gateway exited normally. yay");
 151
 152
 153 $tickets = RT::Tickets->new($RT::SystemUser);
 154 $tickets->OrderBy(FIELD => 'id', ORDER => 'DESC');
 155 $tickets->Limit(FIELD => 'id' ,OPERATOR => '>', VALUE => '0');
 156 $tick = $tickets->First();
 157 ok ($tick->Id, "found ticket ".$tick->Id);
 158 ok ($tick->Subject eq 'This is a test of new ticket creation as an unknown user', "failed to create the new ticket from an unprivileged account");
 159 my $u = RT::User->new($RT::SystemUser);
 160 $u->Load('doesnotexist@example.com');
 161 ok( $u->Id != 0, " user does not exist and was created by ticket submission");
 162
 163 # }}}
 164
 165
 166 # {{{  can another random reply to a ticket without being granted privs? answer should be no.
 167
 168
 169 #($val,$msg) = $g->PrincipalObj->GrantRight(Right => 'CreateTicket');
 170 #ok ($val, "Granted everybody the right to create tickets - $msg");
 171 #sleep(60); # gotta sleep so the remote process' ACL cache times out
 172
 173 ok(open(MAIL, "|@RT_BIN_PATH@/rt-mailgate --url http://localhost".$RT::WebPath."/ --queue general --action correspond"), "Opened the mailgate - $@");
 174 print MAIL <<EOF;
 175 From: doesnotexist-2\@example.com
 176 To: rt\@example.com
 177 Subject: [example.com #@{[$tick->Id]}] This is a test of a reply as an unknown user
 178
 179 Blah!
 180 Foob!
 181 EOF
 182 close (MAIL);
 183 #Check the return value
 184 is ($? >> 8, 0, "The mail gateway exited normally. yay");
 185
 186 $u = RT::User->new($RT::SystemUser);
 187 $u->Load('doesnotexist-2@example.com');
 188 ok( $u->Id == 0, " user does not exist and was not created by ticket correspondence submission");
 189 # }}}
 190
 191
 192 # {{{  can another random reply to a ticket after being granted privs? answer should be yes
 193
 194
 195 ($val,$msg) = $g->PrincipalObj->GrantRight(Right => 'ReplyToTicket');
 196 ok ($val, "Granted everybody the right to reply to  tickets - $msg");
 197 sleep(60); # gotta sleep so the remote process' ACL cache times out
 198
 199 ok(open(MAIL, "|@RT_BIN_PATH@/rt-mailgate --url http://localhost".$RT::WebPath."/ --queue general --action correspond"), "Opened the mailgate - $@");
 200 print MAIL <<EOF;
 201 From: doesnotexist-2\@example.com
 202 To: rt\@example.com
 203 Subject: [example.com #@{[$tick->Id]}] This is a test of a reply as an unknown user
 204
 205 Blah!
 206 Foob!
 207 EOF
 208 close (MAIL);
 209 #Check the return value
 210 is ($? >> 8, 0, "The mail gateway exited normally. yay");
 211
 212
 213 $u = RT::User->new($RT::SystemUser);
 214 $u->Load('doesnotexist-2@example.com');
 215 ok( $u->Id != 0, " user exists and was created by ticket correspondence submission");
 216
 217 # }}}
 218
 219 # {{{  can another random comment on a ticket without being granted privs? answer should be no.
 220
 221
 222 #($val,$msg) = $g->PrincipalObj->GrantRight(Right => 'CreateTicket');
 223 #ok ($val, "Granted everybody the right to create tickets - $msg");
 224 #sleep(60); # gotta sleep so the remote process' ACL cache times out
 225
 226 ok(open(MAIL, "|@RT_BIN_PATH@/rt-mailgate --url http://localhost".$RT::WebPath."/ --queue general --action comment"), "Opened the mailgate - $@");
 227 print MAIL <<EOF;
 228 From: doesnotexist-3\@example.com
 229 To: rt\@example.com
 230 Subject: [example.com #@{[$tick->Id]}] This is a test of a comment as an unknown user
 231
 232 Blah!
 233 Foob!
 234 EOF
 235 close (MAIL);
 236
 237 #Check the return value
 238 is ($? >> 8, 0, "The mail gateway exited normally. yay");
 239
 240 $u = RT::User->new($RT::SystemUser);
 241 $u->Load('doesnotexist-3@example.com');
 242 ok( $u->Id == 0, " user does not exist and was not created by ticket comment submission");
 243
 244 # }}}
 245 # {{{  can another random reply to a ticket after being granted privs? answer should be yes
 246
 247
 248 ($val,$msg) = $g->PrincipalObj->GrantRight(Right => 'CommentOnTicket');
 249 ok ($val, "Granted everybody the right to reply to  tickets - $msg");
 250 sleep(60); # gotta sleep so the remote process' ACL cache times out
 251
 252 ok(open(MAIL, "|@RT_BIN_PATH@/rt-mailgate --url http://localhost".$RT::WebPath."/ --queue general --action comment"), "Opened the mailgate - $@");
 253 print MAIL <<EOF;
 254 From: doesnotexist-3\@example.com
 255 To: rt\@example.com
 256 Subject: [example.com #@{[$tick->Id]}] This is a test of a comment as an unknown user
 257
 258 Blah!
 259 Foob!
 260 EOF
 261 close (MAIL);
 262
 263 #Check the return value
 264 is ($? >> 8, 0, "The mail gateway exited normally. yay");
 265
 266 $u = RT::User->new($RT::SystemUser);
 267 $u->Load('doesnotexist-3@example.com');
 268 ok( $u->Id != 0, " user exists and was created by ticket comment submission");
 269
 270 # }}}
 271
 272 # {{{ Testing preservation of binary attachments
 273
 274 # Get a binary blob (Best Practical logo)
 275
 276 # Create a mime entity with an attachment
 277
 278 use MIME::Entity;
 279 my $entity = MIME::Entity->build( From => 'root@localhost',
 280                                  To => 'rt@localhost',
 281                                 Subject => 'binary attachment test',
 282                                 Data => ['This is a test of a binary attachment']);
 283
 284 # currently in lib/t/autogen
 285 $entity->attach(Path => '@MASON_HTML_PATH@/NoAuth/images/spacer.gif',
 286                 Type => 'image/gif',
 287                 Encoding => 'base64');
 288
 289 # Create a ticket with a binary attachment
 290 ok(open(MAIL, "|@RT_BIN_PATH@/rt-mailgate --url http://localhost".$RT::WebPath."/ --queue general --action correspond"), "Opened the mailgate - $@");
 291
 292 $entity->print(\*MAIL);
 293
 294 close (MAIL);
 295
 296 #Check the return value
 297 is ($? >> 8, 0, "The mail gateway exited normally. yay");
 298
 299 my $tickets = RT::Tickets->new($RT::SystemUser);
 300 $tickets->OrderBy(FIELD => 'id', ORDER => 'DESC');
 301 $tickets->Limit(FIELD => 'id', OPERATOR => '>', VALUE => '0');
 302  $tick = $tickets->First();
 303 ok (UNIVERSAL::isa($tick,'RT::Ticket'));
 304 ok ($tick->Id, "found ticket ".$tick->Id);
 305 ok ($tick->Subject eq 'binary attachment test', "Created the ticket - ".$tick->Id);
 306
 307 my $file = `cat ../../../html/NoAuth/images/spacer.gif`;
 308 ok ($file, "Read in the logo image");
 309
 310
 311         use Digest::MD5;
 312 warn "for the raw file the content is ".Digest::MD5::md5_base64($file);
 313
 314
 315
 316 # Verify that the binary attachment is valid in the database
 317 my $attachments = RT::Attachments->new($RT::SystemUser);
 318 $attachments->Limit(FIELD => 'ContentType', VALUE => 'image/gif');
 319 ok ($attachments->Count == 1, 'Found only one gif in the database');
 320 my $attachment = $attachments->First;
 321 ok($attachment->Id);
 322 my $acontent = $attachment->Content;
 323
 324         warn "coming from the  database, the content is ".Digest::MD5::md5_base64($acontent);
 325
 326 is( $acontent, $file, 'The attachment isn\'t screwed up in the database.');
 327 # Log in as root
 328 use Getopt::Long;
 329 use LWP::UserAgent;
 330
 331
 332 # Grab the binary attachment via the web ui
 333 my $ua      = LWP::UserAgent->new();
 334
 335 my $full_url = "http://localhost".$RT::WebPath."/Ticket/Attachment/".$attachment->TransactionId."/".$attachment->id."/spacer.gif?&user=root&pass=password";
 336 my $r = $ua->get( $full_url);
 337
 338
 339 # Verify that the downloaded attachment is the same as what we uploaded.
 340 is($file, $r->content, 'The attachment isn\'t screwed up in download');
 341
 342
 343
 344 # }}}
 345
 346 # {{{ Simple I18N testing
 347
 348 ok(open(MAIL, "|@RT_BIN_PATH@/rt-mailgate --url http://localhost".$RT::WebPath."/ --queue general --action correspond"), "Opened the mailgate - $@");
 349
 350 print MAIL <<EOF;
 351 From: root\@localhost
 352 To: rtemail\@example.com
 353 Subject: This is a test of I18N ticket creation
 354 Content-Type: text/plain; charset="utf-8"
 355
 356 2 accented lines
 357 \303\242\303\252\303\256\303\264\303\273
 358 \303\241\303\251\303\255\303\263\303\272
 359 bye
 360 EOF
 361 close (MAIL);
 362
 363 #Check the return value
 364 is ($? >> 8, 0, "The mail gateway exited normally. yay");
 365
 366 my $unitickets = RT::Tickets->new($RT::SystemUser);
 367 $unitickets->OrderBy(FIELD => 'id', ORDER => 'DESC');
 368 $unitickets->Limit(FIELD => 'id', OPERATOR => '>', VALUE => '0');
 369 my $unitick = $unitickets->First();
 370 ok (UNIVERSAL::isa($unitick,'RT::Ticket'));
 371 ok ($unitick->Id, "found ticket ".$unitick->Id);
 372 ok ($unitick->Subject eq 'This is a test of I18N ticket creation', "Created the ticket - ". $unitick->Subject);
 373
 374
 375
 376 my $unistring = "\303\241\303\251\303\255\303\263\303\272";
 377 Encode::_utf8_on($unistring);
 378 is ($unitick->Transactions->First->Content, $unitick->Transactions->First->Attachments->First->Content, "Content is ". $unitick->Transactions->First->Attachments->First->Content);
 379 ok($unitick->Transactions->First->Attachments->First->Content =~ /$unistring/i, $unitick->Id." appears to be unicode ". $unitick->Transactions->First->Attachments->First->Id);
 380 # supposedly I18N fails on the second message sent in.
 381
 382 ok(open(MAIL, "|@RT_BIN_PATH@/rt-mailgate --url http://localhost".$RT::WebPath."/ --queue general --action correspond"), "Opened the mailgate - $@");
 383
 384 print MAIL <<EOF;
 385 From: root\@localhost
 386 To: rtemail\@example.com
 387 Subject: This is a test of I18N ticket creation
 388 Content-Type: text/plain; charset="utf-8"
 389
 390 2 accented lines
 391 \303\242\303\252\303\256\303\264\303\273
 392 \303\241\303\251\303\255\303\263\303\272
 393 bye
 394 EOF
 395 close (MAIL);
 396
 397 #Check the return value
 398 is ($? >> 8, 0, "The mail gateway exited normally. yay");
 399
 400 my $tickets2 = RT::Tickets->new($RT::SystemUser);
 401 $tickets2->OrderBy(FIELD => 'id', ORDER => 'DESC');
 402 $tickets2->Limit(FIELD => 'id', OPERATOR => '>', VALUE => '0');
 403 my $tick2 = $tickets2->First();
 404 ok (UNIVERSAL::isa($tick2,'RT::Ticket'));
 405 ok ($tick2->Id, "found ticket ".$tick2->Id);
 406 ok ($tick2->Subject eq 'This is a test of I18N ticket creation', "Created the ticket");
 407
 408
 409
 410 my $unistring = "\303\241\303\251\303\255\303\263\303\272";
 411 Encode::_utf8_on($unistring);
 412
 413 ok ($tick2->Transactions->First->Content =~ $unistring, "It appears to be unicode - ".$tick2->Transactions->First->Content);
 414
 415 # }}}
 416
 417
 418 ($val,$msg) = $g->PrincipalObj->RevokeRight(Right => 'CreateTicket');
 419 ok ($val, $msg);
 420
 421
 422
 423 =end testing
 424
 425 =cut
 426
 427
 428 use strict;
 429 use Getopt::Long;
 430 use LWP::UserAgent;
 431
 432 use constant EX_TEMPFAIL => 75;
 433
 434 my %opts;
 435 GetOptions( \%opts, "queue=s", "action=s", "url=s", "jar=s", "help", "debug", "extension=s", "timeout=i" );
 436
 437 if ( $opts{help} ) {
 438     require Pod::Usage;
 439     import Pod::Usage;
 440     pod2usage("RT Mail Gateway\n");
 441     exit 1;    # Don't want to succeed if this is really an email!
 442 }
 443
 444 for (qw(url)) {
 445     die "$0 invoked improperly\n\nNo $_ provided to mail gateway!\n" unless $opts{$_};
 446 }
 447
 448 undef $/;
 449 my $ua      = LWP::UserAgent->new();
 450 $ua->cookie_jar( { file => $opts{jar} } );
 451
 452 my %args = (
 453     queue   => $opts{queue},
 454     action  => $opts{action},
 455     SessionType => 'REST',    # Surpress login box
 456 );
 457
 458 # Read the message in from STDIN
 459 $args{'message'} = <>;
 460
 461 unless ( $args{message} =~ /\S/ ) {
 462     print STDERR "$0: no message passed on STDIN!\n";
 463     exit 0;
 464 }
 465
 466 if ($opts{'extension'}) {
 467         $args{$opts{'extension'}} = $ENV{'EXTENSION'};
 468 }
 469
 470 # Set up cookie here.
 471
 472 my $full_url = $opts{'url'}. "/REST/1.0/NoAuth/mail-gateway";
 473 warn "Connecting to $full_url" if $opts{'debug'};
 474
 475
 476
 477 $ua->timeout(exists($opts{'timeout'}) ? $opts{'timeout'} : 180);
 478 my $r = $ua->post( $full_url, {%args} );
 479 check_failure($r);
 480
 481 my $content = $r->content;
 482 warn $content if ($opts{debug});
 483
 484 if ( $content !~ /^(ok|not ok)/ ) {
 485
 486     # It's not the server's fault if the mail is bogus. We just want to know that
 487     # *something* came out of the server.
 488     warn <<EOF;
 489 RT server error.
 490
 491 The RT server which handled your email did not behave as expected. It
 492 said:
 493
 494 $content
 495 EOF
 496
 497 exit EX_TEMPFAIL;
 498
 499 }
 500
 501 exit;
 502
 503
 504 sub check_failure {
 505     my $r = shift;
 506     return if $r->is_success();
 507
 508     # This ordinarily oughtn't to be able to happen, suggests a bug in RT.
 509     # So only load these heavy modules when they're needed.
 510     require HTML::TreeBuilder;
 511     require HTML::FormatText;
 512
 513     my $error = $r->error_as_HTML;
 514     my $tree  = HTML::TreeBuilder->new->parse($error);
 515     $tree->eof;
 516
 517     # It'll be a cold day in hell before RT sends out bounces in HTML
 518     my $formatter = HTML::FormatText->new( leftmargin  => 0,
 519                                            rightmargin => 50 );
 520     warn $formatter->format($tree);
 521     warn "This is $0 exiting because of an undefined server error" if ($opts{debug});
 522     exit EX_TEMPFAIL;
 523 }
 524
 525
 526 =head1 SYNOPSIS
 527
 528     rt-mailgate --help : this text
 529
 530 Usual invocation (from MTA):
 531
 532     rt-mailgate --action (correspond|comment) --queue queuename
 533                 --url http://your.rt.server/
 534                 [ --debug ]
 535                 [ --extension (queue|action|ticket) ]
 536                 [ --timeout seconds ]
 537
 538
 539
 540 See C<man rt-mailgate> for more.
 541
 542 =head1 OPTIONS
 543
 544 =over 3
 545
 546 =item C<--action>
 547
 548 Specifies whether this is a correspondence or comment address.
 549
 550 =item C<--queue>
 551
 552 Reflects which queue this address handles.
 553
 554 =item C<--url>
 555
 556 The location of the web server for your RT instance.
 557
 558
 559 =item C<--extension> OPTIONAL
 560
 561 Some MTAs will route mail sent to user-foo@host or user+foo@host to user@host
 562 and present "foo" in the environment variable $EXTENSION. By specifying
 563 the value "queue" for this parameter, the queue this message should be
 564 submitted to will be set to the value of $EXTENSION. By specifying
 565 "ticket", $EXTENSION will be interpreted as the id of the ticket this message
 566 is related to.  "action" will allow the user to specify either "comment" or
 567 "correspond" in the address extension.
 568
 569 =item C<--debug> OPTIONAL
 570
 571 Print debugging output to standard error
 572
 573
 574 =item C<--timeout> OPTIONAL
 575
 576 Configure the timeout for posting the message to the web server.  The
 577 default timeout is 3 minutes (180 seconds).
 578
 579
 580 =head1 DESCRIPTION
 581
 582 The RT mail gateway is the primary mechanism for communicating with RT
 583 via email. This program simply directs the email to the RT web server,
 584 which handles filing correspondence and sending out any required mail.
 585 It is designed to be run as part of the mail delivery process, either
 586 called directly by the MTA or C<procmail>, or in a F<.forward> or
 587 equivalent.
 588
 589 =head1 SETUP
 590
 591 Much of the set up of the mail gateway depends on your MTA and mail
 592 routing configuration. However, you will need first of all to create an
 593 RT user for the mail gateway and assign it a password; this helps to
 594 ensure that mail coming into the web server did originate from the
 595 gateway.
 596
 597 Next, you need to route mail to C<rt-mailgate> for the queues you're
 598 monitoring. For instance, if you're using F</etc/aliases> and you have a
 599 "bugs" queue, you will want something like this:
 600
 601     bugs:         "|/opt/rt3/bin/rt-mailgate --queue bugs --action correspond
 602               --url http://rt.mycorp.com/"
 603
 604     bugs-comment: "|/opt/rt3/bin/rt-mailgate --queue bugs --action comment
 605               --url http://rt.mycorp.com/"
 606
 607 Note that you don't have to run your RT server on your mail server, as
 608 the mail gateway will happily relay to a different machine.
 609
 610 =head1 CUSTOMIZATION
 611
 612 By default, the mail gateway will accept mail from anyone. However,
 613 there are situations in which you will want to authenticate users
 614 before allowing them to communicate with the system. You can do this
 615 via a plug-in mechanism in the RT configuration.
 616
 617 You can set the array C<@RT::MailPlugins> to be a list of plugins. The
 618 default plugin, if this is not given, is C<Auth::MailFrom> - that is,
 619 authentication of the person is done based on the C<From> header of the
 620 email. If you have additional filters or authentication mechanisms, you
 621 can list them here and they will be called in order:
 622
 623     @RT::MailPlugins = (
 624         "Filter::SpamAssassin",
 625         "Auth::LDAP",
 626         # ...
 627     );
 628
 629 See the documentation for any additional plugins you have.
 630
 631 You may also put Perl subroutines into the C<@RT::MailPlugins> array, if
 632 they behave as described below.
 633
 634 =head1 WRITING PLUGINS
 635
 636 What's actually going on in the above is that C<@RT::MailPlugins> is a
 637 list of Perl modules; RT prepends C<RT::Interface::Email::> to the name,
 638 to form a package name, and then C<use>'s this module. The module is
 639 expected to provide a C<GetCurrentUser> subroutine, which takes a hash of
 640 several parameters:
 641
 642 =over 4
 643
 644 =item Message
 645
 646 A C<MIME::Entity> object representing the email
 647 =item CurrentUser
 648
 649 An C<RT::CurrentUser> object
 650
 651 =item AuthStat
 652
 653 The authentication level returned from the previous plugin.
 654
 655 =item Ticket [OPTIONAL]
 656
 657 The ticket under discussion
 658
 659 =item Queue [OPTIONAL]
 660
 661 If we don't already have a ticket id, we need to know which queue we're talking about
 662
 663 =item Action
 664
 665 The action being performed. At the moment, it's one of "comment" or "correspond"
 666
 667 =back 4
 668
 669 It returns two values, the new C<RT::CurrentUser> object, and the new
 670 authentication level. The authentication level can be zero, not allowed
 671 to communicate with RT at all, (a "permission denied" error is mailed to
 672 the correspondent) or one, which is the normal mode of operation.
 673 Additionally, if C<-1> is returned, then the processing of the plug-ins
 674 stops immediately and the message is ignored.
 675
 676 =cut
 677