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