rt/bin/rt-mailgate.in

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