.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "rt-mailgate 1"
.TH rt-mailgate 1 "2023-10-29" "perl v5.36.0" "Request Tracker Reference"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
rt\-mailgate \- Mail gateway for Request Tracker
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    rt\-mailgate \-\-help : this text
.Ve
.PP
Usual invocation (from \s-1MTA\s0):
.PP
.Vb 5
\&    rt\-mailgate \-\-action (correspond|comment|...) \-\-queue queuename
\&                \-\-url http://your.rt.server/
\&                [ \-\-debug ]
\&                [ \-\-extension (queue|action|ticket) ]
\&                [ \-\-timeout seconds ]
.Ve
.SH "OPTIONS"
.IX Header "OPTIONS"
.ie n .IP """\-\-action""" 3
.el .IP "\f(CW\-\-action\fR" 3
.IX Item "--action"
Specifies what happens to email sent to this alias.  The available basic
actions are: \f(CW\*(C`correspond\*(C'\fR, \f(CW\*(C`comment\*(C'\fR.  Additional actions, such as
\&\f(CW\*(C`take\*(C'\fR or \f(CW\*(C`resolve\*(C'\fR, may be available depending on your local
\&\f(CW@MailPlugins\fR configuration.
.Sp
You can execute two or more actions on a single message using a \f(CW\*(C`\-\*(C'\fR
separated list.  \s-1RT\s0 will execute the actions in the listed order.  For
example you can use \f(CW\*(C`take\-comment\*(C'\fR, \f(CW\*(C`correspond\-resolve\*(C'\fR or
\&\f(CW\*(C`take\-comment\-resolve\*(C'\fR as actions.
.Sp
Note that \f(CW\*(C`take\*(C'\fR and \f(CW\*(C`resolve\*(C'\fR actions ignore message text if used
alone.  Include a  \f(CW\*(C`comment\*(C'\fR or \f(CW\*(C`correspond\*(C'\fR action if you want \s-1RT\s0
to record the incoming message.
.Sp
The default action is \f(CW\*(C`correspond\*(C'\fR.
.ie n .IP """\-\-queue""" 3
.el .IP "\f(CW\-\-queue\fR" 3
.IX Item "--queue"
This flag determines which queue this alias should create a ticket in if no ticket identifier
is found.
.ie n .IP """\-\-url""" 3
.el .IP "\f(CW\-\-url\fR" 3
.IX Item "--url"
This flag tells the mail gateway where it can find your \s-1RT\s0 server. You should 
probably use the same \s-1URL\s0 that users use to log into \s-1RT.\s0
.Sp
If you have a self-signed \s-1SSL\s0 certificate, you may also need to pass
\&\f(CW\*(C`\-\-ca\-file\*(C'\fR or \f(CW\*(C`\-\-no\-verify\-ssl\*(C'\fR, below.
.ie n .IP """\-\-ca\-file"" \fIpath\fR" 3
.el .IP "\f(CW\-\-ca\-file\fR \fIpath\fR" 3
.IX Item "--ca-file path"
Specifies the path to the public \s-1SSL\s0 certificate for the certificate
authority that should be used to verify the website's \s-1SSL\s0 certificate.
If your webserver uses a self-signed certificate, you should
preferentially use this option over \f(CW\*(C`\-\-no\-verify\-ssl\*(C'\fR, as it will
ensure that the self-signed certificate that the mailgate is seeing the
\&\fIright\fR self-signed certificate.
.ie n .IP """\-\-no\-verify\-ssl""" 3
.el .IP "\f(CW\-\-no\-verify\-ssl\fR" 3
.IX Item "--no-verify-ssl"
This flag tells the mail gateway to trust all \s-1SSL\s0 certificates,
regardless of if their hostname matches the certificate, and regardless
of \s-1CA.\s0  This is required if you have a self-signed certificate, or some
other certificate which is not traceable back to an certificate your
system ultimitely trusts.
.ie n .IP """\-\-extension"" \s-1OPTIONAL\s0" 3
.el .IP "\f(CW\-\-extension\fR \s-1OPTIONAL\s0" 3
.IX Item "--extension OPTIONAL"
Some MTAs will route mail sent to user\-foo@host or user+foo@host to user@host
and present \*(L"foo\*(R" in the environment variable \f(CW$EXTENSION\fR. By specifying
the value \*(L"queue\*(R" for this parameter, the queue this message should be
submitted to will be set to the value of \f(CW$EXTENSION\fR. By specifying
\&\*(L"ticket\*(R", \f(CW$EXTENSION\fR will be interpreted as the id of the ticket this message
is related to.  \*(L"action\*(R" will allow the user to specify either \*(L"comment\*(R" or
\&\*(L"correspond\*(R" in the address extension.
.ie n .IP """\-\-debug"" \s-1OPTIONAL\s0" 3
.el .IP "\f(CW\-\-debug\fR \s-1OPTIONAL\s0" 3
.IX Item "--debug OPTIONAL"
Print debugging output to standard error
.ie n .IP """\-\-timeout"" \s-1OPTIONAL\s0" 3
.el .IP "\f(CW\-\-timeout\fR \s-1OPTIONAL\s0" 3
.IX Item "--timeout OPTIONAL"
Configure the timeout for posting the message to the web server.  The
default timeout is 3 minutes (180 seconds).
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \s-1RT\s0 mail gateway is the primary mechanism for communicating with \s-1RT\s0
via email. This program simply directs the email to the \s-1RT\s0 web server,
which handles filing correspondence and sending out any required mail.
It is designed to be run as part of the mail delivery process, either
called directly by the \s-1MTA\s0 or \f(CW\*(C`procmail\*(C'\fR, or in a \fI.forward\fR or
equivalent.
.SH "SETUP"
.IX Header "SETUP"
Much of the set up of the mail gateway depends on your \s-1MTA\s0 and mail
routing configuration.
.PP
You need to route mail to \f(CW\*(C`rt\-mailgate\*(C'\fR for the queues you're
monitoring. For instance, if you're using \fI/etc/aliases\fR and you have a
\&\*(L"bugs\*(R" queue, you will want something like this:
.PP
.Vb 2
\&    bugs:         "|/usr/bin/rt\-mailgate \-\-queue bugs \-\-action correspond
\&              \-\-url http://rt.mycorp.com/"
\&
\&    bugs\-comment: "|/usr/bin/rt\-mailgate \-\-queue bugs \-\-action comment
\&              \-\-url http://rt.mycorp.com/"
.Ve
.PP
Note that you don't have to run your \s-1RT\s0 server on your mail server, as
the mail gateway will happily relay to a different machine.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
.IP "\s-1EXTENSION\s0" 4
.IX Item "EXTENSION"
Some MTAs will route mail sent to user\-foo@host or user+foo@host to user@host
and present \*(L"foo\*(R" in the environment variable \f(CW\*(C`EXTENSION\*(C'\fR. Mailgate adds value
of this variable to message in the \f(CW\*(C`X\-RT\-Mail\-Extension\*(C'\fR field of the message
header.
.Sp
See also \f(CW\*(C`\-\-extension\*(C'\fR option. Note that value of the environment variable is
always added to the message header when it's not empty even if \f(CW\*(C`\-\-extension\*(C'\fR
option is not provided.