summaryrefslogtreecommitdiffstats
path: root/docs/sgml/installation.sgml
diff options
context:
space:
mode:
authorjake%bugzilla.org <>2003-04-23 11:04:01 +0200
committerjake%bugzilla.org <>2003-04-23 11:04:01 +0200
commit78e29c8900fa96d67163a34a0c02c7cecb31b55f (patch)
treef4e97e5b99809faa9f3bc1c48f7a6adaefb6bbb7 /docs/sgml/installation.sgml
parent58ab63119c6de5dbdfa74d268196da734e5c5fc2 (diff)
downloadbugzilla-78e29c8900fa96d67163a34a0c02c7cecb31b55f.tar.gz
bugzilla-78e29c8900fa96d67163a34a0c02c7cecb31b55f.tar.xz
The source files for the Bugzilla Guide have long been using the XML version of DocBook but still residing in the sgml/ directory with an extension of .sgml.
In an effort to maintain CVS history, the raw files were copied on the CVS server to the xml/ directory and renamed to have .xml for the extension; any checkins before this one did have the .sgml extension.
Diffstat (limited to 'docs/sgml/installation.sgml')
-rw-r--r--docs/sgml/installation.sgml1615
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 "&lt;modulename&gt;"'</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 &lt;Directory&gt; 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&gt;</prompt>
-
- <command>UPDATE user SET Password=PASSWORD('&lt;new_password'&gt;)
- WHERE user='root';</command>
- </computeroutput>
- </member>
-
- <member>
- <computeroutput>
- <prompt>mysql&gt;</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 &lt;new_password&gt;. 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 &lt;bugs_password&gt; to some unique password.
- <simplelist>
- <member>
- <computeroutput>
- <prompt>mysql&gt;</prompt>
-
- <command>GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,
- ALTER,CREATE,DROP,REFERENCES ON bugs.* TO bugs@localhost
- IDENTIFIED BY '&lt;bugs_password&gt;';</command>
- </computeroutput>
- </member>
-
- <member>
- <computeroutput>
- <prompt>mysql&gt;</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; (&lt;bugs_password&gt;) 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&amp;T
- public webdot server (the
- default for the webdotbase param). Note that AT&amp;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 &lt;your-bugzilla-directory&gt; ;
- ./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 &lt;your-bugzilla-directory&gt; ;
- ./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 &lt;meta&gt; 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 &lt;DirectoryIndex&gt; 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&gt; <command>ppm &lt;module name&gt;</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&gt;</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 &lt; 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>&lt;path-to-perl&gt;/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:
--->
-