diff options
Diffstat (limited to 'docs/sgml/installation.sgml')
-rw-r--r-- | docs/sgml/installation.sgml | 1615 |
1 files changed, 0 insertions, 1615 deletions
diff --git a/docs/sgml/installation.sgml b/docs/sgml/installation.sgml deleted file mode 100644 index b9fee2cc8..000000000 --- a/docs/sgml/installation.sgml +++ /dev/null @@ -1,1615 +0,0 @@ -<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> --> -<chapter id="installation" xreflabel="Bugzilla Installation"> - <title>Installation</title> - - <section id="stepbystep" xreflabel="Bugzilla Installation Step-by-step"> - <title>Step-by-step Install</title> - - <section id="intstall-into"> - <title>Introduction</title> - - <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 - <xref linkend="os-win32" /> - for further advice on getting Bugzilla to work on Microsoft - Windows.</para> - - </section> - - <section id="install-package-list"> - <title>Package List</title> - - <note> - <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> - (&min-mysql-ver; or greater) - </para> -</listitem> - -<listitem> - <para> - <ulink url="http://www.perl.org">Perl</ulink> - (&min-perl-ver;, 5.6.1 is recommended if you wish to - use Bundle::Bugzilla) - </para> -</listitem> - -<listitem> - <para>Perl Modules (minimum version): - <orderedlist> - - <listitem> - <para> - <ulink url="http://www.template-toolkit.org">Template</ulink> - (v&min-template-ver;) - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://www.perldoc.com/perl5.6/lib/File/Temp.html"> - File::Temp</ulink> - (&min-file-temp-ver;) (Prerequisite for Template) - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://www.cpan.org/modules/by-module/AppConfig/">AppConfig - </ulink> - (&min-appconfig-ver;) - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://www.cpan.org/authors/id/MUIR/modules/Text-Tabs%2BWrap-2001.0131.tar.gz">Text::Wrap</ulink> - (&min-text-wrap-ver;) - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://search.cpan.org/search?dist=File-Spec">File::Spec - </ulink> - (&min-file-spec-ver;) - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://www.cpan.org/modules/by-module/Data/">Data::Dumper - </ulink> - (&min-data-dumper-ver;) - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://www.cpan.org/modules/by-module/Mysql/">DBD::mysql - </ulink> - (&min-dbd-mysql-ver;) - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://www.cpan.org/modules/by-module/DBI/">DBI</ulink> - (&min-dbi-ver;) - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://www.cpan.org/modules/by-module/Date/">Date::Parse - </ulink> - (&min-date-format-ver;) - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://www.cpan.org/modules/by-module/CGI/">CGI - </ulink> - (&min-cgi-ver;) - </para> - </listitem> - - </orderedlist> - and, optionally: - <orderedlist> - <listitem> - <para> - <ulink url="http://www.cpan.org/modules/by-module/GD/">GD</ulink> - (&min-gd-ver;) for bug charting - </para> - </listitem> - - <listitem> - <para> - GD::Graph - (&min-gd-graph-ver;) for bug charting - </para> - </listitem> - - <listitem> - <para> - GD::Text::Align - (&min-gd-text-align-ver;) for bug charting - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://www.cpan.org/modules/by-module/Chart/">Chart::Base - </ulink> - (&min-chart-base-ver;) for bug charting - </para> - </listitem> - - <listitem> - <para> - XML::Parser - (&min-xml-parser-ver;) for the XML interface - </para> - </listitem> - - <listitem> - <para> - MIME::Parser - (&min-mime-parser-ver;) for the email interface - </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> - - </para> - </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> - - <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 perl &min-perl-ver;, - 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 &newest-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> - - <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> - <computeroutput> - <prompt>bash#</prompt> - <command>perl -MCPAN -e 'install "<modulename>"'</command> - </computeroutput> - </para> - - <para> - To do it the hard way: - </para> - - <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> - - <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> - </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 programmatic 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 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>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. - </para> - </section> - - - </section> - - <section id="sbs-http"> - <title>HTTP Server</title> - - <para>You have freedom of choice here, pretty much any web server that - is capable of running <glossterm linkend="gloss-cgi">CGI</glossterm> - scripts will work. <xref linkend="http"/> has more information about - configuring web servers to work with Bugzilla. - </para> - - <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> - - </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>If you symlink the bugzilla directory into your Apache's HTML - hierarchy, 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> - </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 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>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> - - <note> - <para>If you are using MySQL 4, the bugs user also needs to be granted - the LOCK TABLES and CREATE TEMPORARY TABLES permissions. - </para> - </note> - </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>Configuring Bugzilla</title> - <para> - 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="extraconfig"> - <title>Optional Additional Configuration</title> - - <section> - <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> - <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>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 HARTS. - </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>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> - <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> - 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> - 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> - - <para>You can also try using <ulink url="http://www.openldap.org/"> - OpenLDAP</ulink> with Bugzilla, using any of a number of administration - tools. You should apply the patch attached this bug: - <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=158630"> - http://bugzilla.mozilla.org/show_bug.cgi?id=158630</ulink>, then set - the following object classes for your users: - - <orderedlist> - <listitem><para>objectClass: person</para></listitem> - <listitem><para>objectClass: organizationalPerson</para></listitem> - <listitem><para>objectClass: inetOrgPerson</para></listitem> - <listitem><para>objectClass: top</para></listitem> - <listitem><para>objectClass: posixAccount</para></listitem> - <listitem><para>objectClass: shadowAccount</para></listitem> - </orderedlist> - - Please note that this patch <emphasis>has not</emphasis> yet been - accepted by the Bugzilla team, and so you may need to do some - manual tweaking. That said, it looks like Net::LDAP is probably - the way to go in the future. - </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> - - <para> - <programlisting> -bash# perl -pi -e "s/Content-Type\: text\/html/Content-Type\: text\/html\; charset=ISO-8859-1/i" *.cgi *.pl - </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>.</para> - - <note> - <para>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. See - <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=126266">bug - 126266</ulink> for more information including progress toward making - bugzilla charset aware by default. - </para> - </note> - </section> - - <section id="directoryindex" xreflabel="Modifying the Apache - DirectoryIndex parameter to use index.cgi"> - <title> - <filename>directoryindex</filename> for the Bugzilla default page. - </title> - - <para>You should modify the <DirectoryIndex> parameter for - the Apache virtual host running your Bugzilla installation to - allow <filename>index.cgi</filename> as the index page for a - directory, as well as the usual <filename>index.html</filename>, - <filename>index.htm</filename>, and so forth. </para> - </section> - - <section id="mod_perl" xreflabel="Bugzilla and mod_perl"> - <title> - Bugzilla and <filename>mod_perl</filename> - </title> - <para>Bugzilla is unsupported under mod_perl. Effort is underway - to make it work cleanly in a mod_perl environment, but it is - slow going. - </para> - </section> - - <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="os-specific"> - <title>OS Specific Installation Notes</title> - - <para>Many aspects of the Bugzilla installation can be affected by the - the operating system you choose to install it on. Sometimes it can be made - easier and others more difficult. This section will attempt to help you - understand both the difficulties of running on specific operating systems - and the utilities available to make it easier. - </para> - - <para>If you have anything to add or notes for an operating system not - covered, please file a bug in &bzg-bugs;. - </para> - - <section id="os-win32"> - <title>Microsoft Windows</title> - - <para>Making Bugzilla work on windows is still a very painful processes. - The Bugzilla Team is working to make it easier, but that goal is not - considered a top priority. If you wish to run Bugzilla, we still - recommend doing so on a Unix based system such as GNU/Linux. As of this - writing, all members of the Bugzilla team and all known large installations - run on Unix based systems. - </para> - - <para>If after hearing all that, you have enough pain tolerance to attempt - installing Bugzilla on Win32, here are some pointers. - <![%bz-devel;[ - Because this is a development version of the guide, these instructions - are subject to change without notice. In fact, the Bugzilla Team hopes - they do as we would like to have Bugzilla resonabally close to "out of - the box" compatibility by the 2.18 release. - ]]> - </para> - - <section id="win32-perl"> - <title>Win32 Perl</title> - - <para>Perl for Windows can be obtained from <ulink - url="http://www.activestate.com/">ActiveState</ulink>. You should be - able to find a compiled binary at <ulink - url="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/">http://aspn.activestate.com/ASPN/Downloads/ActivePerl/</ulink>. - </para> - </section> - - <section id="win32-perl-modules"> - <title>Perl Modules on Win32</title> - - <para>Bugzilla on Windows requires the same perl modules found in - <xref linkend="install-package-list"/>. The main difference is that - windows uses <command>ppm</command> instead of CPAN. - </para> - - <programlisting> -C:\perl> <command>ppm <module name></command> - </programlisting> - - <note> - <para>The above syntax should work for all modules with the exception - of Template Toolkit. The <ulink - url="http://tt2.org/download.html#win32">Template Toolkit website</ulink> - suggests using the instructions on <ulink - url="http://openinteract.sourceforge.net/">OpenInteract's website</ulink>. - </para> - </note> - - <tip> - <para>A complete list of modules that can be installed using ppm can - be found at <ulink url="http://www.activestate.com/PPMPackages/5.6plus">http://www.activestate.com/PPMPackages/5.6plus</ulink>. - </para> - </tip> - </section> - - <section id="win32-code-changes"> - <title>Code changes required to run on win32</title> - - <para>Unfortunately, Bugzilla still doesn't run "out of the box" on - Windows. There is work in progress to make this easier, but until that - happens code will have to be modified. This section is an attempt to - list the required changes. It is an attempt to be all inclusive, but - there may be other changes required. If you find something is missing, - please file a bug in &bzg-bugs;. - </para> - - <section id="win32-code-checksetup"> - <title>Changes to <filename>checksetup.pl</filename></title> - - <para>In <filename>checksetup.pl</filename>, the line reading:</para> - - <programlisting> -my $mysql_binaries = `which mysql`; - </programlisting> - <para>to</para> - <programlisting> -my $mysql_binaries = "D:\\mysql\\bin\\mysql"; - </programlisting> - - <para>And you'll also need to change:</para> - - <programlisting> -my $webservergid = getgrnam($my_webservergroup) - </programlisting> - <para>to</para> - <programlisting> -my $webservergid = '8' - </programlisting> - </section> - - </section> - - <section id="win32-http"> - <title>Serving the web pages</title> - - <para>As is the case on Unix based systems, any web server should be - able to handle Bugzilla; however, the Bugzilla Team still recommends - Apache whenever asked. No matter what web server you choose, be sure - to pay attention to the security notes in <xref linkend="security-access"/>. - More information on configuring specific web servers can be found in - <xref linkend="http"/>. - </para> - - <note> - <para>If using Apache on windows, you can set the <ulink - url="http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource">ScriptInterpreterSource</ulink> - directive in your Apache config, if you don't do this, you'll have - to modify the first line of every script to contain your path to - perl instead of <filename>/usr/bin/perl</filename>. - </para> - </note> - - </section> - - </section> - - <section id="os-macosx"> - <title><productname>Mac OS X</productname></title> - - <!-- TODO: Clean me up... (Mac OS X) --> - <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 - <ulink url="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> - - <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="os-mandrake"> - <title>Linux-Mandrake 8.0</title> - - <para>Linux-Mandrake 8.0 includes every required and optional library - for Bugzilla. The easiest way to install them is by using the - <command>urpmi</command> utility. If you follow these commands, you - should have everything you need for Bugzilla, and - <command>./checksetup.pl</command> should not complain about any - missing libraries. You may already have some of these installed. - </para> - - <screen> -<prompt>bash#</prompt> <command>urpmi perl-mysql</command> -<prompt>bash#</prompt> <command>urpmi perl-chart</command> -<prompt>bash#</prompt> <command>urpmi perl-gd</command> -<prompt>bash#</prompt> <command>urpmi perl-MailTools</command> <co id="test-mailtools"/> -<prompt>bash#</prompt> <command>urpmi apache-modules</command> - </screen> - <calloutlist> - <callout arearefs="test-mailtools"> - <para>for Bugzilla e-mail integration</para> - </callout> - </calloutlist> - - </section> - - </section> - - <section id="http"> - <title>HTTP Server Configuration</title> - - <para>The Bugzilla Team recommends Apache when using Bugzilla, however, any web server - that can be configured to run <glossterm linkend="gloss-cgi">CGI</glossterm> scripts - should be able to handle Bugzilla. No matter what web server you choose, but - especially if you choose something other than Apache, you should be sure to read - <xref linkend="security-access"/>. - </para> - - <para>The plan for this section is to eventually document the specifics of how to lock - down permissions on individual web servers. - </para> - - <section id="http-apache"> - <title>Apache <productname>httpd</productname></title> - - <para>As mentioned above, the Bugzilla Team recommends Apache for use - with Bugzilla. You will have to make sure that Apache is properly - configured to run the Bugzilla CGI scripts. You also need to make sure - that the <filename>.htaccess</filename> files created by - <command>./checksetup.pl</command> (shown in <xref linkend="http-apache-htaccess"/> - for the curious) are allowed to override Apache's normal access - permissions or else important password information may be exposed to the - Internet. - </para> - - <para>Many Apache installations are not configured to run scripts - anywhere but in the <filename class="directory">cgi-bin</filename> - directory; however, we recommend that Bugzilla not be installed in the - <filename class="directory">cgi-bin</filename>, otherwise the static - files such as images and <xref linkend="gloss-javascript"/> - will not work correctly. To allow scripts to run in the normal - web space, the following changes should be made to your - <filename>httpd.conf</filename> file. - </para> - - <para>To allow files with a .cgi extension to be run, make sure the - following line exists and is uncommented:</para> - <programlisting> -AddHandler cgi-script .cgi - </programlisting> - - <para>To allow <filename>.htaccess</filename> files to override - permissions and .cgi files to run in the Bugzilla directory, make sure - the following two lines are in a <computeroutput>Directory</computeroutput> - directive that applies to the Bugzilla directory on your system - (either the Bugzilla directory or one of its parents). - </para> - <programlisting> -Options +ExecCGI -AllowOverride Limit - </programlisting> - - <note> - <para>For more information on Apache and its directives, see the - glossary entry on <xref linkend="gloss-apache"/>. - </para> - </note> - - <example id="http-apache-htaccess"> - <title><filename>.htaccess</filename> files for Apache</title> - - <para><filename>$BUGZILLA_HOME/.htaccess</filename> - <programlisting><![CDATA[ -# don't allow people to retrieve non-cgi executable files or our private data -<FilesMatch ^(.*\.pl|.*localconfig.*|runtests.sh)$> - deny from all -</FilesMatch> -<FilesMatch ^(localconfig.js|localconfig.rdf)$> - allow from all -</FilesMatch> - ]]></programlisting> - </para> - - <para><filename>$BUGZILLA_HOME/data/.htaccess</filename> - <programlisting><![CDATA[ -# nothing in this directory is retrievable unless overriden by an .htaccess -# in a subdirectory; the only exception is duplicates.rdf, which is used by -# duplicates.xul and must be loadable over the web -deny from all -<Files duplicates.rdf> - allow from all -</Files> - ]]></programlisting> - </para> - - <para><filename>$BUGZILLA_HOME/data/webdot</filename> - <programlisting><![CDATA[ -# Restrict access to .dot files to the public webdot server at research.att.com -# if research.att.com ever changed their IP, or if you use a different -# webdot server, you'll need to edit this -<FilesMatch ^[0-9]+\.dot$> - Allow from 192.20.225.10 - Deny from all -</FilesMatch> - -# Allow access by a local copy of 'dot' to .png, .gif, .jpg, and -# .map files -<FilesMatch ^[0-9]+\.(png|gif|jpg|map)$> - Allow from all -</FilesMatch> - -# And no directory listings, either. -Deny from all - ]]></programlisting> - </para> - - <para><filename>$BUGZILLA_HOME/Bugzilla/.htaccess</filename> - <programlisting> -# nothing in this directory is retrievable unless overriden by an .htaccess -# in a subdirectory -deny from all - </programlisting> - </para> - - <para><filename>$BUGZILLA_HOME/template/.htaccess</filename> - <programlisting> -# nothing in this directory is retrievable unless overriden by an .htaccess -# in a subdirectory -deny from all - </programlisting> - </para> - - </example> - - </section> - - <section id="http-iis"> - <title>Microsoft <productname>Internet Information Services</productname></title> - - <para>If you need, or for some reason even want, to use Microsoft's - <productname>Internet Information Services</productname> or - <productname>Personal Web Server</productname> you should be able - to. You will need to configure them to know how to run CGI scripts, - however. This is described in Microsoft Knowledge Base article - <ulink url="http://support.microsoft.com/support/kb/articles/Q245/2/25.asp">Q245225 </ulink> - for <productname>Internet Information Services</productname> and - <ulink url="http://support.microsoft.com/support/kb/articles/Q231/9/98.asp">Q231998</ulink> - for <productname>Personal Web Server</productname>. - </para> - - <para>Also, and this can't be stressed enough, make sure that files such as - <filename>localconfig</filename> and your <filename class="directory">data</filename> - directory are secured as described in <xref linkend="security-access"/>. - </para> - - </section> - - <section id="http-aol"> - <title>AOL Server</title> - - <para>Ben FrantzDale reported success using AOL Server with Bugzilla. He - reported his experience and what appears below is based on that. - </para> - - <para>AOL Server will have to be configured to run - <glossterm linkend="gloss-cgi">CGI</glossterm> scripts, please consult - the documentation that came with your server for more information on - how to do this. - </para> - - <para>Because AOL Server doesn't support <filename>.htaccess</filename> - files, you'll have to create a <glossterm linkend="gloss-tcl">TCL</glossterm> - script. You should create an <filename>aolserver/modules/tcl/filter.tcl</filename> - file (the filename shouldn't matter) with the following contents (change - <computeroutput>/bugzilla/</computeroutput> to the web-based path to - your Bugzilla installation): - </para> - - <programlisting> -ns_register_filter preauth GET /bugzilla/localconfig filter_deny -ns_register_filter preauth GET /bugzilla/localconfig~ filter_deny -ns_register_filter preauth GET /bugzilla/\#localconfig\# filter_deny -ns_register_filter preauth GET /bugzilla/*.pl filter_deny -ns_register_filter preauth GET /bugzilla/syncshadowdb filter_deny -ns_register_filter preauth GET /bugzilla/runtests.sh filter_deny -ns_register_filter preauth GET /bugzilla/data/* filter_deny -ns_register_filter preauth GET /bugzilla/template/* filter_deny - -proc filter_deny { why } { - ns_log Notice "filter_deny" - return "filter_return" -} - </programlisting> - - <warning> - <para>This probably doesn't account for all possible editor backup - files so you may wish to add some additional variations of - <filename>localconfig</filename>. For more information, see - <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=186383">bug - 186383</ulink> or <ulink - url="http://online.securityfocus.com/bid/6501">Bugtraq ID 6501</ulink>. - </para> - </warning> - - <note> - <para>If you are using webdot from research.att.com (the default - configuration for the <option>webdotbase</option> paramater), you - will need to allow access to <filename>data/webdot/*.dot</filename> - for the reasearch.att.com machine. - </para> - <para>If you are using a local installation of <ulink - url="http://www.graphviz.org">GraphViz</ulink>, you will need to allow - everybody to access <filename>*.png</filename>, - <filename>*.gif</filename>, <filename>*.jpg</filename>, and - <filename>*.map</filename> in the - <filename class="directory">data/webdot</filename> directory. - </para> - </note> - </section> - </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> - 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> - </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 id="trouble-filetemp"> - <title>Your vendor has not defined Fcntl macro O_NOINHERIT</title> - - <para>This is caused by a bug in the version of - <productname>File::Temp</productname> that is distributed with perl - 5.6.0. Many minor variations of this error have been reported. Examples - can be found in <xref linkend="trouble-filetemp-errors"/>. - </para> - - <figure id="trouble-filetemp-errors"> - <title>Other File::Temp error messages</title> - - <programlisting> -Your vendor has not defined Fcntl macro O_NOINHERIT, used -at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 208. - -Your vendor has not defined Fcntl macro O_EXLOCK, used -at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 210. - -Your vendor has not defined Fcntl macro O_TEMPORARY, used -at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 233. - </programlisting> - </figure> - - <para>Numerous people have reported that upgrading to version 5.6.1 - or higher solved the problem for them. A less involved fix is to apply - the patch in <xref linkend="trouble-filetemp-patch"/>. The patch is also - available as a <ulink url="../sgml/filetemp.patch">patch file</ulink>. - </para> - - <figure id="trouble-filetemp-patch"> - <title>Patch for File::Temp in Perl 5.6.0</title> - - <programlisting><![CDATA[ ---- File/Temp.pm.orig Thu Feb 6 16:26:00 2003 -+++ File/Temp.pm Thu Feb 6 16:26:23 2003 -@@ -205,6 +205,7 @@ - # eg CGI::Carp - local $SIG{__DIE__} = sub {}; - local $SIG{__WARN__} = sub {}; -+ local *CORE::GLOBAL::die = sub {}; - $bit = &$func(); - 1; - }; -@@ -226,6 +227,7 @@ - # eg CGI::Carp - local $SIG{__DIE__} = sub {}; - local $SIG{__WARN__} = sub {}; -+ local *CORE::GLOBAL::die = sub {}; - $bit = &$func(); - 1; - }; - ]]></programlisting> - </figure> - </section> - </section> -</chapter> - -<!-- Keep this comment at the end of the file -Local variables: -mode: sgml -sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t -sgml-indent-step:2 -sgml-local-catalogs:nil -sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t -End: ---> - |