rt/bin/rt-mailgate.in

   1 #!@PERL@ -w
   2 # BEGIN BPS TAGGED BLOCK {{{
   3 #
   4 # COPYRIGHT:
   5 #
   6 # This software is Copyright (c) 1996-2005 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 =cut
  53
  54
  55 use strict;
  56 use Getopt::Long;
  57 use LWP::UserAgent;
  58
  59 use constant EX_TEMPFAIL => 75;
  60
  61 my %opts;
  62 GetOptions( \%opts, "queue=s", "action=s", "url=s", "jar=s", "help", "debug", "extension=s", "timeout=i" );
  63
  64 if ( $opts{help} ) {
  65     require Pod::Usage;
  66     import Pod::Usage;
  67     pod2usage("RT Mail Gateway\n");
  68     exit 1;    # Don't want to succeed if this is really an email!
  69 }
  70
  71 for (qw(url)) {
  72     die "$0 invoked improperly\n\nNo $_ provided to mail gateway!\n" unless $opts{$_};
  73 }
  74
  75 my $ua      = LWP::UserAgent->new();
  76 $ua->cookie_jar( { file => $opts{jar} } );
  77
  78 my %args = (
  79     queue   => $opts{queue},
  80     action  => $opts{action},
  81     SessionType => 'REST',    # Surpress login box
  82 );
  83
  84 # Read the message in from STDIN
  85 $args{'message'} = do { local (@ARGV, $/); <> };
  86
  87 unless ( $args{message} =~ /\S/ ) {
  88     print STDERR "$0: no message passed on STDIN!\n";
  89     exit 0;
  90 }
  91
  92 if ($opts{'extension'}) {
  93         $args{$opts{'extension'}} = $ENV{'EXTENSION'};
  94 }
  95
  96 # Set up cookie here.
  97
  98 my $full_url = $opts{'url'}. "/REST/1.0/NoAuth/mail-gateway";
  99 warn "Connecting to $full_url" if $opts{'debug'};
 100
 101
 102
 103 $ua->timeout(exists($opts{'timeout'}) ? $opts{'timeout'} : 180);
 104 my $r = $ua->post( $full_url, {%args} );
 105 check_failure($r);
 106
 107 my $content = $r->content;
 108 warn $content if ($opts{debug});
 109
 110 if ( $content !~ /^(ok|not ok)/ ) {
 111
 112     # It's not the server's fault if the mail is bogus. We just want to know that
 113     # *something* came out of the server.
 114     warn <<EOF;
 115 RT server error.
 116
 117 The RT server which handled your email did not behave as expected. It
 118 said:
 119
 120 $content
 121 EOF
 122
 123 exit EX_TEMPFAIL;
 124
 125 }
 126
 127 exit;
 128
 129
 130 sub check_failure {
 131     my $r = shift;
 132     return if $r->is_success();
 133
 134     # This ordinarily oughtn't to be able to happen, suggests a bug in RT.
 135     # So only load these heavy modules when they're needed.
 136     require HTML::TreeBuilder;
 137     require HTML::FormatText;
 138
 139     my $error = $r->error_as_HTML;
 140     my $tree  = HTML::TreeBuilder->new->parse($error);
 141     $tree->eof;
 142
 143     # It'll be a cold day in hell before RT sends out bounces in HTML
 144     my $formatter = HTML::FormatText->new( leftmargin  => 0,
 145                                            rightmargin => 50 );
 146     warn $formatter->format($tree);
 147     warn "This is $0 exiting because of an undefined server error" if ($opts{debug});
 148     exit EX_TEMPFAIL;
 149 }
 150
 151
 152 =head1 SYNOPSIS
 153
 154     rt-mailgate --help : this text
 155
 156 Usual invocation (from MTA):
 157
 158     rt-mailgate --action (correspond|comment|...) --queue queuename
 159                 --url http://your.rt.server/
 160                 [ --debug ]
 161                 [ --extension (queue|action|ticket) ]
 162                 [ --timeout seconds ]
 163
 164
 165
 166 See C<man rt-mailgate> for more.
 167
 168 =head1 OPTIONS
 169
 170 =over 3
 171
 172 =item C<--action>
 173
 174 Specifies what happens to email sent to this alias.  The avaliable
 175 basic actions are: C<correspond>, C<comment>.
 176
 177
 178 If you've set the RT configuration variable B<$RT::UnsafeEmailCommands>,
 179 C<take> and C<resolve> are also available.  You can execute two or more
 180 actions on a single message using a C<-> separated list.  RT will execute
 181 the actions in the listed order.  For example you can use C<take-comment>,
 182 C<correspond-resolve> or C<take-comment-resolve> as actions.
 183
 184 Note that C<take> and C<resolve> actions ignore message text if used
 185 alone.  Include a  C<comment> or C<correspond> action if you want RT
 186 to record the incoming message.
 187
 188 The default action is C<correspond>.
 189
 190 =item C<--queue>
 191
 192 This flag determines which queue this alias should create a ticket in if no ticket identifier
 193 is found.
 194
 195 =item C<--url>
 196
 197 This flag tells the mail gateway where it can find your RT server. You should
 198 probably use the same URL that users use to log into RT.
 199
 200
 201 =item C<--extension> OPTIONAL
 202
 203 Some MTAs will route mail sent to user-foo@host or user+foo@host to user@host
 204 and present "foo" in the environment variable $EXTENSION. By specifying
 205 the value "queue" for this parameter, the queue this message should be
 206 submitted to will be set to the value of $EXTENSION. By specifying
 207 "ticket", $EXTENSION will be interpreted as the id of the ticket this message
 208 is related to.  "action" will allow the user to specify either "comment" or
 209 "correspond" in the address extension.
 210
 211 =item C<--debug> OPTIONAL
 212
 213 Print debugging output to standard error
 214
 215
 216 =item C<--timeout> OPTIONAL
 217
 218 Configure the timeout for posting the message to the web server.  The
 219 default timeout is 3 minutes (180 seconds).
 220
 221
 222 =head1 DESCRIPTION
 223
 224 The RT mail gateway is the primary mechanism for communicating with RT
 225 via email. This program simply directs the email to the RT web server,
 226 which handles filing correspondence and sending out any required mail.
 227 It is designed to be run as part of the mail delivery process, either
 228 called directly by the MTA or C<procmail>, or in a F<.forward> or
 229 equivalent.
 230
 231 =head1 SETUP
 232
 233 Much of the set up of the mail gateway depends on your MTA and mail
 234 routing configuration. However, you will need first of all to create an
 235 RT user for the mail gateway and assign it a password; this helps to
 236 ensure that mail coming into the web server did originate from the
 237 gateway.
 238
 239 Next, you need to route mail to C<rt-mailgate> for the queues you're
 240 monitoring. For instance, if you're using F</etc/aliases> and you have a
 241 "bugs" queue, you will want something like this:
 242
 243     bugs:         "|/opt/rt3/bin/rt-mailgate --queue bugs --action correspond
 244               --url http://rt.mycorp.com/"
 245
 246     bugs-comment: "|/opt/rt3/bin/rt-mailgate --queue bugs --action comment
 247               --url http://rt.mycorp.com/"
 248
 249 Note that you don't have to run your RT server on your mail server, as
 250 the mail gateway will happily relay to a different machine.
 251
 252 =head1 CUSTOMIZATION
 253
 254 By default, the mail gateway will accept mail from anyone. However,
 255 there are situations in which you will want to authenticate users
 256 before allowing them to communicate with the system. You can do this
 257 via a plug-in mechanism in the RT configuration.
 258
 259 You can set the array C<@RT::MailPlugins> to be a list of plugins. The
 260 default plugin, if this is not given, is C<Auth::MailFrom> - that is,
 261 authentication of the person is done based on the C<From> header of the
 262 email. If you have additional filters or authentication mechanisms, you
 263 can list them here and they will be called in order:
 264
 265     @RT::MailPlugins = (
 266         "Filter::SpamAssassin",
 267         "Auth::LDAP",
 268         # ...
 269     );
 270
 271 See the documentation for any additional plugins you have.
 272
 273 You may also put Perl subroutines into the C<@RT::MailPlugins> array, if
 274 they behave as described below.
 275
 276 =head1 WRITING PLUGINS
 277
 278 What's actually going on in the above is that C<@RT::MailPlugins> is a
 279 list of Perl modules; RT prepends C<RT::Interface::Email::> to the name,
 280 to form a package name, and then C<use>'s this module. The module is
 281 expected to provide a C<GetCurrentUser> subroutine, which takes a hash of
 282 several parameters:
 283
 284 =over 4
 285
 286 =item Message
 287
 288 A C<MIME::Entity> object representing the email
 289
 290 =item CurrentUser
 291
 292 An C<RT::CurrentUser> object
 293
 294 =item AuthStat
 295
 296 The authentication level returned from the previous plugin.
 297
 298 =item Ticket [OPTIONAL]
 299
 300 The ticket under discussion
 301
 302 =item Queue [OPTIONAL]
 303
 304 If we don't already have a ticket id, we need to know which queue we're talking about
 305
 306 =item Action
 307
 308 The action being performed. At the moment, it's one of "comment" or "correspond"
 309
 310 =back 4
 311
 312 It returns two values, the new C<RT::CurrentUser> object, and the new
 313 authentication level. The authentication level can be zero, not allowed
 314 to communicate with RT at all, (a "permission denied" error is mailed to
 315 the correspondent) or one, which is the normal mode of operation.
 316 Additionally, if C<-1> is returned, then the processing of the plug-ins
 317 stops immediately and the message is ignored.
 318
 319 =cut
 320