bugzilla-guide.txt

bugzilla

       Warning

   You should also ensure that you have disabled KeepAlive support in your
   Apache install when utilizing Bugzilla under mod_perl

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


    3. checksetup.pl can set tighter permissions on Bugzilla's files and
       directories if it knows what group the web server runs as. Find the
       Group line in httpd.conf, place the value found there in the
       $webservergroup variable in localconfig, then rerun checksetup.pl.

   On restarting Apache, Bugzilla should now be running within the mod_perl
   environment. Please ensure you have run checksetup.pl to set permissions
   before you restart Apache.

   Note

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

     * mod_perl support in Bugzilla can take up a HUGE amount of RAM. You could
       be looking at 30MB per httpd child, easily. Basically, you just need a
       lot of RAM. 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.
     _________________________________________________________________

2.2.4.2. Microsoft Internet Information Services

   If you are running Bugzilla on Windows and choose to use Microsoft's
   Internet Information Services or Personal Web Server you will need to
   perform a number of other configuration steps as explained below. You may
   also want to refer to the following Microsoft Knowledge Base articles:
   245225 "HOW TO: Configure and Test a PERL Script with IIS 4.0, 5.0, and 5.1"
   (for Internet Information Services) and 231998 "HOW TO: FP2000: How to Use
   Perl with Microsoft Personal Web Server on Windows 95/98" (for Personal Web
   Server).

   You will need to create a virtual directory for the Bugzilla install. Put
   the Bugzilla files in a directory that is named something other than what
   you want your end-users accessing. That is, if you want your users to access
   your Bugzilla installation through "http://<yourdomainname>/Bugzilla", then
   do not put your Bugzilla files in a directory named "Bugzilla". Instead,
   place them in a different location, and then use the IIS Administration tool
   to create a Virtual Directory named "Bugzilla" that acts as an alias for the
   actual location of the files. When creating that virtual directory, make
   sure you add the "Execute (such as ISAPI applications or CGI)" access
   permission.

   You will also need to tell IIS how to handle Bugzilla's .cgi files. Using
   the IIS Administration tool again, open up the properties for the new
   virtual directory and select the Configuration option to access the Script
   Mappings. Create an entry mapping .cgi to:
<full path to perl.exe >\perl.exe -x<full path to Bugzilla> -wT "%s" %s

   For example:
c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s

   Note

   The ActiveState install may have already created an entry for .pl files that
   is limited to "GET,HEAD,POST". If so, this mapping should be removed as
   Bugzilla's .pl files are not designed to be run via a web server.

   IIS will also need to know that the index.cgi should be treated as a default
   document. On the Documents tab page of the virtual directory properties, you
   need to add index.cgi as a default document type. If you wish, you may
   remove the other default document types for this particular virtual
   directory, since Bugzilla doesn't use any of them.

   Also, and this can't be stressed enough, make sure that files such as
   localconfig and your data directory are secured as described in Section
   4.3.1.
     _________________________________________________________________

2.2.5. Bugzilla

   Your Bugzilla should now be working. Access http://<your-bugzilla-server>/ -
   you should see the Bugzilla front page. If not, consult the Troubleshooting
   section, Appendix B.

   Note

   The URL above may be incorrect if you installed Bugzilla into a subdirectory
   or used a symbolic link from your web site root to the Bugzilla directory.

   Log in with the administrator account you defined in the last checksetup.pl
   run. You should go through the parameters on the Edit Parameters page (see
   link in the footer) and see if there are any you wish to change. They key
   parameters are documented in Section 3.1; you should certainly alter
   maintainer and urlbase; you may also want to alter cookiepath or
   requirelogin.

   This would also be a good time to revisit the localconfig file and make sure
   that the names of the priorities, severities, platforms and operating
   systems are those you wish to use when you start creating bugs. Remember to
   rerun checksetup.pl if you change it.

   Bugzilla has several optional features which require extra configuration.
   You can read about those in Section 2.3.
     _________________________________________________________________

2.3. Optional Additional Configuration

   Bugzilla has a number of optional features. This section describes how to
   configure or enable them.
     _________________________________________________________________

2.3.1. Bug Graphs

   If you have installed the necessary Perl modules you can start collecting
   statistics for the nifty Bugzilla graphs.
   bash# crontab -e

   This should bring up the crontab file in your editor. Add a cron entry like
   this to run collectstats.pl daily at 5 after midnight:
   5 0 * * * cd <your-bugzilla-directory> ; ./collectstats.pl

   After two days have passed you'll be able to view bug graphs from the
   Reports page.

   When upgrading Bugzilla, this format may change. To create new status data,
   (re)move old data and run the following commands:
        bash$
        cd <your-bugzilla-directory>
        bash$
        ./collectstats.pl --regenerate

   Note

   Windows does not have 'cron', but it does have the Task Scheduler, which
   performs the same duties. There are also third-party tools that can be used
   to implement cron, such as nncron.
     _________________________________________________________________

2.3.2. Dependency Charts

   As well as the text-based dependency trees, Bugzilla also supports a
   graphical view of dependency relationships, using a package called 'dot'.
   Exactly how this works is controlled by the 'webdotbase' parameter, which
   can have one of three values:

    1. A complete file path to the command 'dot' (part of GraphViz) will
       generate the graphs locally
    2. A URL prefix pointing to an installation of the webdot package will
       generate the graphs remotely
    3. A blank value will disable dependency graphing.

   The easiest way to get this working is to install GraphViz. If you do that,
   you need to enable server-side image maps in Apache. Alternatively, you
   could set up a webdot server, or use the AT&T public webdot server. This is
   the default for the webdotbase param, but it's often overloaded and slow.
   Note that AT&T's server won't work if Bugzilla is only accessible using
   HARTS. Editor's note: What the heck is HARTS? Google doesn't know... 
     _________________________________________________________________

