Notes for the Debian package rt5-clients.

RT COMMAND-LINE TOOL
--------------------

The file /etc/request-tracker5/rt.conf should be edited to reflect the
server URL.

Note that the rt command-line tool (and the REST interface underlying it)
does not provide all possible functionality. It is designed to allow
common operations on tickets and queues, but cannot be used to configure
all aspects of RT.

It is possible to write standalone specialised administrative tools
by writing Perl code against the RT Perl API; however this is not
particularly well documented. See
<http://wiki.bestpractical.com/view/Contributions> for inspiration.

HTTPS
-----

If you want mailgate or the RT CLI to talk HTTPS to the server rather
than plain HTTP, you need libio-socket-ssl-perl.


MAIL CONFIGURATION
------------------

Integrating RT with your MTA is a fairly complex topic and there is more
than one way to do it.

Generic aliases
---------------

The most general is to configure a general correspondence and comment
alias as follows:

Add the following lines to the mail aliases (/etc/aliases):

rt:         "|/usr/bin/rt-mailgate --queue General --action correspond --url <url>"
rt-comment: "|/usr/bin/rt-mailgate --queue General --action comment --url <url>"

where <url> is the base URL of your RT system,
e.g. https://rt.example.com/ or http://www.example.com/rt/.

If you want your URL to be HTTPS, you need to install
libio-socket-ssl-perl too.

If you are using exim4 you will probably need to manually turn on pipe
support. There are two options
  1- (using exim split config)
  2- (using exim monolithic config)

(1) Create a file:

  # echo "SYSTEM_ALIASES_PIPE_TRANSPORT = address_pipe" >> /etc/exim4/conf.d/main/90_exim4-config_requesttracker

(2) Do this:

  Edit the file /etc/exim4/exim4.conf.template and find the line "begin acl"
  before this line, add:

.ifndef SYSTEM_ALIASES_PIPE_TRANSPORT
SYSTEM_ALIASES_PIPE_TRANSPORT = address_pipe
.endif

After both (1) and (2), you need to update and reload exim4:

  # /usr/sbin/update-exim4.conf
  # /etc/init.d/exim4 reload

If you are using Sendmail you will need to add rt-mailgate into the
/etc/mail/smrsh/ directory. Do something like:

ln -s /usr/bin/rt-mailgate /etc/mail/smrsh/rt-mailgate

The smrsh directory contains all the binaries that Sendmail is
permitted to run via the '|program' syntax in order to improve the
over all security of your system. See smrsh(8) for more details.

Configuration hints for other MTAs are warmly appreciated! (Please
file wishlist bug-reports.)

Exim 4 example configuration
----------------------------

If you are using Exim 4 you can use a more powerful alternative to
the aliases above which does not require specific configuration for
each queue. You will need to be familiar with Exim 4 configuration
before using these snippets. You will also need to know whether you
are using a split config mechanism or not.

These really are just examples; you will need to tweak them depending
on your exact requirements.

General config:

RT_USER=nobody
RT_URL=http://rt.example.com

The RT transport can look something like this:

rt_transport:
  driver = pipe
  user = RT_USER
  command = rt-mailgate \
    --action '${if def:local_part_suffix {comment}{correspond}}' \
    --queue "$local_part" \
    --url RT_URL

and the router:

rt_router:
  driver = accept
  local_part_prefix = rt-
  # Enable this if you want the rt addresses to work only for specific virtual
  # hosts:
  #domains = rt.example.org : rt.example.com
  # Enable this if you only want certain queues to work, instead of anything:
  #local_parts = general : network-problems : administration
  local_part_suffix_optional
  local_part_suffix = -comment
  transport = rt_transport

If you are able to give Exim access to your database you don't even need
to hard-code the list of valid queues. You could add some configuration
such as:

QUEUENAME_QUERY   = \
  SELECT Name FROM Queues WHERE \
  CorrespondAddress = '${quote_mysql:$local_part}@${quote_mysql:$domain}' \
  AND Disabled = '0'

hide mysql_servers = $DBHOST/$DBNAME/$DBUSER/$DBPASSWORD

and then add to your rt_router:

  local_parts = mysql; QUEUENAME_QUERY

DEBUGGING DEFERRED DELIVERIES
-----------------------------

If your mails are just getting deferred with temporary failures, running
rt-mailgate from the command line may help to pinpoint the problem. An
example where libio-socket-ssl-perl is missing:

  % echo 'From: <root@localhost>' | rt-mailgate --queue general --action correspond --url https://localhost/rt/
  An Error Occurred
  =================
  
  501 Protocol scheme 'https' is not supported
  (Crypt::SSLeay not installed)

Authors
-------

Stephen Quinney <sjq@debian.org>, Thu Sep 15 15:23:30 2005
Niko Tyni <ntyni@iki.fi> Mon, 27 Nov 2006 22:57:00 +0200
Dominic Hargreaves <dom@earth.li>, Sun Jan 30 13:17:49 UTC 2011
