<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
<!-- $Id: installation.xml,v 1.101 2005/07/25 12:50:49 mozilla%colinogilvie.co.uk Exp $ -->
<chapter id="installing-bugzilla">
  <title>Installing Bugzilla</title>

  <section id="installation">
    <title>Installation</title>

    <note>
      <para>If you just want to <emphasis>use</emphasis> Bugzilla, 
      you do not need to install it. None of this chapter is relevant to
      you. Ask your Bugzilla administrator
      for the URL to access it over the web.
      </para>
    </note>

    <para>The Bugzilla server software is usually installed on Linux or 
    Solaris. 
    If you are installing on another OS, check <xref linkend="os-specific"/>
    before you start your installation to see if there are any special
    instructions.
    </para>

    <para>
      As an alternative to following these instructions, you may wish to
      try Arne Schirmacher's unofficial and unsupported 
      <ulink url="http://www.softwaretesting.de/article/view/33/1/8/">Bugzilla
      Installer</ulink>, which installs Bugzilla and all its prerequisites
      on Linux or Solaris systems.
    </para>

    <para>This guide assumes that you have administrative access to the
    Bugzilla machine. It not possible to
    install and run Bugzilla itself without administrative access except
    in the very unlikely event that every single prerequisite is
    already installed.
    </para>

    <warning>
      <para>The installation process may make your machine insecure for
      short periods of time. Make sure there is a firewall between you
      and the Internet.
      </para>
    </warning>

    <para>
    You are strongly recommended to make a backup of your system
    before installing Bugzilla (and at regular intervals thereafter :-).
    </para>

    <para>In outline, the installation proceeds as follows:
    </para>

    <procedure>
      <step>
        <para><link linkend="install-perl">Install Perl</link>
        (&min-perl-ver; or above for non-Windows platforms; &min-perl-ver-win;
        for Windows)
        </para>
      </step>
      <step>
        <para><link linkend="install-database">Install a Database Engine</link>
        </para>
      </step>
      <step>
        <para><link linkend="install-webserver">Install a Webserver</link>
        </para>
      </step>
      <step>
        <para><link linkend="install-bzfiles">Install Bugzilla</link>
        </para>
      </step>
      <step>
        <para><link linkend="install-perlmodules">Install Perl modules</link>
        </para>
      </step>
      <step>
        <para>
          <link linkend="install-MTA">Install a Mail Transfer Agent</link>
          (Sendmail 8.7 or above, or an MTA that is Sendmail-compatible with at least this version)
        </para>
      </step>
      <step>
        <para>Configure all of the above.
        </para>
      </step>
    </procedure>

    <section id="install-perl">
      <title>Perl</title>

      <para>Installed Version Test: <filename>perl -v</filename></para>
      
      <para>Any machine that doesn't have Perl on it is a sad machine indeed.
      If you don't have it and your OS doesn't provide official packages, 
      visit <ulink url="http://www.perl.com"/>.
      Although Bugzilla runs with Perl &min-perl-ver;,
      it's a good idea to be using the latest stable version. 
      </para>
    </section>

    <section id="install-database">
      <title>Database Engine</title>
      
      <para>From Bugzilla 2.20, support is included for using both the MySQL and
      PostgreSQL database servers. You only require one of these systems to make
      use of Bugzilla.</para>

      <section id="install-mysql">
          <title>MySQL</title>
          <para>Installed Version Test: <filename>mysql -V</filename></para>
      
          <para>
          If you don't have it and your OS doesn't provide official packages, 
          visit <ulink url="http://www.mysql.com"/>. You need MySQL version
          &min-mysql-ver; or higher.
          </para>
      
          <note>
            <para> Many of the binary
            versions of MySQL store their data files in 
            <filename class="directory">/var</filename>.
            On some Unix systems, this is part of a smaller root partition,
            and may not have room for your bug database. To change the data
            directory, you have to build MySQL from source yourself, and
            set it as an option to <filename>configure</filename>.</para>
          </note> 
           
          <para>If you install from something other than a packaging/installation
          system, such as .rpm (Redhat Package), .deb (Debian Package), .exe
          (Windows Executable), or .msi (Microsoft Installer), make sure the MySQL
          server is started when the machine boots.
          </para>
      </section>
      
      <section id="install-pg">
          <title>PostgreSQL</title>
          <para>Installed Version Test: <filename>psql -V</filename></para>
      
          <para>
          If you don't have it and your OS doesn't provide official packages, 
          visit <ulink url="http://www.postgresql.org/"/>. You need PostgreSQL
          version &min-pg-ver; or higher.
          </para>
           
          <para>If you install from something other than a packaging/installation
          system, such as .rpm (Redhat Package), .deb (Debian Package), .exe
          (Windows Executable), or .msi (Microsoft Installer), make sure the
          PostgreSQL server is started when the machine boots.
          </para>
      </section>
      
    </section>
    
    <section id="install-webserver">
      <title>Web Server</title>

      <para>Installed Version Test: view the default welcome page at
      http://&lt;your-machine&gt;/</para>
      
      <para>You have freedom of choice here, pretty much any web server that
      is capable of running <glossterm linkend="gloss-cgi">CGI</glossterm>
      scripts will work.
       However, we strongly recommend using the Apache web server
       (either 1.3.x or 2.x), and 
       the installation instructions usually assume you are
        using it. If you have got Bugzilla working using another webserver,
        please share your experiences with us by filing a bug in &bzg-bugs;.
      </para>
      
      <para>
      If you don't have Apache and your OS doesn't provide official packages, 
      visit <ulink url="http://httpd.apache.org/"/>.
      </para>

    </section>

    <section id="install-bzfiles">
      <title>Bugzilla</title>

      <para>
        Download a Bugzilla tarball (or check it out from CVS) and place
        it in a suitable directory, accessible by the default web server user 
        (probably <quote>apache</quote> or <quote>www</quote>). 
        Good locations are either directly in the main web space for your
        web server or perhaps in 
        <filename>/usr/local</filename>
        with a symbolic link from the web space.
      </para>

      <caution>
        <para>The default Bugzilla distribution is NOT designed to be placed
        in a <filename class="directory">cgi-bin</filename> directory. This
        includes any directory which is configured using the
        <option>ScriptAlias</option> directive of Apache.
        </para>
      </caution>
      
      <para>Once all the files are in a web accessible directory, make that
      directory writable by your webserver's user. This is a temporary step
      until you run the 
      <filename>checksetup.pl</filename>
      script, which locks down your installation.</para>
    </section>

    <section id="install-perlmodules">
      <title>Perl Modules</title>
      
      <para>Bugzilla's installation process is based
      on a script called <filename>checksetup.pl</filename>. 
      The first thing it checks is whether you have appropriate 
      versions of all the required
      Perl modules. The aim of this section is to pass this check. 
      When it passes, 
      <emphasis>do not run it again</emphasis>, 
      but proceed to <xref linkend="configuration"/>.
      </para>
      
      <para>
      At this point, you need to <filename>su</filename> to root. You should
      remain as root until the end of the install. To check you have the
      required modules, run:
      </para>
      
      <screen><prompt>bash#</prompt> ./checksetup.pl --check-modules</screen>
 
      <para>
        <filename>checksetup.pl</filename> will print out a list of the
        required and optional Perl modules, together with the versions
        (if any) installed on your machine.
        The list of required modules is reasonably long; however, you 
        may already have several of them installed.
      </para>
      
      <para>
        There is a meta-module called Bundle::Bugzilla, 
        which installs all the other 
        modules with a single command. You should use this if you are running
        Perl 5.6.1 or above.
      </para>
      
      <para>
        The preferred way of installing Perl modules is via CPAN on Unix, 
        or PPM on Windows (see <xref linkend="win32-perl-modules"/>). These
        instructions assume you are using CPAN; if for some reason you need 
        to install the Perl modules manually, see 
        <xref linkend="install-perlmodules-manual"/>.
      </para>  
        
      <screen><prompt>bash#</prompt> perl -MCPAN -e 'install "&lt;modulename&gt;"'</screen>

      <para>
        If you using Bundle::Bugzilla, invoke the magic CPAN command on it.
        Otherwise, you need to work down the 
        list of modules that <filename>checksetup.pl</filename> says are
        required, in the order given, invoking the command on each.
      </para>
      
      <tip>
        <para>Many people complain that Perl modules will not install for
        them. Most times, the error messages complain that they are missing a
        file in 
        <quote>@INC</quote>. 
        Virtually every time, this error is due to permissions being set too
        restrictively for you to compile Perl modules or not having the
        necessary Perl development libraries installed on your system.
        Consult your local UNIX systems administrator for help solving these
        permissions issues; if you 
        <emphasis>are</emphasis>
        the local UNIX sysadmin, please consult the newsgroup/mailing list
        for further assistance or hire someone to help you out.</para>
      </tip>

      <note>
        <para>If you are using a package-based system, and attempting to install the
        Perl modules from CPAN, you may need to install the "development" packages for
        MySQL and GD before attempting to install the related Perl modules. The names of
        these packages will vary depending on the specific distribution you are using,
        but are often called <filename>&lt;packagename&gt;-devel</filename>.</para>
      </note>
 
      <para>
        Here is a complete list of modules and their minimum versions.
        Some modules have special installation notes, which follow.
      </para>

      <para>Required Perl modules:
      <orderedlist>

        <listitem>
          <para>
            AppConfig (&min-appconfig-ver;)
          </para>
        </listitem>

        <listitem>
          <para>
            CGI (&min-cgi-ver;)
          </para>
        </listitem>

        <listitem>
          <para>
            Data::Dumper (&min-data-dumper-ver;)
          </para>
        </listitem>
    
        <listitem>
          <para>
            Date::Format (&min-date-format-ver;)
          </para>
        </listitem>
    
        <listitem>
          <para>
            DBI (&min-dbi-ver;)
          </para>
        </listitem>

        <listitem>
          <para>
            <link linkend="install-modules-dbd-mysql">DBD::mysql</link>
            (&min-dbd-mysql-ver;) if using MySQL
          </para>
        </listitem>
        
        <listitem>
          <para>
            DBD::Pg (&min-dbd-pg-ver;) if using PostgreSQL
          </para>
        </listitem>

        <listitem>
          <para>
            File::Spec (&min-file-spec-ver;)
          </para>
        </listitem>

        <listitem>
          <para>
            File::Temp (&min-file-temp-ver;)
          </para>
        </listitem>

        <listitem>
          <para>
            <link linkend="install-modules-template">Template</link>
            (&min-template-ver;)
          </para>
        </listitem>

        <listitem>
          <para>
            Text::Wrap (&min-text-wrap-ver;)
          </para>
        </listitem>
        
        <listitem>
          <para>
            Mail::Mailer (&min-mail-mailer-ver;)
          </para>
        </listitem>
        
        <listitem>
          <para>
            Storable (&min-storable-ver;)
          </para>
        </listitem>
      </orderedlist>

      Optional Perl modules:
      <orderedlist>  
        <listitem>
          <para>
            <link linkend="install-modules-gd">GD</link>
            (&min-gd-ver;) for bug charting
          </para>
        </listitem>

        <listitem>
          <para>
            <link linkend="install-modules-chart-base">Chart::Base</link>
            (&min-chart-base-ver;) for bug charting
          </para>
        </listitem>

        <listitem>
          <para>
            <link linkend="install-modules-gd-graph">GD::Graph</link>
            (&min-gd-graph-ver;) for bug charting
          </para>
        </listitem>

        <listitem>
          <para>
            <link linkend="install-modules-gd-text-align">GD::Text::Align</link>
            (&min-gd-text-align-ver;) for bug charting
          </para>
        </listitem>

        <listitem>
          <para>
            <link linkend="install-modules-xml-parser">XML::Parser</link>
            (&min-xml-parser-ver;) for the XML interface
          </para>
        </listitem>

        <listitem>
          <para>
            <link linkend="install-modules-patchreader">PatchReader</link>
            (&min-patchreader-ver;) for pretty HTML view of patches
          </para>
        </listitem>
        
        <listitem>
          <para>
            <link linkend="install-modules-mime-parser">MIME::Parser</link>
            (&min-mime-parser-ver;) for the optional email interface
          </para>
        </listitem>
      </orderedlist>          
      </para>

      <section id="install-modules-dbd-mysql">
        <title>DBD::mysql</title>

        <para>The installation process will ask you a few questions about the
        desired compilation target and your MySQL installation. For most of the
        questions the provided default will be adequate, but when asked if your
        desired target is the MySQL or mSQL packages, you should
        select the MySQL-related ones. Later you will be asked if you wish to
        provide backwards compatibility with the older MySQL packages; you
        should answer YES to this question. The default is NO.</para>

        <para>A host of 'localhost' should be fine. A testing user of 'test',
        with a null password, should have sufficient access to run
        tests on the 'test' database which MySQL creates upon installation.
        </para>
      </section>

      <section id="install-modules-template">
        <title>Template Toolkit (&min-template-ver;)</title>

        <para>When you install Template Toolkit, you'll get asked various
        questions about features to enable. The defaults are fine, except
        that it is recommended you use the high speed XS Stash of the Template
        Toolkit, in order to achieve best performance.
        </para>
      </section> 

      <section id="install-modules-gd">
        <title>GD (&min-gd-ver;)</title>

        <para>The GD module is only required if you want graphical reports.
        </para>

        <note>
          <para>The Perl GD module requires some other libraries that may or
          may not be installed on your system, including 
          <classname>libpng</classname>
          and 
          <classname>libgd</classname>. 
          The full requirements are listed in the Perl GD module README.
          If compiling GD fails, it's probably because you're
          missing a required library.</para>
        </note>

        <tip>
          <para>The version of the GD module you need is very closely tied
          to the <classname>libgd</classname> version installed on your system.
          If you have a version 1.x of <classname>libgd</classname> the 2.x
          versions of the GD module won't work for you.
         </para>
       </tip>
      </section>

      <section id="install-modules-chart-base">
        <title>Chart::Base (&min-chart-base-ver;)</title>

        <para>The Chart::Base module is only required if you want graphical 
        reports. 
        Note that earlier versions that 0.99c used GIFs, which are no longer
        supported by the latest versions of GD.</para>
      </section>

      <section id="install-modules-gd-graph">
        <title>GD::Graph (&min-gd-graph-ver;)</title>

        <para>The GD::Graph module is only required if you want graphical 
        reports.
        </para>
      </section>

      <section id="install-modules-gd-text-align">
        <title>GD::Text::Align (&min-gd-text-align-ver;)</title>

        <para>The GD::Text::Align module is only required if you want graphical 
        reports.
        </para>
      </section>

      <section id="install-modules-xml-parser">
        <title>XML::Parser (&min-xml-parser-ver;)</title>

        <para>The XML::Parser module is only required if you want to import
        XML bugs using the <filename>importxml.pl</filename>
        script. This is required to use Bugzilla's "move bugs" feature;
        you may also want to use it for migrating from another bug database.
        XML::Parser requires that the
        <classname>expat</classname> library is already installed on your machine.
        </para>
      </section>

      <section id="install-modules-mime-parser">
        <title>MIME::Parser (&min-mime-parser-ver;)</title>

        <para>The MIME::Parser module is only required if you want to use the 
        email interface
        located in the <filename class="directory">contrib</filename> directory.
        </para>
      </section>

      <section id="install-modules-patchreader">
        <title>PatchReader (&min-patchreader-ver;)</title>

        <para>The PatchReader module is only required if you want to use 
        Patch Viewer, a
        Bugzilla feature to show code patches in your web browser in a more
        readable form. 
        </para>
      </section>
    </section>    
    <section id="install-MTA">
      <title>Mail Transfer Agent (MTA)</title>
    
      <para>Bugzilla is dependent on the availability of an e-mail system for its user
      authentication and for other tasks. </para>
    
      <para>On Linux, any Sendmail-compatible MTA (Mail Transfer Agent) will suffice.
      Sendmail, Postfix, qmail and Exim are examples of common MTAs. Sendmail is the 
      original Unix MTA, but the others are easier to configure, and therefore many people
      replace Sendmail with Postfix or Exim. They are drop-in replacements, so that Bugzilla
      will not distinguish between them.</para>

      <para>
        If you are using Sendmail, version 8.7 or higher is required.
        If you are using a Sendmail-compatible MTA, it must be congruent with at least version 8.7 of Sendmail.
      </para>

      <para>Consult the manual for the specific MTA you choose for detailed installation
      instructions. Each of these programs will have their own configuration files where you must
      configure certain parameters to ensure that the mail is delivered properly. They
      are implemented as services, and you should ensure that the MTA is in the
      auto-start list of services for the machine.</para>

      <para>If a simple mail sent with the command-line 'mail' program succeeds, then
      Bugzilla should also be fine.</para>
    </section>  
  </section>
  
  
  <section id="configuration">
    <title>Configuration</title>

    <warning>
      <para>
        Poorly-configured MySQL and Bugzilla installations have
        given attackers full access to systems in the past. Please take the
        security parts of these guidelines seriously, even for Bugzilla 
        machines hidden away behind your firewall. Be certain to read
        <xref linkend="security"/> for some important security tips.
      </para>      
    </warning>

    <section id="localconfig">
      <title>localconfig</title>
      
      <para>
        You should now run <filename>checksetup.pl</filename> again, this time
        without the <literal>--check-modules</literal> switch.
      </para>
      <screen><prompt>bash#</prompt> ./checksetup.pl</screen>
      <para>
        This time, <filename>checksetup.pl</filename> should tell you that all
        the correct modules are installed and will display a message about, and
        write out a  file called, <filename>localconfig</filename>. This file
        contains the default settings for a number of Bugzilla parameters.
      </para>
      
      <para>
        Load this file in your editor. The only value you 
        <emphasis>need</emphasis> to change is $db_pass, the password for
        the user you will create for your database. Pick a strong
        password (for simplicity, it should not contain single quote
        characters) and put it here.
      </para>
      
      <para>
        The other options in the <filename>localconfig</filename> file
        are documented by their accompanying comments. If you have a slightly
        non-standard MySQL setup, you may wish to change one or more of
        the other "$db_*" parameters. 
      </para>
      
      <para>
        You may also wish to change the names of 
        the priorities, severities, operating systems and platforms for your
        installation. However, you can always change these after installation
        has finished; if you then re-run <filename>checksetup.pl</filename>,
        the changes will get picked up.
      </para>
    </section>
    
    <section id="mysql">
      <title>MySQL</title>

      <caution>
        <para>
          MySQL's default configuration is very insecure.
          <xref linkend="security-mysql"/> has some good information for
          improving your installation's security.
        </para>
      </caution>
     
      <section id="install-setupdatabase">
        <title>Allow large attachments</title>
        
        <para>
          By default, MySQL will only accept packets up to 64Kb in size.
          If you want to have attachments larger than this, you will need
          to modify your <filename>/etc/my.cnf</filename> as below.
        </para>

        <para>
          If you are using MySQL 4.0 or newer, enter:
        </para>
        <screen>  [mysqld]
  # Allow packets up to 1M
  max_allowed_packet=1M</screen>

        <para>
          If you are using an older version of MySQL, enter:
        </para>
        <screen>  [mysqld]
  # Allow packets up to 1M
  set-variable = max_allowed_packet=1M</screen>

        <para>
          There is also a parameter in Bugzilla called 'maxattachmentsize'
          (default = 1000 Kb) that controls the maximum allowable attachment
          size. Attachments larger than <emphasis>either</emphasis> the 
          'max_allowed_packet' or 'maxattachmentsize' value will not be
          accepted by Bugzilla.
        </para>

        <note>
          <para>
            This does not affect Big Files, attachments that are stored directly
            on disk instead of in the database.  Their maximum size is
            controlled using the 'maxlocalattachment' parameter.
          </para>
        </note>
      </section>



      <section>
        <title>Allow small words in full-text indexes</title>

        <para>By default, words must be at least four characters in length
        in order to be indexed by MySQL's full-text indexes. This causes
        a lot of Bugzilla specific words to be missed, including "cc",
        "ftp" and "uri".</para>

        <para>MySQL can be configured to index those words by setting the
        ft_min_word_len param to the minimum size of the words to index.
        This can be done by modifying the <filename>/etc/my.cnf</filename>
        according to the example below:</para>

        <screen>  [mysqld]
  # Allow small words in full-text indexes
  ft_min_word_len=2</screen>

        <para>Rebuilding the indexes can be done based on documentation found at
        <ulink url="http://www.mysql.com/doc/en/Fulltext_Fine-tuning.html"/>.
        </para>

        <note>
          <para>
            The ft_min_word_len parameter is only suported in MySQL v4 or higher.
          </para>
        </note>
      </section>

      <section>
        <title>Permit attachments table to grow beyond 4GB</title>

        <para>
          By default, MySQL will limit the size of a table to 4GB.
          This limit is present even if the underlying filesystem
          has no such limit.  To set a higher limit, follow these
          instructions.
        </para>

        <para>
          Run the <filename>MySQL</filename> command-line client and
          enter:
        </para>

        <screen>  <prompt>mysql&gt;</prompt> ALTER TABLE attachments 
          AVG_ROW_LENGTH=1000000, MAX_ROWS=20000;
        </screen>

        <para>
          The above command will change the limit to 20GB. Mysql will have 
          to make a temporary copy of your entire table to do this. Ideally, 
          you should do this when your attachments table is still small.
        </para>

        <note>
          <para>
            This does not affect Big Files, attachments that are stored directly
            on disk instead of in the database.
          </para>
        </note>
      </section>
            
      <section id="install-setupdatabase-adduser">
        <title>Add a user to MySQL</title>

        <para>
          You need to add a new MySQL user for Bugzilla to use.
          (It's not safe to have Bugzilla use the MySQL root account.)
          The following instructions assume the defaults in
          <filename>localconfig</filename>; if you changed those,
          you need to modify the SQL command appropriately. You will
          need the <replaceable>$db_pass</replaceable> password you
          set in <filename>localconfig</filename> in 
          <xref linkend="localconfig"/>.
        </para>

        <para>
          We use an SQL <command>GRANT</command> command to create
          a <quote>bugs</quote> user. This also restricts the 
          <quote>bugs</quote>user to operations within a database
          called <quote>bugs</quote>, and only allows the account
          to connect from <quote>localhost</quote>. Modify it to
          reflect your setup if you will be connecting from another
          machine or as a different user.
        </para>
        
        <para>
          Run the <filename>mysql</filename> command-line client.
        </para>

        <para>
          If you are using MySQL 4.0 or newer, enter:
        </para>

        <screen>  <prompt>mysql&gt;</prompt> GRANT SELECT, INSERT,
         UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES,
         CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.*
         TO bugs@localhost IDENTIFIED BY '<replaceable>$db_pass</replaceable>';
  <prompt>mysql&gt;</prompt> FLUSH PRIVILEGES;</screen>

        <para>
          If you are using an older version of MySQL,the
          <computeroutput>LOCK TABLES</computeroutput> and 
          <computeroutput>CREATE TEMPORARY TABLES</computeroutput>
          permissions will be unavailable and should be removed from
          the permissions list. In this case, the following command
          line can be used:
        </para>

        <screen>  <prompt>mysql&gt;</prompt> GRANT SELECT, INSERT,
         UPDATE, DELETE, INDEX, ALTER, CREATE, DROP,
         REFERENCES ON bugs.* TO bugs@localhost IDENTIFIED BY
         '<replaceable>$db_pass</replaceable>';
  <prompt>mysql&gt;</prompt> FLUSH PRIVILEGES;</screen>
      </section>      
    </section>

    <section>
      <title>checksetup.pl</title>

      <para>
        Next, rerun <filename>checksetup.pl</filename>. It reconfirms
        that all the modules are present, and notices the altered 
        localconfig file, which it assumes you have edited to your
        satisfaction. It compiles the UI templates,
        connects to the database using the 'bugs'
        user you created and the password you defined, and creates the 
        'bugs' database and the tables therein. 
      </para>

      <para>
        After that, it asks for details of an administrator account. Bugzilla
        can have multiple administrators - you can create more later - but
        it needs one to start off with.
        Enter the email address of an administrator, his or her full name, 
        and a suitable Bugzilla password.
      </para>
      
      <para>
        <filename>checksetup.pl</filename> will then finish. You may rerun
        <filename>checksetup.pl</filename> at any time if you wish.
      </para>
    </section>


    <section id="http">
      <title>Web server</title>
      <para>
        Configure your web server according to the instructions in the
        appropriate section. (If it makes a difference in your choice,
        the Bugzilla Team recommends Apache.) Regardless of which webserver
        you are using, however, ensure that sensitive information is
        not remotely available by properly applying the access controls in
        <xref linkend="security-webserver-access"/>.
      </para>

      <section id="http-apache">
        <title>Apache <productname>httpd</productname></title>

        <para>
          To configure your Apache web server to work with Bugzilla,
          do the following:
        </para>
           
        <procedure>
          <step>
            <para>
              Load <filename>httpd.conf</filename> in your editor.
              In Fedora and Red Hat Linux, this file is found in
              <filename class="directory">/etc/httpd/conf</filename>.
            </para>
          </step>

          <step>
            <para>
              Apache uses <computeroutput>&lt;Directory&gt;</computeroutput>
              directives to permit fine-grained permission setting. Add the
              following lines to a directive that applies to the location
              of your Bugzilla installation. (If such a section does not
              exist, you'll want to add one.) In this example, Bugzilla has
              been installed at 
              <filename class="directory">/var/www/html/bugzilla</filename>.
            </para>

            <programlisting>
&lt;Directory /var/www/html/bugzilla&gt;
  AddHandler cgi-script .cgi
  Options +Indexes +ExecCGI
  DirectoryIndex index.cgi
  AllowOverride Limit
&lt;/Directory&gt;
            </programlisting>

            <para>
              These instructions: allow apache to run .cgi files found
              within the bugzilla directory; instructs the server to look
              for a file called <filename>index.cgi</filename> if someone
              only types the directory name into the browser; and allows
              Bugzilla's <filename>.htaccess</filename> files to override
              global permissions.
            </para>

            <note>
              <para>
                It is possible to make these changes globally, or to the
                directive controlling Bugzilla's parent directory (e.g.
                <computeroutput>&lt;Directory /var/www/html/&gt;</computeroutput>).
                Such changes would also apply to the Bugzilla directory...
                but they would also apply to many other places where they
                may or may not be appropriate. In most cases, including
                this one, it is better to be as restrictive as possible
                when granting extra access.
              </para>
            </note>
          </step>                    

          <step>
            <para>
              <filename>checksetup.pl</filename> can set tighter permissions
              on Bugzilla's files and directories if it knows what group the
              webserver runs as. Find the <computeroutput>Group</computeroutput>
              line in <filename>httpd.conf</filename>, place the value found
              there in the <replaceable>$webservergroup</replaceable> variable
              in <filename>localconfig</filename>, then rerun
              <filename>checksetup.pl</filename>.
            </para>
          </step>

          <step>
            <para>
              Optional: If Bugzilla does not actually reside in the webspace
              directory, but instead has been symbolically linked there, you
              will need to add the following to the
              <computeroutput>Options</computeroutput> line of the Bugzilla 
              <computeroutput>&lt;Directory&gt;</computeroutput> directive
              (the same one as in the step above):
            </para>

            <programlisting>
 +FollowSymLinks
            </programlisting>

            <para>
              Without this directive, Apache will not follow symbolic links
              to places outside its own directory structure, and you will be
              unable to run Bugzilla.
            </para>
          </step>
        </procedure>
      </section>

      <section id="http-iis">
        <title>Microsoft <productname>Internet Information Services</productname></title>

        <para>
          If you are running Bugzilla on Windows and choose to use
          Microsoft's <productname>Internet Information Services</productname>
          or <productname>Personal Web Server</productname> 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: 
          <ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;245225">245225</ulink> 
          <quote>HOW TO: Configure and Test a PERL Script with IIS 4.0,
          5.0, and 5.1</quote> (for <productname>Internet Information
          Services</productname>) and 
          <ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;231998">231998</ulink>          
          <quote>HOW TO: FP2000: How to Use Perl with Microsoft Personal Web
          Server on Windows 95/98</quote> (for <productname>Personal Web
          Server</productname>).
        </para>

        <para>
          You will need to create a virtual directory for the Bugzilla
          install.  Put the Bugzilla files in a directory that is named
          something <emphasis>other</emphasis> than what you want your
          end-users accessing.  That is, if you want your users to access
          your Bugzilla installation through 
          <quote>http://&lt;yourdomainname&gt;/Bugzilla</quote>, then do
          <emphasis>not</emphasis> put your Bugzilla files in a directory
          named <quote>Bugzilla</quote>.  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 <quote>Execute (such as ISAPI applications or
          CGI)</quote> access permission.
        </para>

        <para>
          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:
        </para>

        <programlisting>
&lt;full path to perl.exe &gt;\perl.exe -x&lt;full path to Bugzilla&gt; -wT "%s" %s
        </programlisting>

        <para>
          For example:
        </para>

        <programlisting>
c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
        </programlisting>

        <note>
          <para>
            The ActiveState install may have already created an entry for
            .pl files that is limited to <quote>GET,HEAD,POST</quote>. If
            so, this mapping should be <emphasis>removed</emphasis> as
            Bugzilla's .pl files are not designed to be run via a webserver.
          </para>
        </note>

        <para>
          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.
        </para>

        <para>
          Also, and this can't be stressed enough, make sure that files
          such as <filename>localconfig</filename> and your
          <filename class="directory">data</filename> directory are
          secured as described in <xref linkend="security-webserver-access"/>.
        </para>

      </section>

      <section id="http-aol">
        <title>AOL Server</title>

        <para>Ben FrantzDale reported success using AOL Server with Bugzilla. He