2.3.3. The Whining Cron

   What good are bugs if they're not annoying? To help make them more so you
   can set up Bugzilla's automatic whining system to complain at engineers
   which leave their bugs in the NEW or REOPENED state without triaging them.

   This can be done by adding the following command as a daily crontab entry,
   in the same manner as explained above for bug graphs. This example runs it
   at 12.55am.
   55 0 * * * cd <your-bugzilla-directory> ; ./whineatnews.pl

   Note

   Windows does not have 'cron', but it does have the Task Scheduler, which
   performs the same duties. There are also third-party tools that can be used
   to implement cron, such as nncron.
     _________________________________________________________________

2.3.4. Whining

   As of Bugzilla 2.20, users can configure Bugzilla to regularly annoy them at
   regular intervals, by having Bugzilla execute saved searches at certain
   times and emailing the results to the user. This is known as "Whining". The
   process of configuring Whining is described in Section 5.13, but for it to
   work a Perl script must be executed at regular intervals.

   This can be done by adding the following command as a daily crontab entry,
   in the same manner as explained above for bug graphs. This example runs it
   every 15 minutes.
   */15 * * * * cd <your-bugzilla-directory> ; ./whine.pl

   Note

   Whines can be executed as often as every 15 minutes, so if you specify
   longer intervals between executions of whine.pl, some users may not be
   whined at as often as they would expect. Depending on the person, this can
   either be a very Good Thing or a very Bad Thing.

   Note

   Windows does not have 'cron', but it does have the Task Scheduler, which
   performs the same duties. There are also third-party tools that can be used
   to implement cron, such as nncron.
     _________________________________________________________________

2.3.5. Serving Alternate Formats with the right MIME type

   Some Bugzilla pages have alternate formats, other than just plain HTML. In
   particular, a few Bugzilla pages can output their contents as either XUL (a
   special Mozilla format, that looks like a program GUI) or RDF (a type of
   structured XML that can be read by various programs).

   In order for your users to see these pages correctly, Apache must send them
   with the right MIME type. To do this, add the following lines to your Apache
   configuration, either in the <VirtualHost> section for your Bugzilla, or in
   the <Directory> section for your Bugzilla:

AddType application/vnd.mozilla.xul+xml .xul
AddType application/rdf+xml .rdf
     _________________________________________________________________

2.4. Multiple Bugzilla databases with a single installation

   The previous instructions referred to a standard installation, with one
   unique Bugzilla database. However, you may want to host several distinct
   installations, without having several copies of the code. This is possible
   by using the PROJECT environment variable. When accessed, Bugzilla checks
   for the existence of this variable, and if present, uses its value to check
   for an alternative configuration file named localconfig.<PROJECT> in the
   same location as the default one (localconfig). It also checks for
   customized templates in a directory named <PROJECT> in the same location as
   the default one (template/<langcode>). By default this is
   template/en/default so PROJECT's templates would be located at
   template/en/PROJECT.

   To set up an alternate installation, just export PROJECT=foo before running
   checksetup.pl for the first time. It will result in a file called
   localconfig.foo instead of localconfig. Edit this file as described above,
   with reference to a new database, and re-run checksetup.pl to populate it.
   That's all.

   Now you have to configure the web server to pass this environment variable
   when accessed via an alternate URL, such as virtual host for instance. The
   following is an example of how you could do it in Apache, other Webservers
   may differ.
<VirtualHost 212.85.153.228:80>
    ServerName foo.bar.baz
    SetEnv PROJECT foo
    Alias /bugzilla /var/www/bugzilla
</VirtualHost>

   Don't forget to also export this variable before accessing Bugzilla by other
   means, such as cron tasks for instance.
     _________________________________________________________________

2.5. OS-Specific Installation Notes

   Many aspects of the Bugzilla installation can be affected by the operating
   system you choose to install it on. Sometimes it can be made easier and
   others more difficult. This section will attempt to help you understand both
   the difficulties of running on specific operating systems and the utilities
   available to make it easier.

   If you have anything to add or notes for an operating system not covered,
   please file a bug in Bugzilla Documentation.
     _________________________________________________________________

2.5.1. Microsoft Windows

   Making Bugzilla work on Windows is more difficult than making it work on
   Unix. For that reason, we still recommend doing so on a Unix based system
   such as GNU/Linux. That said, if you do want to get Bugzilla running on
   Windows, you will need to make the following adjustments. A detailed
   step-by-step installation guide for Windows is also available if you need
   more help with your installation.
     _________________________________________________________________

2.5.1.1. Win32 Perl

   Perl for Windows can be obtained from ActiveState. You should be able to
   find a compiled binary at
   http://aspn.activestate.com/ASPN/Downloads/ActivePerl/. The following
   instructions assume that you are using version 5.8.1 of ActiveState.

   Note

   These instructions are for 32-bit versions of Windows. If you are using a
   64-bit version of Windows, you will need to install 32-bit Perl in order to
   install the 32-bit modules as described below.
     _________________________________________________________________

2.5.1.2. Perl Modules on Win32

   Bugzilla on Windows requires the same perl modules found in Section 2.1.5.
   The main difference is that windows uses PPM instead of CPAN. ActiveState