[rt-users] Updated installation docs
Dan Shearer
dan at tellurian.com.au
Sun May 5 11:14:18 EDT 2002
Following is a diff against the README in the current CVS for 2.0.x. It
should probably have gone into the docs at http://fsck.com/rtfm/ but I
don't know where their sources are. It needs some review but I think it
does clear up quite a lot of ambiguities, implied assumptions and errors.
If someone can point me to the sources for the proper docs I might (or
might not) produce some patches. There is a list called Rtfm-devel, but
I can't work out what it is for; presumably not RT docco.
--
Dan Shearer
Open Source Manager
Tel: +61 8 8130 3104
dan at tellurian.com.au
--- ../rt/README Mon Jan 28 16:16:47 2002
+++ README Mon May 6 00:30:09 2002
@@ -1,6 +1,18 @@
$Header: /raid/cvsroot/rt/README,v 1.40 2002/01/28 05:46:47 jesse Exp $
RT is (c) 1996-2002 by Jesse Vincent <jesse at bestpractical.com>
+INTRODUCTION
+------------
+
+This README is for the RT request tracking system, see
+http://www.bestpractical.com/rt. It covers the version 2.0.x series of
+releases. There is also a version 2.1.x series under heavy development, which
+will one day surface as version 2.2.x. You will learn nothing about 2.1.x
+from this file.
+
+LICENSING
+---------
+
RT is licensed to you under the terms of version 2 of the GNU General
Public License.
@@ -23,19 +35,46 @@
RT's command line and mail gateway tools run setgid to the 'rt' group
to protect RT's database password. You may need to install a special
"suidperl" package or reconfigure your perl setup to support
- "setuid scripts".
+ "setuid scripts". For example, in FreeBSD this package is called
+ "sperl", in Debian GNU/* it is called "perl-suid".
o A DB backend; MySQL is recommended ( http://www.mysql.com )
Currently supported: Mysql 3.23.38 or newer.
(Some older releases had crippling SQL bugs)
- Postgres 7.1 or newer.
+ Postgres 7.1 or newer
+ ( http://www.postgresql.org)
+
+ Because the Perl::DBI package needs to talk with the database via
+ a C calling interface you need to install the appropriate C header files
+ for your database. Many Unix distributions have two packages, the
+ database (eg mysql or postgresql) and the development libraries and
+ header files (eg mysql-dev or postgresql-dev). Both need to be installed.
+ If you are installing the database from pristine sources then you should
+ have no problem. If you are using some other packaging scheme such as the
+ FreeBSD ports collection then please contribute your experiences here.
+
+ To summarise the previous paragraph: unless the C header files for the
+ database are present, the essential Perl::DBI module cannot be installed.
+
+ Don't forget to setup permissions for your database. For example, with
+ Postgresql, maybe you need to edit the pg_hba (Host Based Access) file
+ to allow connections from localhost using something less than encrypted
+ passwords for convenience (if that is what you want to do, which can
+ frequently be a very bad idea!).
o Apache + mod_perl -- ( http://perl.apache.org)
- or A webserver with FastCGI support (www.fastcgi.com)
+ (or a webserver with FastCGI support (www.fastcgi.com), but only
+ if you want to live on the bleeding edge.)
+
+ The Perl::Apache:Cookie module needs to interface to Apache via C
+ header files in a similar way to the database routines. For many
+ Unixes this means you have to install the apache-dev package as well
+ as apache (and usually apache-perl too). If you are installing from
+ pristine Apache sources then you should have no problem.
If you compile mod_perl as a DSO, you're on your own. It's known
to have massive stability problems.
- mod_perl must be build with EVERYTHING=1
+ mod_perl must be built with EVERYTHING=1
o Various and sundry perl modules
RT takes care of the installation of most of these automatically
@@ -51,26 +90,53 @@
tar xzvf rt.tar.gz -C /tmp
+ another good place might be /usr/src, so you have a copy of the
+ install files (and the ability to uninstall) somewhere more
+ permanent than in /tmp.
+
2 Check over /tmp/rt/Makefile
There are many variables you NEED to customize for your site.
Even if you are just upgrading, you must set ALL variables.
3 Satisfy RT's myriad dependencies. There's a perl script in rt/tools
- called testdeps that uses CPAN to automate all of this.
+ called testdeps that uses CPAN to automate all of this, but you are
+ not expected to call it directly. Use it via the makefile as explained
+ below, because the results may well be different.
3.1 Check for compliance:
make testdeps
3.2 If there are unsatisfied dependencies, install them by hand or run
- make fixdeps
-
- (You may need to install Apache::Session and Apache::DBI by hand.
+ make fixdeps.
+
+ make fixdeps must be run as a user with write privilege to various
+ bits of the Perl hierachy, usually root.
- You might need to install Msql-Mysql-Modules by hand.
- perl -MCPAN -e'install DBD::mysql::Install' should do it for you.
- )
+ If you are using Postgresql for your database then you will need
+ to set two environment variables something like the following
+ before running make fixdeps:
+ export POSTGRES_LIB=/usr/lib/libpq.so.2
+ export POSTGRES_INCLUDE=/usr/include/postgresql
+
+ Depending on how badly or well your operating system distributor has
+ put together Perl, CPAN and all the other bits required, you may need
+ to install Apache::Session and Apache::DBI by hand. However at least
+ one Linux (Debian) has no need for this.
+
+ Similarly, you might need to install Msql-Mysql-Modules by hand.
+ perl -MCPAN -e'install DBD::mysql::Install' should do it for you.
+
+ If something went wrong (eg you suddenly realised that you hadn't
+ got the Postgresql header files, or weren't running as root) then
+ you can restart as many times as you like. A cache is kept under
+ the directory .cpan in the home directory of the user running
+ make testdeps. Using a tool such as sudo to run make fixdeps
+ as root can help by keeping the CPAN cache in the home directory of
+ whoever is running sudo rather than spreading it across the
+ root user's homedir as well.
+
3.3 Check to make sure everything was installed properly:
make testdeps
@@ -84,7 +150,7 @@
If the make fails, type:
make dropdb
- and start over from step 5a
+ and goto step 5a
5b FOR UPGRADING: (Within the RT 2.0.x series)
@@ -92,7 +158,7 @@
As root, type:
make upgrade (replace "make" with the local name for
- Make, if you need to)
+ Make, if you need toi, such as Gmake)
This will build new binaries, config files and libraries without
overwriting your RT database.
@@ -133,7 +199,8 @@
6 Edit etc/config.pm in your RT installation directory. In many
cases sensible defaults have been included. In others, you MUST
- supply a value.
+ supply a value. Some values (such as the RT log directory) will come
+ from values you supplied in the Makefile.
7 Configure the email and web gateways, as described below.
@@ -152,11 +219,33 @@
SETTING UP THE MAIL GATEWAY
---------------------------
-An alias for the initial queue will need to be made in either your
-global mail aliases file (if you are using NIS) or locally on your
-machine.
-
-Add the following lines to /etc/aliases (or your local equivalent) :
+Before doing anything else, make sure that rt-mailgate runs from the
+commandline. You might have to point it specifically to your setuid perl
+package (using something like "#!/usr/bin/perl-suid") or your perl might
+do this automatically. If rt-mailgate can't find config.pm then check
+the permissions - it should be setgid to the rt group as defined in the
+Makefile.
+
+You also need to give the Everyone pseudogroup the privilege "CreateTicket"
+on all queues that rt-mailgate will be using, because mail requests are by
+default unauthenticated. (There is a mechanism where %RT USER and %RT PASS are
+variables that can be set in email text, but if you are that desperate you
+will find out about it yourself.) If you also wish to allow comments to
+be added by email, as is usually the case, then you also need to grant the
+two privileges "CommentOnTicket" and "ReplyToTicket".
+
+Next, you need to review the (scanty) documentation on rt-mailgate. Understand
+the difference between the three kinds of actions, and be aware that only
+the "correspond" action can create queues.
+
+There are many ways of interfacing your mail transport agent (Exim, Postfix,
+qmail, Sendmail etc) to the RT mail program rt-mailgate. The general idea
+is that some amount of work is done by the aliases mechanism your MTA
+usually uses, and some amount in the configuration files of your MTA.
+
+If you want to just use /etc/aliases, and your MTA is happy with this,
+you might add some entries that look like this, one pair for every RT queue
+that you have:
rt: "|/path/to/rt2/bin/rt-mailgate --queue general --action correspond"
rt-comment: "|/path/to/rt2/bin/rt-mailgate --queue general --action comment"
@@ -166,7 +255,19 @@
<correspond or comment depending on whether |
the mail should be resent to the requestor>---/
+However this doesn't scale very well, because you need to make changes every
+time you add a queue or even change its name. And besides, there is no
+reason why the mail alias that users know about should be tied in any way
+to the RT processing mechanism.
+
+So a smarter scheme is to configure the MTA so that it has a cue that
+a particular message format belongs to RT, and then just pass all such
+messages to RT. For example, rt-queuename-comment and rt-queuename-correspond
+might be the mail alias names, but the MTA knows to strip off the "rt-" at
+the beginning, and to parse the "-action" bit at the end into a separate
+parameter for mailgate.
+There are some examples of this on the web, especially for Exim.
THE WEB UI
----------
@@ -193,6 +294,9 @@
PerlHandler RT::Mason
</Location>
</VirtualHost>
+
+Many sites may not need the "PerlModule Apache:DBI" and PerlFreshRestart On"
+lines, in fact in many cases Apache:DBI will cause an error.
Additionally, you should set up a cron job to remove stale session data.
More information about the rt-users
mailing list