diff options
| author | gerv%gerv.net <> | 2002-07-28 07:00:17 +0200 |
|---|---|---|
| committer | gerv%gerv.net <> | 2002-07-28 07:00:17 +0200 |
| commit | d8caf6045d10344c431918128e3803ca497565f3 (patch) | |
| tree | 1b2fbc50e442b6413a4ef0949e8ff7eed1df1361 /docs/sgml/installation.sgml | |
| parent | a9bb18746686c1bf5497e27f7ac2e12d0e3fc31a (diff) | |
| download | bugzilla-d8caf6045d10344c431918128e3803ca497565f3.tar.gz bugzilla-d8caf6045d10344c431918128e3803ca497565f3.tar.xz | |
Merging new docs from 2.16 branch.
Diffstat (limited to 'docs/sgml/installation.sgml')
| -rw-r--r-- | docs/sgml/installation.sgml | 3760 |
1 files changed, 1955 insertions, 1805 deletions
diff --git a/docs/sgml/installation.sgml b/docs/sgml/installation.sgml index 8cadbdd58..0433b4b52 100644 --- a/docs/sgml/installation.sgml +++ b/docs/sgml/installation.sgml @@ -1,1729 +1,1766 @@ <!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> --> +<chapter id="installation" xreflabel="Bugzilla Installation"> + <title>Installation</title> - <chapter id="installation" xreflabel="Bugzilla Installation"> - <title>Installation</title> - <para> - These installation instructions are presented assuming you are - installing on a UNIX or completely POSIX-compliant system. If - you are installing on Microsoft Windows or another oddball - operating system, please consult the appropriate sections in - this installation guide for notes on how to be successful. - </para> - <section id="errata"> - <title>ERRATA</title> - <para>Here are some miscellaneous notes about possible issues you - main run into when you begin your Bugzilla installation. - Reference platforms for Bugzilla installation are Redhat Linux - 7.2, Linux-Mandrake 8.0, and Solaris 8.</para> - - <simplelist> - <member> - If you are installing Bugzilla on S.u.S.e. Linux, or some - other distributions with <quote>paranoid</quote> security - options, it is possible that the checksetup.pl script may fail - with the error: <errorname>cannot chdir(/var/spool/mqueue): - Permission denied</errorname> This is because your - <filename>/var/spool/mqueue</filename> directory has a mode of - <quote>drwx------</quote>. Type <command>chmod 755 - <filename>/var/spool/mqueue</filename></command> as root to - fix this problem. - </member> - - <member> - Bugzilla may be installed on Macintosh OS X (10), which is a - unix-based (BSD) operating system. Everything required for - Bugzilla on OS X will install cleanly, but the optional GD - perl module which is used for bug charting requires some - additional setup for installation. Please see the Mac OS X - installation section below for details - </member> - - <member> - Release Notes for Bugzilla &bz-ver; are available at - <filename>docs/rel_notes.txt</filename> in your Bugzilla - source distribution. - </member> - - <member> - The preferred documentation for Bugzilla is available in - docs/, with a variety of document types available. Please - refer to these documents when installing, configuring, and - maintaining your Bugzilla installation. - </member> - - </simplelist> - - <warning> - <para> - Bugzilla is not a package where you can just plop it in a directory, - twiddle a few things, and you're off. Installing Bugzilla assumes you - know your variant of UNIX or Microsoft Windows well, are familiar with the - command line, and are comfortable compiling and installing a plethora - of third-party utilities. To install Bugzilla on Win32 requires - fair Perl proficiency, and if you use a webserver other than Apache you - should be intimately familiar with the security mechanisms and CGI - environment thereof. - </para> - </warning> - - <warning> - <para> - Bugzilla has not undergone a complete security review. Security holes - may exist in the code. Great care should be taken both in the installation - and usage of this software. Carefully consider the implications of - installing other network services with Bugzilla. - </para> - </warning> - </section> - <section id="stepbystep" xreflabel="Bugzilla Installation Step-by-step"> <title>Step-by-step Install</title> + <section> <title>Introduction</title> - <para> - Installation of bugzilla is pretty straightforward, particularly if your - machine already has MySQL and the MySQL-related perl packages installed. - If those aren't installed yet, then that's the first order of business. The - other necessary ingredient is a web server set up to run cgi scripts. - While using Apache for your webserver is not required, it is recommended. - </para> - - <para> - Bugzilla has been successfully installed under Solaris, Linux, - and Win32. The peculiarities of installing on Win32 (Microsoft - Windows) are not included in this section of the Guide; please - check out the <xref linkend="win32" /> for further advice - on getting Bugzilla to work on Microsoft Windows. - </para> - - <para> - The Bugzilla Guide is contained in the "docs/" folder in your - Bugzilla distribution. It is available in plain text - (docs/txt), HTML (docs/html), or SGML source (docs/sgml). - </para> + + <para>Bugzilla has been successfully installed under Solaris, Linux, + and Win32. Win32 is not yet officially supported, but many people + have got it working fine. + Please see the + <xref linkend="win32" /> + for further advice on getting Bugzilla to work on Microsoft + Windows.</para> + </section> + <section> - <title>Installing the Prerequisites</title> + <title>Package List</title> + <note> - <para>If you want to skip these manual installation steps for - the CPAN dependencies listed below, and are running the very - most recent version of Perl and MySQL (both the executables - and development libraries) on your system, check out - Bundle::Bugzilla in <xref linkend="bundlebugzilla" /></para> + <para> If you are running the very most recent + version of Perl and MySQL (both the executables and development + libraries) on your system, you can skip these manual installation + steps for the Perl modules by using Bundle::Bugzilla; see + <xref linkend="bundlebugzilla" />. + </para> </note> + + <para>The software packages necessary for the proper running of + Bugzilla (with download links) are: + <orderedlist> + + +<listitem> + <para> + <ulink url="http://www.mysql.com/">MySQL database server</ulink> + (3.22.5 or greater) + </para> +</listitem> + +<listitem> + <para> + <ulink url="http://www.perl.org">Perl</ulink> + (5.005 or greater, 5.6.1 is recommended if you wish to + use Bundle::Bugzilla) + </para> +</listitem> + +<listitem> + <para>Perl Modules (minimum version): + <orderedlist> + <listitem> <para> - The software packages necessary for the proper running of bugzilla are: - <orderedlist> - <listitem> - <para> - MySQL database server and the mysql client (3.22.5 or greater) - </para> - </listitem> - <listitem> - <para> - Perl (5.004 or greater, 5.6.1 is recommended if you wish - to use Bundle::Bugzilla) - </para> - </listitem> - <listitem> - <para> - DBI Perl module - </para> - </listitem> - <listitem> - <para> - Data::Dumper Perl module - </para> - </listitem> - <listitem> - <para> - Bundle::Mysql Perl module collection - </para> - </listitem> - <listitem> - <para> - TimeDate Perl module collection - </para> - </listitem> - <listitem> - <para> - GD perl module (1.8.3) (optional, for bug charting) - </para> - </listitem> - <listitem> - <para> - Chart::Base Perl module (0.99c) (optional, for bug charting) - </para> - </listitem> - <listitem> - <para> - DB_File Perl module (optional, for bug charting) - </para> - </listitem> - <listitem> - <para> - The web server of your choice. Apache is recommended. - </para> - </listitem> - <listitem> - <para> - MIME::Parser Perl module (optional, for contrib/bug_email.pl interface) - </para> - </listitem> - </orderedlist> - - <warning> - <para> - It is a good idea, while installing Bugzilla, to ensure it - is not <emphasis>accessible</emphasis> by other machines - on the Internet. Your machine may be vulnerable to attacks - while you are installing. In other words, ensure there is - some kind of firewall between you and the rest of the - Internet. Many installation steps require an active - Internet connection to complete, but you must take care to - ensure that at no point is your machine vulnerable to an - attack. - </para> - </warning> - <note> - <para>Linux-Mandrake 8.0, the author's test system, includes - every required and optional library for Bugzilla. The - easiest way to install them is by using the - <filename>urpmi</filename> utility. If you follow these - commands, you should have everything you need for - Bugzilla, and <filename>checksetup.pl</filename> should - not complain about any missing libraries. You may already - have some of these installed.</para> - <simplelist> - <member><prompt>bash#</prompt><command> urpmi - perl-mysql</command></member> - <member><prompt>bash#</prompt><command> urpmi - perl-chart</command></member> - <member><prompt>bash#</prompt><command> urpmi - perl-gd</command></member> - <member><prompt>bash#</prompt><command> urpmi - perl-MailTools</command> (for Bugzilla email - integration)</member> - <member><prompt>bash#</prompt><command> urpmi - apache-modules</command></member> - </simplelist> - </note> - + <ulink url="http://www.template-toolkit.org">Template</ulink> + (v2.07) </para> - </section> - <section id="install-mysql"> - <title>Installing MySQL Database</title> + </listitem> + + <listitem> <para> - Visit MySQL homepage at <ulink - url="http://www.mysql.com">www.mysql.com</ulink> and grab the latest stable release of the server. Many of the binary versions of MySQL store their data files in <filename>/var</filename> which is often part of a smaller root partition. If you decide to build from sources you can easily set the dataDir as an option to <filename>configure</filename>. + <ulink url="http://www.cpan.org/modules/by-module/AppConfig/">AppConfig + </ulink> + (v1.52) </para> - <para> - If you install from source or non-package (RPM, deb, etc.) - binaries you need to add - <firstterm>mysqld</firstterm> to your - init scripts so the server daemon will come back up whenever - your machine reboots. Further discussion of UNIX init - sequences are beyond the scope of this guide. - <note> - <para>You should have your init script start - <glossterm>mysqld</glossterm> with the ability to accept - large packets. By default, <filename>mysqld</filename> - only accepts packets up to 64K long. This limits the size - of attachments you may put on bugs. If you add <option>-O - max_allowed_packet=1M</option> to the command that starts - <filename>mysqld</filename> (or - <filename>safe_mysqld</filename>), then you will be able - to have attachments up to about 1 megabyte.</para> - </note> + </listitem> - </para> - <note> - <para> - If you plan on running Bugzilla and MySQL on the same - machine, consider using the <option>--skip-networking</option> - option in the init script. This enhances security by - preventing network access to MySQL. - </para> - </note> - </section> - - <section id="install-perl"> - <title>Perl (5.004 or greater)</title> + <listitem> <para> - Any machine that doesn't have perl on it is a sad machine - indeed. Perl for *nix systems can be gotten in source form - from http://www.perl.com. Although Bugzilla runs with most - post-5.004 versions of Perl, it's a good idea to be up to the - very latest version if you can when running Bugzilla. As of - this writing, that is perl version &perl-ver;. + <ulink url="http://www.cpan.org/authors/id/MUIR/modules/Text-Tabs%2BWrap-2001.0131.tar.gz">Text::Wrap</ulink> + (v2001.0131) </para> + </listitem> + + <listitem> <para> - Perl is now a far cry from the the single compiler/interpreter - binary it once was. It includes a great many required modules - and quite a few other support files. If you're not up to or - not inclined to build perl from source, you'll want to install - it on your machine using some sort of packaging system (be it - RPM, deb, or what have you) to ensure a sane install. In the - subsequent sections you'll be installing quite a few perl - modules; this can be quite ornery if your perl installation - isn't up to snuff. + <ulink url="http://search.cpan.org/search?dist=File-Spec">File::Spec + </ulink> + (v0.8.2) </para> - <warning> - <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 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> - </warning> - <tip id="bundlebugzilla" xreflabel="Using Bundle::Bugzilla instead of manually installing Perl modules"> - <para> - You can skip the following Perl module installation steps by - installing <productname>Bundle::Bugzilla</productname> from - <glossterm linkend="gloss-cpan">CPAN</glossterm>, which - includes them. All Perl module installation steps require - you have an active Internet connection. If you wish to use - Bundle::Bugzilla, however, you must be using the latest - version of Perl (at this writing, version &perl-ver;) - </para> - <para> - <computeroutput> <prompt>bash#</prompt> <command>perl -MCPAN - -e 'install "Bundle::Bugzilla"'</command> - </computeroutput> - </para> - <para> - Bundle::Bugzilla doesn't include GD, Chart::Base, or - MIME::Parser, which are not essential to a basic Bugzilla - install. If installing this bundle fails, you should - install each module individually to isolate the problem. - </para> - </tip> - </section> - - <section> - <title>DBI Perl Module</title> + </listitem> + + <listitem> <para> - The DBI module is a generic Perl module used by other database related - Perl modules. For our purposes it's required by the MySQL-related - modules. As long as your Perl installation was done correctly the - DBI module should be a breeze. It's a mixed Perl/C module, but Perl's - MakeMaker system simplifies the C compilation greatly. + <ulink url="http://www.cpan.org/modules/by-module/Data/">Data::Dumper + </ulink> + (any) </para> + </listitem> + + <listitem> <para> - Like almost all Perl modules DBI can be found on the Comprehensive Perl - Archive Network (CPAN) at http://www.cpan.org. The CPAN servers have a - real tendency to bog down, so please use mirrors. The current location - at the time of this writing can be found in <xref linkend="downloadlinks" />. + <ulink url="http://www.cpan.org/modules/by-module/Mysql/">DBD::mysql + </ulink> + (v1.2209) </para> + </listitem> + + <listitem> <para> - Quality, general Perl module installation instructions can be found on - the CPAN website, but the easy thing to do is to just use the CPAN shell - which does all the hard work for you. + <ulink url="http://www.cpan.org/modules/by-module/DBI/">DBI</ulink> + (v1.13) </para> + </listitem> + + <listitem> <para> - To use the CPAN shell to install DBI: - <informalexample> - <para> - <computeroutput> - <prompt>bash#</prompt> - <command>perl -MCPAN -e 'install "DBI"'</command> - </computeroutput> - <note> - <para>Replace "DBI" with the name of whichever module you wish - to install, such as Data::Dumper, TimeDate, GD, etc.</para> - </note> - </para> - </informalexample> - To do it the hard way: - <informalexample> - <para> - Untar the module tarball -- it should create its own directory - </para> - <para> - CD to the directory just created, and enter the following commands: - <orderedlist> - <listitem> - <para> - <computeroutput> - <prompt>bash#</prompt> - <command>perl Makefile.PL</command> - </computeroutput> - </para> - </listitem> - <listitem> - <para> - <computeroutput> - <prompt>bash#</prompt> - <command>make</command> - </computeroutput> - </para> - </listitem> - <listitem> - <para> - <computeroutput> - <prompt>bash#</prompt> - <command>make test</command> - </computeroutput> - </para> - </listitem> - <listitem> - <para> - <computeroutput> - <prompt>bash#</prompt> - <command>make install</command> - </computeroutput> - </para> - </listitem> - </orderedlist> - If everything went ok that should be all it takes. For the vast - majority of perl modules this is all that's required. - </para> - </informalexample> + <ulink url="http://www.cpan.org/modules/by-module/Date/">Date::Parse + </ulink> + (any) </para> - </section> - <section> - <title>Data::Dumper Perl Module</title> + </listitem> + + <listitem> <para> - The Data::Dumper module provides data structure persistence for Perl - (similar to Java's serialization). It comes with later sub-releases of - Perl 5.004, but a re-installation just to be sure it's available won't - hurt anything. + CGI::Carp + (any) </para> + </listitem> + + </orderedlist> + and, optionally: + <orderedlist> + <listitem> <para> - Data::Dumper is used by the MySQL-related Perl modules. It - can be found on CPAN (see <xref linkend="downloadlinks" />) and - can be - installed by following the same four step make sequence used - for the DBI module. + <ulink url="http://www.cpan.org/modules/by-module/GD/">GD</ulink> + (v1.19) for bug charting </para> - </section> - - <section> - <title>MySQL related Perl Module Collection</title> + </listitem> + + <listitem> <para> - The Perl/MySQL interface requires a few mutually-dependent perl - modules. These modules are grouped together into the the - Msql-Mysql-modules package. This package can be found at CPAN. - After the archive file has been downloaded it should - be untarred. + <ulink url="http://www.cpan.org/modules/by-module/Chart/">Chart::Base + </ulink> + (v0.99c) for bug charting </para> + </listitem> + + <listitem> <para> - The MySQL modules are all built using one make file which is generated - by running: - <prompt>bash#</prompt> - <command>perl Makefile.pl</command> + XML::Parser + (any) for the XML interface </para> + </listitem> + + <listitem> <para> - The MakeMaker process will ask you a few questions about the desired - compilation target and your MySQL installation. For many of the questions - the provided default will be adequate. + MIME::Parser + (any) for the email interface </para> - <para> - When asked if your desired target is the MySQL or mSQL packages, - 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 and a testing user of 'test' and - a null password should find itself with sufficient access to run tests - on the 'test' database which MySQL created upon installation. If 'make - test' and 'make install' go through without errors you should be ready - to go as far as database connectivity is concerned. - </para> - </section> - - <section> - <title>TimeDate Perl Module Collection</title> - <para> - Many of the more common date/time/calendar related Perl - modules have been grouped into a bundle similar to the MySQL - modules bundle. This bundle is stored on the CPAN under the - name TimeDate (see link: <xref linkend="downloadlinks" />). The - component module we're most interested in is the Date::Format - module, but installing all of them is probably a good idea - anyway. The standard Perl module installation instructions - should work perfectly for this simple package. - </para> - </section> - <section> - <title>GD Perl Module (1.8.3)</title> - <para> - The GD library was written by Thomas Boutell a long while - ago to programatically generate images in C. Since then it's - become the defacto standard for programatic image - construction. The Perl bindings to it found in the GD library - are used on millions of web pages to generate graphs on the - fly. That's what bugzilla will be using it for so you must - install it if you want any of the graphing to work. - </para> - <para> - Actually bugzilla uses the Graph module which relies on GD - itself. Isn't that always the way with object-oriented - programming? At any rate, you can find the GD library on CPAN - in <xref linkend="downloadlinks" />. - </para> - <note> - <para> - The Perl GD library 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 library README. Just realize that if - compiling GD fails, it's probably because you're missing a - required library. - </para> - </note> - </section> - - <section> - <title>Chart::Base Perl Module (0.99c)</title> - <para> - The Chart module provides bugzilla with on-the-fly charting - abilities. It can be installed in the usual fashion after it - has been fetched from CPAN where it is found as the - Chart-x.x... tarball, linked in <xref linkend="downloadlinks" />. Note that - as with the GD perl module, only the version listed above, or - newer, will work. Earlier versions used GIF's, which are no - longer supported by the latest versions of GD. - </para> - </section> - - <section> - <title>DB_File Perl Module</title> - <para> - DB_File is a module which allows Perl programs to make use - of the facilities provided by Berkeley DB version 1.x. This - module is required by collectstats.pl which is used for bug - charting. If you plan to make use of bug charting, you must - install this module. - </para> - </section> - - <section> - <title>HTTP Server</title> - <para> - You have a freedom of choice here - Apache, Netscape or any - other server on UNIX would do. You can easily run the web - server on a different machine than MySQL, but need to adjust - the MySQL <quote>bugs</quote> user permissions accordingly. - <note> - <para>I strongly recommend Apache as the web server to use. - The Bugzilla Guide installation instructions, in general, - assume you are using Apache. As more users use different - webservers and send me information on the peculiarities of - installing using their favorite webserver, I will provide - notes for them.</para> - </note> - </para> - <para> - You'll want to make sure that your web server will run any - file with the .cgi extension as a cgi and not just display it. - If you're using apache that means uncommenting the following - line in the srm.conf file: - <programlisting> -AddHandler cgi-script .cgi - </programlisting> - </para> - <para> - With apache you'll also want to make sure that within the - access.conf file the line: - <programlisting> -Options ExecCGI -AllowOverride Limit -</programlisting> - is in the stanza that covers the directories into which - you intend to put the bugzilla .html and .cgi files. - </para> + </listitem> + </orderedlist> + </para> +</listitem> + + +<listitem> + <para> + The web server of your choice. + <ulink url="http://www.apache.org/">Apache</ulink> + is highly recommended. + </para> +</listitem> + + + </orderedlist> + + <warning> + <para>It is a good idea, while installing Bugzilla, to ensure that there + is some kind of firewall between you and the rest of the Internet, + because your machine may be insecure for periods during the install. + Many + installation steps require an active Internet connection to complete, + but you must take care to ensure that at no point is your machine + vulnerable to an attack.</para> + </warning> + <note> - <para> - AllowOverride Limit allows the use of a Deny statement in the - .htaccess file generated by checksetup.pl - </para> - <para> - Users of newer versions of Apache will generally find both - of the above lines will be in the httpd.conf file, rather - than srm.conf or access.conf. - </para> + <para>Linux-Mandrake 8.0 includes every + required and optional library for Bugzilla. The easiest way to + install them is by using the + <filename>urpmi</filename> + + utility. If you follow these commands, you should have everything you + need for Bugzilla, and + <filename>checksetup.pl</filename> + + should not complain about any missing libraries. You may already have + some of these installed.</para> + + <simplelist> + <member> + <prompt>bash#</prompt> + + <command>urpmi perl-mysql</command> + </member> + + <member> + <prompt>bash#</prompt> + + <command>urpmi perl-chart</command> + </member> + + <member> + <prompt>bash#</prompt> + + <command>urpmi perl-gd</command> + </member> + + <member> + <prompt>bash#</prompt> + + <command>urpmi perl-MailTools</command> + + (for Bugzilla email integration)</member> + + <member> + <prompt>bash#</prompt> + + <command>urpmi apache-modules</command> + </member> + </simplelist> </note> - <warning> - <para> - There are important files and directories that should not - be a served by the HTTP server. These are most files in the - <quote>data</quote> and <quote>shadow</quote> directories - and the <quote>localconfig</quote> file. You should - configure your HTTP server to not serve content from these - files. Failure to do so will expose critical passwords and - other data. Please see <xref linkend="htaccess" /> for details - on how to do this for Apache. I appreciate notes on how to - get this same functionality using other webservers. - </para> - </warning> - </section> - - <section> - <title>Installing the Bugzilla Files</title> - <para> - You should untar the Bugzilla files into a directory that - you're willing to make writable by the default web server user - (probably <quote>nobody</quote>). You may decide to put the - files off of the main web space for your web server or perhaps - off of <filename>/usr/local</filename> with a symbolic link in - the web space that points to the Bugzilla directory. At any - rate, just dump all the files in the same place, and make sure - you can access the files in that directory through your web - server. - </para> - <tip> - <para> - If you symlink the bugzilla directory into your Apache's - HTML heirarchy, you may receive - <errorname>Forbidden</errorname> errors unless you add the - <quote>FollowSymLinks</quote> directive to the - <Directory> entry for the HTML root. - </para> - </tip> - <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 post-install - <filename>checksetup.pl</filename> script, which locks down your - installation. </para> - <para> - Lastly, you'll need to set up a symbolic link to - <filename>/usr/bonsaitools/bin/perl</filename> for the correct - location of your perl executable (probably - <filename>/usr/bin/perl</filename>). Otherwise you must hack - all the .cgi files to change where they look for perl, or use - <xref linkend="setperl" />, found in - <xref linkend="patches" />. I suggest using the symlink - approach for future release compatability. - <example> - <title>Setting up bonsaitools symlink</title> - <para> - Here's how you set up the Perl symlink on Linux to make - Bugzilla work. Your mileage may vary. For some UNIX - operating systems, you probably need to subsitute - <quote>/usr/local/bin/perl</quote> for - <quote>/usr/bin/perl</quote> below; if on certain other - UNIX systems, Perl may live in weird places like - <quote>/opt/perl</quote>. As root, run these commands: - <programlisting> -bash# mkdir /usr/bonsaitools -bash# mkdir /usr/bonsaitools/bin -bash# ln -s /usr/bin/perl /usr/bonsaitools/bin/perl - </programlisting> - </para> - <para> - Alternately, you can simply run this perl one-liner to - change your path to perl in all the files in your Bugzilla - installation: - <programlisting> -perl -pi -e 's@#\!/usr/bonsaitools/bin/perl@#\!/usr/bin/perl@' *cgi *pl Bug.pm -processmail syncshadowdb - </programlisting> - Change the second path to perl to match your installation. - </para> - </example> - <tip> - <para> - If you don't have root access to set this symlink up, - check out the - <xref linkend="setperl" />, listed in <xref - linkend="patches" />. It will change the path to perl in all your Bugzilla files for you. - </para> - </tip> - </para> - </section> - - <section> - <title>Setting Up the MySQL Database</title> - <para> - After you've gotten all the software installed and working you're ready - to start preparing the database for its life as a the back end to a high - quality bug tracker. - </para> - <para> - First, you'll want to fix MySQL permissions to allow access - from Bugzilla. For the purpose of this Installation section, - the Bugzilla username will be <quote>bugs</quote>, and will - have minimal permissions. - - <warning> - <para> - Bugzilla has not undergone a thorough security audit. It - may be possible for a system cracker to somehow trick - Bugzilla into executing a command such as <command>DROP - DATABASE mysql</command>. - </para> - <para>That would be bad.</para> - </warning> + </section> + + <section id="install-mysql"> + <title>MySQL</title> + + <para>Visit the MySQL homepage at + <ulink url="http://www.mysql.com">www.mysql.com</ulink> + to grab and install the latest stable release of the server. </para> - <para> - Give the MySQL root user a password. MySQL passwords are - limited to 16 characters. - <simplelist> - <member> - <computeroutput> <prompt>bash#</prompt> <command>mysql - -u root mysql</command> </computeroutput> - </member> - <member> - <computeroutput> <prompt>mysql></prompt> <command> - UPDATE user SET Password=PASSWORD ('new_password') - WHERE user='root'; </command> </computeroutput> - </member> - <member> - <computeroutput> <prompt>mysql></prompt> <command>FLUSH - PRIVILEGES;</command> </computeroutput> - </member> - </simplelist> From this point on, if you need to access - MySQL as the MySQL root user, you will need to use - <command>mysql -u root -p</command> and enter your - new_password. Remember that MySQL user names have nothing to - do with Unix user names (login names). - </para> - <para> - Next, we create the <quote>bugs</quote> user, and grant - sufficient permissions for checksetup.pl, which we'll use - later, to work its magic. 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> - Remember to set bugs_password to some unique password. - <simplelist> - <member> - <computeroutput> - <prompt>mysql></prompt> - <command>GRANT SELECT,INSERT,UPDATE,DELETE,INDEX, - ALTER,CREATE,DROP,REFERENCES - ON bugs.* TO bugs@localhost - IDENTIFIED BY 'bugs_password';</command> - </computeroutput> - </member> - <member> - <computeroutput> - <prompt> - mysql> - </prompt> - <command> - FLUSH PRIVILEGES; - </command> - </computeroutput> - </member> - </simplelist> - </para> - <para> - Next, run the magic checksetup.pl script. (Many thanks to - Holger Schurig <holgerschurig@nikocity.de> for writing - this script!) It will make sure Bugzilla files and directories - have reasonable permissions, set up the - <filename>data</filename> directory, and create all the MySQL - tables. - <simplelist> - <member> - <computeroutput> <prompt>bash#</prompt> - <command>./checksetup.pl</command> </computeroutput> - </member> - </simplelist> The first time you run it, it will create a - file called <filename>localconfig</filename>. + <note> + <para> Many of the binary + versions of MySQL store their data files in + <filename>/var</filename>. + On some Unix systems, this is part of a smaller root partition, + and may not have room for your bug database. You can set the data + directory as an option to <filename>configure</filename> + if you build MySQL from source yourself.</para> + </note> + + <para>If you install from something other than an RPM or Debian + package, you will need to add <filename>mysqld</filename> + to your init scripts so the server daemon will come back up whenever + your machine reboots. Further discussion of UNIX init sequences are + beyond the scope of this guide. </para> + + <para>Change your init script to start + <filename>mysqld</filename> + with the ability to accept large packets. By default, + <filename>mysqld</filename> + only accepts packets up to 64K long. This limits the size of + attachments you may put on bugs. If you add + <option>-O max_allowed_packet=1M</option> + to the command that starts + <filename>mysqld</filename> + (or <filename>safe_mysqld</filename>), + then you will be able to have attachments up to about 1 megabyte. + There is a Bugzilla parameter for maximum attachment size; + you should configure it to match the value you choose here.</para> + + <para>If you plan on running Bugzilla and MySQL on the same machine, + consider using the + <option>--skip-networking</option> + option in the init script. This enhances security by preventing + network access to MySQL.</para> + </section> + + <section id="install-perl"> + <title>Perl</title> + + <para>Any machine that doesn't have Perl on it is a sad machine indeed. + Perl can be got in source form from + <ulink url="http://www.perl.com">perl.com</ulink> for the rare + *nix systems which don't have it. + Although Bugzilla runs with all post-5.005 + versions of Perl, it's a good idea to be up to the very latest version + if you can when running Bugzilla. As of this writing, that is Perl + version &perl-ver;.</para> + + <tip id="bundlebugzilla" + xreflabel="Using Bundle::Bugzilla instead of manually installing Perl modules"> + + <para>You can skip the following Perl module installation steps by + installing + <productname>Bundle::Bugzilla</productname> + + from + <glossterm linkend="gloss-cpan">CPAN</glossterm>, + which installs all required modules for you.</para> + + <para> + <computeroutput> + <prompt>bash#</prompt> + + <command>perl -MCPAN -e 'install "Bundle::Bugzilla"'</command> + </computeroutput> + </para> + + <para>Bundle::Bugzilla doesn't include GD, Chart::Base, or + MIME::Parser, which are not essential to a basic Bugzilla install. If + installing this bundle fails, you should install each module + individually to isolate the problem.</para> + </tip> + </section> + + <section id="perl-modules"> + <title>Perl Modules</title> + + <para> + All Perl modules can be found on the + <ulink url="http://www.cpan.org">Comprehensive Perl + Archive Network</ulink> (CPAN). The + CPAN servers have a real tendency to bog down, so please use mirrors. + </para> - <section> - <title>Tweaking <filename>localconfig</filename></title> - <para> - This file contains a variety of settings you may need to tweak including - how Bugzilla should connect to the MySQL database. - </para> - <para> - The connection settings include: - <orderedlist> - <listitem> - <para> - server's host: just use <quote>localhost</quote> if the - MySQL server is local - </para> - </listitem> - <listitem> - <para> - database name: <quote>bugs</quote> if you're following - these directions - </para> - </listitem> - <listitem> - <para> - MySQL username: <quote>bugs</quote> if you're following - these directions - </para> - </listitem> - <listitem> - <para> - Password for the <quote>bugs</quote> MySQL account above - </para> - </listitem> - </orderedlist> + <para>Quality, general Perl module installation instructions can be + found on the CPAN website, but the easy thing to do is to just use the + CPAN shell which does all the hard work for you. + To use the CPAN shell to install a module: </para> + <para> - You should also install .htaccess files that the Apache - webserver will use to restrict access to Bugzilla data files. - See <xref - linkend="htaccess" />. + <computeroutput> + <prompt>bash#</prompt> + <command>perl -MCPAN -e 'install "<modulename>"'</command> + </computeroutput> </para> + <para> - Once you are happy with the settings, re-run - <filename>checksetup.pl</filename>. On this second run, it will - create the database and an administrator account for which - you will be prompted to provide information. + To do it the hard way: </para> - <para> - When logged into an administrator account once Bugzilla is - running, if you go to the query page (off of the Bugzilla main - menu), you'll find an <quote>edit parameters</quote> option - that is filled with editable treats. + + <para>Untar the module tarball -- it should create its own + directory</para> + + <para>CD to the directory just created, and enter the following + commands: + <orderedlist> + <listitem> + <para> + <computeroutput> + <prompt>bash#</prompt> + + <command>perl Makefile.PL</command> + </computeroutput> + </para> + </listitem> + + <listitem> + <para> + <computeroutput> + <prompt>bash#</prompt> + + <command>make</command> + </computeroutput> + </para> + </listitem> + + <listitem> + <para> + <computeroutput> + <prompt>bash#</prompt> + + <command>make test</command> + </computeroutput> + </para> + </listitem> + + <listitem> + <para> + <computeroutput> + <prompt>bash#</prompt> + + <command>make install</command> + </computeroutput> + </para> + </listitem> + </orderedlist> </para> - <para> - Should everything work, you will have a nearly empty Bugzilla - database and a newly-created <filename>localconfig</filename> - file in your Bugzilla root directory. + + <warning> + <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> + </warning> + + + <section> + <title>DBI</title> + + <para>The DBI module is a generic Perl module used the + MySQL-related modules. As long as your Perl installation was done + correctly the DBI module should be a breeze. It's a mixed Perl/C + module, but Perl's MakeMaker system simplifies the C compilation + greatly.</para> + </section> + + <section> + <title>Data::Dumper</title> + + <para>The Data::Dumper module provides data structure persistence for + Perl (similar to Java's serialization). It comes with later + sub-releases of Perl 5.004, but a re-installation just to be sure it's + available won't hurt anything.</para> + </section> + + <section> + <title>MySQL-related modules</title> + + <para>The Perl/MySQL interface requires a few mutually-dependent Perl + modules. These modules are grouped together into the the + Msql-Mysql-modules package.</para> + + <para>The MakeMaker 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 and a testing user of 'test' + with a null password should find itself with sufficient access to run + tests on the 'test' database which MySQL created upon installation. </para> - <para> - <note> - <para> - The second time you run checksetup.pl, you should become - the user your web server runs as, and that you ensure that - you set the <quote>webservergroup</quote> parameter in localconfig to - match the web server's group name, if any. I believe, - for the next release of Bugzilla, this will be fixed so - that Bugzilla supports a <quote>webserveruser</quote> parameter in - localconfig as well. - <example> - <title>Running checksetup.pl as the web user</title> - <para> - Assuming your web server runs as user "apache", and - Bugzilla is installed in "/usr/local/bugzilla", here's - one way to run checksetup.pl as the web server user. - As root, for the <emphasis>second run</emphasis> of - checksetup.pl, do this: - <programlisting> -bash# chown -R apache:apache /usr/local/bugzilla -bash# su - apache -bash# cd /usr/local/bugzilla -bash# ./checksetup.pl - </programlisting> - </para> - </example> - </para> - </note> + </section> + + <section> + <title>TimeDate modules</title> + + <para>Many of the more common date/time/calendar related Perl modules + have been grouped into a bundle similar to the MySQL modules bundle. + This bundle is stored on the CPAN under the name TimeDate. + The component module we're most interested in is the Date::Format + module, but installing all of them is probably a good idea anyway. </para> + </section> + + <section> + <title>GD (optional)</title> + + <para>The GD library was written by Thomas Boutell a long while ago to + programatically generate images in C. Since then it's become the + defacto standard for programatic image construction. The Perl bindings + to it found in the GD library are used on millions of web pages to + generate graphs on the fly. That's what Bugzilla will be using it for + so you must install it if you want any of the graphing to work.</para> + <note> - <para> - The checksetup.pl script is designed so that you can run - it at any time without causing harm. You should run it - after any upgrade to Bugzilla. - </para> + <para>The Perl GD library 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 library README. + If compiling GD fails, it's probably because you're + missing a required library.</para> </note> </section> + + <section> + <title>Chart::Base (optional)</title> + + <para>The Chart module provides Bugzilla with on-the-fly charting + abilities. It can be installed in the usual fashion after it has been + fetched from CPAN. + Note that earlier versions that 0.99c used GIFs, which are no longer + supported by the latest versions of GD.</para> + </section> <section> - <title>Setting Up Maintainers Manually (Optional)</title> - <para> - If you want to add someone else to every group by hand, you - can do it by typing the appropriate MySQL commands. Run - <command> mysql -u root -p bugs</command> You - may need different parameters, depending on your security - settings. Then: - <simplelist> - <member> - <computeroutput> <prompt>mysql></prompt> <command>update - profiles set groupset=0x7fffffffffffffff where - login_name = 'XXX';</command> </computeroutput> (yes, that's <emphasis>fifteen</emphasis><quote>f</quote>'s. - </member> - </simplelist> replacing XXX with the Bugzilla email address. - </para> - </section> - - <section> - <title>The Whining Cron (Optional)</title> - <para> - By now you have a fully functional bugzilla, but what good - are bugs if they're not annoying? To help make those bugs - more annoying you can set up bugzilla's automatic whining - system. This can be done by adding the following command as a - daily crontab entry (for help on that see that crontab man - page): - <simplelist> - <member> - <computeroutput> <command>cd - <your-bugzilla-directory> ; - ./whineatnews.pl</command> </computeroutput> - </member> - </simplelist> + <title>Template Toolkit</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. However, there are + known problems with XS Stash and Perl 5.005_02 and lower. If you + wish to use these older versions of Perl, please use the regular + stash.</para> + </section> + + + </section> + + <section> + <title>HTTP Server</title> + + <para>You have a freedom of choice here - Apache, Netscape or any other + server on UNIX would do. You can run the web server on a + different machine than MySQL, but need to adjust the MySQL + <quote>bugs</quote> + user permissions accordingly. + <note> + <para>We strongly recommend Apache as the web server to use. The + Bugzilla Guide installation instructions, in general, assume you are + using Apache. If you have got Bugzilla working using another webserver, + please share your experiences with us.</para> + </note> + </para> + + <para>You'll want to make sure that your web server will run any file + with the .cgi extension as a CGI and not just display it. If you're + using Apache that means uncommenting the following line in the httpd.conf + file: + <programlisting>AddHandler cgi-script .cgi</programlisting> + </para> + + <para>With Apache you'll also want to make sure that within the + httpd.conf file the line: + <programlisting>Options ExecCGI AllowOverride Limit</programlisting> + + is in the stanza that covers the directories into which you intend to + put the bugzilla .html and .cgi files. + + <note> + <para>AllowOverride Limit allows the use of a Deny statement in the + .htaccess file generated by checksetup.pl</para> + + <para>Users of older versions of Apache may find the above lines + in the srm.conf and access.conf files, respecitvely.</para> + </note> </para> + + <warning> + <para>There are important files and directories that should not be a + served by the HTTP server - most files in the + <quote>data</quote> + and + <quote>shadow</quote> + directories and the + <quote>localconfig</quote> + file. You should configure your HTTP server to not serve + these files. Failure to do so will expose critical passwords and + other data. Please see + <xref linkend="htaccess" /> + for details on how to do this for Apache; the checksetup.pl + script should create appropriate .htaccess files for you.</para> + </warning> + </section> + + <section> + <title>Bugzilla</title> + + <para>You should untar the Bugzilla files into a directory that you're + willing to make writable by the default web server user (probably + <quote>nobody</quote>). + You may decide to put the files in the main web space for your + web server or perhaps in + <filename>/usr/local</filename> + with a symbolic link in the web space that points to the Bugzilla + directory.</para> + <tip> - <para> - Depending on your system, crontab may have several manpages. - The following command should lead you to the most useful - page for this purpose: - <programlisting> - man 5 crontab - </programlisting> - </para> + <para>If you symlink the bugzilla directory into your Apache's HTML + heirarchy, you may receive + <errorname>Forbidden</errorname> + errors unless you add the + <quote>FollowSymLinks</quote> + directive to the <Directory> entry for the HTML root + in httpd.conf.</para> </tip> + + <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 post-install + <filename>checksetup.pl</filename> + script, which locks down your installation.</para> + + <para>Lastly, you'll need to set up a symbolic link to + <filename>/usr/bonsaitools/bin/perl</filename> + for the correct location of your Perl executable (probably + <filename>/usr/bin/perl</filename>). + Otherwise you must hack all the .cgi files to change where they look + for Perl. This can be done using the following Perl one-liner, but + I suggest using the symlink approach to avoid upgrade hassles. + </para> + + <para> + <programlisting>perl -pi -e + 's@#\!/usr/bonsaitools/bin/perl@#\!/usr/bin/perl@' *cgi *pl Bug.pm + processmail syncshadowdb</programlisting> + + Change <filename>/usr/bin/perl</filename> to match the location + of Perl on your machine. + </para> </section> - + <section> - <title>Bug Graphs (Optional)</title> - <para> - As long as you installed the GD and Graph::Base Perl modules - you might as well turn on the nifty bugzilla bug reporting - graphs. + <title>Setting Up the MySQL Database</title> + + <para>After you've gotten all the software installed and working you're + ready to start preparing the database for its life as the back end to + a high quality bug tracker.</para> + + <para>First, you'll want to fix MySQL permissions to allow access from + Bugzilla. For the purpose of this Installation section, the Bugzilla + username will be + <quote>bugs</quote>, and will have minimal permissions. </para> - <para> - Add a cron entry like this to run collectstats daily at 5 - after midnight: - <simplelist> - <member> - <computeroutput> <prompt>bash#</prompt> <command>crontab - -e</command> </computeroutput> - </member> - <member> - <computeroutput> 5 0 * * * cd - <your-bugzilla-directory> ; ./collectstats.pl - </computeroutput> - </member> - </simplelist> + + <para>Begin by giving the MySQL root user a password. MySQL passwords are limited + to 16 characters. + <simplelist> + <member> + <computeroutput> + <prompt>bash#</prompt> + + <command>mysql -u root mysql</command> + </computeroutput> + </member> + + <member> + <computeroutput> + <prompt>mysql></prompt> + + <command>UPDATE user SET Password=PASSWORD('<new_password'>) + WHERE user='root';</command> + </computeroutput> + </member> + + <member> + <computeroutput> + <prompt>mysql></prompt> + + <command>FLUSH PRIVILEGES;</command> + </computeroutput> + </member> + </simplelist> + + From this point on, if you need to access MySQL as the MySQL root user, + you will need to use + <command>mysql -u root -p</command> + + and enter <new_password>. Remember that MySQL user names have + nothing to do with Unix user names (login names).</para> + + <para>Next, we use an SQL <command>GRANT</command> command to create a + <quote>bugs</quote> + + user, and grant sufficient permissions for checksetup.pl, which we'll + use later, to work its magic. 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>Remember to set <bugs_password> to some unique password. + <simplelist> + <member> + <computeroutput> + <prompt>mysql></prompt> + + <command>GRANT SELECT,INSERT,UPDATE,DELETE,INDEX, + ALTER,CREATE,DROP,REFERENCES ON bugs.* TO bugs@localhost + IDENTIFIED BY '<bugs_password>';</command> + </computeroutput> + </member> + + <member> + <computeroutput> + <prompt>mysql></prompt> + + <command>FLUSH PRIVILEGES;</command> + </computeroutput> + </member> + </simplelist> </para> - <para> - After two days have passed you'll be able to view bug graphs - from the Bug Reports page. + </section> + + <section> + <title> + <filename>checksetup.pl</filename> + </title> + + <para>Next, run the magic checksetup.pl script. (Many thanks to + <ulink url="mailto:holgerschurig@nikocity.de">Holger Schurig </ulink> + for writing this script!) + This script is designed to make sure your MySQL database and other + configuration options are consistent with the Bugzilla CGI files. + It will make sure Bugzilla files and directories have reasonable + permissions, set up the + <filename>data</filename> + directory, and create all the MySQL tables. + <simplelist> + <member> + <computeroutput> + <prompt>bash#</prompt> + + <command>./checksetup.pl</command> + </computeroutput> + </member> + </simplelist> + + The first time you run it, it will create a file called + <filename>localconfig</filename>.</para> + + <para>This file contains a variety of settings you may need to tweak + including how Bugzilla should connect to the MySQL database.</para> + + <para>The connection settings include: + <orderedlist> + <listitem> + <para>server's host: just use + <quote>localhost</quote> + if the MySQL server is local</para> + </listitem> + + <listitem> + <para>database name: + <quote>bugs</quote> + if you're following these directions</para> + </listitem> + + <listitem> + <para>MySQL username: + <quote>bugs</quote> + if you're following these directions</para> + </listitem> + + <listitem> + <para>Password for the + <quote>bugs</quote> + MySQL account; (<bugs_password>) above</para> + </listitem> + </orderedlist> </para> + + <para>Once you are happy with the settings, + <filename>su</filename> to the user + your web server runs as, and re-run + <filename>checksetup.pl</filename>. (Note: on some security-conscious + systems, you may need to change the login shell for the webserver + account before you can do this.) + On this second run, it will create the database and an administrator + account for which you will be prompted to provide information.</para> + + <note> + <para>The checksetup.pl script is designed so that you can run it at + any time without causing harm. You should run it after any upgrade to + Bugzilla.</para> + </note> </section> - + <section> <title>Securing MySQL</title> - <para> - If you followed the installation instructions for setting up - your "bugs" and "root" user in MySQL, much of this should not - apply to you. If you are upgrading an existing installation - of Bugzilla, you should pay close attention to this section. - </para> - <para> - Most MySQL installs have "interesting" default security parameters: - <simplelist> - <member>mysqld defaults to running as root</member> - <member>it defaults to allowing external network connections</member> - <member>it has a known port number, and is easy to detect</member> - <member>it defaults to no passwords whatsoever</member> - <member>it defaults to allowing "File_Priv"</member> - </simplelist> - </para> - <para> - This means anyone from anywhere on the internet can not only - drop the database with one SQL command, and they can write as - root to the system. + + <para>If you followed the installation instructions for setting up your + "bugs" and "root" user in MySQL, much of this should not apply to you. + If you are upgrading an existing installation of Bugzilla, you should + pay close attention to this section.</para> + + <para>Most MySQL installs have "interesting" default security + parameters: + <simplelist> + <member>mysqld defaults to running as root</member> + + <member>it defaults to allowing external network connections</member> + + <member>it has a known port number, and is easy to detect</member> + + <member>it defaults to no passwords whatsoever</member> + + <member>it defaults to allowing "File_Priv"</member> + </simplelist> </para> - <para> - To see your permissions do: - <simplelist> - <member> - <computeroutput> - <prompt>bash#</prompt> - <command>mysql -u root -p</command> - </computeroutput> - </member> - <member> - <computeroutput> - <prompt>mysql></prompt> - <command>use mysql;</command> - </computeroutput> - </member> - <member> - <computeroutput> - <prompt>mysql></prompt> - <command>show tables;</command> - </computeroutput> - </member> - <member> - <computeroutput> - <prompt>mysql></prompt> - <command>select * from user;</command> - </computeroutput> - </member> - <member> - <computeroutput> - <prompt>mysql></prompt> - <command>select * from db;</command> - </computeroutput> - </member> - </simplelist> + + <para>This means anyone from anywhere on the internet can not only drop + the database with one SQL command, and they can write as root to the + system.</para> + + <para>To see your permissions do: + <simplelist> + <member> + <computeroutput> + <prompt>bash#</prompt> + + <command>mysql -u root -p</command> + </computeroutput> + </member> + + <member> + <computeroutput> + <prompt>mysql></prompt> + + <command>use mysql;</command> + </computeroutput> + </member> + + <member> + <computeroutput> + <prompt>mysql></prompt> + + <command>show tables;</command> + </computeroutput> + </member> + + <member> + <computeroutput> + <prompt>mysql></prompt> + + <command>select * from user;</command> + </computeroutput> + </member> + + <member> + <computeroutput> + <prompt>mysql></prompt> + + <command>select * from db;</command> + </computeroutput> + </member> + </simplelist> </para> - <para> - To fix the gaping holes: - <simplelist> - <member>DELETE FROM user WHERE User='';</member> - <member>UPDATE user SET Password=PASSWORD('new_password') WHERE user='root';</member> - <member> FLUSH PRIVILEGES;</member> - </simplelist> + + <para>To fix the gaping holes: + <simplelist> + <member>DELETE FROM user WHERE User='';</member> + + <member>UPDATE user SET Password=PASSWORD('new_password') WHERE + user='root';</member> + + <member>FLUSH PRIVILEGES;</member> + </simplelist> </para> - <para> - If you're not running "mit-pthreads" you can use: - <simplelist> - <member>GRANT USAGE ON *.* TO bugs@localhost;</member> - <member>GRANT ALL ON bugs.* TO bugs@localhost;</member> - <member>REVOKE DROP ON bugs.* FROM bugs@localhost;</member> - <member>FLUSH PRIVILEGES;</member> - </simplelist> + + <para>If you're not running "mit-pthreads" you can use: + <simplelist> + <member>GRANT USAGE ON *.* TO bugs@localhost;</member> + + <member>GRANT ALL ON bugs.* TO bugs@localhost;</member> + + <member>REVOKE DROP ON bugs.* FROM bugs@localhost;</member> + + <member>FLUSH PRIVILEGES;</member> + </simplelist> </para> - <para> - With "mit-pthreads" you'll need to modify the "globals.pl" Mysql->Connect - line to specify a specific host name instead of "localhost", and accept - external connections: - <simplelist> - <member>GRANT USAGE ON *.* TO bugs@bounce.hop.com;</member> - <member>GRANT ALL ON bugs.* TO bugs@bounce.hop.com;</member> - <member>REVOKE DROP ON bugs.* FROM bugs@bounce.hop.com;</member> - <member>FLUSH PRIVILEGES;</member> - </simplelist> + + <para>With "mit-pthreads" you'll need to modify the "globals.pl" + Mysql->Connect line to specify a specific host name instead of + "localhost", and accept external connections: + <simplelist> + <member>GRANT USAGE ON *.* TO bugs@bounce.hop.com;</member> + + <member>GRANT ALL ON bugs.* TO bugs@bounce.hop.com;</member> + + <member>REVOKE DROP ON bugs.* FROM bugs@bounce.hop.com;</member> + + <member>FLUSH PRIVILEGES;</member> + </simplelist> </para> - <para> - Use .htaccess files with the Apache webserver to secure your - bugzilla install. See <xref linkend="htaccess" /> + + <para>Consider also: + <orderedlist> + <listitem> + <para>Turning off external networking with "--skip-networking", + unless you have "mit-pthreads", in which case you can't. Without + networking, MySQL connects with a Unix domain socket.</para> + </listitem> + + <listitem> + <para>using the --user= option to mysqld to run it as an + unprivileged user.</para> + </listitem> + + <listitem> + <para>running MySQL in a chroot jail</para> + </listitem> + + <listitem> + <para>running the httpd in a chroot jail</para> + </listitem> + + <listitem> + <para>making sure the MySQL passwords are different from the OS + passwords (MySQL "root" has nothing to do with system + "root").</para> + </listitem> + + <listitem> + <para>running MySQL on a separate untrusted machine</para> + </listitem> + + <listitem> + <para>making backups ;-)</para> + </listitem> + </orderedlist> </para> + </section> + + <section> + <title>Configuring Bugzilla</title> <para> - Consider also: - <orderedlist> - <listitem> - <para> - Turning off external networking with "--skip-networking", - unless you have "mit-pthreads", in which case you can't. - Without networking, MySQL connects with a Unix domain socket. - </para> - </listitem> - <listitem> - <para> - using the --user= option to mysqld to run it as an unprivileged - user. - </para> - </listitem> - <listitem> - <para> - starting MySQL in a chroot jail - </para> - </listitem> - <listitem> - <para> - running the httpd in a "chrooted" jail - </para> - </listitem> - <listitem> - <para> - making sure the MySQL passwords are different from the OS - passwords (MySQL "root" has nothing to do with system "root"). - </para> - </listitem> - <listitem> - <para> - running MySQL on a separate untrusted machine - </para> - </listitem> - <listitem> - <para> - making backups ;-) - </para> - </listitem> - </orderedlist> + You should run through the parameters on the Edit Parameters page + (link in the footer) and set them all to appropriate values. + They key parameters are documented in <xref linkend="parameters" />. </para> </section> - </section> - <section id="osx"> - <title>Mac OS X Installation Notes</title> - <para> - There are a lot of common libraries and utilities out there - that Apple did not include with Mac OS X, but which run - perfectly well on it. The GD library, which Bugzilla needs to - do bug graphs, is one of these. - </para> - <para> - The easiest way to get a lot of these is with a program called - Fink, which is similar in nature to the CPAN installer, but - installs common GNU utilities. Fink is available from - <http://sourceforge.net/projects/fink/>. - </para> - <para> - Follow the instructions for setting up Fink. Once it's - installed, you'll want to run the following as root: - <command>fink install gd</command> - </para> - <para> - It will prompt you for a number of dependencies, type 'y' and - hit enter to install all of the dependencies. Then watch it - work. - </para> - <para> - To prevent creating conflicts with the software that Apple - installs by default, Fink creates its own directory tree at - /sw where it installs most of the software that it installs. - This means your libraries and headers for libgd will be at - /sw/lib and /sw/include instead of /usr/lib and - /usr/local/include. Because of these changed locations for - the libraries, the Perl GD module will not install directly - via CPAN (it looks for the specific paths instead of getting - them from your environment). But there's a way around that - :-) - </para> - <para> - Instead of typing <quote>install GD</quote> at the - <prompt>cpan></prompt> prompt, type <command>look - GD</command>. This should go through the motions of - downloading the latest version of the GD module, then it will - open a shell and drop you into the build directory. Apply the - following patch to the Makefile.PL file (save the patch into a - file and use the command <command>patch < - patchfile</command>: - </para> - <para> - <programlisting> -<![CDATA[ - ---- GD-1.33/Makefile.PL Fri Aug 4 16:59:22 2000 -+++ GD-1.33-darwin/Makefile.PL Tue Jun 26 01:29:32 2001 -@@ -3,8 +3,8 @@ - warn "NOTICE: This module requires libgd 1.8.3 or higher (shared library version 4.X).\n"; - - # =====> PATHS: CHECK AND ADJUST <===== --my @INC = qw(-I/usr/local/include -I/usr/local/include/gd); --my @LIBPATH = qw(-L/usr/lib/X11 -L/usr/X11R6/lib -L/usr/X11/lib -L/usr/local/lib ); -+my @INC = qw(-I/sw/include -I/sw/include/gd -I/usr/local/include -I/usr/local/include/gd); -+my @LIBPATH = qw(-L/usr/lib/X11 -L/usr/X11R6/lib -L/usr/X11/lib -L/sw/lib -L/usr/local/lib); - my @LIBS = qw(-lgd -lpng -lz); - - # FEATURE FLAGS -@@ -23,7 +23,7 @@ - - push @LIBS,'-lttf' if $TTF; - push @LIBS,'-ljpeg' if $JPEG; --push @LIBS, '-lm' unless $^O eq 'MSWin32'; -+push @LIBS, '-lm' unless ($^O =~ /^MSWin32|darwin$/); - - # FreeBSD 3.3 with libgd built from ports croaks if -lXpm is specified - if ($^O ne 'freebsd' && $^O ne 'MSWin32') { - -]]> - </programlisting> - </para> - <para> - Then, run these commands to finish the installation of the perl module: - <simplelist> - <member><command>perl Makefile.PL</command></member> - <member><command>make</command></member> - <member><command>make test</command></member> - <member><command>make install</command></member> - <member>And don't forget to run <command>exit</command> to get back to cpan.</member> - </simplelist> - </para> - <para> - Happy Hacking! - </para> - </section> - - <section id="bsdinstall" xreflabel="BSD Installation Notes"> - <title>BSD Installation Notes</title> - <para> - For instructions on how to set up Bugzilla on FreeBSD, NetBSD, OpenBSD, BSDi, etc. please - consult <xref linkend="osx" />. - </para> </section> - - <section id="geninstall" xreflabel="Installation General Notes"> - <title>Installation General Notes</title> + <section id="extraconfig"> + <title>Optional Additional Configuration</title> + <section> - <title>Modifying Your Running System</title> - <para> - Bugzilla optimizes database lookups by storing all relatively static - information in the versioncache file, located in the data/ subdirectory - under your installation directory. + <title>Dependency Charts</title> + + <para>As well as the text-based dependency graphs, Bugzilla also + supports dependency graphing, using a package called 'dot'. + Exactly how this works is controlled by the 'webdotbase' parameter, + which can have one of three values: </para> + <para> - If you make a change to the structural data in your database - (the versions table for example), or to the - <quote>constants</quote> encoded in defparams.pl, you will - need to remove the cached content from the data directory - (by doing a <quote>rm data/versioncache</quote>), or your - changes won't show up. + <orderedlist> + <listitem> + <para> + A complete file path to the command 'dot' (part of + <ulink url="http://www.graphviz.org/">GraphViz</ulink>) + will generate the graphs locally + </para> + </listitem> + <listitem> + <para> + A URL prefix pointing to an installation of the webdot package will + generate the graphs remotely + </para> + </listitem> + <listitem> + <para> + A blank value will disable dependency graphing. + </para> + </listitem> + </orderedlist> </para> - <para> - That file gets automatically regenerated whenever it's more than an - hour old, so Bugzilla will eventually notice your changes by itself, but - generally you want it to notice right away, so that you can test things. + + <para>So, to get this working, install + <ulink url="http://www.graphviz.org/">GraphViz</ulink>. If you + do that, you need to + <ulink url="http://httpd.apache.org/docs/mod/mod_imap.html">enable + server-side image maps</ulink> in Apache. + Alternatively, you could set up a webdot server, or use the AT&T + public webdot server (the + default for the webdotbase param). Note that AT&T's server won't work + if Bugzilla is only accessible using HTTPS. </para> + </section> + + <section> + <title>Bug Graphs</title> + + <para>As long as you installed the GD and Graph::Base Perl modules you + might as well turn on the nifty Bugzilla bug reporting graphs.</para> + + <para>Add a cron entry like this to run + <filename>collectstats.pl</filename> + daily at 5 after midnight: + <simplelist> + <member> + <computeroutput> + <prompt>bash#</prompt> + + <command>crontab -e</command> + </computeroutput> + </member> + + <member> + <computeroutput>5 0 * * * cd <your-bugzilla-directory> ; + ./collectstats.pl</computeroutput> + </member> + </simplelist> + </para> + + <para>After two days have passed you'll be able to view bug graphs from + the Bug Reports page.</para> </section> + <section> - <title>Upgrading From Previous Versions</title> + <title>The Whining Cron</title> + + <para>By now you have a fully functional Bugzilla, but what good are + bugs if they're not annoying? To help make those bugs more annoying you + can set up Bugzilla's automatic whining system to complain at engineers + which leave their bugs in the NEW state without triaging them. + </para> + <para> + This can be done by + adding the following command as a daily crontab entry (for help on that + see that crontab man page): + <simplelist> + <member> + <computeroutput> + <command>cd <your-bugzilla-directory> ; + ./whineatnews.pl</command> + </computeroutput> + </member> + </simplelist> + </para> + + <tip> + <para>Depending on your system, crontab may have several manpages. + The following command should lead you to the most useful page for + this purpose: + <programlisting>man 5 crontab</programlisting> + </para> + </tip> + </section> + + <section id="bzldap"> + <title>LDAP Authentication</title> <para> - A plain Bugzilla is fairly easy to upgrade from one version to a newer one. - However, things get a bit more complicated if you've made changes to - Bugzilla's code. In this case, you may have to re-make or reapply those - changes. - It is recommended that you take a backup of your database and your entire - Bugzilla installation before attempting an upgrade. You can upgrade a 'clean' - installation by untarring a new tarball over the old installation. If you - are upgrading from 2.12 or later, you can type <filename>cvs -z3 - update</filename>, and resolve conflicts if there are any. + <warning> + <para>This information on using the LDAP + authentication options with Bugzilla is old, and the authors do + not know of anyone who has tested it. Approach with caution. + </para> + </warning> </para> + <para> - Because the developers of Bugzilla are constantly adding new tables, columns - and fields, you'll probably get SQL errors if you just update the code and - attempt to use Bugzilla. Always run the checksetup.pl script whenever - you upgrade your installation. + The existing authentication + scheme for Bugzilla uses email addresses as the primary user ID, and a + password to authenticate that user. All places within Bugzilla where + you need to deal with user ID (e.g assigning a bug) use the email + address. The LDAP authentication builds on top of this scheme, rather + than replacing it. The initial log in is done with a username and + password for the LDAP directory. This then fetches the email address + from LDAP and authenticates seamlessly in the standard Bugzilla + authentication scheme using this email address. If an account for this + address already exists in your Bugzilla system, it will log in to that + account. If no account for that email address exists, one is created at + the time of login. (In this case, Bugzilla will attempt to use the + "displayName" or "cn" attribute to determine the user's full name.) + After authentication, all other user-related tasks are still handled by + email address, not LDAP username. You still assign bugs by email + address, query on users by email address, etc. + </para> + + <para>Using LDAP for Bugzilla authentication requires the + Mozilla::LDAP (aka PerLDAP) Perl module. The + Mozilla::LDAP module in turn requires Netscape's Directory SDK for C. + After you have installed the SDK, then install the PerLDAP module. + Mozilla::LDAP and the Directory SDK for C are both + <ulink url="http://www.mozilla.org/directory/">available for + download</ulink> from mozilla.org. </para> + <para> - If you are running Bugzilla version 2.8 or lower, and wish to upgrade to - the latest version, please consult the file, "UPGRADING-pre-2.8" in the - Bugzilla root directory after untarring the archive. + Set the Param 'useLDAP' to "On" **only** if you will be using an LDAP + directory for + authentication. Be very careful when setting up this parameter; if you + set LDAP authentication, but do not have a valid LDAP directory set up, + you will not be able to log back in to Bugzilla once you log out. (If + this happens, you can get back in by manually editing the data/params + file, and setting useLDAP back to 0.) </para> + + <para>If using LDAP, you must set the + three additional parameters: Set LDAPserver to the name (and optionally + port) of your LDAP server. If no port is specified, it defaults to the + default port of 389. (e.g "ldap.mycompany.com" or + "ldap.mycompany.com:1234") Set LDAPBaseDN to the base DN for searching + for users in your LDAP directory. (e.g. "ou=People,o=MyCompany") uids + must be unique under the DN specified here. Set LDAPmailattribute to + the name of the attribute in your LDAP directory which contains the + primary email address. On most directory servers available, this is + "mail", but you may need to change this. + </para> </section> + + <section id="content-type" + xreflabel="Preventing untrusted Bugzilla content from executing malicious Javascript code"> + + <title>Preventing untrusted Bugzilla content from executing malicious + Javascript code</title> + + <para>It is possible for a Bugzilla to execute malicious Javascript + code. Due to internationalization concerns, we are unable to + incorporate the code changes necessary to fulfill the CERT advisory + requirements mentioned in + <ulink + url="http://www.cet.org/tech_tips/malicious_code_mitigation.html/#3"> + http://www.cet.org/tech_tips/malicious_code_mitigation.html/#3</ulink>. + Executing the following code snippet from a UNIX command shell will + rectify the problem if your Bugzilla installation is intended for an + English-speaking audience. As always, be sure your Bugzilla + installation has a good backup before making changes, and I recommend + you understand what the script is doing before executing it.</para> - <section id="htaccess" xreflabel=".htaccess files and security"> - <title><filename>.htaccess</filename> files and security</title> <para> - To enhance the security of your Bugzilla installation, - Bugzilla will generate - <glossterm><filename>.htaccess</filename></glossterm> files - which the Apache webserver can use to restrict access to - the bugzilla data files. The checksetup script will - generate the <filename>.htaccess</filename> files. These .htaccess files - will not work with Apache 1.2.x - but this has security holes, so you - shouldn't be using it anyway. - - <note> - <para> - If you are using an alternate provider of - <productname>webdot</productname> services for graphing - (as described when viewing - <filename>editparams.cgi</filename> in your web - browser), you will need to change the ip address in - <filename>data/webdot/.htaccess</filename> to the ip - address of the webdot server that you are using. - </para> - </note> - + <programlisting>bash# perl -pi -e "s/Content-Type\: text\/html/Content-Type\: text\/html\; charset=ISO-8859-1/i" *.cgi *.pl + </programlisting> </para> - <para> - The default .htaccess file may not provide adequate access - restrictions, depending on your web server configuration. - Be sure to check the <Directory> entries for your - Bugzilla directory so that the <filename>.htaccess</filename> - file is allowed to override web server defaults. For instance, - let's assume your installation of Bugzilla is installed to - <filename>/usr/local/bugzilla</filename>. You should have - this <Directory> entry in your <filename>httpd.conf</filename> - file: + <para>All this one-liner command does is search for all instances of + <quote>Content-type: text/html</quote> + + and replaces it with + <quote>Content-Type: text/html; charset=ISO-8859-1</quote> + + . This specification prevents possible Javascript attacks on the + browser, and is suggested for all English-speaking sites. For + non-English-speaking Bugzilla sites, I suggest changing + <quote>ISO-8859-1</quote>, above, to + <quote>UTF-8</quote>.</para> + + <para>Note: using <meta> tags to set the charset is not + recommended, as there's a bug in Netscape 4.x which causes pages + marked up in this way to load twice.</para> + </section> + + <section id="htaccess" xreflabel=".htaccess files and security"> + <title> + <filename>.htaccess</filename> + files and security</title> + + <para>To enhance the security of your Bugzilla installation, Bugzilla's + <filename>checksetup.pl</filename> script will generate + <glossterm> + <filename>.htaccess</filename> + </glossterm> + + files which the Apache webserver can use to restrict access to the + bugzilla data files. + These .htaccess files will not work with Apache 1.2.x - but this + has security holes, so you shouldn't be using it anyway. + <note> + <para>If you are using an alternate provider of + <productname>webdot</productname> + + services for graphing (as described when viewing + <filename>editparams.cgi</filename> + + in your web browser), you will need to change the ip address in + <filename>data/webdot/.htaccess</filename> + + to the ip address of the webdot server that you are using.</para> + </note> </para> + <para>The default .htaccess file may not provide adequate access + restrictions, depending on your web server configuration. Be sure to + check the <Directory> entries for your Bugzilla directory so that + the + <filename>.htaccess</filename> + + file is allowed to override web server defaults. For instance, let's + assume your installation of Bugzilla is installed to + <filename>/usr/local/bugzilla</filename> + + . You should have this <Directory> entry in your + <filename>httpd.conf</filename> + + file:</para> + <para> - <programlisting> -<![CDATA[ -<Directory /usr/local/bugzilla/> + +<programlisting><![CDATA[ + <Directory /usr/local/bugzilla/> Options +FollowSymLinks +Indexes +Includes +ExecCGI AllowOverride All </Directory> -]]> - </programlisting> - </para> +]]></programlisting> - <para> - The important part above is <quote>AllowOverride All</quote>. - Without that, the <filename>.htaccess</filename> file created by - <filename>checksetup.pl</filename> will not have sufficient - permissions to protect your Bugzilla installation. </para> - <para> - If you are using Internet Information Server or other web - server which does not observe <filename>.htaccess</filename> - conventions, you can disable their creation by editing - <filename>localconfig</filename> and setting the - <varname>$create_htaccess</varname> variable to - <parameter>0</parameter>. - </para> - </section> + <para>The important part above is + <quote>AllowOverride All</quote> - <section id="mod-throttle" xreflabel="Using mod_throttle to prevent Denial of Service attacks"> - <title><filename>mod_throttle</filename> and Security</title> - <para> - It is possible for a user, by mistake or on purpose, to access - the database many times in a row which can result in very slow - access speeds for other users. If your Bugzilla installation - is experiencing this problem , you may install the Apache - module <filename>mod_throttle</filename> which can limit - connections by ip-address. You may download this module at - <ulink - url="http://www.snert.com/Software/Throttle/">http://www.snert.com/Software/Throttle/</ulink>. Follow the instructions to install into your Apache install. <emphasis>This module only functions with the Apache web server!</emphasis>. You may use the <command>ThrottleClientIP</command> command provided by this module to accomplish this goal. See the <ulink url="http://www.snert.com/Software/Throttle/">Module Instructions</ulink> for more information. </para> - </section> - - <section id="content-type" xreflabel="Preventing untrusted Bugzilla contentfrom executing malicious Javascript code"> - <title>Preventing untrusted Bugzilla content from executing malicious Javascript code</title> - <para>It is possible for a Bugzilla to execute malicious - Javascript code. Due to internationalization concerns, we are - unable to incorporate the code changes necessary to fulfill - the CERT advisory requirements mentioned in <ulink - url="http://www.cet.org/tech_tips/malicious_code_mitigation.html/#3">http://www.cet.org/tech_tips/malicious_code_mitigation.html/#3</ulink>. Executing the following code snippet from a UNIX command shell will rectify the problem if your Bugzilla installation is intended for an English-speaking audience. As always, be sure your Bugzilla installation has a good backup before making changes, and I recommend you understand what the script is doing before executing it. </para> - <para><programlisting> -bash# cd $BUGZILLA_HOME; for i in `ls *.cgi`; \ - do cat $i | sed 's/Content-type\: text\/html/Content-Type: text\/html\; charset=ISO-8859-1/' >$i.tmp; \ - mv $i.tmp $i; done - </programlisting></para> - <para> - All this one-liner command does is search for all instances of - <quote>Content-type: text/html</quote> and replaces it with - <quote>Content-Type: text/html; charset=ISO-8859-1</quote>. - This specification prevents possible Javascript attacks on the - browser, and is suggested for all English-speaking sites. For - non-english-speaking Bugzilla sites, I suggest changing - <quote>ISO-8859-1</quote>, above, to <quote>UTF-8</quote>. + . Without that, the + <filename>.htaccess</filename> + + file created by + <filename>checksetup.pl</filename> + + will not have sufficient permissions to protect your Bugzilla + installation.</para> + + <para>If you are using Internet Information Server (IIS) or another + web server which does not observe + <filename>.htaccess</filename> + conventions, you can disable their creation by editing + <filename>localconfig</filename> + and setting the + <varname>$create_htaccess</varname> + variable to + <parameter>0</parameter>. </para> </section> - - <section id="unixhistory"> - <title>UNIX Installation Instructions History</title> - <para> - This document was originally adapted from the Bonsai - installation instructions by Terry Weissman - <terry@mozilla.org>. - </para> - <para> - The February 25, 1999 re-write of this page was done by Ry4an - Brase <ry4an@ry4an.org>, with some edits by Terry - Weissman, Bryce Nesbitt, Martin Pool, & Dan Mosedale (But - don't send bug reports to them; report them using bugzilla, at <ulink - url="http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla">http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla</ulink> ). - </para> - <para> - This document was heavily modified again Wednesday, March 07 - 2001 to reflect changes for Bugzilla 2.12 release by Matthew - P. Barnson. The securing MySQL section should be changed to - become standard procedure for Bugzilla installations. - </para> - <para> - Finally, the README in its entirety was marked up in SGML and - included into the Guide on April 24, 2001 by Matt Barnson. - Since that time, it's undergone extensive modification as - Bugzilla grew. - </para> - <para> - Comments from people using this Guide for the first time are - particularly welcome. - </para> + <section id="mod-throttle" + xreflabel="Using mod_throttle to prevent Denial of Service attacks"> + <title> + <filename>mod_throttle</filename> + + and Security</title> + + <para>It is possible for a user, by mistake or on purpose, to access + the database many times in a row which can result in very slow access + speeds for other users. If your Bugzilla installation is experiencing + this problem , you may install the Apache module + <filename>mod_throttle</filename> + + which can limit connections by ip-address. You may download this module + at + <ulink url="http://www.snert.com/Software/Throttle/"> + http://www.snert.com/Software/Throttle/</ulink>. + Follow the instructions to install into your Apache install. + <emphasis>This module only functions with the Apache web + server!</emphasis> + You may use the + <command>ThrottleClientIP</command> + + command provided by this module to accomplish this goal. See the + <ulink url="http://www.snert.com/Software/Throttle/">Module + Instructions</ulink> + for more information.</para> </section> </section> - + <section id="win32" xreflabel="Win32 Installation Notes"> <title>Win32 Installation Notes</title> - <para>This section covers installation on Microsoft Windows 95, - 98, ME, NT, and 2000. Bugzilla works fine on Win32 platforms, - but please remember that the Bugzilla team and the author of the - Guide neither endorse nor support installation on Microsoft - Windows. Bugzilla installs and runs <emphasis>best</emphasis> - and <emphasis>easiest</emphasis> on UNIX-like operating systems, - and that is the way it will stay for the foreseeable future. The - Bugzilla team is considering supporting Win32 for the 2.16 - release and later.</para> - <para>The easiest way to install Bugzilla on Intel-archiecture - machines is to install some variant of GNU/Linux, then follow - the UNIX installation instructions in this Guide. If you have - any influence in the platform choice for running this system, - please choose GNU/Linux instead of Microsoft Windows.</para> + <para>This section covers installation on Microsoft Windows. + Bugzilla has been made to work on Win32 platforms, but the Bugzilla team + wish to emphasise that The easiest way to install Bugzilla on + Intel-archiecture machines + is to install some variant of GNU/Linux, then follow the UNIX + installation instructions in this Guide. If you have any influence in the + platform choice for running this system, please choose GNU/Linux instead + of Microsoft Windows.</para> + + <warning> + <para>After that warning, here's the situation for 2.16 + and Windows. It doesn't work at all out of the box. + You are almost certainly better off getting + the 2.17 version from CVS (after consultation with the Bugzilla Team to + make sure you are pulling on a stable day) because we'll be doing a load + of work to make the Win32 experience more pleasant than it is now. + </para> + </warning> + + <para> + If you still want to try this, to have any hope of getting it to work, + you'll need to apply the + <ulink url="">mail patch</ulink> from + <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=124174">bug 124174</ulink>. + After that, you'll need to read the (outdated) installation + instructions below, some (probably a lot better) <ulink url="http://bugzilla.mozilla.org/attachment.cgi?id=84430&action=view">more + recent ones</ulink> kindly provided by Toms Baugis and Jean-Sebastien + Guay, and also check the + <ulink url="http://www.bugzilla.org/releases/2.16/docs/win32.html">Bugzilla 2.16 Win32 update page + </ulink>. If we get time, + we'll write some better installation instructions for 2.16 and put + them up there. But no promises. + </para> + <section id="wininstall" xreflabel="Win32 Installation: Step-by-step"> <title>Win32 Installation: Step-by-step</title> + <note> - <para> - You should be familiar with, and cross-reference, the rest - of the - <xref linkend="installation" /> section while performing your - Win32 installation. - </para> - <para> Making Bugzilla work on Microsoft Windows is no - picnic. Support for Win32 has improved dramatically in the - last few releases, but, if you choose to proceed, you should - be a <emphasis>very</emphasis> skilled Windows Systems - Administrator with strong troubleshooting abilities, a high - tolerance for pain, and moderate perl skills. Bugzilla on NT - requires hacking source code and implementing some advanced - utilities. What follows is the recommended installation - procedure for Win32; additional suggestions are provided in - <xref linkend="faq" />. - </para> + <para>You should be familiar with, and cross-reference, the rest of + the + <xref linkend="installation" /> + + section while performing your Win32 installation.</para> + + <para>Making Bugzilla work on Microsoft Windows is no picnic. Support + for Win32 has improved dramatically in the last few releases, but, if + you choose to proceed, you should be a + <emphasis>very</emphasis> + + skilled Windows Systems Administrator with strong troubleshooting + abilities, a high tolerance for pain, and moderate perl skills. + Bugzilla on NT requires hacking source code and implementing some + advanced utilities. What follows is the recommended installation + procedure for Win32; additional suggestions are provided in + <xref linkend="faq" /> + + .</para> </note> - + <procedure> - <step> - <para> - Install <ulink url="http://www.apache.org/">Apache Web - Server</ulink> for Windows, and copy the Bugzilla files - somewhere Apache can serve them. Please follow all the - instructions referenced in <xref linkend="installation" /> - regarding your Apache configuration, particularly - instructions regarding the <quote>AddHandler</quote> - parameter and <quote>ExecCGI</quote>. - </para> - <note> - <para> - You may also use Internet Information Server or Personal - Web Server for this purpose. However, setup is quite - different. If ActivePerl doesn't seem to handle your - file associations correctly (for .cgi and .pl files), - please consult <xref linkend="faq" />. - </para> - <para> - If you are going to use IIS, if on Windows NT you must - be updated to at least Service Pack 4. Windows 2000 - ships with a sufficient version of IIS. - </para> - </note> - </step> - <step> - <para> - Install <ulink url="http://www.activestate.com/">ActivePerl</ulink> for Windows. Check <ulink url="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/">http://aspn.activestate.com/ASPN/Downloads/ActivePerl</ulink> for a current compiled binary. - </para> - <para> - Please also check the following links to fully understand the status - of ActivePerl on Win32: - <ulink url="http://language.perl.com/newdocs/pod/perlport.html"> - Perl Porting</ulink>, and - <ulink url="http://ftp.univie.ac.at/packages/perl/ports/nt/FAQ/perlwin32faq5.html"> - Perl on Win32 FAQ</ulink> - </para> - </step> - <step> - <para> - Use ppm from your perl\bin directory to install the following - packs: DBI, DBD-Mysql, TimeDate, Chart, Date-Calc, Date-Manip, - GD, AppConfig, and Template. You may need to extract them from - .zip format using Winzip or other unzip program first. Most of - these additional ppm modules can be downloaded from ActiveState, - but AppConfig and Template should be obtained from OpenInteract - using <ulink type="http" - url="http://openinteract.sourceforge.net/">the instructions on - the Template Toolkit web site</ulink>. + <step> + <para>Install + <ulink url="http://www.apache.org/">Apache Web Server</ulink> + + for Windows, and copy the Bugzilla files somewhere Apache can serve + them. Please follow all the instructions referenced in + <xref linkend="installation" /> + + regarding your Apache configuration, particularly instructions + regarding the + <quote>AddHandler</quote> + + parameter and + <quote>ExecCGI</quote> + + .</para> + + <note> + <para>You may also use Internet Information Server or Personal + Web Server for this purpose. However, setup is quite different. + If ActivePerl doesn't seem to handle your file associations + correctly (for .cgi and .pl files), please consult + <xref linkend="faq" /> + + .</para> + + <para>If you are going to use IIS, if on Windows NT you must be + updated to at least Service Pack 4. Windows 2000 ships with a + sufficient version of IIS.</para> + </note> + </step> + + <step> + <para>Install + <ulink url="http://www.activestate.com/">ActivePerl</ulink> + + for Windows. Check + <ulink + url="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/"> + http://aspn.activestate.com/ASPN/Downloads/ActivePerl</ulink> + + for a current compiled binary.</para> + + <para>Please also check the following links to fully understand the + status of ActivePerl on Win32: + <ulink url="http://language.perl.com/newdocs/pod/perlport.html"> + Perl Porting</ulink> + + , and + <ulink + url="http://ftp.univie.ac.at/packages/perl/ports/nt/FAQ/perlwin32faq5.html"> + Perl on Win32 FAQ</ulink> </para> - <note> - <para> - You can find a list of modules at - <ulink url="http://www.activestate.com/PPMPackages/zips/5xx-builds-only"> - http://www.activestate.com/PPMPackages/zips/5xx-builds-only/</ulink> - or <ulink - url="http://www.activestate.com/PPMPackages/5.6plus">http://www.activestate.com/PPMPackages/5.6plus</ulink> - </para> - </note> - <para> - The syntax for ppm is: - <computeroutput> - <prompt>C:> </prompt><command>ppm <modulename></command> - </computeroutput> - </para> - - <example> - <title>Installing ActivePerl ppd Modules on Microsoft Windows</title> - <para><prompt>C:></prompt><command>ppm - <option>DBD-Mysql</option></command></para> - <para>Watch your capitalization!</para> - </example> - - <para> - ActiveState's 5.6Plus directory also contains an AppConfig ppm, so - you might see the following error when trying to install the - version at OpenInteract: + </step> + + <step> + <para>Use ppm from your perl\bin directory to install the following + packs: DBI, DBD-Mysql, TimeDate, Chart, Date-Calc, Date-Manip, GD, + AppConfig, and Template. You may need to extract them from .zip + format using Winzip or other unzip program first. Most of these + additional ppm modules can be downloaded from ActiveState, but + AppConfig and Template should be obtained from OpenInteract using + <ulink type="http" url="http://openinteract.sourceforge.net/">the + instructions on the Template Toolkit web site</ulink> + + .</para> + + <note> + <para>You can find a list of modules at + <ulink + url="http://www.activestate.com/PPMPackages/zips/5xx-builds-only"> + http://www.activestate.com/PPMPackages/zips/5xx-builds-only/</ulink> + + or + <ulink url="http://www.activestate.com/PPMPackages/5.6plus"> + http://www.activestate.com/PPMPackages/5.6plus</ulink> + </para> + </note> + + <para>The syntax for ppm is: + <computeroutput> + <prompt>C:></prompt> + + <command>ppm <modulename></command> + </computeroutput> </para> + + <example> + <title>Installing ActivePerl ppd Modules on Microsoft + Windows</title> + + <para> + <prompt>C:></prompt> + + <command>ppm + <option>DBD-Mysql</option> + </command> + </para> + + <para>Watch your capitalization!</para> + </example> + + <para>ActiveState's 5.6Plus directory also contains an AppConfig + ppm, so you might see the following error when trying to install + the version at OpenInteract:</para> + <para> - <computeroutput> - Error installing package 'AppConfig': Read a PPD for - 'AppConfig', but it is not intended for this build of Perl - (MSWin32-x86-multi-thread) - </computeroutput> - </para> - <para> - If so, download both <ulink - url="http://openinteract.sourceforge.net/ppmpackages/AppConfig.tar.gz">the - tarball</ulink> and <ulink - url="http://openinteract.sourceforge.net/ppmpackages/AppConfig.ppd">the - ppd</ulink> directly from OpenInteract, then run ppm from within - the same directory to which you downloaded those files and - install the package by referencing the ppd file explicitly via in - the install command, f.e.: - <example> - <title>Installing OpenInteract ppd Modules manually on Microsoft - Windows</title> + <computeroutput>Error installing package 'AppConfig': Read a PPD + for 'AppConfig', but it is not intended for this build of Perl + (MSWin32-x86-multi-thread)</computeroutput> + </para> + + <para>If so, download both + <ulink + url="http://openinteract.sourceforge.net/ppmpackages/AppConfig.tar.gz"> + the tarball</ulink> + + and + <ulink + url="http://openinteract.sourceforge.net/ppmpackages/AppConfig.ppd"> + the ppd</ulink> + + directly from OpenInteract, then run ppm from within the same + directory to which you downloaded those files and install the + package by referencing the ppd file explicitly via in the install + command, f.e.: + <example> + <title>Installing OpenInteract ppd Modules manually on Microsoft + Windows</title> + + <para> + <computeroutput> + <command>install + <filename>C:\AppConfig.ppd</filename> + </command> + </computeroutput> + </para> + </example> + </para> + </step> + + <step> + <para>Install MySQL for NT. + <note> + <para>You can download MySQL for Windows NT from + <ulink url="http://www.mysql.com/">MySQL.com</ulink> + + . Some find it helpful to use the WinMySqlAdmin utility, included + with the download, to set up the database.</para> + </note> + </para> + </step> + + <step> + <para>Setup MySQL</para> + + <substeps> + <step> + <para> + <computeroutput> + <prompt>C:></prompt> + + <command>C:\mysql\bin\mysql -u root mysql</command> + </computeroutput> + </para> + </step> + + <step> + <para> + <computeroutput> + <prompt>mysql></prompt> + + <command>DELETE FROM user WHERE Host='localhost' AND + User='';</command> + </computeroutput> + </para> + </step> + + <step> + <para> + <computeroutput> + <prompt>mysql></prompt> + + <command>UPDATE user SET Password=PASSWORD ('new_password') + WHERE user='root';</command> + </computeroutput> + </para> + + <para> + <quote>new_password</quote> + + , above, indicates whatever password you wish to use for your + <quote>root</quote> + + user.</para> + </step> + + <step id="ntbugs-password"> <para> - <computeroutput><command>install - <filename>C:\AppConfig.ppd</filename></command></computeroutput> + <computeroutput> + <prompt>mysql></prompt> + + <command>GRANT SELECT, INSERT, UPDATE, DELETE, INDEX, + ALTER, CREATE, DROP, REFERENCES ON bugs.* to bugs@localhost + IDENTIFIED BY 'bugs_password';</command> + </computeroutput> </para> - </example> + + <para> + <quote>bugs_password</quote> + + , above, indicates whatever password you wish to use for your + <quote>bugs</quote> + + user.</para> + </step> + + <step> + <para> + <computeroutput> + <prompt>mysql></prompt> + + <command>FLUSH PRIVILEGES;</command> + </computeroutput> + </para> + </step> + + <step> + <para> + <computeroutput> + <prompt>mysql></prompt> + + <command>create database bugs;</command> + </computeroutput> + </para> + </step> + + <step> + <para> + <computeroutput> + <prompt>mysql></prompt> + + <command>exit;</command> + </computeroutput> + </para> + </step> + + <step> + <para> + <computeroutput> + <prompt>C:></prompt> + + <command>C:\mysql\bin\mysqladmin -u root -p + reload</command> + </computeroutput> + </para> + </step> + </substeps> + </step> + + <step> + <para>Edit + <filename>checksetup.pl</filename> + + in your Bugzilla directory. Change this line:</para> + + <para> + <programlisting>my $webservergid = + getgrnam($my_webservergroup);</programlisting> </para> - </step> - - <step> - <para> - Install MySQL for NT. - <note> - <para> - You can download MySQL for Windows NT from <ulink url="http://www.mysql.com/">MySQL.com</ulink>. Some find it helpful to use the WinMySqlAdmin utility, included with the download, to set up the database. - </para> - </note> - </para> - </step> - <step> - <para> - Setup MySQL - </para> - <substeps> - <step> - <para> - <computeroutput> - <prompt>C:> </prompt> - <command>C:\mysql\bin\mysql -u root mysql</command> - </computeroutput> - </para> - </step> - <step> - <para> - <computeroutput> - <prompt>mysql></prompt> - <command>DELETE FROM user WHERE Host='localhost' AND User='';</command> - </computeroutput> - </para> - </step> - <step> - <para> - <computeroutput> - <prompt>mysql></prompt> - <command>UPDATE user SET Password=PASSWORD ('new_password') - WHERE user='root';</command> - </computeroutput> - </para> - <para><quote>new_password</quote>, above, indicates - whatever password you wish to use for your - <quote>root</quote> user.</para> - </step> - <step id="ntbugs-password"> - <para> - <computeroutput> - <prompt>mysql></prompt> - <command>GRANT SELECT, INSERT, UPDATE, DELETE, - INDEX, ALTER, CREATE, DROP, REFERENCES - ON bugs.* to bugs@localhost - IDENTIFIED BY 'bugs_password';</command> - </computeroutput> - </para> - <para><quote>bugs_password</quote>, above, indicates - whatever password you wish to use for your - <quote>bugs</quote> user.</para> - </step> - <step> - <para> - <computeroutput> - <prompt>mysql></prompt> - <command>FLUSH PRIVILEGES;</command> - </computeroutput> - </para> - </step> - <step> - <para> - <computeroutput> - <prompt>mysql></prompt> - <command>create database bugs;</command> - </computeroutput> - </para> - </step> - <step> - <para> - <computeroutput> - <prompt>mysql></prompt> - <command>exit;</command> - </computeroutput> - </para> - </step> - <step> - <para> - <computeroutput> - <prompt>C:></prompt> - <command>C:\mysql\bin\mysqladmin -u root -p reload</command> - </computeroutput> - </para> - </step> - </substeps> - </step> - - <step> - <para> - Edit <filename>checksetup.pl</filename> in your Bugzilla directory. Change - this line: - </para> - <para> - <programlisting> -my $webservergid = getgrnam($my_webservergroup); - </programlisting> - </para> - <para> - to - </para> - <para> - <programlisting> -my $webservergid = $my_webservergroup; - </programlisting> -or the name of the group you wish to own the files explicitly: - <programlisting> -my $webservergid = 'Administrators' - </programlisting> - </para> - </step> - - <step> - <para> - Run <filename>checksetup.pl</filename> from the Bugzilla directory. - </para> - </step> - - <step> - <para>Edit <filename>localconfig</filename> to suit your - requirements. Set <varname>$db_pass</varname> to your - <quote>bugs_password</quote> from <xref linkend="ntbugs-password" />, and <varname>$webservergroup</varname> to <quote>8</quote>.</para> - <note> - <para>Not sure on the <quote>8</quote> for - <varname>$webservergroup</varname> above. If it's - wrong, please send corrections.</para> - </note> - </step> - - <step> - <para> - Edit <filename>defparams.pl</filename> to suit your - requirements. Particularly, set - <varname>DefParam("maintainer")</varname> and - <varname>DefParam("urlbase") to match your - install.</varname> - </para> - <note> - <para>This is yet another step I'm not sure of, since the - maintainer of this documentation does not maintain - Bugzilla on NT. If you can confirm or deny that this - step is required, please let me know.</para> - </note> - </step> - - <step> - <note> - <para> - There are several alternatives to Sendmail that will work on Win32. - The one mentioned here is a <emphasis>suggestion</emphasis>, not - a requirement. Some other mail packages that can work include - <ulink url="http://www.blat.net/">BLAT</ulink>, - <ulink url="http://www.geocel.com/windmail/">Windmail</ulink>, - <ulink url="http://www.dynamicstate.com/">Mercury Sendmail</ulink>, - and the CPAN Net::SMTP Perl module (available in .ppm). - Every option requires some hacking of the Perl scripts for Bugzilla - to make it work. The option here simply requires the least. - </para> - </note> - - <procedure> - <step> - <para> - Download NTsendmail, available from<ulink url="http://www.ntsendmail.com/"> www.ntsendmail.com</ulink>. You must have a "real" mail server which allows you to relay off it in your $ENV{"NTsendmail"} (which you should probably place in globals.pl) - </para> - </step> - - <step> - <para>Put ntsendmail.pm into your .\perl\lib directory.</para> - </step> - - <step> - <para>Add to globals.pl:</para> - <programlisting> -# these settings configure the NTsendmail process -use NTsendmail; -$ENV{"NTsendmail"}="your.smtpserver.box"; -$ENV{"NTsendmail_debug"}=1; -$ENV{"NTsendmail_max_tries"}=5; - </programlisting> - <note> - <para> - Some mention to also edit - <varname>$db_pass</varname> in - <filename>globals.pl</filename> to be your - <quote>bugs_password</quote>. Although this may get - you around some problem authenticating to your - database, since globals.pl is not normally - restricted by <filename>.htaccess</filename>, your - database password is exposed to whoever uses your - web server. - </para> - </note> - </step> - - <step> - <para> - Find and comment out all occurences of - <quote><command>open(SENDMAIL</command></quote> in - your Bugzilla directory. Then replace them with: - <programlisting> -# new sendmail functionality -my $mail=new NTsendmail; -my $from="bugzilla\@your.machine.name.tld"; -my $to=$login; -my $subject=$urlbase; -$mail->send($from,$to,$subject,$msg); - </programlisting> - </para> - <note> - <para> - Some have found success using the commercial product, - <productname>Windmail</productname>. - You could try replacing your sendmail calls with: - <programlisting> -open SENDMAIL, "|\"C:/General/Web/tools/Windmail 4.0 Beta/windmail\" -t > mail.log"; - </programlisting> - or something to that effect. - </para> - </note> - </step> - </procedure> - </step> - - <step> - <para> - Change all references in all files from - <filename>processmail</filename> to - <filename>processmail.pl</filename>, and - rename <filename>processmail</filename> to - <filename>processmail.pl</filename>. - </para> - <note> - <para> - Many think this may be a change we want to make for - main-tree Bugzilla. It's painless for the UNIX folks, - and will make the Win32 people happier. - </para> - </note> - <note> - <para> - Some people have suggested using the Net::SMTP Perl module instead of NTsendmail or the other options listed here. You can change processmail.pl to make this work. - <programlisting> + + <para>to</para> + + <para> + <programlisting>my $webservergid = + $my_webservergroup;</programlisting> + + or the name of the group you wish to own the files explicitly: + <programlisting>my $webservergid = + 'Administrators'</programlisting> + </para> + </step> + + <step> + <para>Run + <filename>checksetup.pl</filename> + + from the Bugzilla directory.</para> + </step> + + <step> + <para>Edit + <filename>localconfig</filename> + + to suit your requirements. Set + <varname>$db_pass</varname> + + to your + <quote>bugs_password</quote> + + from + <xref linkend="ntbugs-password" /> + + , and + <varname>$webservergroup</varname> + + to + <quote>8</quote> + + .</para> + + <note> + <para>Not sure on the + <quote>8</quote> + + for + <varname>$webservergroup</varname> + + above. If it's wrong, please send corrections.</para> + </note> + </step> + + <step> + <para>Edit + <filename>defparams.pl</filename> + + to suit your requirements. Particularly, set + <varname>DefParam("maintainer")</varname> + + and + <varname>DefParam("urlbase") to match your install.</varname> + </para> + + <note> + <para>This is yet another step I'm not sure of, since the + maintainer of this documentation does not maintain Bugzilla on + NT. If you can confirm or deny that this step is required, please + let me know.</para> + </note> + </step> + + <step> + <note> + <para>There are several alternatives to Sendmail that will work + on Win32. The one mentioned here is a + <emphasis>suggestion</emphasis> + + , not a requirement. Some other mail packages that can work + include + <ulink url="http://www.blat.net/">BLAT</ulink> + + , + <ulink url="http://www.geocel.com/windmail/">Windmail</ulink> + + , + <ulink url="http://www.dynamicstate.com/">Mercury + Sendmail</ulink> + + , and the CPAN Net::SMTP Perl module (available in .ppm). Every + option requires some hacking of the Perl scripts for Bugzilla to + make it work. The option here simply requires the least.</para> + </note> + + <procedure> + <step> + <para>Download NTsendmail, available from + <ulink url="http://www.ntsendmail.com/"> + www.ntsendmail.com</ulink> + + . You must have a "real" mail server which allows you to relay + off it in your $ENV{"NTsendmail"} (which you should probably + place in globals.pl)</para> + </step> + + <step> + <para>Put ntsendmail.pm into your .\perl\lib directory.</para> + </step> + + <step> + <para>Add to globals.pl:</para> + + <programlisting># these settings configure the NTsendmail + process use NTsendmail; + $ENV{"NTsendmail"}="your.smtpserver.box"; + $ENV{"NTsendmail_debug"}=1; + $ENV{"NTsendmail_max_tries"}=5;</programlisting> + + <note> + <para>Some mention to also edit + <varname>$db_pass</varname> + + in + <filename>globals.pl</filename> + + to be your + <quote>bugs_password</quote> + + . Although this may get you around some problem + authenticating to your database, since globals.pl is not + normally restricted by + <filename>.htaccess</filename> + + , your database password is exposed to whoever uses your web + server.</para> + </note> + </step> + + <step> + <para>Find and comment out all occurences of + <quote> + <command>open(SENDMAIL</command> + </quote> + + in your Bugzilla directory. Then replace them with: + <programlisting># new sendmail functionality my $mail=new + NTsendmail; my $from="bugzilla\@your.machine.name.tld"; my + $to=$login; my $subject=$urlbase; + $mail->send($from,$to,$subject,$msg);</programlisting> + </para> + + <note> + <para>Some have found success using the commercial product, + <productname>Windmail</productname> + + . You could try replacing your sendmail calls with: + <programlisting>open SENDMAIL, + "|\"C:/General/Web/tools/Windmail 4.0 Beta/windmail\" -t > + mail.log";</programlisting> + + or something to that effect.</para> + </note> + </step> + </procedure> + </step> + + <step> + <para>Change all references in all files from + <filename>processmail</filename> + + to + <filename>processmail.pl</filename> + + , and rename + <filename>processmail</filename> + + to + <filename>processmail.pl</filename> + + .</para> + + <note> + <para>Many think this may be a change we want to make for + main-tree Bugzilla. It's painless for the UNIX folks, and will + make the Win32 people happier.</para> + </note> + + <note> + <para>Some people have suggested using the Net::SMTP Perl module + instead of NTsendmail or the other options listed here. You can + change processmail.pl to make this work. + <programlisting> <![CDATA[ my $smtp = Net::SMTP->new('<Name of your SMTP server>'); #connect to SMTP server @@ -1737,9 +1774,10 @@ $logstr = "$logstr; mail sent to $tolist $cclist"; } ]]> -</programlisting> -here is a test mail program for Net::SMTP: -<programlisting> + </programlisting> + + here is a test mail program for Net::SMTP: + <programlisting> <![CDATA[ use Net::SMTP; @@ -1757,241 +1795,352 @@ recipient's address exit; ]]> -</programlisting> - </para> - </note> - </step> - <step> - <note> - <para> - This step is optional if you are using IIS or another - web server which only decides on an interpreter based - upon the file extension (.pl), rather than the - <quote>shebang</quote> line (#/usr/bonsaitools/bin/perl) - </para> - </note> - <para> - Modify the path to perl on the first line (#!) of all - files to point to your Perl installation, and add - <quote>perl</quote> to the beginning of all Perl system - calls that use a perl script as an argument. This may - take you a while. There is a <quote>setperl.csh</quote> - utility to speed part of this procedure, available in the - <xref linkend="patches" /> section of The Bugzilla Guide. - However, it requires the Cygwin GNU-compatible environment - for Win32 be set up in order to work. See <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink> for details on obtaining Cygwin. - </para> - </step> - - <step> - <para> - Modify the invocation of all system() calls in all perl - scripts in your Bugzilla directory. You should specify the - full path to perl for each system() call. For instance, change - this line in processmail: - <programlisting><![CDATA[ + </programlisting> + </para> + </note> + </step> + + <step> + <note> + <para>This step is optional if you are using IIS or another web + server which only decides on an interpreter based upon the file + extension (.pl), rather than the + <quote>shebang</quote> + + line (#/usr/bonsaitools/bin/perl)</para> + </note> + + <para>Modify the path to perl on the first line (#!) of all files + to point to your Perl installation, and add + <quote>perl</quote> + + to the beginning of all Perl system calls that use a perl script as + an argument. This may take you a while. There is a + <quote>setperl.csh</quote> + + utility to speed part of this procedure, available in the + <xref linkend="patches" /> + + section of The Bugzilla Guide. However, it requires the Cygwin + GNU-compatible environment for Win32 be set up in order to work. + See + <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink> + + for details on obtaining Cygwin.</para> + </step> + + <step> + <para>Modify the invocation of all system() calls in all perl + scripts in your Bugzilla directory. You should specify the full + path to perl for each system() call. For instance, change this line + in processmail: + <programlisting> +<![CDATA[ system ("./processmail",@ARGLIST); - </programlisting> to - <programlisting> + </programlisting> to + <programlisting> system ("C:\\perl\\bin\\perl", "processmail", @ARGLIST); -]]> </programlisting> - </para> - </step> - <step> - <para> - Add <function>binmode()</function> calls so attachments - will work (<ulink - url="http://bugzilla.mozilla.org/show_bug.cgi?id=62000">bug 62000</ulink>). +]]> + </programlisting> </para> + </step> + + <step> + <para>Add + <function>binmode()</function> + + calls so attachments will work ( + <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=62000">bug + 62000</ulink> + + ).</para> + + <para>Because Microsoft Windows based systems handle binary files + different than Unix based systems, you need to add the following + lines to + <filename>createattachment.cgi</filename> + + and + <filename>showattachment.cgi</filename> + + before the + <function>require 'CGI.pl';</function> + + line.</para> + <para> - Because Microsoft Windows based systems handle binary - files different than Unix based systems, you need to add - the following lines to - <filename>createattachment.cgi</filename> and - <filename>showattachment.cgi</filename> before the - <function>require 'CGI.pl';</function> line. -</para> -<para> -<programlisting> + <programlisting> <![CDATA[ binmode(STDIN); binmode(STDOUT); ]]> -</programlisting> + </programlisting> </para> + <note> - <para> - According to <ulink - url="http://bugzilla.mozilla.org/show_bug.cgi?id=62000">bug 62000</ulink>, - the perl documentation says that you should always use - <function>binmode()</function> when dealing with binary - files, but never when dealing with text files. That seems - to suggest that rather than arbitrarily putting - <function>binmode()</function> at the beginning of the - attachment files, there should be logic to determine if - <function>binmode()</function> is needed or not. - </para> + <para>According to + <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=62000"> + bug 62000</ulink> + + , the perl documentation says that you should always use + <function>binmode()</function> + + when dealing with binary files, but never when dealing with text + files. That seems to suggest that rather than arbitrarily putting + + <function>binmode()</function> + + at the beginning of the attachment files, there should be logic + to determine if + <function>binmode()</function> + + is needed or not.</para> </note> </step> </procedure> <tip> - <para> - If you are using IIS or Personal Web Server, you must add cgi - relationships to Properties -> Home directory (tab) -> - Application Settings (section) -> Configuration (button), - such as: - </para> - <para> - <programlisting> -.cgi to: <perl install directory>\perl.exe %s %s -.pl to: <perl install directory>\perl.exe %s %s -GET,HEAD,POST - </programlisting> - Change the path to Perl to match your - install, of course. - </para> + <para>If you are using IIS or Personal Web Server, you must add cgi + relationships to Properties -> Home directory (tab) -> + Application Settings (section) -> Configuration (button), such + as:</para> + + <para> + <programlisting>.cgi to: <perl install directory>\perl.exe %s + %s .pl to: <perl install directory>\perl.exe %s %s + GET,HEAD,POST</programlisting> + + Change the path to Perl to match your install, of course.</para> </tip> </section> <section id="addlwintips"> <title>Additional Windows Tips</title> + <tip> - <para> - From Andrew Pearson: - <blockquote> - <para> - You can make Bugzilla work with Personal Web Server for - Windows 98 and higher, as well as for IIS 4.0. - Microsoft has information available at <ulink url=" - http://support.microsoft.com/support/kb/articles/Q231/9/98.ASP"> http://support.microsoft.com/support/kb/articles/Q231/9/98.ASP</ulink> - </para> - <para> - Basically you need to add two String Keys in the - registry at the following location: - </para> - <para> - <programlisting> -HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\ScriptMap - </programlisting> - </para> - <para> - The keys should be called ".pl" and ".cgi", and both - should have a value something like: - <command>c:/perl/bin/perl.exe "%s" "%s"</command> - </para> - <para> - The KB article only talks about .pl, but it goes into - more detail and provides a perl test script. - </para> - </blockquote> - </para> + <para>From Andrew Pearson: + <blockquote> + <para>You can make Bugzilla work with Personal Web Server for + Windows 98 and higher, as well as for IIS 4.0. Microsoft has + information available at + <ulink + url=" http://support.microsoft.com/support/kb/articles/Q231/9/98.ASP"> + http://support.microsoft.com/support/kb/articles/Q231/9/98.ASP</ulink> + </para> + + <para>Basically you need to add two String Keys in the registry at + the following location:</para> + + <para> + <programlisting> + HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\ScriptMap</programlisting> + </para> + + <para>The keys should be called ".pl" and ".cgi", and both should + have a value something like: + <command>c:/perl/bin/perl.exe "%s" "%s"</command> + </para> + + <para>The KB article only talks about .pl, but it goes into more + detail and provides a perl test script.</para> + </blockquote> + </para> </tip> + <tip> - <para> - If attempting to run Bugzilla 2.12 or older, you will need - to remove encrypt() calls from the Perl source. This is - <emphasis>not necessary</emphasis> for Bugzilla 2.13 and - later, which includes the current release, Bugzilla - &bz-ver;. - <example> - <title>Removing encrypt() for Windows NT Bugzilla version - 2.12 or earlier</title> - <para> - Replace this: - <programlisting> -SendSQL("SELECT encrypt(" . SqlQuote($enteredpwd) . ", " . SQLQuote(substr($realcryptpwd, 0, 2)) . ")"); -my $enteredcryptpwd = FetchOneColumn(); - </programlisting> -with this: - <programlisting> -my $enteredcryptpwd = $enteredpwd - </programlisting> - in cgi.pl. - </para> - </example> - </para> + <para>If attempting to run Bugzilla 2.12 or older, you will need to + remove encrypt() calls from the Perl source. This is + <emphasis>not necessary</emphasis> + + for Bugzilla 2.13 and later, which includes the current release, + Bugzilla &bz-ver;. + <example> + <title>Removing encrypt() for Windows NT Bugzilla version 2.12 or + earlier</title> + + <para>Replace this: + <programlisting>SendSQL("SELECT encrypt(" . SqlQuote($enteredpwd) . + ", " . SQLQuote(substr($realcryptpwd, 0, 2)) . ")"); my + $enteredcryptpwd = FetchOneColumn();</programlisting> + + with this: + <programlisting>my $enteredcryptpwd = $enteredpwd</programlisting> + + in cgi.pl.</para> + </example> + </para> </tip> </section> + </section> + + <section id="osx"> + <title>Mac OS X Installation Notes</title> + + <para>There are a lot of common libraries and utilities out there that + Apple did not include with Mac OS X, but which run perfectly well on it. + The GD library, which Bugzilla needs to do bug graphs, is one of + these.</para> + + <para>The easiest way to get a lot of these is with a program called + Fink, which is similar in nature to the CPAN installer, but installs + common GNU utilities. Fink is available from + <http://sourceforge.net/projects/fink/>.</para> + + <para>Follow the instructions for setting up Fink. Once it's installed, + you'll want to run the following as root: + <command>fink install gd</command> + </para> + + <para>It will prompt you for a number of dependencies, type 'y' and hit + enter to install all of the dependencies. Then watch it work.</para> + + <para>To prevent creating conflicts with the software that Apple installs + by default, Fink creates its own directory tree at /sw where it installs + most of the software that it installs. This means your libraries and + headers for libgd will be at /sw/lib and /sw/include instead of /usr/lib + and /usr/local/include. Because of these changed locations for the + libraries, the Perl GD module will not install directly via CPAN, because it + looks for the specific paths instead of getting them from your + environment. But there's a way around that :-)</para> + + <para>Instead of typing + <quote>install GD</quote> + at the + <prompt>cpan></prompt> + prompt, type + <command>look GD</command>. + This should go through the motions of downloading the latest version of + the GD module, then it will open a shell and drop you into the build + directory. Apply <ulink url="../sgml/gd-makefile.patch">this patch</ulink> + to the Makefile.PL file (save the + patch into a file and use the command + <command>patch < patchfile</command>.) + </para> - <section id="bzldap"> - <title>Bugzilla LDAP Integration</title> + <para>Then, run these commands to finish the installation of the GD + module: + <simplelist> + <member> + <command>perl Makefile.PL</command> + </member> + + <member> + <command>make</command> + </member> + + <member> + <command>make test</command> + </member> + + <member> + <command>make install</command> + </member> + + <member>And don't forget to run + <command>exit</command> + + to get back to CPAN.</member> + </simplelist> + </para> + + </section> + + <section id="troubleshooting"> + <title>Troubleshooting</title> + + <para>This section gives solutions to common Bugzilla installation + problems. + </para> + + <section> + <title>Bundle::Bugzilla makes me upgrade to Perl 5.6.1</title> + <para> - What follows is some late-breaking information on using the - LDAP authentication options with Bugzilla. The author has not - tested these (nor even formatted this section!) so please - contribute feedback to the newsgroup. + Try executing <command>perl -MCPAN -e 'install CPAN'</command> + and then continuing. + </para> + + <para> + Certain older versions of the CPAN toolset were somewhat naive about how + to upgrade Perl modules. When a couple of modules got rolled into the core + Perl distribution for 5.6.1, CPAN thought that the best way to get those + modules up to date was to haul down the Perl distribution itself and + build it. Needless to say, this has caused headaches for just about + everybody. Upgrading to a newer version of CPAN with the + commandline above should fix things. </para> - <literallayout> -Mozilla::LDAP module - -The Mozilla::LDAP module allows you to use LDAP for authentication to -the Bugzilla system. This module is not required if you are not using -LDAP. - -Mozilla::LDAP (aka PerLDAP) is available for download from -http://www.mozilla.org/directory. - -NOTE: The Mozilla::LDAP module requires Netscape's Directory SDK. -Follow the link for "Directory SDK for C" on that same page to -download the SDK first. After you have installed this SDK, then -install the PerLDAP module. ----------------------------------------------------------------------- - -Post-Installation Checklist ----------------------------------------------------------------------- -Set useLDAP to "On" **only** if you will be using an LDAP directory -for authentication. Be very careful when setting up this parameter; -if you set LDAP authentication, but do not have a valid LDAP directory -set up, you will not be able to log back in to Bugzilla once you log -out. (If this happens, you can get back in by manually editing the -data/params file, and setting useLDAP back to 0.) - -If using LDAP, you must set the three additional parameters: - -Set LDAPserver to the name (and optionally port) of your LDAP server. -If no port is specified, it defaults to the default port of 389. (e.g -"ldap.mycompany.com" or "ldap.mycompany.com:1234") - -Set LDAPBaseDN to the base DN for searching for users in your LDAP -directory. (e.g. "ou=People,o=MyCompany") uids must be unique under -the DN specified here. - -Set LDAPmailattribute to the name of the attribute in your LDAP -directory which contains the primary email address. On most directory -servers available, this is "mail", but you may need to change this. ----------------------------------------------------------------------- - -(Not sure where this bit should go, but it's important that it be in -there somewhere...) ----------------------------------------------------------------------- -Using LDAP authentication for Bugzilla: - -The existing authentication scheme for Bugzilla uses email addresses -as the primary user ID, and a password to authenticate that user. All -places within Bugzilla where you need to deal with user ID (e.g -assigning a bug) use the email address. - -The LDAP authentication builds on top of this scheme, rather than -replacing it. The initial log in is done with a username and password -for the LDAP directory. This then fetches the email address from LDAP -and authenticates seamlessly in the standard Bugzilla authentication -scheme using this email address. If an account for this address -already exists in your Bugzilla system, it will log in to that -account. If no account for that email address exists, one is created -at the time of login. (In this case, Bugzilla will attempt to use the -"displayName" or "cn" attribute to determine the user's full name.) - -After authentication, all other user-related tasks are still handled -by email address, not LDAP username. You still assign bugs by email -address, query on users by email address, etc. ----------------------------------------------------------------------- - </literallayout> </section> + + + <section> + <title>DBD::Sponge::db prepare failed</title> + + <para> + The following error message may appear due to a bug in DBD::mysql + (over which the Bugzilla team have no control): + </para> + +<programlisting><![CDATA[ DBD::Sponge::db prepare failed: Cannot determine NUM_OF_FIELDS at D:/Perl/site/lib/DBD/mysql.pm line 248. + SV = NULL(0x0) at 0x20fc444 + REFCNT = 1 + FLAGS = (PADBUSY,PADMY) +]]></programlisting> + + <para> + To fix this, go to + <filename><path-to-perl>/lib/DBD/sponge.pm</filename> + in your Perl installation and replace + </para> + +<programlisting><![CDATA[ my $numFields; + if ($attribs->{'NUM_OF_FIELDS'}) { + $numFields = $attribs->{'NUM_OF_FIELDS'}; + } elsif ($attribs->{'NAME'}) { + $numFields = @{$attribs->{NAME}}; +]]></programlisting> + + <para> + by + </para> + +<programlisting><![CDATA[ my $numFields; + if ($attribs->{'NUM_OF_FIELDS'}) { + $numFields = $attribs->{'NUM_OF_FIELDS'}; + } elsif ($attribs->{'NAMES'}) { + $numFields = @{$attribs->{NAMES}}; +]]></programlisting> + + <para> + (note the S added to NAME.) + </para> + </section> + + <section id="paranoid-security"> + <title>cannot chdir(/var/spool/mqueue)</title> + + <para>If you are installing Bugzilla on SuSE Linux, or some other + distributions with + <quote>paranoid</quote> + security options, it is possible that the checksetup.pl script may fail + with the error: +<programlisting><![CDATA[cannot chdir(/var/spool/mqueue): Permission denied +]]></programlisting> + </para> + + <para> + This is because your + <filename>/var/spool/mqueue</filename> + directory has a mode of + <quote>drwx------</quote>. Type + <command>chmod 755 + <filename>/var/spool/mqueue</filename> + </command> + as root to fix this problem. + </para> + </section> </section> </chapter> - <!-- Keep this comment at the end of the file Local variables: mode: sgml @@ -2012,3 +2161,4 @@ sgml-shorttag:t sgml-tag-region-if-active:t End: --> + |