Difference between revisions of "ManualEmailConfig"

From Request Tracker Wiki
Jump to navigation Jump to search
Line 9: Line 9:
The mail gateway requires the web UI to be set up and functional. If you intend to use SSL to secure your mail gateway, you need to make sure that lib-www-perl, a.k.a LWP, is built with SSL support.
The mail gateway requires the web UI to be set up and functional. If you intend to use SSL to secure your mail gateway, you need to make sure that lib-www-perl, a.k.a LWP, is built with SSL support.


1) Documentation for setting up the mail gateway can be found by typing:
1) Documentation for setting up the mail gateway can be found at:


perldoc /<path to installed program>/rt-mailgate
https://docs.bestpractical.com/rt/latest/rt-mailgate.html
 
(For Debian, the default path is /usr/bin.) The rt-mailgate program is installed in /opt/rt4/bin by default, so that command will probably be, more specifically:
 
perldoc /opt/rt4/bin/rt-mailgate
 
unless you've moved your install (not build) directory.


2) You need to tell your Mail Transfer Agent (e.g. sendmail, postfix, or qmail) how to forward messages to RT's mail gateway. To do this, create an aliases in your system's mail aliases file. Here's an example, which routes mail to the mailbox [=[mailto:rt@example.com rt@example.com]] (and [=[mailto:rt-comment@example.com rt-comment@example.com]]) into new tickets in the RT queue named '''General'''. Note that the queue name is case-insensitive.
2) You need to tell your Mail Transfer Agent (e.g. sendmail, postfix, or qmail) how to forward messages to RT's mail gateway. To do this, create an aliases in your system's mail aliases file. Here's an example, which routes mail to the mailbox [=[mailto:rt@example.com rt@example.com]] (and [=[mailto:rt-comment@example.com rt-comment@example.com]]) into new tickets in the RT queue named '''General'''. Note that the queue name is case-insensitive.


Add the following lines to /etc/aliases (or your local equivalent such as /etc/mail/aliases):
Add the following lines to /etc/aliases (or your local equivalent such as /etc/mail/aliases):
 
    rt: "|/opt/rt4/bin/rt-mailgate --queue general --action correspond --url http://localhost/rt"
rt: "|/opt/rt4/bin/rt-mailgate --queue general --action correspond --url http://localhost/rt"
    rt-comment: "|/opt/rt4/bin/rt-mailgate --queue general --action comment --url http://localhost/rt"
rt-comment: "|/opt/rt4/bin/rt-mailgate --queue general --action comment --url http://localhost/rt"
 
(Replace /opt/rt4 by your RT installation path and http://localhost/rt by the URL of your RT installation on your webserver)
(Replace /opt/rt4 by your RT installation path and http://localhost/rt by the URL of your RT installation on your webserver)


Line 36: Line 27:


The queue name may have spaces. <code>rt-mailgate</code> works as well with them, but do not forget to escape these spaces by enclosing the queue name in single quote:
The queue name may have spaces. <code>rt-mailgate</code> works as well with them, but do not forget to escape these spaces by enclosing the queue name in single quote:
 
    my-queue: "|/opt/rt4/bin/rt-mailgate --queue 'My Queue' --action correspond --url http://localhost/"
my-queue: "|/opt/rt4/bin/rt-mailgate --queue 'My Queue' --action correspond --url http://localhost/"
 
If you are using the default sendmail included in most redhat distro's you will most likely need to copy (cp) rt-mailgate to /etc/smrsh or create a symbolic link and change /opt/rt4/bin above to /etc/smrsh or sendmail will complain. These sendmails will only execute programs as alias targets which have been blessed by placing them in a special directory. This is not necessary for Exim or postfix.
If you are using the default sendmail included in most redhat distro's you will most likely need to copy (cp) rt-mailgate to /etc/smrsh or create a symbolic link and change /opt/rt4/bin above to /etc/smrsh or sendmail will complain. These sendmails will only execute programs as alias targets which have been blessed by placing them in a special directory. This is not necessary for Exim or postfix.


Line 46: Line 35:


3) Stop and start your mail server, so it picks up your configuration changes. With sendmail or postfix (possibly others), you usually also need to type the command "newaliases" to get the server to recognize the new aliases.  If this command is unrecognized, it's probably not in your default path; a common location is "/usr/sbin/newaliases".
3) Stop and start your mail server, so it picks up your configuration changes. With sendmail or postfix (possibly others), you usually also need to type the command "newaliases" to get the server to recognize the new aliases.  If this command is unrecognized, it's probably not in your default path; a common location is "/usr/sbin/newaliases".
4) Change the password. The default root password for the web interface is password, as installed. Changing this should be the first thing you do after installation.


You '''can''' have the mail gateway on your MX or some other server and have it talk to RT via HTTP. For more details, see [[InstallMailgateOnly]].
You '''can''' have the mail gateway on your MX or some other server and have it talk to RT via HTTP. For more details, see [[InstallMailgateOnly]].


To configure a mail transfer agent (postfix) to post tickets to RT4 on a separate server ....
To configure a mail transfer agent (postfix) to post tickets to RT4 on a separate server ....
#(download and un-tar RT)
./configure
make sbin-install
make bin-install (where rt-mailgate lives)
make libs-install


Add the following lines to /etc/aliases (or your local equivalent such as /etc/mail/aliases):
Add the following lines to /etc/aliases (or your local equivalent such as /etc/mail/aliases):
 
    rt: "|/&lt;path-to-mailgate&gt;/rt-mailgate --queue general --action correspond --url http://&lt;the-URL-of-the-RT-server&gt;/"
rt: "|/&lt;path-to-mailgate&gt;/rt-mailgate --queue general --action correspond --url http://&lt;the-URL-of-the-RT-server&gt;/"
    rt-comment: "|/&lt;path-to-mailgate&gt;/rt-mailgate --queue general --action comment --url http://&lt;the-URL-of-the-RT-server&gt;/"
rt-comment: "|/&lt;path-to-mailgate&gt;/rt-mailgate --queue general --action comment --url http://&lt;the-URL-of-the-RT-server&gt;/"
 
The link to RT is now configured. However, the rt-mailgate script is a perl script which requires support. On a fresh [[SuSE]] 9.3 server install, the following was needed to provide the necessary perl libraries (someone with deeper knowledge may know of a more restrictive set of libraries, but these worked).
The link to RT is now configured. However, the rt-mailgate script is a perl script which requires support. On a fresh [[SuSE]] 9.3 server install, the following was needed to provide the necessary perl libraries (someone with deeper knowledge may know of a more restrictive set of libraries, but these worked).


Line 72: Line 51:


If Using SSL, add:
If Using SSL, add:
    perl -MCPAN -e 'install("Crypt::SSLeay")'
To test the connection...
  echo 'hello' | mail -s "Test subject" rt
If you get a "command died with status 1" error message, the rt-mailgate script possibly doesn't have the execute bit set for the user/group under which postfix is running.
  chmod o+x /&lt;path-to-mailgate&gt;/rt-mailgate
For more information on configuring your mail gateway, see [[ManualAdministration]]


perl -MCPAN -e 'install("Crypt::SSLeay")'


To test the connection...
= Using Fetchmail/Getmail For Incoming Email =


echo 'hello' | mail -s "Test subject" rt
Fetchmail or Getmail can be used to fetch email from a inbox using IMAP or POP. An example configuration for Fetchmail can be seen below:
    set daemon 0


If you get a "command died with status 1" error message, the rt-mailgate script possibly doesn't have the execute bit set for the user/group under which postfix is running.
    # PID files are more useful for forking systemd services. But fetchmail will
    # always write one. Since the service runs fetchmail as the apache user,
    # www-data, we need to give fetchmail a path that it has write permission to.
    #set pidfile '/opt/rt4/var/run/fetchmail-rtir.pid'


  chmod o+x /&lt;path-to-mailgate&gt;/rt-mailgate
    poll "IP_OF_MAIL_SERVER" proto imap port 993
        user "rt@mycompany.com" password "password"
        ssl
        folder 'Inbox'
    # Some IMAP servers generate an error like this:
    #
    # could not decode BASE64 challenge
    #
    # This might be because the server is configured to expect
    # certain authentication attempt types, first. fetchmail also
    # tries certain authentication methods first, but not password,
    # even with the 'password' keyword.
    #
    # The 'auth' keyword tells fetchmail to attempt the given
    # authentication type, first. That can eliminate initial
    # authentication failures, which might eliminate this error
    # messgae
    # auth password


For more information on configuring your mail gateway, see [[ManualAdministration]]
    # IMAP supports flags on individual messages to indicate the
    # message status. The 'Seen' flag indicates that the message has
    # been read by a client. This could be a webmail client like Gmail
    # our Outlook, or fetchmail. The RT use case for fetchmail expects
    # that fetchmail will get all mail that hasn't been delivered to
    # RT, regardless of whether other clients have seen it. Without
    # this option, fetchmail will only download mail from an IMAP
    # server without the 'Seen' flag. This option tells fetchmail to
    # ignore 'Seen' flags and download all messages.
    # fetchall


    mda '/opt/rt4/bin/rt-mailgate --url https://rt.mycompany.com --queue "support" --action correspond'
    idle
----
----


Prev: [[ManualApacheConfig]] --- Up: [[UserManual]] --- Next: [[ManualBasicAdministration]]
Prev: [[ManualApacheConfig]] --- Up: [[UserManual]] --- Next: [[ManualBasicAdministration]]
[[Category:RT User Manual]]
[[Category:RT User Manual]]

Revision as of 10:24, 22 March 2019

Prev: ManualApacheConfig --- Up: UserManual --- Next: ManualBasicAdministration


SETTING UP THE MAIL GATEWAY

The mail gateway is used to receive mail messages into an RT instance; outbound mail is usually just handed off to the local SMTP sending program, or a specified SMTP smarthost.

The mail gateway requires the web UI to be set up and functional. If you intend to use SSL to secure your mail gateway, you need to make sure that lib-www-perl, a.k.a LWP, is built with SSL support.

1) Documentation for setting up the mail gateway can be found at:

https://docs.bestpractical.com/rt/latest/rt-mailgate.html

2) You need to tell your Mail Transfer Agent (e.g. sendmail, postfix, or qmail) how to forward messages to RT's mail gateway. To do this, create an aliases in your system's mail aliases file. Here's an example, which routes mail to the mailbox [=rt@example.com] (and [=rt-comment@example.com]) into new tickets in the RT queue named General. Note that the queue name is case-insensitive.

Add the following lines to /etc/aliases (or your local equivalent such as /etc/mail/aliases):

    rt: "|/opt/rt4/bin/rt-mailgate --queue general --action correspond --url http://localhost/rt"
    rt-comment: "|/opt/rt4/bin/rt-mailgate --queue general --action comment --url http://localhost/rt"

(Replace /opt/rt4 by your RT installation path and http://localhost/rt by the URL of your RT installation on your webserver)

NOTE: When you add the above each alias entry should be all one line; make sure you include the quotes.

NOTE: qmail users should follow the QMail link to review caveats about fastforward command aliases.

Replace general with the name of your queue and rt (before the colon in the alias) with the email address you wish people to send their messages to. You might, for example, have messages to support go into the service queue, and abuse go into the ops queue. You can have more than one set of aliases point to the same queue, if, for example, you wanted mail to both abuse and security both go to the ops queue.

The queue name may have spaces. rt-mailgate works as well with them, but do not forget to escape these spaces by enclosing the queue name in single quote:

   my-queue: "|/opt/rt4/bin/rt-mailgate --queue 'My Queue' --action correspond --url http://localhost/"

If you are using the default sendmail included in most redhat distro's you will most likely need to copy (cp) rt-mailgate to /etc/smrsh or create a symbolic link and change /opt/rt4/bin above to /etc/smrsh or sendmail will complain. These sendmails will only execute programs as alias targets which have been blessed by placing them in a special directory. This is not necessary for Exim or postfix.

You'll choose from "--action correspond" and "--action comment" depending on whether the mail should be resent to the requestor. If you want the requestor to see it, choose correspond; if you want to keep it from the requestor, choose comment.

The URL will be the URL for RT's web interface, such as http://issues.bestpractical.com/, =; whatever is the root of your RT install.

3) Stop and start your mail server, so it picks up your configuration changes. With sendmail or postfix (possibly others), you usually also need to type the command "newaliases" to get the server to recognize the new aliases. If this command is unrecognized, it's probably not in your default path; a common location is "/usr/sbin/newaliases".

You can have the mail gateway on your MX or some other server and have it talk to RT via HTTP. For more details, see InstallMailgateOnly.

To configure a mail transfer agent (postfix) to post tickets to RT4 on a separate server ....

Add the following lines to /etc/aliases (or your local equivalent such as /etc/mail/aliases):

   rt: "|/<path-to-mailgate>/rt-mailgate --queue general --action correspond --url http://<the-URL-of-the-RT-server>/"
   rt-comment: "|/<path-to-mailgate>/rt-mailgate --queue general --action comment --url http://<the-URL-of-the-RT-server>/"

The link to RT is now configured. However, the rt-mailgate script is a perl script which requires support. On a fresh SuSE 9.3 server install, the following was needed to provide the necessary perl libraries (someone with deeper knowledge may know of a more restrictive set of libraries, but these worked).

#(install gcc and glibc, if necessary)
perl -MCPAN -eshell (to configure CPAN)
perl -MCPAN -e 'install("LWP")'
perl -MCPAN -e 'install("Bundle::LWP")'

If Using SSL, add:

   perl -MCPAN -e 'install("Crypt::SSLeay")'

To test the connection...

  echo 'hello' | mail -s "Test subject" rt

If you get a "command died with status 1" error message, the rt-mailgate script possibly doesn't have the execute bit set for the user/group under which postfix is running.

  chmod o+x /<path-to-mailgate>/rt-mailgate

For more information on configuring your mail gateway, see ManualAdministration


Using Fetchmail/Getmail For Incoming Email

Fetchmail or Getmail can be used to fetch email from a inbox using IMAP or POP. An example configuration for Fetchmail can be seen below:

   set daemon 0
   # PID files are more useful for forking systemd services. But fetchmail will
   # always write one. Since the service runs fetchmail as the apache user,
   # www-data, we need to give fetchmail a path that it has write permission to.
   #set pidfile '/opt/rt4/var/run/fetchmail-rtir.pid'
   poll "IP_OF_MAIL_SERVER" proto imap port 993
       user "rt@mycompany.com" password "password"
       ssl
       folder 'Inbox'
   # Some IMAP servers generate an error like this:
   #
   # could not decode BASE64 challenge
   #
   # This might be because the server is configured to expect
   # certain authentication attempt types, first. fetchmail also
   # tries certain authentication methods first, but not password,
   # even with the 'password' keyword.
   #
   # The 'auth' keyword tells fetchmail to attempt the given
   # authentication type, first. That can eliminate initial
   # authentication failures, which might eliminate this error
   # messgae
   #  auth password
   # IMAP supports flags on individual messages to indicate the
   # message status. The 'Seen' flag indicates that the message has
   # been read by a client. This could be a webmail client like Gmail
   # our Outlook, or fetchmail. The RT use case for fetchmail expects
   # that fetchmail will get all mail that hasn't been delivered to
   # RT, regardless of whether other clients have seen it. Without
   # this option, fetchmail will only download mail from an IMAP
   # server without the 'Seen' flag. This option tells fetchmail to
   # ignore 'Seen' flags and download all messages.
   # fetchall
   mda '/opt/rt4/bin/rt-mailgate --url https://rt.mycompany.com --queue "support" --action correspond'
   idle

Prev: ManualApacheConfig --- Up: UserManual --- Next: ManualBasicAdministration