Apache
******

You have two options for running Bugzilla under Apache - mod_cgi (the
default) and mod_perl. mod_perl is faster but takes more resources.
You should probably only consider mod_perl if your Bugzilla is going
to be heavily used.

These instructions require editing the Apache configuration file,
which is:

* Fedora/Red Hat: "/etc/httpd/conf/httpd.conf"

* Debian/Ubuntu: "/etc/apache2/apache2.conf"

* Mac OS X: "/etc/apache2/httpd.conf"

Alternatively, on Debian or Ubuntu, you can instead put the below code
into a separate file in the directory "/etc/apache2/sites-enabled/".

In these instructions, when asked to restart Apache, the command is:

**sudo apachectl start**

(or run it as root if your OS installation does not use sudo).


Securing Apache
===============

When external systems interact with Bugzilla via webservices
(REST/XMLRPC/JSONRPC) they include the user's credentials as part of
the URL (in the "query string"). Therefore, to avoid storing passwords
in clear text on the server we recommend configuring Apache to not
include the query string in its log files.

1. Edit the Apache configuration file (see above).

2. Find the following line in the above mentioned file, which
   defines the logging format for "vhost_combined":

      LogFormat "%v:%p %h %l %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-Agent}i\"" vhost_combined

3. Replace "%r" with "%m %U".

4. Restart Apache.


Apache with mod_cgi
===================

To configure your Apache web server to work with Bugzilla while using
mod_cgi, do the following:

1. Edit the Apache configuration file (see above).

2. Create a "<Directory>" directive that applies to the location of
   your Bugzilla installation. In this example, Bugzilla has been
   installed at "/var/www/html/bugzilla". On Mac OS X, use
   "/Library/WebServer/Documents/bugzilla".

   <Directory /var/www/html/bugzilla>
     AddHandler cgi-script .cgi
     Options +ExecCGI +FollowSymLinks
     DirectoryIndex index.cgi index.html
     AllowOverride All
   </Directory>

These instructions allow Apache to run .cgi files found within the
Bugzilla directory; instructs the server to look for a file called
"index.cgi" or, if not found, "index.html" if someone only types the
directory name into the browser; and allows Bugzilla's ".htaccess"
files to override some global permissions.

On some Linux distributions you will need to enable the Apache CGI
module. On Debian/Ubuntu, this is done with:

**sudo a2enmod cgi**

If you find that the webserver is returning the Perl code as text
rather than executing it, then this is the problem.


Apache with mod_perl
====================

Some configuration is required to make Bugzilla work with Apache and
mod_perl.

Note: It is not known whether anyone has even tried mod_perl on Mac
  OS X.

1. Edit the Apache configuration file (see above).

2. Add the following information, substituting where appropriate
   with your own local paths.

      PerlSwitches -w -T
      PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl

   Note: This should be used instead of the <Directory> block shown
     above. This should also be above any other "mod_perl" directives
     within the "httpd.conf" and the directives must be specified in
     the order above.

   Warning: You should also ensure that you have disabled
     "KeepAlive" support in your Apache install when utilizing
     Bugzilla under mod_perl or you may suffer a performance penalty.

On restarting Apache, Bugzilla should now be running within the
mod_perl environment.

Please bear the following points in mind when considering using
Bugzilla under mod_perl:

* mod_perl support in Bugzilla can take up a HUGE amount of RAM -
  easily 30MB per httpd child. The more RAM you can get, the better.
  mod_perl is basically trading RAM for speed. At least 2GB total
  system RAM is recommended for running Bugzilla under mod_perl.

* Under mod_perl, you have to restart Apache if you make any manual
  change to any Bugzilla file. You can't just reload--you have to
  actually *restart* the server (as in make sure it stops and starts
  again). You *can* change "localconfig" and the "params" file
  manually, if you want, because those are re-read every time you load
  a page.

* You must run in Apache's Prefork MPM (this is the default). The
  Worker MPM may not work -- we haven't tested Bugzilla's mod_perl
  support under threads. (And, in fact, we're fairly sure it *won't*
  work.)

* Bugzilla generally expects to be the only mod_perl application
  running on your entire server. It may or may not work if there are
  other applications also running under mod_perl. It does try its best
  to play nice with other mod_perl applications, but it still may have
  conflicts.

* It is recommended that you have one Bugzilla instance running
  under mod_perl on your server. Bugzilla has not been tested with
  more than one instance running.

======================================================================

This documentation undoubtedly has bugs; if you find some, please file
them here.