2 # BEGIN BPS TAGGED BLOCK {{{
6 # This software is Copyright (c) 1996-2011 Best Practical Solutions, LLC
7 # <sales@bestpractical.com>
9 # (Except where explicitly superseded by other copyright notices)
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
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.
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/licenses/old-licenses/gpl-2.0.html.
31 # CONTRIBUTION SUBMISSION POLICY:
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.)
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.
48 # END BPS TAGGED BLOCK }}}
51 rt-mailgate - Mail interface to RT3.
60 use HTTP::Request::Common qw($DYNAMIC_FILE_UPLOAD);
61 $DYNAMIC_FILE_UPLOAD = 1;
63 use constant EX_TEMPFAIL => 75;
64 use constant BUFFER_SIZE => 8192;
67 GetOptions( \%opts, "queue=s", "action=s", "url=s", "jar=s", "help", "debug", "extension=s", "timeout=i" );
69 if ( $opts{'help'} ) {
72 pod2usage("RT Mail Gateway\n");
73 exit 1; # Don't want to succeed if this is really an email!
76 unless ( $opts{'url'} ) {
77 print STDERR "$0 invoked improperly\n\nNo 'url' provided to mail gateway!\n";
81 my $ua = new LWP::UserAgent;
82 $ua->cookie_jar( { file => $opts{'jar'} } ) if $opts{'jar'};
85 foreach ( qw(queue action) ) {
86 $args{$_} = $opts{$_} if defined $opts{$_};
89 if ( ($opts{'extension'} || '') =~ /^(?:action|queue|ticket)$/i ) {
90 $args{ lc $opts{'extension'} } = $ENV{'EXTENSION'} || $opts{$opts{'extension'}};
91 } elsif ( $opts{'extension'} && $ENV{'EXTENSION'} ) {
92 print STDERR "Value of the --extension argument is not action, queue or ticket"
93 .", but environment variable EXTENSION is also defined. The former is ignored.\n";
96 # add ENV{'EXTENSION'} as X-RT-MailExtension to the message header
97 if ( my $value = ( $ENV{'EXTENSION'} || $opts{'extension'} ) ) {
98 # prepare value to avoid MIME format breakage
99 # strip trailing newline symbols
100 $value =~ s/(\r*\n)+$//;
101 # make a correct multiline header field,
102 # with tabs in the beginning of each line
103 $value =~ s/(\r*\n)/$1\t/g;
104 $opts{'headers'} .= "X-RT-Mail-Extension: $value\n";
107 # Read the message in from STDIN
108 my %message = write_down_message();
109 unless( $message{'filename'} ) {
112 'Content-Type' => 'application/octet-stream',
113 Content => ${ $message{'content'} },
117 $message{'filename'}, '',
118 'Content-Type' => 'application/octet-stream',
122 my $full_url = $opts{'url'}. "/REST/1.0/NoAuth/mail-gateway";
123 print STDERR "$0: connecting to $full_url\n" if $opts{'debug'};
125 $ua->timeout( exists( $opts{'timeout'} )? $opts{'timeout'}: 180 );
126 my $r = $ua->post( $full_url, \%args, Content_Type => 'form-data' );
129 my $content = $r->content;
130 print STDERR $content ."\n" if $opts{'debug'};
132 if ( $content !~ /^(ok|not ok)/ ) {
134 # It's not the server's fault if the mail is bogus. We just want to know that
135 # *something* came out of the server.
139 The RT server which handled your email did not behave as expected. It
151 unlink $message{'filename'} if $message{'filename'};
157 return if $r->is_success;
159 # This ordinarily oughtn't to be able to happen, suggests a bug in RT.
160 # So only load these heavy modules when they're needed.
161 require HTML::TreeBuilder;
162 require HTML::FormatText;
164 my $error = $r->error_as_HTML;
165 my $tree = HTML::TreeBuilder->new->parse( $error );
168 # It'll be a cold day in hell before RT sends out bounces in HTML
169 my $formatter = HTML::FormatText->new(
173 print STDERR $formatter->format( $tree );
174 print STDERR "\n$0: undefined server error\n" if $opts{'debug'};
178 sub write_down_message {
179 use File::Temp qw(tempfile);
182 my ($fh, $filename) = eval { tempfile() };
184 print STDERR "$0: Couldn't create temp file, using memory\n";
185 print STDERR "error: $@\n" if $@;
187 my $message = \do { local (@ARGV, $/); <STDIN> };
188 unless ( $$message =~ /\S/ ) {
189 print STDERR "$0: no message passed on STDIN\n";
192 $$message = $opts{'headers'} . $$message if $opts{'headers'};
193 return ( content => $message );
199 print $fh $opts{'headers'} if $opts{'headers'};
201 my $buf; my $empty = 1;
203 my $status = read \*STDIN, $buf, BUFFER_SIZE;
204 unless ( defined $status ) {
205 print STDERR "$0: couldn't read message: $!\n";
207 } elsif ( !$status ) {
210 $empty = 0 if $buf =~ /\S/;
216 print STDERR "$0: no message passed on STDIN\n";
219 print STDERR "$0: temp file is '$filename'\n" if $opts{'debug'};
220 return (filename => $filename);
226 rt-mailgate --help : this text
228 Usual invocation (from MTA):
230 rt-mailgate --action (correspond|comment|...) --queue queuename
231 --url http://your.rt.server/
233 [ --extension (queue|action|ticket) ]
234 [ --timeout seconds ]
244 Specifies what happens to email sent to this alias. The avaliable
245 basic actions are: C<correspond>, C<comment>.
248 If you've set the RT configuration variable B<< C<UnsafeEmailCommands> >>,
249 C<take> and C<resolve> are also available. You can execute two or more
250 actions on a single message using a C<-> separated list. RT will execute
251 the actions in the listed order. For example you can use C<take-comment>,
252 C<correspond-resolve> or C<take-comment-resolve> as actions.
254 Note that C<take> and C<resolve> actions ignore message text if used
255 alone. Include a C<comment> or C<correspond> action if you want RT
256 to record the incoming message.
258 The default action is C<correspond>.
262 This flag determines which queue this alias should create a ticket in if no ticket identifier
267 This flag tells the mail gateway where it can find your RT server. You should
268 probably use the same URL that users use to log into RT.
271 =item C<--extension> OPTIONAL
273 Some MTAs will route mail sent to user-foo@host or user+foo@host to user@host
274 and present "foo" in the environment variable $EXTENSION. By specifying
275 the value "queue" for this parameter, the queue this message should be
276 submitted to will be set to the value of $EXTENSION. By specifying
277 "ticket", $EXTENSION will be interpreted as the id of the ticket this message
278 is related to. "action" will allow the user to specify either "comment" or
279 "correspond" in the address extension.
281 =item C<--debug> OPTIONAL
283 Print debugging output to standard error
286 =item C<--timeout> OPTIONAL
288 Configure the timeout for posting the message to the web server. The
289 default timeout is 3 minutes (180 seconds).
294 The RT mail gateway is the primary mechanism for communicating with RT
295 via email. This program simply directs the email to the RT web server,
296 which handles filing correspondence and sending out any required mail.
297 It is designed to be run as part of the mail delivery process, either
298 called directly by the MTA or C<procmail>, or in a F<.forward> or
303 Much of the set up of the mail gateway depends on your MTA and mail
304 routing configuration. However, you will need first of all to create an
305 RT user for the mail gateway and assign it a password; this helps to
306 ensure that mail coming into the web server did originate from the
309 Next, you need to route mail to C<rt-mailgate> for the queues you're
310 monitoring. For instance, if you're using F</etc/aliases> and you have a
311 "bugs" queue, you will want something like this:
313 bugs: "|/opt/rt3/bin/rt-mailgate --queue bugs --action correspond
314 --url http://rt.mycorp.com/"
316 bugs-comment: "|/opt/rt3/bin/rt-mailgate --queue bugs --action comment
317 --url http://rt.mycorp.com/"
319 Note that you don't have to run your RT server on your mail server, as
320 the mail gateway will happily relay to a different machine.
324 By default, the mail gateway will accept mail from anyone. However,
325 there are situations in which you will want to authenticate users
326 before allowing them to communicate with the system. You can do this
327 via a plug-in mechanism in the RT configuration.
329 You can set the array C<@MailPlugins> to be a list of plugins. The
330 default plugin, if this is not given, is C<Auth::MailFrom> - that is,
331 authentication of the person is done based on the C<From> header of the
332 email. If you have additional filters or authentication mechanisms, you
333 can list them here and they will be called in order:
336 "Filter::SpamAssassin",
341 See the documentation for any additional plugins you have.
343 You may also put Perl subroutines into the C<@MailPlugins> array, if
344 they behave as described below.
346 =head1 WRITING PLUGINS
348 What's actually going on in the above is that C<@MailPlugins> is a
349 list of Perl modules; RT prepends C<RT::Interface::Email::> to the name,
350 to form a package name, and then C<use>'s this module. The module is
351 expected to provide a C<GetCurrentUser> subroutine, which takes a hash of
358 A C<MIME::Entity> object representing the email
362 An C<RT::CurrentUser> object
366 The authentication level returned from the previous plugin.
368 =item Ticket [OPTIONAL]
370 The ticket under discussion
372 =item Queue [OPTIONAL]
374 If we don't already have a ticket id, we need to know which queue we're talking about
378 The action being performed. At the moment, it's one of "comment" or "correspond"
382 It returns two values, the new C<RT::CurrentUser> object, and the new
383 authentication level. The authentication level can be zero, not allowed
384 to communicate with RT at all, (a "permission denied" error is mailed to
385 the correspondent) or one, which is the normal mode of operation.
386 Additionally, if C<-1> is returned, then the processing of the plug-ins
387 stops immediately and the message is ignored.
395 Some MTAs will route mail sent to user-foo@host or user+foo@host to user@host
396 and present "foo" in the environment variable C<EXTENSION>. Mailgate adds value
397 of this variable to message in the C<X-RT-Mail-Extension> field of the message
400 See also C<--extension> option. Note that value of the environment variable is
401 always added to the message header when it's not empty even if C<--extension>
402 option is not provided.