Skip to content

bugzilla
bugzilla
Commit 98be5699 authored by gerv%gerv.net's avatar gerv%gerv.net
Browse files
Options

Massive rearrangement of the installation section. Hopefully it makes sense now.

parent 2b00308f
Show whitespace changes
Inline Side-by-side
Showing with 1373 additions and 1394 deletions
docs/en/xml/Bugzilla-Guide.xml
View file @ 98be5699
...@@ -11,13 +11,11 @@ ...@@ -11,13 +11,11 @@
<!ENTITY administration SYSTEM "administration.xml"> <!ENTITY administration SYSTEM "administration.xml">
<!ENTITY using SYSTEM "using.xml"> <!ENTITY using SYSTEM "using.xml">
<!ENTITY integration SYSTEM "integration.xml"> <!ENTITY integration SYSTEM "integration.xml">
<!ENTITY future SYSTEM "future.xml">
<!ENTITY index SYSTEM "index.xml"> <!ENTITY index SYSTEM "index.xml">
<!ENTITY customization SYSTEM "customization.xml"> <!ENTITY customization SYSTEM "customization.xml">
<!ENTITY patches SYSTEM "patches.xml"> <!ENTITY patches SYSTEM "patches.xml">
<!ENTITY variants SYSTEM "variants.xml">
<!ENTITY introduction SYSTEM "introduction.xml"> <!ENTITY introduction SYSTEM "introduction.xml">
<!ENTITY revhistory SYSTEM "revhistory.xml"> <!ENTITY modules SYSTEM "modules.xml">
<!-- Things to change for a stable release: <!-- Things to change for a stable release:
* bz-ver to current stable * bz-ver to current stable
...@@ -32,9 +30,9 @@ ...@@ -32,9 +30,9 @@
For a devel release, simple bump bz-ver and bz-date For a devel release, simple bump bz-ver and bz-date
--> -->
<!ENTITY bz-ver "2.17.5"> <!ENTITY bz-ver "2.17.7">
<!ENTITY bz-nextver "2.18"> <!ENTITY bz-nextver "2.18">
<!ENTITY bz-date "2004-01-15"> <!ENTITY bz-date "2004-01-24">
<!ENTITY % bz-devel "INCLUDE"> <!ENTITY % bz-devel "INCLUDE">
<!ENTITY bz "http://www.bugzilla.org/"> <!ENTITY bz "http://www.bugzilla.org/">
...@@ -54,7 +52,7 @@ ...@@ -54,7 +52,7 @@
<!ENTITY min-dbd-mysql-ver "2.1010"> <!ENTITY min-dbd-mysql-ver "2.1010">
<!ENTITY min-dbi-ver "1.32"> <!ENTITY min-dbi-ver "1.32">
<!ENTITY min-date-format-ver "2.21"> <!ENTITY min-date-format-ver "2.21">
<!ENTITY min-cgi-ver "2.88"> <!ENTITY min-cgi-ver "2.93">
<!-- Optional modules --> <!-- Optional modules -->
<!ENTITY min-gd-ver "1.20"> <!ENTITY min-gd-ver "1.20">
<!ENTITY min-gd-graph-ver "any"> <!ENTITY min-gd-graph-ver "any">
...@@ -136,12 +134,6 @@ ...@@ -136,12 +134,6 @@
<!-- About This Guide --> <!-- About This Guide -->
&about; &about;
<!-- Introduction -->
&introduction;
<!-- Using Bugzilla -->
&using;
<!-- Installing Bugzilla --> <!-- Installing Bugzilla -->
&installation; &installation;
...@@ -151,12 +143,18 @@ ...@@ -151,12 +143,18 @@
<!-- Customizing Bugzilla --> <!-- Customizing Bugzilla -->
&customization; &customization;
<!-- Using Bugzilla -->
&using;
<!-- Appendix: The Frequently Asked Questions --> <!-- Appendix: The Frequently Asked Questions -->
&faq; &faq;
<!-- Appendix: Custom Patches --> <!-- Appendix: Custom Patches -->
&patches; &patches;
<!-- Appendix: Manually Installing Perl Modules -->
&modules;
<!-- Appendix: GNU Free Documentation License --> <!-- Appendix: GNU Free Documentation License -->
&gfdl; &gfdl;
......
docs/en/xml/about.xml
View file @ 98be5699
...@@ -6,8 +6,11 @@ ...@@ -6,8 +6,11 @@
<section id="copyright"> <section id="copyright">
<title>Copyright Information</title> <title>Copyright Information</title>
<para>This document is copyright (c) 2000-2004 by the various
Bugzilla contributors who wrote it.</para>
<blockquote> <blockquote>
<attribution>Copyright (c) 2000-2004 The Bugzilla Team</attribution>
<para> <para>
Permission is granted to copy, distribute and/or modify this Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation document under the terms of the GNU Free Documentation
...@@ -45,10 +48,10 @@ ...@@ -45,10 +48,10 @@
</para> </para>
<para> <para>
Although the Bugzilla development team has taken great care to Although the Bugzilla development team has taken great care to
ensure that all exploitable bugs or options have been ensure that all exploitable bugs have been fixed, security holes surely
fixed, security holes surely exist. Great care should be taken both in exist in any piece of code. Great care should be taken both in
the installation and usage of this software. The Bugzilla development the installation and usage of this software. The Bugzilla development
team members assume no liability for your use of this software. You have team members assume no liability for your use of Bugzilla. You have
the source code, and are responsible for auditing it yourself to ensure the source code, and are responsible for auditing it yourself to ensure
your security needs are met. your security needs are met.
</para> </para>
...@@ -68,16 +71,36 @@ ...@@ -68,16 +71,36 @@
</para> </para>
<para> <para>
The latest version of this guide can always be found at <ulink The latest version of this guide can always be found at <ulink
url="http://www.bugzilla.org"/>, or checked out via CVS. url="http://www.bugzilla.org"/>, or checked out via CVS by
(Please follow the <ulink url="http://www.mozilla.org/cvs.html">Mozilla following the <ulink url="http://www.mozilla.org/cvs.html">Mozilla
CVS</ulink> instructions and check out the CVS</ulink> instructions and check out the
<filename>mozilla/webtools/bugzilla/docs/</filename> <filename>mozilla/webtools/bugzilla/docs/</filename>
subtree.) However, you should read the version subtree. However, you should read the version
which came with the Bugzilla release you are using. which came with the Bugzilla release you are using.
</para> </para>
<para> <para>
The Bugzilla Guide is currently only available in English. The Bugzilla Guide, or a section of it, is also available in
If you would like to volunteer to translate it, please contact the following languages:
<ulink url="http://bugzilla-de.sourceforge.net/docs/html/">German</ulink>.
</para>
<para>
In addition, there are Bugzilla template localisation projects in
the following languages. They may have translated documentation
available:
<ulink url="http://sourceforge.net/projects/bugzilla-be/">Belarusian</ulink>,
<ulink url="http://sourceforge.net/projects/bugzilla-br/">Brazilian Portuguese</ulink>,
<ulink url="http://sourceforge.net/projects/bugzilla-cn/">Chinese</ulink>,
<ulink url="http://sourceforge.net/projects/bugzilla-fr/">French</ulink>,
<ulink url="http://sourceforge.net/projects/bugzilla-de/">German</ulink>,
<ulink url="http://sourceforge.net/projects/bugzilla-kr/">Korean</ulink>,
<ulink url="http://sourceforge.net/projects/bugzilla-ru/">Russian</ulink> and
<ulink url="http://sourceforge.net/projects/bugzilla-es/">Spanish</ulink>.
</para>
<para>
If you would like to volunteer to translate the Guide into additional
languages, please contact
<ulink url="mailto:justdave@syndicomm.com">Dave Miller</ulink>. <ulink url="mailto:justdave@syndicomm.com">Dave Miller</ulink>.
</para> </para>
</section> </section>
...@@ -113,7 +136,7 @@ ...@@ -113,7 +136,7 @@
</para> </para>
<para> <para>
Last but not least, all the members of the Also, thanks are due to the members of the
<ulink url="news://news.mozilla.org/netscape.public.mozilla.webtools"> <ulink url="news://news.mozilla.org/netscape.public.mozilla.webtools">
netscape.public.mozilla.webtools</ulink> netscape.public.mozilla.webtools</ulink>
newsgroup. Without your discussions, insight, suggestions, and patches, newsgroup. Without your discussions, insight, suggestions, and patches,
......
docs/en/xml/customization.xml
View file @ 98be5699
<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> <!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
<chapter id="customization"> <chapter id="customization">
<title>Customizing Bugzilla</title> <title>Customising Bugzilla</title>
<section id="cust-skins">
<title>Custom Skins</title>
<para>
Bugzilla allows you to have multiple skins. These are custom CSS and possibly
also custom images for Bugzilla. To create a new custom skin, you have two
choices:
<itemizedlist>
<listitem>
<para>
Make a single CSS file, and put it in the
<filename>skins/contrib</filename> directory.
</para>
</listitem>
<listitem>
<para>
Make a directory that contains all the same CSS file
names as <filename>skins/standard/</filename>, and put
your directory in <filename>skins/contrib/</filename>.
</para>
</listitem>
</itemizedlist>
</para>
<para>
After you put the file or the directory there, make sure to run checksetup.pl
so that it can reset the file permissions correctly.
</para>
<para>
After you have installed the new skin, it will show up as an option in the
user's General Preferences. If you would like to force a particular skin on all
users, just select it in the Default Preferences and then uncheck "Enabled" on
the preference.
</para>
</section>
<section id="cust-templates"> <section id="cust-templates">
<title>Template Customization</title> <title>Template Customization</title>
...@@ -54,78 +18,45 @@ ...@@ -54,78 +18,45 @@
<xref linkend="template-http-accept"/>. <xref linkend="template-http-accept"/>.
</para> </para>
<section id="template-directory"> <section>
<title>Template Directory Structure</title> <title>What to Edit</title>
<para> <para>
The template directory structure starts with top level directory The template directory structure is that there's a top level directory,
named <filename>template</filename>, which contains a directory <filename>template</filename>, which contains a directory for
for each installed localization. The next level defines the each installed localization. The default English templates are
language used in the templates. Bugzilla comes with English therefore in <filename>en</filename>. Underneath that, there
templates, so the directory name is <filename>en</filename>, is the <filename>default</filename> directory and optionally the
and we will discuss <filename>template/en</filename> throughout <filename>custom</filename> directory. The <filename>default</filename>
the documentation. Below <filename>template/en</filename> is the directory contains all the templates shipped with Bugzilla, whereas
<filename>default</filename> directory, which contains all the the <filename>custom</filename> directory does not exist at first and
standard templates shipped with Bugzilla. must be created if you want to use it.
</para>
<warning>
<para>
A directory <filename>data/templates</filename> also exists;
this is where Template Toolkit puts the compiled versions of
the templates from either the default or custom directories.
<emphasis>Do not</emphasis> directly edit the files in this
directory, or all your changes will be lost the next time
Template Toolkit recompiles the templates.
</para>
</warning>
</section>
<section id="template-method">
<title>Choosing a Customization Method</title>
<para>
If you want to edit Bugzilla's templates, the first decision
you must make is how you want to go about doing so. There are two
choices, and which you use depends mainly on the scope of your
modifications, and the method you plan to use to upgrade Bugzilla.
</para> </para>
<para> <para>
There are two different ways of editing Bugzilla's templates,
and which you use depends mainly on the method you plan to use to
upgrade Bugzilla.
The first method of making customizations is to directly edit the The first method of making customizations is to directly edit the
templates found in <filename>template/en/default</filename>. templates in <filename>template/en/default</filename>. This is
This is probably the best way to go about it if you are going to probably the best method for small changes if you are going to use
be upgrading Bugzilla through CVS, because if you then execute the CVS method of upgrading, because if you then execute a
a <command>cvs update</command>, any changes you have made will <command>cvs update</command>, any template fixes will get
be merged automagically with the updated versions. automagically merged into your modified versions.
</para> </para>
<note>
<para> <para>
If you use this method, and CVS conflicts occur during an If you use this method, your installation will break if CVS conflicts
update, the conflicted templates (and possibly other parts occur.
of your installation) will not work until they are resolved.
</para> </para>
</note>
<para>
The second method is to copy the templates to be modified
into a mirrored directory structure under
<filename>template/en/custom</filename>. Templates in this
directory structure automatically override any identically-named
and identically-located templates in the
<filename>default</filename> directory.
</para>
<note>
<para>
The <filename>custom</filename> directory does not exist
at first and must be created if you want to use it.
</para>
</note>
<para> <para>
The second method of customization should be used if you The other method is to copy the templates to be modified into a
use the overwriting method of upgrade, because otherwise mirrored directory
your changes will be lost. This method may also be better if structure under <filename>template/en/custom</filename>. The templates
in this directory automatically override those in default.
This is the technique you
need to use if you use the overwriting method of upgrade, because
otherwise your changes will be lost. This method is also better if
you are using the CVS method of upgrading and are going to make major you are using the CVS method of upgrading and are going to make major
changes, because it is guaranteed that the contents of this directory changes, because it is guaranteed that the contents of this directory
will not be touched during an upgrade, and you can then decide whether will not be touched during an upgrade, and you can then decide whether
...@@ -134,9 +65,9 @@ ...@@ -134,9 +65,9 @@
</para> </para>
<para> <para>
Using this method, your installation may break if incompatible If you use this method, your installation may break if incompatible
changes are made to the template interface. Such changes should changes are made to the template interface. If such changes are made
be documented in the release notes, provided you are using a they will be documented in the release notes, provided you are using a
stable release of Bugzilla. If you use using unstable code, you will stable release of Bugzilla. If you use using unstable code, you will
need to deal with this one yourself, although if possible the changes need to deal with this one yourself, although if possible the changes
will be mentioned before they occur in the deprecations section of the will be mentioned before they occur in the deprecations section of the
...@@ -145,25 +76,21 @@ ...@@ -145,25 +76,21 @@
<note> <note>
<para> <para>
Regardless of which method you choose, it is recommended that Don't directly edit the compiled templates in
you run <command>./checksetup.pl</command> after creating or <filename class="directory">data/template/*</filename> - your
editing any templates in the <filename>template/en/default</filename> changes will be lost when Template Toolkit recompiles them.
directory, and after editing any templates in the
<filename>custom</filename> directory.
</para> </para>
</note> </note>
<warning> <note>
<para> <para>It is recommended that you run <command>./checksetup.pl</command>
It is <emphasis>required</emphasis> that you run after any template edits, especially if you've created a new file in
<command>./checksetup.pl</command> after creating a new the <filename class="directory">custom</filename> directory.
template in the <filename>custom</filename> directory. Failure
to do so will raise an incomprehensible error message.
</para> </para>
</warning> </note>
</section> </section>
<section id="template-edit"> <section>
<title>How To Edit Templates</title> <title>How To Edit Templates</title>
<note> <note>
...@@ -171,7 +98,7 @@ ...@@ -171,7 +98,7 @@
If you are making template changes that you intend on submitting back If you are making template changes that you intend on submitting back
for inclusion in standard Bugzilla, you should read the relevant for inclusion in standard Bugzilla, you should read the relevant
sections of the sections of the
<ulink url="http://www.bugzilla.org/docs/developer.html">Developers' <ulink url="http://www.bugzilla.org/developerguide.html">Developers'
Guide</ulink>. Guide</ulink>.
</para> </para>
</note> </note>
...@@ -189,7 +116,7 @@ ...@@ -189,7 +116,7 @@
to properly HTML filter data that has been passed into the template. to properly HTML filter data that has been passed into the template.
This means that if the data can possibly contain special HTML characters This means that if the data can possibly contain special HTML characters
such as &lt;, and the data was not intended to be HTML, they need to be such as &lt;, and the data was not intended to be HTML, they need to be
converted to entity form, i.e. &amp;lt;. You use the 'html' filter in the converted to entity form, ie &amp;lt;. You use the 'html' filter in the
Template Toolkit to do this. If you forget, you may open up Template Toolkit to do this. If you forget, you may open up
your installation to cross-site scripting attacks. your installation to cross-site scripting attacks.
</para> </para>
...@@ -198,18 +125,16 @@ ...@@ -198,18 +125,16 @@
Also note that Bugzilla adds a few filters of its own, that are not Also note that Bugzilla adds a few filters of its own, that are not
in standard Template Toolkit. In particular, the 'url_quote' filter in standard Template Toolkit. In particular, the 'url_quote' filter
can convert characters that are illegal or have special meaning in URLs, can convert characters that are illegal or have special meaning in URLs,
such as &amp;, to the encoded form, i.e. %26. This actually encodes most such as &amp;, to the encoded form, ie %26. This actually encodes most
characters (but not the common ones such as letters and numbers and so characters (but not the common ones such as letters and numbers and so
on), including the HTML-special characters, so there's never a need to on), including the HTML-special characters, so there's never a need to
HTML filter afterwards. HTML filter afterwards.
</para> </para>
<para> <para>
Editing templates is a good way of doing a <quote>poor man's custom Editing templates is a good way of doing a "poor man's custom fields".
fields</quote>.
For example, if you don't use the Status Whiteboard, but want to have For example, if you don't use the Status Whiteboard, but want to have
a free-form text entry box for <quote>Build Identifier</quote>, a free-form text entry box for "Build Identifier", then you can just
then you can just
edit the templates to change the field labels. It's still be called edit the templates to change the field labels. It's still be called
status_whiteboard internally, but your users don't need to know that. status_whiteboard internally, but your users don't need to know that.
</para> </para>
...@@ -217,29 +142,22 @@ ...@@ -217,29 +142,22 @@
</section> </section>
<section id="template-formats"> <section>
<title>Template Formats and Types</title> <title>Template Formats</title>
<para> <para>
Some CGI's have the ability to use more than one template. For example, Some CGIs have the ability to use more than one template. For
<filename>buglist.cgi</filename> can output itself as RDF, or as two example, buglist.cgi can output bug lists as RDF or two
formats of HTML (complex and simple). The mechanism that provides this different forms of HTML (complex and simple). (Try this out
feature is extensible. by appending <filename>&amp;format=simple</filename> to a buglist.cgi
URL on your Bugzilla installation.) This
mechanism, called template 'formats', is extensible.
</para> </para>
<para> <para>
Bugzilla can support different types of output, which again can have To see if a CGI supports multiple output formats, grep the
multiple formats. In order to request a certain type, you can append CGI for "GetFormat". If it's not present, adding
the &amp;ctype=&lt;contenttype&gt; (such as rdf or html) to the multiple format support isn't too hard - see how it's done in
<filename>&lt;cginame&gt;.cgi</filename> URL. If you would like to
retrieve a certain format, you can use the &amp;format=&lt;format&gt;
(such as simple or complex) in the URL.
</para>
<para>
To see if a CGI supports multiple output formats and types, grep the
CGI for <quote>get_format</quote>. If it's not present, adding
multiple format/type support isn't too hard - see how it's done in
other CGIs, e.g. config.cgi. other CGIs, e.g. config.cgi.
</para> </para>
...@@ -258,32 +176,22 @@ ...@@ -258,32 +176,22 @@
<para> <para>
You now need to decide what content type you want your template You now need to decide what content type you want your template
served as. The content types are defined in the served as. Open up the <filename>localconfig</filename> file and find the
<filename>Bugzilla/Constants.pm</filename> file in the <filename>$contenttypes</filename>
<filename>contenttypes</filename> variable. If your content type is not there, add it. Remember
constant. If your content type is not there, add it. Remember the three- or four-letter tag assigned to you content type.
the three- or four-letter tag assigned to your content type.
This tag will be part of the template filename. This tag will be part of the template filename.
</para> </para>
<note>
<para>
After adding or changing a content type, it's suitable to edit
<filename>Bugzilla/Constants.pm</filename> in order to reflect
the changes. Also, the file should be kept up to date after an
upgrade if content types have been customized in the past.
</para>
</note>
<para> <para>
Save the template as <filename>&lt;stubname&gt;-&lt;formatname&gt;.&lt;contenttypetag&gt;.tmpl</filename>. Save the template as <filename>&lt;stubname&gt;-&lt;formatname&gt;.&lt;contenttypetag&gt;.tmpl</filename>.
Try out the template by calling the CGI as Try out the template by calling the CGI as
<filename>&lt;cginame&gt;.cgi?format=&lt;formatname&gt;&amp;ctype=&lt;type&gt;</filename> . <filename>&lt;cginame&gt;.cgi?format=&lt;formatname&gt;</filename> .
</para> </para>
</section> </section>
<section id="template-specific"> <section>
<title>Particular Templates</title> <title>Particular Templates</title>
<para> <para>
...@@ -307,8 +215,7 @@ ...@@ -307,8 +215,7 @@
<para> <para>
<command>global/banner.html.tmpl</command>: <command>global/banner.html.tmpl</command>:
This contains the <quote>banner</quote>, the part of the header This contains the "banner", the part of the header that appears
that appears
at the top of all Bugzilla pages. The default banner is reasonably at the top of all Bugzilla pages. The default banner is reasonably
barren, so you'll probably want to customize this to give your barren, so you'll probably want to customize this to give your
installation a distinctive look and feel. It is recommended you installation a distinctive look and feel. It is recommended you
...@@ -324,26 +231,6 @@ ...@@ -324,26 +231,6 @@
</para> </para>
<para> <para>
<command>global/variables.none.tmpl</command>:
This defines a list of terms that may be changed in order to
<quote>brand</quote> the Bugzilla instance In this way, terms
like <quote>bugs</quote> can be replaced with <quote>issues</quote>
across the whole Bugzilla installation. The name
<quote>Bugzilla</quote> and other words can be customized as well.
</para>
<para>
<command>list/table.html.tmpl</command>:
This template controls the appearance of the bug lists created
by Bugzilla. Editing this template allows per-column control of
the width and title of a column, the maximum display length of
each entry, and the wrap behaviour of long entries.
For long bug lists, Bugzilla inserts a 'break' every 100 bugs by
default; this behaviour is also controlled by this template, and
that value can be modified here.
</para>
<para>
<command>bug/create/user-message.html.tmpl</command>: <command>bug/create/user-message.html.tmpl</command>:
This is a message that appears near the top of the bug reporting page. This is a message that appears near the top of the bug reporting page.
By modifying this, you can tell your users how they should report By modifying this, you can tell your users how they should report
...@@ -351,75 +238,47 @@ ...@@ -351,75 +238,47 @@
</para> </para>
<para> <para>
<command>bug/process/midair.html.tmpl</command>:
This is the page used if two people submit simultaneous changes to the
same bug. The second person to submit their changes will get this page
to tell them what the first person did, and ask if they wish to
overwrite those changes or go back and revisit the bug. The default
title and header on this page read "Mid-air collision detected!" If
you work in the aviation industry, or other environment where this
might be found offensive (yes, we have true stories of this happening)
you'll want to change this to something more appropriate for your
environment.
</para>
<para>
<command>bug/create/create.html.tmpl</command> and <command>bug/create/create.html.tmpl</command> and
<command>bug/create/comment.txt.tmpl</command>: <command>bug/create/comment.txt.tmpl</command>:
You may not wish to go to the effort of creating custom fields in You may wish to get bug submitters to give certain bits of structured
Bugzilla, yet you want to make sure that each bug report contains information, each in a separate input widget, for which there is not a
a number of pieces of important information for which there is not field in the database. The bug entry system has been designed in an
a special field. The bug entry system has been designed in an extensible fashion to enable you to define arbitrary fields and widgets,
extensible fashion to enable you to add arbitrary HTML widgets, and have their values appear formatted in the initial
such as drop-down lists or textboxes, to the bug entry page Description, rather than in database fields. An example of this
and have their values appear formatted in the initial comment. is the mozilla.org
A hidden field that indicates the format should be added inside <ulink url="http://bugzilla.mozilla.org/enter_bug.cgi?format=guided">guided
the form in order to make the template functional. Its value should bug submission form</ulink>.
be the suffix of the template filename. For example, if the file </para>
is called <filename>create-cust.html.tmpl</filename>, then
<programlisting>&lt;input type="hidden" name="format" value="cust"&gt;</programlisting> <para>
should be used inside the form. To make this work, create a custom template for
</para> <filename>enter_bug.cgi</filename> (the default template, on which you
could base it, is <filename>create.html.tmpl</filename>),
<para> and either call it <filename>create.html.tmpl</filename> or use a format and
An example of this is the mozilla.org call it <filename>create-&lt;formatname&gt;.html.tmpl</filename>.
<ulink url="http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl&amp;format=guided">guided Put it in the <filename class="directory">custom/bug/create</filename>
bug submission form</ulink>. The code for this comes with the Bugzilla directory. In it, add widgets for each piece of information you'd like
distribution as an example for you to copy. It can be found in the
files
<filename>create-guided.html.tmpl</filename> and
<filename>comment-guided.html.tmpl</filename>.
</para>
<para>
So to use this feature, create a custom template for
<filename>enter_bug.cgi</filename>. The default template, on which you
could base it, is
<filename>custom/bug/create/create.html.tmpl</filename>.
Call it <filename>create-&lt;formatname&gt;.html.tmpl</filename>, and
in it, add widgets for each piece of information you'd like
collected - such as a build number, or set of steps to reproduce. collected - such as a build number, or set of steps to reproduce.
</para> </para>
<para> <para>
Then, create a template like Then, create a template like
<filename>custom/bug/create/comment.txt.tmpl</filename>, and call it <filename>custom/bug/create/comment.txt.tmpl</filename>, also named
<filename>comment-&lt;formatname&gt;.txt.tmpl</filename>. This after your format if you are using one, which
template should reference the form fields you have created using references the form fields you have created. When a bug report is
the syntax <filename>[% form.&lt;fieldname&gt; %]</filename>. When a
bug report is
submitted, the initial comment attached to the bug report will be submitted, the initial comment attached to the bug report will be
formatted according to the layout of this template. formatted according to the layout of this template.
</para> </para>
<para> <para>
For example, if your custom enter_bug template had a field For example, if your enter_bug template had a field
<programlisting>&lt;input type="text" name="buildid" size="30"&gt;</programlisting> <programlisting>&lt;input type="text" name="buildid" size="30"&gt;</programlisting>
and then your comment.txt.tmpl had and then your comment.txt.tmpl had
<programlisting>BuildID: [% form.buildid %]</programlisting> <programlisting>BuildID: [% form.buildid %]</programlisting>
then something like then
<programlisting>BuildID: 20020303</programlisting> <programlisting>BuildID: 20020303</programlisting>
would appear in the initial comment. would appear in the initial checkin comment.
</para> </para>
</section> </section>
...@@ -434,99 +293,78 @@ ...@@ -434,99 +293,78 @@
url="http://www.bugzilla.org/download.html#localizations"/>. Instructions url="http://www.bugzilla.org/download.html#localizations"/>. Instructions
for submitting new languages are also available from that location. for submitting new languages are also available from that location.
</para> </para>
<para>After untarring the localizations (or creating your own) in the
<filename class="directory">BUGZILLA_ROOT/template</filename> directory,
you must update the <option>languages</option> parameter to contain any
localizations you'd like to permit. You may also wish to set the
<option>defaultlanguage</option> parameter to something other than
<quote>en</quote> if you don't want Engish to be the default language.
</para>
</section> </section>
</section> </section>
<section id="cust-hooks"> <section id="cust-hooks">
<title>The Bugzilla Extension Mechanism</title> <title>Template Hooks</title>
<warning>
<para>
Custom extensions require Template Toolkit version 2.12 or
above, or the application of a patch. See <ulink
url="http://bugzilla.mozilla.org/show_bug.cgi?id=239112">bug
239112</ulink> for details.
</para>
</warning>
<para> <para>
Extensions are a way for extensions to Bugzilla to insert code Template hooks are a way for extensions to Bugzilla to insert code
into the standard Bugzilla templates and source files into the standard Bugzilla templates without modifying the template files
without modifying these files themselves. The extension mechanism themselves. The hooks mechanism defines a consistent API for extending
defines a consistent API for extending the standard templates and source files the standard templates in a way that cleanly separates standard code
in a way that cleanly separates standard code from extension code. from extension code. Hooks reduce merge conflicts and make it easier
Hooks reduce merge conflicts and make it easier to write extensions that work to write extensions that work across multiple versions of Bugzilla,
across multiple versions of Bugzilla, making upgrading a Bugzilla installation making upgrading a Bugzilla installation with installed extensions easier.
with installed extensions easier. Furthermore, they make it easy to install
and remove extensions as each extension is nothing more than a
simple directory structure.
</para> </para>
<para> <para>
There are two main types of hooks: code hooks and template hooks. Code A template hook is just a named place in a standard template file
hooks allow extensions to invoke code at specific points in various where extension template files for that hook get processed. Each hook
source files, while template hooks allow extensions to add elements to has a corresponding directory in the Bugzilla directory tree. Hooking an
the Bugzilla user interface. extension template to a hook is as simple as putting the extension file
into the hook's directory. When Bugzilla processes the standard template
and reaches the hook, it will process all extension templates in the
hook's directory. The hooks themselves can be added into any standard
template upon request by extension authors.
</para> </para>
<para> <para>
A hook is just a named place in a standard source or template file To use hooks to extend a Bugzilla template, first make sure there is
where extension source code or template files for that hook get processed. a hook at the appropriate place within the template you want to extend.
Each extension has a corresponding directory in the Bugzilla directory Hooks appear in the standard Bugzilla templates as a single directive
tree (<filename>BUGZILLA_ROOT/extensions/extension_name</filename>). Hooking in the format
an extension source file or template to a hook is as simple as putting <literal role="code">[% Hook.process("<varname>name</varname>") %]</literal>,
the extension file into extension's template or code directory. where <varname>name</varname> is the unique (within that template)
When Bugzilla processes the source file or template and reaches the hook, name of the hook.
it will process all extension files in the hook's directory.
The hooks themselves can be added into any source file or standard template
upon request by extension authors.
</para>
<para>
To use hooks to extend Bugzilla, first make sure there is
a hook at the appropriate place within the source file or template you
want to extend. The exact appearance of a hook depends on if the hook
is a code hook or a template hook.
</para>
<para>
Code hooks appear in Bugzilla source files as a single method call
in the format <literal role="code">Bugzilla::Hook->process("<varname>name</varname>");</literal>.
For instance, <filename>enter_bug.cgi</filename> may invoke the hook
"<varname>enter_bug-entrydefaultvars</varname>". Thus, a source file at
<filename>BUGZILLA_ROOT/extensions/EXTENSION_NAME/code/enter_bug-entrydefaultvars.pl</filename>
will be automatically invoked when the code hook is reached.
</para> </para>
<para> <para>
Template hooks appear in the standard Bugzilla templates as a If you aren't sure which template you want to extend or just want
single directive in the format to browse the available hooks, either use your favorite multi-file search
<literal role="code">[% Hook.process("<varname>name</varname>") %]</literal>, tool (e.g. <command>grep</command>) to search the standard templates
where <varname>name</varname> is the unique name of the hook. for occurrences of <methodname>Hook.process</methodname> or browse
the directory tree in
<filename>BUGZILLA_ROOT/template/en/extension/hook/</filename>,
which contains a directory for each hook in the following location:
</para> </para>
<para> <para>
If you aren't sure what you want to extend or just want to browse the <filename>BUGZILLA_ROOT/template/en/extension/hook/PATH_TO_STANDARD_TEMPLATE/STANDARD_TEMPLATE_NAME/HOOK_NAME/</filename>
available hooks, either use your favorite multi-file search
tool (e.g. <command>grep</command>) to search the standard templates
for occurrences of <methodname>Hook.process</methodname> or the source
files for occurrences of <methodname>Bugzilla::Hook::process</methodname>.
</para> </para>
<para> <para>
If there is no hook at the appropriate place within the Bugzilla If there is no hook at the appropriate place within the Bugzilla template
source file or template you want to extend, you want to extend,
<ulink url="http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&amp;component=User%20Interface">file <ulink url="http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&amp;component=User%20Interface">file
a bug requesting one</ulink>, specifying: a bug requesting one</ulink>, specifying:
</para> </para>
<simplelist> <simplelist>
<member>the source or template file for which you are <member>the template for which you are requesting a hook;</member>
requesting a hook;</member>
<member> <member>
where in the file you would like the hook to be placed where in the template you would like the hook to be placed
(line number/position for latest version of the file in CVS (line number/position for latest version of template in CVS
or description of location); or description of location);
</member> </member>
<member>the purpose of the hook;</member> <member>the purpose of the hook;</member>
...@@ -535,8 +373,9 @@ ...@@ -535,8 +373,9 @@
<para> <para>
The Bugzilla reviewers will promptly review each hook request, The Bugzilla reviewers will promptly review each hook request,
name the hook, add it to the template or source file, and check name the hook, add it to the template, check the new version
the new version of the template into CVS. of the template into CVS, and create the corresponding directory in
<filename>BUGZILLA_ROOT/template/en/extension/hook/</filename>.
</para> </para>
<para> <para>
...@@ -552,13 +391,13 @@ ...@@ -552,13 +391,13 @@
<para> <para>
After making sure the hook you need exists (or getting it added if not), After making sure the hook you need exists (or getting it added if not),
add your extension to the directory within the Bugzilla add your extension template to the directory within the Bugzilla
extensions tree corresponding to the hook. directory tree corresponding to the hook.
</para> </para>
<para> <para>
That's it! Now, when the source file or template containing the hook That's it! Now, when the standard template containing the hook
is processed, your extension file will be processed at the point is processed, your extension template will be processed at the point
where the hook appears. where the hook appears.
</para> </para>
...@@ -589,9 +428,14 @@ ...@@ -589,9 +428,14 @@
...]]></programlisting> ...]]></programlisting>
<para> <para>
The corresponding extension file for this hook is The corresponding directory for this hook is
<filename>BUGZILLA_ROOT/extensions/projman/template/en/hook/global/useful-links-edit.html.tmpl</filename>. <filename>BUGZILLA_ROOT/template/en/extension/hook/global/useful-links.html.tmpl/edit/</filename>.
You then create that template file and add the following constant: </para>
<para>
You put a template named
<filename>projman-edit-projects.html.tmpl</filename>
into that directory with the following content:
</para> </para>
<programlisting><![CDATA[...[% ', <a href="edit-projects.cgi">projects</a>' IF user.groups.projman_admins %]]]></programlisting> <programlisting><![CDATA[...[% ', <a href="edit-projects.cgi">projects</a>' IF user.groups.projman_admins %]]]></programlisting>
...@@ -602,74 +446,67 @@ ...@@ -602,74 +446,67 @@
</para> </para>
<para> <para>
Now, let us say your extension adds a custom "project_manager" field Notes:
to enter_bug.cgi. You want to modify the CGI script to set the default
project manager to be productname@company.com. Looking at
<filename>enter_bug.cgi</filename>, you see the enter_bug-entrydefaultvars
hook near the bottom of the file before the default form values are set.
The corresponding extension source file for this hook is located at
<filename>BUGZILLA_ROOT/extensions/projman/code/enter_bug-entrydefaultvars.pl</filename>.
You then create that file and add the following:
</para>
<programlisting>$default{'project_manager'} = $product.'@company.com';</programlisting>
<para>
This code will be invoked whenever enter_bug.cgi is executed.
Assuming that the rest of the customization was completed (e.g. the
custom field was added to the enter_bug template and the required hooks
were used in process_bug.cgi), the new field will now have this
default value.
</para> </para>
<itemizedlist>
<listitem>
<para> <para>
Notes: You may want to prefix your extension template names
with the name of your extension, e.g.
<filename>projman-foo.html.tmpl</filename>,
so they do not conflict with the names of templates installed by
other extensions.
</para> </para>
</listitem>
<itemizedlist>
<listitem> <listitem>
<para> <para>
If your extension includes entirely new templates in addition to If your extension includes entirely new templates in addition to
extensions of standard templates, it should store those new extensions of standard templates, it should install those new
templates in its templates into an extension-specific subdirectory of the
<filename>BUGZILLA_ROOT/extensions/template/en/</filename> <filename>BUGZILLA_ROOT/template/en/extension/</filename>
directory. Extension template directories, like the directory. The <filename>extension/</filename> directory, like the
<filename>default/</filename> and <filename>custom/</filename> <filename>default/</filename> and <filename>custom/</filename>
directories, are part of the template search path, so putting templates directories, is part of the template search path, so putting templates
there enables them to be found by the template processor. there enables them to be found by the template processor.
</para> </para>
<para> <para>
The template processor looks for templates first in the The template processor looks for templates first in the
<filename>custom/</filename> directory (i.e. templates added by the <filename>custom/</filename> directory (i.e. templates added by the
specific installation), then in the <filename>extensions/</filename> specific installation), then in the <filename>extension/</filename>
directory (i.e. templates added by extensions), and finally in the directory (i.e. templates added by extensions), and finally in the
<filename>default/</filename> directory (i.e. the standard Bugzilla <filename>default/</filename> directory (i.e. the standard Bugzilla
templates). Thus, installation-specific templates override both templates). Thus extension templates can override standard templates,
default and extension templates. but installation-specific templates override both.
</para>
<para>
Note that overriding standard templates with extension templates
gives you great power but also makes upgrading an installation harder.
As with custom templates, we recommend using this functionality
sparingly and only when absolutely necessary.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
If you are looking to customize Bugzilla, you can also take advantage Installation customizers can also take advantage of hooks when adding
of template hooks. To do so, create a directory in code to a Bugzilla template. To do so, create directories in
<filename>BUGZILLA_ROOT/template/en/custom/hook/</filename> <filename>BUGZILLA_ROOT/template/en/custom/hook/</filename>
that corresponds to the hook you wish to use, then place your equivalent to the directories in
customization templates into those directories. For example, <filename>BUGZILLA_ROOT/template/en/extension/hook/</filename>
if you wanted to use the hook "end" in for the hooks you want to use, then place your customization templates
<filename>global/useful-links.html.tmpl</filename>, you would into those directories.
create the directory <filename>BUGZILLA_ROOT/template/en/custom/hook/
global/useful-links.html.tmpl/end/</filename> and add your customization
template to this directory.
</para> </para>
<para> <para>
Obviously this method of customizing Bugzilla only lets you add code Obviously this method of customizing Bugzilla only lets you add code
to the standard source files and templates; you cannot change the to the standard templates; you cannot change the existing code.
existing code. Nevertheless, for those customizations that only add Nevertheless, for those customizations that only add code, this method
code, this method can reduce conflicts when merging changes, can reduce conflicts when merging changes, making upgrading
making upgrading your customized Bugzilla installation easier. your customized Bugzilla installation easier.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
...@@ -699,32 +536,22 @@ ...@@ -699,32 +536,22 @@
</para> </para>
<para> <para>
By default, assignees, QA owners and users
with <emphasis>editbugs</emphasis> privileges can edit all fields of bugs,
except group restrictions (unless they are members of the groups they
are trying to change). Bug reporters also have the ability to edit some
fields, but in a more restrictive manner. Other users, without
<emphasis>editbugs</emphasis> privileges, can not edit
bugs, except to comment and add themselves to the CC list.
</para>
<para>
For maximum flexibility, customizing this means editing Bugzilla's Perl For maximum flexibility, customizing this means editing Bugzilla's Perl
code. This gives the administrator complete control over exactly who is code. This gives the administrator complete control over exactly who is
allowed to do what. The relevant method is called allowed to do what. The relevant function is called
<filename>check_can_change_field()</filename>, <filename>CheckCanChangeField()</filename>,
and is found in <filename>Bug.pm</filename> in your and is found in <filename>process_bug.cgi</filename> in your
Bugzilla/ directory. If you open that file and search for Bugzilla directory. If you open that file and grep for
<quote>sub check_can_change_field</quote>, you'll find it. "sub CheckCanChangeField", you'll find it.
</para> </para>
<para> <para>
This function has been carefully commented to allow you to see exactly This function has been carefully commented to allow you to see exactly
how it works, and give you an idea of how to make changes to it. how it works, and give you an idea of how to make changes to it. Certain
Certain marked sections should not be changed - these are marked sections should not be changed - these are the "plumbing" which
the <quote>plumbing</quote> which makes the rest of the function work. makes the rest of the function work. In between those sections, you'll
In between those sections, you'll find snippets of code like: find snippets of code like:
<programlisting> # Allow the assignee to change anything. <programlisting> # Allow the owner to change anything.
if ($ownerid eq $whoid) { if ($ownerid eq $whoid) {
return 1; return 1;
}</programlisting> }</programlisting>
...@@ -733,11 +560,11 @@ ...@@ -733,11 +560,11 @@
<para> <para>
So, how does one go about changing this function? Well, simple changes So, how does one go about changing this function? Well, simple changes
can be made just by removing pieces - for example, if you wanted to can be made just be removing pieces - for example, if you wanted to
prevent any user adding a comment to a bug, just remove the lines marked prevent any user adding a comment to a bug, just remove the lines marked
<quote>Allow anyone to change comments.</quote> If you don't want the "Allow anyone to change comments." And if you want the reporter to have
Reporter to have any special rights on bugs they have filed, just no special rights on bugs they have filed, just remove the entire section
remove the entire section that deals with the Reporter. which refers to him.
</para> </para>
<para> <para>
...@@ -756,12 +583,8 @@ ...@@ -756,12 +583,8 @@
} }
}</programlisting> }</programlisting>
This says that only users in the group "quality_assurance" can change This says that only users in the group "quality_assurance" can change
the QA Contact field of a bug. the QA Contact field of a bug. Getting more weird:
</para> <programlisting> if (($field eq "priority") &&
<para>
Getting more weird:
<programlisting><![CDATA[ if (($field eq "priority") &&
(Bugzilla->user->email =~ /.*\@example\.com$/)) (Bugzilla->user->email =~ /.*\@example\.com$/))
{ {
if ($oldvalue eq "P1") { if ($oldvalue eq "P1") {
...@@ -770,26 +593,377 @@ ...@@ -770,26 +593,377 @@
else { else {
return 0; return 0;
} }
}]]></programlisting> }</programlisting>
This says that if the user is trying to change the priority field, This says that if the user is trying to change the priority field,
and their email address is @example.com, they can only do so if the and their email address is @example.com, they can only do so if the
old value of the field was "P1". Not very useful, but illustrative. old value of the field was "P1". Not very useful, but illustrative.
</para> </para>
<warning>
<para> <para>
If you are modifying <filename>process_bug.cgi</filename> in any For a list of possible field names, look in
way, do not change the code that is bounded by DO_NOT_CHANGE blocks. <filename>data/versioncache</filename> for the list called
Doing so could compromise security, or cause your installation to <filename>@::log_columns</filename>. If you need help writing custom
stop working entirely. rules for your organization, ask in the newsgroup.
</para> </para>
</warning> </section>
<section id="dbmodify">
<title>Modifying Your Running System</title>
<para>Bugzilla optimizes database lookups by storing all relatively
static information in the
<filename>versioncache</filename> file, located in the
<filename class="directory">data/</filename>
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 <filename>defparams.pl</filename>, 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> <filename>versioncache</filename>
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 id="dbdoc">
<title>MySQL Bugzilla Database Introduction</title>
<para>This information comes straight from my life. I was forced to learn
how Bugzilla organizes database because of nitpicky requests from users
for tiny changes in wording, rather than having people re-educate
themselves or figure out how to work our procedures around the tool. It
sucks, but it can and will happen to you, so learn how the schema works
and deal with it when it comes.</para>
<para>So, here you are with your brand-new installation of Bugzilla.
You've got MySQL set up, Apache working right, Perl DBI and DBD talking
to the database flawlessly. Maybe you've even entered a few test bugs to
make sure email's working; people seem to be notified of new bugs and
changes, and you can enter and edit bugs to your heart's content. Perhaps
you've gone through the trouble of setting up a gateway for people to
submit bugs to your database via email, have had a few people test it,
and received rave reviews from your beta testers.</para>
<para>What's the next thing you do? Outline a training strategy for your
development team, of course, and bring them up to speed on the new tool
you've labored over for hours.</para>
<para>Your first training session starts off very well! You have a
captive audience which seems enraptured by the efficiency embodied in
this thing called "Bugzilla". You are caught up describing the nifty
features, how people can save favorite queries in the database, set them
up as headers and footers on their pages, customize their layouts,
generate reports, track status with greater efficiency than ever before,
leap tall buildings with a single bound and rescue Jane from the clutches
of Certain Death!</para>
<para>But Certain Death speaks up -- a tiny voice, from the dark corners
of the conference room. "I have a concern," the voice hisses from the
darkness, "about the use of the word 'verified'."</para>
<para>The room, previously filled with happy chatter, lapses into
reverential silence as Certain Death (better known as the Vice President
of Software Engineering) continues. "You see, for two years we've used
the word 'verified' to indicate that a developer or quality assurance
engineer has confirmed that, in fact, a bug is valid. I don't want to
lose two years of training to a new software product. You need to change
the bug status of 'verified' to 'approved' as soon as possible. To avoid
confusion, of course."</para>
<para>Oh no! Terror strikes your heart, as you find yourself mumbling
"yes, yes, I don't think that would be a problem," You review the changes
with Certain Death, and continue to jabber on, "no, it's not too big a
change. I mean, we have the source code, right? You know, 'Use the
Source, Luke' and all that... no problem," All the while you quiver
inside like a beached jellyfish bubbling, burbling, and boiling on a hot
Jamaican sand dune...</para>
<para>Thus begins your adventure into the heart of Bugzilla. You've been
forced to learn about non-portable enum() fields, varchar columns, and
tinyint definitions. The Adventure Awaits You!</para>
<section>
<title>Bugzilla Database Basics</title>
<para>If you were like me, at this point you're totally clueless about
the internals of MySQL, and if it weren't for this executive order from
the Vice President you couldn't care less about the difference between
a
<quote>bigint</quote>
and a
<quote>tinyint</quote>
entry in MySQL. I recommend you refer to the
<ulink url="http://www.mysql.com/documentation/">MySQL documentation</ulink>
. Below are the basics you need to know about the Bugzilla database.
Check the chart above for more details.</para>
<para>
<orderedlist>
<listitem>
<para>To connect to your database:</para>
<para> <para>
For a list of possible field names, look at the bugs table in the <prompt>bash#</prompt>
database. If you need help writing custom rules for your organization,
ask in the newsgroup. <command>mysql</command>
<parameter>-u root</parameter>
</para> </para>
<para>If this works without asking you for a password,
<emphasis>shame on you</emphasis>
! You should have locked your security down like the installation
instructions told you to. You can find details on locking down
your database in the Bugzilla FAQ in this directory (under
"Security"), or more robust security generalities in the
<ulink url="http://www.mysql.com/php/manual.php3?section=Privilege_system">MySQL
searchable documentation</ulink>.
</para>
</listitem>
<listitem>
<para>You should now be at a prompt that looks like this:</para>
<para>
<prompt>mysql&gt;</prompt>
</para>
<para>At the prompt, if
<quote>bugs</quote>
is the name you chose in the
<filename>localconfig</filename>
file for your Bugzilla database, type:</para>
<para>
<prompt>mysql</prompt>
<command>use bugs;</command>
</para>
</listitem>
</orderedlist>
</para>
<section>
<title>Bugzilla Database Tables</title>
<para>Imagine your MySQL database as a series of spreadsheets, and
you won't be too far off. If you use this command:</para>
<para>
<prompt>mysql&gt;</prompt>
<command>show tables from bugs;</command>
</para>
<para>you'll be able to see the names of all the
<quote>spreadsheets</quote>
(tables) in your database.</para>
<para>From the command issued above, ou should have some
output that looks like this:
<programlisting>
+-------------------+
| Tables in bugs |
+-------------------+
| attachments |
| bugs |
| bugs_activity |
| cc |
| components |
| dependencies |
| fielddefs |
| groups |
| keyworddefs |
| keywords |
| logincookies |
| longdescs |
| milestones |
| namedqueries |
| products |
| profiles |
| profiles_activity |
| tokens |
| versions |
| votes |
| watch |
+-------------------+
</programlisting>
</para>
<literallayout>
Here's an overview of what each table does. Most columns in each table have
descriptive names that make it fairly trivial to figure out their jobs.
attachments: This table stores all attachments to bugs. It tends to be your
largest table, yet also generally has the fewest entries because file
attachments are so (relatively) large.
bugs: This is the core of your system. The bugs table stores most of the
current information about a bug, with the exception of the info stored in the
other tables.
bugs_activity: This stores information regarding what changes are made to bugs
when -- a history file.
cc: This tiny table simply stores all the CC information for any bug which has
any entries in the CC field of the bug. Note that, like most other tables in
Bugzilla, it does not refer to users by their user names, but by their unique
userid, stored as a primary key in the profiles table.
components: This stores the programs and components (or products and
components, in newer Bugzilla parlance) for Bugzilla. Curiously, the "program"
(product) field is the full name of the product, rather than some other unique
identifier, like bug_id and user_id are elsewhere in the database.
dependencies: Stores data about those cool dependency trees.
fielddefs: A nifty table that defines other tables. For instance, when you
submit a form that changes the value of "AssignedTo" this table allows
translation to the actual field name "assigned_to" for entry into MySQL.
groups: defines bitmasks for groups. A bitmask is a number that can uniquely
identify group memberships. For instance, say the group that is allowed to
tweak parameters is assigned a value of "1", the group that is allowed to edit
users is assigned a "2", and the group that is allowed to create new groups is
assigned the bitmask of "4". By uniquely combining the group bitmasks (much
like the chmod command in UNIX,) you can identify a user is allowed to tweak
parameters and create groups, but not edit users, by giving him a bitmask of
"5", or a user allowed to edit users and create groups, but not tweak
parameters, by giving him a bitmask of "6" Simple, huh?
If this makes no sense to you, try this at the mysql prompt:
mysql> select * from groups;
You'll see the list, it makes much more sense that way.
keyworddefs: Definitions of keywords to be used
keywords: Unlike what you'd think, this table holds which keywords are
associated with which bug id's.
logincookies: This stores every login cookie ever assigned to you for every
machine you've ever logged into Bugzilla from. Curiously, it never does any
housecleaning -- I see cookies in this file I've not used for months. However,
since Bugzilla never expires your cookie (for convenience' sake), it makes
sense.
longdescs: The meat of bugzilla -- here is where all user comments are stored!
You've only got 2^24 bytes per comment (it's a mediumtext field), so speak
sparingly -- that's only the amount of space the Old Testament from the Bible
would take (uncompressed, 16 megabytes). Each comment is keyed to the
bug_id to which it's attached, so the order is necessarily chronological, for
comments are played back in the order in which they are received.
milestones: Interesting that milestones are associated with a specific product
in this table, but Bugzilla does not yet support differing milestones by
product through the standard configuration interfaces.
namedqueries: This is where everybody stores their "custom queries". Very
cool feature; it beats the tar out of having to bookmark each cool query you
construct.
products: What products you have, whether new bug entries are allowed for the
product, what milestone you're working toward on that product, votes, etc. It
will be nice when the components table supports these same features, so you
could close a particular component for bug entry without having to close an
entire product...
profiles: Ahh, so you were wondering where your precious user information was
stored? Here it is! With the passwords in plain text for all to see! (but
sshh... don't tell your users!)
profiles_activity: Need to know who did what when to who's profile? This'll
tell you, it's a pretty complete history.
versions: Version information for every product
votes: Who voted for what when
watch: Who (according to userid) is watching who's bugs (according to their
userid).
===
THE DETAILS
===
Ahh, so you're wondering just what to do with the information above? At the
mysql prompt, you can view any information about the columns in a table with
this command (where "table" is the name of the table you wish to view):
mysql> show columns from table;
You can also view all the data in a table with this command:
mysql> select * from table;
-- note: this is a very bad idea to do on, for instance, the "bugs" table if
you have 50,000 bugs. You'll be sitting there a while until you ctrl-c or
50,000 bugs play across your screen.
You can limit the display from above a little with the command, where
"column" is the name of the column for which you wish to restrict information:
mysql> select * from table where (column = "some info");
-- or the reverse of this
mysql> select * from table where (column != "some info");
Let's take our example from the introduction, and assume you need to change
the word "verified" to "approved" in the resolution field. We know from the
above information that the resolution is likely to be stored in the "bugs"
table. Note we'll need to change a little perl code as well as this database
change, but I won't plunge into that in this document. Let's verify the
information is stored in the "bugs" table:
mysql> show columns from bugs
(exceedingly long output truncated here)
| bug_status| enum('UNCONFIRMED','NEW','ASSIGNED','REOPENED','RESOLVED','VERIFIED','CLOSED')||MUL | UNCONFIRMED||
Sorry about that long line. We see from this that the "bug status" column is
an "enum field", which is a MySQL peculiarity where a string type field can
only have certain types of entries. While I think this is very cool, it's not
standard SQL. Anyway, we need to add the possible enum field entry
'APPROVED' by altering the "bugs" table.
mysql> ALTER table bugs CHANGE bug_status bug_status
-> enum("UNCONFIRMED", "NEW", "ASSIGNED", "REOPENED", "RESOLVED",
-> "VERIFIED", "APPROVED", "CLOSED") not null;
(note we can take three lines or more -- whatever you put in before the
semicolon is evaluated as a single expression)
Now if you do this:
mysql> show columns from bugs;
you'll see that the bug_status field has an extra "APPROVED" enum that's
available! Cool thing, too, is that this is reflected on your query page as
well -- you can query by the new status. But how's it fit into the existing
scheme of things?
Looks like you need to go back and look for instances of the word "verified"
in the perl code for Bugzilla -- wherever you find "verified", change it to
"approved" and you're in business (make sure that's a case-insensitive search).
Although you can query by the enum field, you can't give something a status
of "APPROVED" until you make the perl changes. Note that this change I
mentioned can also be done by editing checksetup.pl, which automates a lot of
this. But you need to know this stuff anyway, right?
</literallayout>
</section>
</section>
</section> </section>
<!-- Integrating Bugzilla with Third-Party Tools --> <!-- Integrating Bugzilla with Third-Party Tools -->
......
docs/en/xml/gfdl.xml
View file @ 98be5699
...@@ -16,7 +16,7 @@ ...@@ -16,7 +16,7 @@
</blockquote> </blockquote>
<section label="0" id="gfdl-0"> <section label="0" id="gfdl-0">
<title>PREAMBLE</title> <title>Preamble</title>
<para>The purpose of this License is to make a manual, textbook, or other <para>The purpose of this License is to make a manual, textbook, or other
written document "free" in the sense of freedom: to assure everyone the written document "free" in the sense of freedom: to assure everyone the
...@@ -41,7 +41,7 @@ ...@@ -41,7 +41,7 @@
</section> </section>
<section label="1" id="gfdl-1"> <section label="1" id="gfdl-1">
<title>APPLICABILITY AND DEFINITIONS</title> <title>Applicability and Definition</title>
<para>This License applies to any manual or other work that contains a <para>This License applies to any manual or other work that contains a
notice placed by the copyright holder saying it can be distributed under notice placed by the copyright holder saying it can be distributed under
...@@ -101,7 +101,7 @@ ...@@ -101,7 +101,7 @@
</section> </section>
<section label="2" id="gfdl-2"> <section label="2" id="gfdl-2">
<title>VERBATIM COPYING</title> <title>Verbatim Copying</title>
<para>You may copy and distribute the Document in any medium, either <para>You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the commercially or noncommercially, provided that this License, the
...@@ -118,7 +118,7 @@ ...@@ -118,7 +118,7 @@
</section> </section>
<section label="3" id="gfdl-3"> <section label="3" id="gfdl-3">
<title>COPYING IN QUANTITY</title> <title>Copying in Quantity</title>
<para>If you publish printed copies of the Document numbering more than <para>If you publish printed copies of the Document numbering more than
100, and the Document's license notice requires Cover Texts, you must 100, and the Document's license notice requires Cover Texts, you must
...@@ -157,7 +157,7 @@ ...@@ -157,7 +157,7 @@
</section> </section>
<section label="4" id="gfdl-4"> <section label="4" id="gfdl-4">
<title>MODIFICATIONS</title> <title>Modifications</title>
<para>You may copy and distribute a Modified Version of the Document <para>You may copy and distribute a Modified Version of the Document
under the conditions of sections 2 and 3 above, provided that you release under the conditions of sections 2 and 3 above, provided that you release
...@@ -287,7 +287,7 @@ ...@@ -287,7 +287,7 @@
</section> </section>
<section label="5" id="gfdl-5"> <section label="5" id="gfdl-5">
<title>COMBINING DOCUMENTS</title> <title>Combining Documents</title>
<para>You may combine the Document with other documents released under <para>You may combine the Document with other documents released under
this License, under the terms defined in section 4 above for modified this License, under the terms defined in section 4 above for modified
...@@ -313,7 +313,7 @@ ...@@ -313,7 +313,7 @@
</section> </section>
<section label="6" id="gfdl-6"> <section label="6" id="gfdl-6">
<title>COLLECTIONS OF DOCUMENTS</title> <title>Collections of Documents</title>
<para>You may make a collection consisting of the Document and other <para>You may make a collection consisting of the Document and other
documents released under this License, and replace the individual copies documents released under this License, and replace the individual copies
...@@ -329,7 +329,7 @@ ...@@ -329,7 +329,7 @@
</section> </section>
<section label="7" id="gfdl-7"> <section label="7" id="gfdl-7">
<title>AGGREGATION WITH INDEPENDENT WORKS</title> <title>Aggregation with Independent Works</title>
<para>A compilation of the Document or its derivatives with other <para>A compilation of the Document or its derivatives with other
separate and independent documents or works, in or on a volume of a separate and independent documents or works, in or on a volume of a
...@@ -348,7 +348,7 @@ ...@@ -348,7 +348,7 @@
</section> </section>
<section label="8" id="gfdl-8"> <section label="8" id="gfdl-8">
<title>TRANSLATION</title> <title>Translation</title>
<para>Translation is considered a kind of modification, so you may <para>Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4. distribute translations of the Document under the terms of section 4.
...@@ -363,7 +363,7 @@ ...@@ -363,7 +363,7 @@
</section> </section>
<section label="9" id="gfdl-9"> <section label="9" id="gfdl-9">
<title>TERMINATION</title> <title>Termination</title>
<para>You may not copy, modify, sublicense, or distribute the Document <para>You may not copy, modify, sublicense, or distribute the Document
except as expressly provided for under this License. Any other attempt to except as expressly provided for under this License. Any other attempt to
...@@ -375,7 +375,7 @@ ...@@ -375,7 +375,7 @@
</section> </section>
<section label="10" id="gfdl-10"> <section label="10" id="gfdl-10">
<title>FUTURE REVISIONS OF THIS LICENSE</title> <title>Future Revisions of this License</title>
<para>The Free Software Foundation may publish new, revised versions of <para>The Free Software Foundation may publish new, revised versions of
the GNU Free Documentation License from time to time. Such new versions the GNU Free Documentation License from time to time. Such new versions
......
docs/en/xml/installation.xml
View file @ 98be5699
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> --> <!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
<!-- $Id: installation.xml,v 1.58 2008/04/04 06:46:48 kiko%async.com.br Exp $ --> <!-- $Id: installation.xml,v 1.59 2008/04/04 06:46:49 gerv%gerv.net Exp $ -->
<chapter id="installation"> <chapter id="installing-bugzilla">
<title>Installing Bugzilla</title>
<section id="installation">
<title>Installation</title> <title>Installation</title>
<section id="stepbystep"> <note>
<title>Step-by-step Install</title> <para>If you just want to <emphasis>use</emphasis> Bugzilla,
you do not need to install it. None of this chapter is relevant to
you. Ask your Bugzilla administrator
for the URL to access it over the web.
</para>
</note>
<para>Bugzilla has been successfully installed under many different <para>The Bugzilla server software is usually installed on Linux or
operating systems including almost all Unix clones and Solaris.
<productname class="registered">Microsoft Windows</productname>. Many If you are installing on another OS, check <xref linkend="os-specific"/>
operating systems have utilities that make installation easier or quirks before you start your installation to see if there are any special
that make it harder. We have tried to collect that information in instructions.
<xref linkend="os-specific"/>, so unless you are on Linux,
be sure to check out that section before
you start your installation.
</para> </para>
<note> <para>
<para>Windows is one of those operating systems that has many quirks As an alternative to following these instructions, you may wish to
and is not yet officially supported by the Bugzilla team. If you wish try Arne Schirmacher's unofficial and unsupported
to install Bugzilla on Windows, be sure to see <ulink url="http://www.softwaretesting.de/article/view/33/1/8/">Bugzilla
<xref linkend="os-win32"/>. Installer</ulink>, which installs Bugzilla and all its prerequisites
on Linux or Solaris systems.
</para> </para>
</note>
<warning> <para>This guide assumes that you have administrative access to the
<para>While installing Bugzilla, it is a good idea to ensure that there Bugzilla machine. It not possible to
is some kind of configurable firewall between you and the rest of the install and run Bugzilla itself without administrative access except
Internet in the very unlikely event that every single prerequisite is
as your machine may be insecure for periods during the install. Many already installed.
installation steps require an active Internet connection to complete, </para>
but you must take care to ensure that at no point is your machine
vulnerable to an attack.</para>
</warning>
<para>This guide assumes that you already have your operating system <warning>
installed, network configured, and have administrative access to the <para>The installation process may make your machine insecure for
machine onto which you are installing Bugzilla. It is possible to short periods of time. Make sure there is a firewall between you
install and run Bugzilla itself without administrative access, but you and the Internet.
have to
either make sure all the required software is installed or get somebody
with administrative access to install it for you.
</para> </para>
</warning>
<para> <para>
You are strongly recommended to make a backup of your system You are strongly recommended to make a backup of your system
before installing Bugzilla (and at regular intervals thereafter :-). before installing Bugzilla (and at regular intervals thereafter :-).
</para> </para>
<para>Here's a basic step-by-step list: <para>In outline, the installation proceeds as follows:
</para> </para>
<procedure> <procedure>
...@@ -67,15 +67,15 @@ ...@@ -67,15 +67,15 @@
</para> </para>
</step> </step>
<step> <step>
<para><link linkend="install-bzfiles">Put Bugzilla in the Webspace</link> <para><link linkend="install-bzfiles">Install Bugzilla</link>
</para> </para>
</step> </step>
<step> <step>
<para><link linkend="install-perlmodules">Install Perl Modules</link> <para><link linkend="install-perlmodules">Install Perl modules</link>
</para> </para>
</step> </step>
<step> <step>
<para><link linkend="install-setupdatabase">Setup the MySQL Database</link> <para>Configure all of the above.
</para> </para>
</step> </step>
</procedure> </procedure>
...@@ -83,24 +83,25 @@ ...@@ -83,24 +83,25 @@
<section id="install-perl"> <section id="install-perl">
<title>Perl</title> <title>Perl</title>
<para>Installed Version Test: <filename>perl -v</filename></para>
<para>Any machine that doesn't have Perl on it is a sad machine indeed. <para>Any machine that doesn't have Perl on it is a sad machine indeed.
If your OS doesn't come with it, Perl can be got in source form If you don't have it and your OS doesn't provide official packages,
from <ulink url="http://www.perl.com"/>. visit <ulink url="http://www.perl.com"/>.
There are also binary versions available for many platforms, most of which Although Bugzilla runs with Perl &min-perl-ver;,
are linked to from perl.com. it's a good idea to be using the latest stable version.
Although Bugzilla runs with perl &min-perl-ver;, As of this writing, that is Perl &newest-perl-ver;.</para>
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>
</section> </section>
<section id="install-mysql"> <section id="install-mysql">
<title>MySQL</title> <title>MySQL</title>
<para>If your OS doesn't come with it or provide official packages, <para>Installed Version Test: <filename>mysql -V</filename></para>
visit the MySQL homepage at
<ulink url="http://www.mysql.com"/> <para>
to grab and install the latest stable release of the server. If you don't have it and your OS doesn't provide official packages,
visit <ulink url="http://www.mysql.com"/>. You need MySQL version
&min-mysql-ver; or higher.
</para> </para>
<note> <note>
...@@ -108,277 +109,125 @@ ...@@ -108,277 +109,125 @@
versions of MySQL store their data files in versions of MySQL store their data files in
<filename class="directory">/var</filename>. <filename class="directory">/var</filename>.
On some Unix systems, this is part of a smaller root partition, 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 and may not have room for your bug database. To change the data
directory as an option to <filename>configure</filename> directory, you have to build MySQL from source yourself, and
if you build MySQL from source yourself.</para> set it as an option to <filename>configure</filename>.</para>
</note> </note>
<para>If you install from something other than a packaging/installation <para>If you install from something other than a packaging/installation
system (such as .rpm, .dep, .exe, or .msi) you will need to configure system (such as .rpm, .dep, .exe, or .msi) make sure the MySQL server
your system so the MySQL server daemon will come back up whenever is started when the machine boots.
your machine reboots.
</para>
<para>If you wish to have attachments larger than 64K, you will have to
configure MySQL to accept large packets. This is done by adding the text
in <xref linkend="install-mysql-packets"/> to your
<filename>my.conf</filename> file. There is also a parameter in Bugzilla
for setting the maximum allowable attachment size.
<!-- TODO: xref to a param() page for max attachment size -->
You should set this value to be slightly larger than that parameter.
</para>
<figure id="install-mysql-packets">
<title>Set Max Packet Size in MySQL</title>
<programlisting>
[mysqld]
# Allow packets up to 1M
set-variable = max_allowed_packet=1M
</programlisting>
</figure>
<para>If you are running Bugzilla and MySQL on the same machine, you may
also wish to utilize the <option>--skip-networking</option> option as
mentioned in <xref linkend="security-mysql"/> for the added security.
</para>
<section id="install-setupdatabase">
<title>Adding a user to MySQL</title>
<para>This first thing you'll want to do is make sure you've given the
<quote>root</quote> user a password as suggested in
<xref linkend="security-mysql"/>. Then, you need to add a user for
Bugzilla to use. For clarity, these instructions will
assume that your MySQL user for Bugzilla will be <quote>bugs_user</quote>,
the database will be called <quote>bugs_db</quote> and the password for
the <quote>bugs_user</quote> user is <quote>bugs_password</quote>. You
should, of course, substitute the values you intend to use for your site.
</para>
<note>
<para>Most people use <quote>bugs</quote> for both the user and
database name. Don't use it for the password, though...
</para> </para>
</note>
<para>We use an SQL <command>GRANT</command> command to create a
<quote>bugs_user</quote>
user. This also restricts the
<quote>bugs_user</quote>
user to operations within a database called
<quote>bugs_db</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>
<screen>
<prompt>mysql&gt;</prompt> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE,
DROP,REFERENCES ON bugs_db.* TO bugs_user@localhost
IDENTIFIED BY 'bugs_password';
<prompt>mysql&gt;</prompt> FLUSH PRIVILEGES;
</screen>
<note>
<para>If you are using MySQL 4, the bugs user also needs to be granted
the <computeroutput>LOCK TABLES</computeroutput> and
<computeroutput>CREATE TEMPORARY TABLES</computeroutput> permissions,
so add them to the list in the
<computeroutput>GRANT</computeroutput> command.
</para>
</note>
</section>
</section> </section>
<section id="install-webserver"> <section id="install-webserver">
<title>HTTP Server</title> <title>Web Server</title>
<para>Installed Version Test: view the default welcome page at
http://&lt;your-machine&gt;/</para>
<para>You have freedom of choice here, pretty much any web server that <para>You have freedom of choice here, pretty much any web server that
is capable of running <glossterm linkend="gloss-cgi">CGI</glossterm> is capable of running <glossterm linkend="gloss-cgi">CGI</glossterm>
scripts will work. <xref linkend="http"/> has more information about scripts will work.
configuring web servers to work with Bugzilla. However, we strongly recommend using the Apache web server
(either 1.3.x or 2.x), and
the installation instructions usually assume you are
using it. If you have got Bugzilla working using another webserver,
please share your experiences with us by filing a bug in &bzg-bugs;.
</para> </para>
<note> <para>
<para>We strongly recommend Apache as the web server to use. The If you don't have Apache and your OS doesn't provide official packages,
Bugzilla Guide installation instructions, in general, assume you are visit <ulink url="http://httpd.apache.org/"/>.
using Apache. If you have got Bugzilla working using another webserver,
please share your experiences with us by filing a bug in &bzg-bugs;.
</para> </para>
</note>
</section> </section>
<section id="install-bzfiles"> <section id="install-bzfiles">
<title>Bugzilla</title> <title>Bugzilla</title>
<para>You should untar the Bugzilla files into a directory that you're <para>
willing to make writable by the default web server user (probably Download a Bugzilla tarball (or check it out from CVS) and place
<quote>nobody</quote>). it in a suitable directory, writable by the default web server user
You may decide to put the files in the main web space for your (probably <quote>nobody</quote>).
Good locations are either directly in the main web space for your
web server or perhaps in web server or perhaps in
<filename>/usr/local</filename> <filename>/usr/local</filename>
with a symbolic link in the web space that points to the Bugzilla with a symbolic link from the web space.
directory.</para> </para>
<tip>
<para>If you symlink the bugzilla directory into your Apache's
<filename>html</filename>
hierarchy, you may receive
<errorname>Forbidden</errorname>
errors unless you add the
<filename>FollowSymLinks</filename>
directive to the <filename>&lt;Directory&gt;</filename> entry for
the HTML root directory in httpd.conf.</para>
</tip>
<caution> <caution>
<para>The default Bugzilla distribution is not designed to be placed <para>The default Bugzilla distribution is not designed to be placed
in a <filename class="directory">cgi-bin</filename> directory (this in a <filename class="directory">cgi-bin</filename> directory. This
includes any directory which is configured using the includes any directory which is configured using the
<option>ScriptAlias</option> directive of Apache). <option>ScriptAlias</option> directive of Apache.
</para> </para>
</caution> </caution>
<para>Once all the files are in a web accessible directory, make that <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 directory writable by your webserver's user. This is a temporary step
until you run the post-install until you run the
<filename>checksetup.pl</filename> <filename>checksetup.pl</filename>
script, which locks down your installation.</para> script, which locks down your installation.</para>
</section> </section>
<section> <section id="install-perlmodules">
<title> <title>Perl Modules</title>
<filename>checksetup.pl</filename>
</title>
<para>Next, run the magic checksetup.pl script. <para>Bugzilla's installation process is based
This is designed to check whether you have all of the right on a script called <filename>checksetup.pl</filename>.
Perl modules in the correct The first thing it checks is whether you have appropriate
versions, and that Bugzilla is generally set up correctly. versions of all the required
Perl modules. The aim of this section is to pass this check.
When it passes,
<emphasis>do not run it again</emphasis>,
but proceed to <xref linkend="configuration"/>.
</para> </para>
<para> <para>
Eventually, At this point, you need to <filename>su</filename> to root. You should
it will make sure Bugzilla files and directories have reasonable remain as root until the end of the install. Then run:
permissions, set up the
<filename>data</filename>
directory, and create all the MySQL tables. But the first time you
run it, it's highly likely to tell you that you are missing a few
Perl modules. Make a note of which ones they are, and then proceed to
the next section to install them.
</para> </para>
<screen> <screen><prompt>bash#</prompt> ./checksetup.pl</screen>
<prompt>bash#</prompt> ./checksetup.pl
</screen>
<para> <!-- We really need a "module-check" switch for checksetup,
The first time you run it with all the correct modules installed, which we can use here to make it really clear when they've got
it will create a file called all the modules. -->
<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_db</quote>
if you're following these directions</para>
</listitem>
<listitem> <para>
<para>MySQL username: <filename>checksetup.pl</filename> will print out a list of the
<quote>bugs_user</quote> required and optional Perl modules, together with the versions
if you're following these directions</para> (if any) installed on your machine.
</listitem> The list of required modules is reasonably long; however, you
may already have several of them installed.
<listitem>
<para>Password for the
<quote>bugs_user</quote>
MySQL account; (<quote>bugs_password</quote> above)</para>
</listitem>
</orderedlist>
</para>
<para>Edit the file to change these. 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 id="install-perlmodules">
<title>Perl Modules</title>
<para>Don't be intimidated by this long list of modules. See
<xref linkend="install-modules-bundle-bugzilla"/> for a way of
installing all the ones you need with a single command.
</para> </para>
<para>Perl modules can be found using <para>
<glossterm linkend="gloss-cpan">CPAN</glossterm> on Unix based systems or There is a meta-module called Bundle::Bugzilla,
<glossterm linkend="gloss-ppm">PPM</glossterm> on Win32. which installs all the other
modules with a single command. You should use this if you are running
Perl 5.6.1 or above.
</para> </para>
<para>Good instuctions can be found for using each of these services on <para>
their respective websites. The basics can be found in The preferred way of installing Perl modules is via CPAN on Unix,
<xref linkend="install-perlmodules-cpan"/> for CPAN and or PPM on Windows (see <xref linkend="win32-perlmodules"/>). These
<xref linkend="win32-perlmodules"/> for PPM. instructions assume you are using CPAN; if for some reason you need
to install the Perl modules manually, see
<xref linkend="install-perlmodules-manual"/>.
</para> </para>
<example id="install-perlmodules-cpan"> <screen><prompt>bash#</prompt> perl -MCPAN -e 'install "&lt;modulename&gt;"'</screen>
<title>Installing perl modules with CPAN</title>
<para>The easy way:
<screen>
<prompt>bash#</prompt> perl -MCPAN -e 'install "&lt;modulename&gt;"'
</screen>
</para>
<para>Or the hard way: <para>
<screen> If you using Bundle::Bugzilla, invoke the magic CPAN command on it.
<prompt>bash#</prompt> tar xzvf &lt;module&gt;.tar.gz <co id="cpan-moduletar"/> Otherwise, you need to work down the
<prompt>bash#</prompt> cd &lt;module&gt; <co id="cpan-moduledir"/> list of modules that <filename>checksetup.pl</filename> says are
<prompt>bash#</prompt> perl Makefile.PL required, in the order given, invoking the command on each.
<prompt>bash#</prompt> make
<prompt>bash#</prompt> make test
<prompt>bash#</prompt> make install
</screen>
<calloutlist>
<callout arearefs="cpan-moduletar">
<para>This assumes that you've already downloaded the
<filename>&lt;module&gt;.tar.gz</filename> to the current working
directory.
</para>
</callout>
<callout arearefs="cpan-moduledir">
<para>The process of untarring the module as defined in
<xref linkend="cpan-moduletar"/> will create the
<filename class="directory">&lt;module&gt;</filename> directory.
</para>
</callout>
</calloutlist>
</para> </para>
</example>
<tip> <tip>
<para>Many people complain that Perl modules will not install for <para>Many people complain that Perl modules will not install for
...@@ -395,35 +244,41 @@ set-variable = max_allowed_packet=1M ...@@ -395,35 +244,41 @@ set-variable = max_allowed_packet=1M
for further assistance or hire someone to help you out.</para> for further assistance or hire someone to help you out.</para>
</tip> </tip>
<para>
Here is a complete list of modules and their minimum versions.
Some modules have special installation notes, which follow.
</para>
<para>Perl Modules (minimum version): <para>Required Perl modules:
<orderedlist> <orderedlist>
<listitem> <listitem>
<para> <para>
<link linkend="install-modules-bundle-bugzilla">Bundle::Bugzilla</link> AppConfig (&min-appconfig-ver;)
(Will allow you to skip the rest) </para>
</listitem>
<listitem>
<para>
CGI (&min-cgi-ver;)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<link linkend="install-modules-cgi">CGI</link> Data::Dumper (&min-data-dumper-ver;)
(&min-cgi-ver;)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<link linkend="install-modules-date-format">Date::Format</link> Date::Format (&min-date-format-ver;)
(&min-date-format-ver;)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<link linkend="install-modules-dbi">DBI</link> DBI (&min-dbi-ver;)
(&min-dbi-ver;)
</para> </para>
</listitem> </listitem>
...@@ -436,34 +291,31 @@ set-variable = max_allowed_packet=1M ...@@ -436,34 +291,31 @@ set-variable = max_allowed_packet=1M
<listitem> <listitem>
<para> <para>
<link linkend="install-file-spec">File::Spec</link> File::Spec (&min-file-spec-ver;)
(&min-file-spec-ver;)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<link linkend="install-modules-file-temp">File::Temp</link> File::Temp (&min-file-temp-ver;)
(&min-file-temp-ver;)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<link linkend="install-modules-template">Template Toolkit</link> <link linkend="install-modules-template">Template</link>
(&min-template-ver;) (&min-template-ver;)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<link linkend="install-modules-text-wrap">Text::Wrap</link> Text::Wrap (&min-text-wrap-ver;)
(&min-text-wrap-ver;)
</para> </para>
</listitem> </listitem>
</orderedlist> </orderedlist>
and, optionally: Optional Perl modules:
<orderedlist> <orderedlist>
<listitem> <listitem>
<para> <para>
...@@ -481,13 +333,6 @@ set-variable = max_allowed_packet=1M ...@@ -481,13 +333,6 @@ set-variable = max_allowed_packet=1M
<listitem> <listitem>
<para> <para>
<link linkend="install-modules-xml-parser">XML::Parser</link>
(&min-xml-parser-ver;) for the XML interface
</para>
</listitem>
<listitem>
<para>
<link linkend="install-modules-gd-graph">GD::Graph</link> <link linkend="install-modules-gd-graph">GD::Graph</link>
(&min-gd-graph-ver;) for bug charting (&min-gd-graph-ver;) for bug charting
</para> </para>
...@@ -502,8 +347,8 @@ set-variable = max_allowed_packet=1M ...@@ -502,8 +347,8 @@ set-variable = max_allowed_packet=1M
<listitem> <listitem>
<para> <para>
<link linkend="install-modules-mime-parser">MIME::Parser</link> <link linkend="install-modules-xml-parser">XML::Parser</link>
(&min-mime-parser-ver;) for the email interface (&min-xml-parser-ver;) for the XML interface
</para> </para>
</listitem> </listitem>
...@@ -513,145 +358,31 @@ set-variable = max_allowed_packet=1M ...@@ -513,145 +358,31 @@ set-variable = max_allowed_packet=1M
(&min-patchreader-ver;) for pretty HTML view of patches (&min-patchreader-ver;) for pretty HTML view of patches
</para> </para>
</listitem> </listitem>
</orderedlist>
</para>
<section id="install-modules-bundle-bugzilla">
<title>Bundle::Bugzilla</title>
<para>If you are running at least perl 5.6.1, you can save yourself a lot
of time by using Bundle::Bugzilla. This bundle contains every module
required to get Bugzilla running. It does not include GD and friends, but
these are not required for a base install and can always be added later
if the need arises.
</para>
<para>Assuming your perl was installed with CPAN (most unix installations
are), using Bundle::Bugzilla is really easy. Simply follow along with the
commands below.
</para>
<listitem>
<screen> <para>
<prompt>bash#</prompt> <command>perl -MCPAN -eshell</command> <co id="bundle-cpanconfig"/> <link linkend="install-modules-mime-parser">MIME::Parser</link>
cpan shell -- CPAN exploration and modules installation (v1.63) (&min-mime-parser-ver;) for the optional email interface
ReadLine support enabled
<prompt>cpan&gt;</prompt>
</screen>
<calloutlist>
<callout arearefs="bundle-cpanconfig">
<para>At this point, unless you've used CPAN on this machine before,
you'll have to go through a series of configuration steps.
</para>
</callout>
</calloutlist>
</section>
<section id="install-modules-cgi">
<title>CGI (&min-cgi-ver;)</title>
<para>The CGI module parses form elements and cookies and does many
other usefule things. It come as a part of recent perl distributions, but
Bugzilla needs a fairly new version.
</para> </para>
</listitem>
<literallayout> </orderedlist>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/CGI.pm/"/>
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/CGI.zip"/>
Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/CGI.html"/>
</literallayout>
</section>
<section id="install-modules-date-format">
<title>TimeDate modules (&min-date-format-ver;)</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> </para>
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/TimeDate/"/>
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/TimeDate.zip"/>
Documentation: <ulink url="http://search.cpan.org/dist/TimeDate/lib/Date/Format.pm"/>
</literallayout>
</section>
<section id="install-modules-dbi">
<title>DBI (&min-dbi-ver;)</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>
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/DBI/"/>
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/DBI.zip"/>
Documentation: <ulink url="http://dbi.perl.org/doc/"/>
</literallayout>
</section>
<section id="install-modules-dbd-mysql"> <section id="install-modules-dbd-mysql">
<title>MySQL-related modules</title> <title>DBD::mysql</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 <para>The installation process will ask you a few questions about the
desired compilation target and your MySQL installation. For most of the desired compilation target and your MySQL installation. For most of the
questions the provided default will be adequate, but when asked if your questions the provided default will be adequate, but when asked if your
desired target is the MySQL or mSQL packages, you should desired target is the MySQL or mSQL packages, you should
select the MySQL related ones. Later you will be asked if you wish to select the MySQL-related ones. Later you will be asked if you wish to
provide backwards compatibility with the older MySQL packages; you provide backwards compatibility with the older MySQL packages; you
should answer YES to this question. The default is NO.</para> 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' <para>A host of 'localhost' should be fine. A testing user of 'test',
with a null password should find itself with sufficient access to run with a null password, should have sufficient access to run
tests on the 'test' database which MySQL created upon installation. tests on the 'test' database which MySQL creates upon installation.
</para> </para>
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/DBD-mysql/"/>
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/DBD-Mysql.zip"/>
Documentation: <ulink url="http://search.cpan.org/dist/DBD-mysql/lib/DBD/mysql.pod"/>
</literallayout>
</section>
<section id="install-file-spec">
<title>File::Spec (&min-file-spec-ver;)</title>
<para>File::Spec is a perl module that allows file operations, such as
generating full path names, to work cross platform.
</para>
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/File-Spec/"/>
PPM Download Page: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/File-Spec.zip"/>
Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/File/Spec.html"/>
</literallayout>
</section>
<section id="install-modules-file-temp">
<title>File::Temp (&min-file-temp-ver;)</title>
<para>File::Temp is used to generate a temporary filename that is
guaranteed to be unique. It comes as a standard part of perl
</para>
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/File-Spec/"/>
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/File-Spec.zip"/>
Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/File/Temp.html"/>
</literallayout>
</section> </section>
<section id="install-modules-template"> <section id="install-modules-template">
...@@ -662,228 +393,337 @@ ReadLine support enabled ...@@ -662,228 +393,337 @@ ReadLine support enabled
that it is recommended you use the high speed XS Stash of the Template that it is recommended you use the high speed XS Stash of the Template
Toolkit, in order to achieve best performance. Toolkit, in order to achieve best performance.
</para> </para>
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/Template-Toolkit/"/>
PPM Download Link: <ulink url="http://openinteract.sourceforge.net/ppmpackages/5.6/Template-Toolkit.tar.gz"/>
Documentation: <ulink url="http://www.template-toolkit.org/docs.html"/>
</literallayout>
</section> </section>
<section id="install-modules-text-wrap">
<title>Text::Wrap (&min-text-wrap-ver;)</title>
<para>Text::Wrap is designed to proved intelligent text wrapping.
</para>
<!-- TODO: Text::Wrap doesn't seem to be available from ActiveState -->
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/Text-Tabs+Wrap/"/>
Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/Text/Wrap.html"/>
</literallayout>
</section>
<section id="install-modules-gd"> <section id="install-modules-gd">
<title>GD (&min-gd-ver;) [optional]</title> <title>GD (&min-gd-ver;)</title>
<para>You need the GD library if you want any of the graphing to work. <para>The GD module is only required if you want graphical reports.
</para> </para>
<note> <note>
<para>The Perl GD library requires some other libraries that may or <para>The Perl GD module requires some other libraries that may or
may not be installed on your system, including may not be installed on your system, including
<classname>libpng</classname> <classname>libpng</classname>
and and
<classname>libgd</classname>. <classname>libgd</classname>.
The full requirements are listed in the Perl GD library README. The full requirements are listed in the Perl GD module README.
If compiling GD fails, it's probably because you're If compiling GD fails, it's probably because you're
missing a required library.</para> missing a required library.</para>
</note> </note>
<tip> <tip>
<para>The version of the GD perl module you need is very closely tied <para>The version of the GD module you need is very closely tied
to the <classname>libgd</classname> version installed on your system. to the <classname>libgd</classname> version installed on your system.
If you have a version 1.x of <classname>libgd</classname> the 2.x If you have a version 1.x of <classname>libgd</classname> the 2.x
versions of the GD perl module won't work for you. versions of the GD module won't work for you.
</para> </para>
</tip> </tip>
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/GD/"/>
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/GD.zip"/>
Documentation: <ulink url="http://stein.cshl.org/WWW/software/GD/"/>
</literallayout>
</section> </section>
<section id="install-modules-chart-base"> <section id="install-modules-chart-base">
<title>Chart::Base (&min-chart-base-ver;) [optional]</title> <title>Chart::Base (&min-chart-base-ver;)</title>
<para>The Chart module provides Bugzilla with on-the-fly charting <para>The Chart::Base module is only required if you want graphical
abilities. It can be installed in the usual fashion after it has been reports.
fetched from CPAN.
Note that earlier versions that 0.99c used GIFs, which are no longer Note that earlier versions that 0.99c used GIFs, which are no longer
supported by the latest versions of GD.</para> supported by the latest versions of GD.</para>
</section>
<section id="install-modules-gd-graph">
<title>GD::Graph (&min-gd-graph-ver;)</title>
<!-- TODO: Chart::Base doesn't seem to have any documentation --> <para>The GD::Graph module is only required if you want graphical
<literallayout> reports.
CPAN Download Page: <ulink url="http://search.cpan.org/dist/Chart/"/> </para>
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/Chart.zip"/> </section>
</literallayout>
<section id="install-modules-gd-text-align">
<title>GD::Text::Align (&min-gd-text-align-ver;)</title>
<para>The GD::Text::Align module is only required if you want graphical
reports.
</para>
</section> </section>
<section id="install-modules-xml-parser"> <section id="install-modules-xml-parser">
<title>XML::Parser (&min-xml-parser-ver;) [optional]</title> <title>XML::Parser (&min-xml-parser-ver;)</title>
<para>XML::Parser is used by the <filename>importxml.pl</filename> <para>The XML::Parser module is only required if you want to import
script. You only need it if you are going to be importing bugs (such as XML bugs using the <filename>importxml.pl</filename>
for bug moving). XML::Parser requires that the script. This is required to use Bugzilla's "move bugs" feature;
you may also want to use it for migrating from another bug database.
XML::Parser requires that the
<classname>expat</classname> library is already installed on your machine. <classname>expat</classname> library is already installed on your machine.
</para> </para>
</section>
<!-- TODO: XML::Parser - the only PPM I see is XML-Parser-EasyTree.zip; <section id="install-modules-mime-parser">
I'm not sure if it's the same thing or not. --> <title>MIME::Parser (&min-mime-parser-ver;)</title>
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/XML-Parser/"/> <para>The MIME::Parser module is only required if you want to use the
Documentation: <ulink url="http://www.perldoc.com/perl5.6.1/lib/XML/Parser.html"/> email interface
</literallayout> located in the <filename class="directory">contrib</filename> directory.
</para>
</section> </section>
<section id="install-modules-gd-graph"> <section id="install-modules-patchreader">
<title>GD::Graph (&min-gd-graph-ver;) [optional]</title> <title>PatchReader (&min-patchreader-ver;)</title>
<para>In addition to GD listed above, the reporting interface of Bugzilla <para>The PatchReader module is only required if you want to use
needs to have the GD::Graph module installed. Patch Viewer, a
Bugzilla feature to show code patches in your web browser in a more
readable form.
</para> </para>
</section>
</section>
</section>
<section id="configuration">
<title>Configuration</title>
<literallayout> <warning>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/GDGraph/"/> <para>Poorly-configured MySQL and Bugzilla installations have
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/GDGraph.zip"/> given attackers full access to systems in the past. Please take the
Documentation: <ulink url="http://search.cpan.org/dist/GDGraph/Graph.pm"/> security parts of these guidelines seriously, even for Bugzilla
</literallayout> machines hidden away behind your firewall.</para>
</warning>
<section id="localconfig">
<title>localconfig</title>
<para>
Once you run <filename>checksetup.pl</filename> with all the correct
modules installed, it displays a message about, and write out a
file called,
<filename>localconfig</filename>. This file contains the default
settings for a number of Bugzilla parameters.
</para>
<para>Load this file in your editor. The only value you
<emphasis>need</emphasis> to change is $db_pass, the password for
the user you will create for your database.
Pick a strong password (for simplicity, it should not contain
single quote characters) and put it here.
</para>
<para>
The other options in the <filename>localconfig</filename> file
are documented by their accompanying comments. If you have a slightly
non-standard MySQL setup, you may wish to change one or more of
the other "$db_*" parameters.
</para>
<para>
You may also wish to change the names of
the priorities, severities, operating systems and platforms for your
installation. However, you can always change these after installation
has finished; if you then re-run
<filename>checksetup.pl</filename>, the changes will get picked up.
</para>
</section> </section>
<section id="install-modules-gd-text-align"> <section id="mysql">
<title>GD::Text::Align (&min-gd-text-align-ver;) [optional]</title> <title>MySQL</title>
<para>GD::Text::Align, as the name implies, is used to draw aligned <section id="security-mysql">
strings of text. It is needed by the reporting interface. <title>Security</title>
<para>MySQL ships as insecure by default.
It allows anybody to on the local machine full administrative
capabilities without requiring a password; the special
MySQL root account (note: this is <emphasis>not</emphasis> the same as
the system root) also has no password.
Also, many installations default to running
<application>mysqld</application> as the system root.
</para>
<orderedlist>
<listitem>
<para>To disable the anonymous user account
and set a password for the root user, execute the following. The
root user password should be different to the bugs user password
you set in
<filename>localconfig</filename> in the previous section,
and also different to
the password for the system root account on your machine.
</para>
<screen> <prompt>bash$</prompt> mysql mysql
<prompt>mysql&gt;</prompt> DELETE FROM user WHERE user = '';
<prompt>mysql&gt;</prompt> UPDATE user SET password = password('<replaceable>new_password</replaceable>') WHERE user = 'root';
<prompt>mysql&gt;</prompt> FLUSH PRIVILEGES;</screen>
<para>From this point forward, to run the
<filename>mysql</filename> command-line client,
you will need to type
<command>mysql -u root -p</command> and enter
<replaceable>new_password</replaceable> when prompted.
</para> </para>
</listitem>
<listitem>
<para>If you run MySQL on the same machine as your web server, you
should disable remote access to MySQL by adding
the following to your <filename>/etc/my.conf</filename>:
</para>
<programlisting> [myslqd]
# Prevent network access to MySQL.
skip-networking</programlisting>
</listitem>
<listitem>
<para>Consult the documentation that came with your system for
information on making <application>mysqld</application> run as an
unprivileged user.
</para>
</listitem>
<listitem>
<para>For added security, you could also run MySQL, or even all
of Bugzilla
in a chroot jail; however, instructions for doing that are beyond
the scope of this document.
</para>
</listitem>
</orderedlist>
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/GDTextUtil/"/>
PPM Download Page: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/GDTextUtil.zip"/>
Documentation: <ulink url="http://search.cpan.org/dist/GDTextUtil/Text/Align.pm"/>
</literallayout>
</section> </section>
<section id="install-modules-mime-parser"> <section id="install-setupdatabase">
<title>MIME::Parser (&min-mime-parser-ver;) [optional]</title> <title>Allow large attachments</title>
<para>MIME::Parser is only needed if you want to use the e-mail interface <para>You need to configure MySQL to accept large packets, if you
located in the <filename class="directory">contrib</filename> directory. want to have attachments larger than 64K. Add the text
below to your
<filename>/etc/my.conf</filename>.
There is also a parameter in Bugzilla
for setting the maximum allowable attachment size, (default 1MB).
Bugzilla will only accept attachments up to the lower of these two
sizes.
</para> </para>
<literallayout> <screen> [mysqld]
CPAN Download Page: <ulink url="http://search.cpan.org/dist/MIME-tools/"/> # Allow packets up to 1M
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/MIME-tools.zip"/> set-variable = max_allowed_packet=1M</screen>
Documentation: <ulink url="http://search.cpan.org/dist/MIME-tools/lib/MIME/Parser.pm"/>
</literallayout>
</section> </section>
<section id="install-modules-patchreader"> <section id="install-setupdatabase-adduser">
<title>PatchReader (&min-patchreader-ver;) [optional]</title> <title>Add a user to MySQL</title>
<para>PatchReader is only needed if you want to use Patch Viewer, a <para>You need to add a new MySQL user for
Bugzilla feature to format patches in a pretty HTML fashion. There are a Bugzilla to use. (It's not safe to have Bugzilla use the MySQL root
number of optional parameters you can configure Patch Viewer with as well, account.) The following instructions assume the defaults in
including cvsroot, cvsroot_get, lxr_root, bonsai_url, lxr_url, and <filename>localconfig</filename>;
lxr_root. Patch Viewer also optionally will use cvs, diff and interdiff if you changed those, you need to modify the
utilities if they exist on the system (interdiff can be found in the SQL command appropriately. You will need the
patchutils package at <ulink url="http://cyberelk.net/tim/patchutils/"/>. <replaceable>$db_pass</replaceable> password you set in
These programs' locations can be configured in localconfig. <filename>localconfig</filename> in
</para> <xref linkend="localconfig"/>.
</para>
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/author/JKEISER/PatchReader/"/> <para>We use an SQL <command>GRANT</command> command to create a
Documentation: <ulink url="http://www.johnkeiser.com/mozilla/Patch_Viewer.html"/> <quote>bugs</quote>
</literallayout> user. This also restricts the
<quote>bugs</quote>
user to operations within a database called
<quote>bugs</quote>, and only allows the account to connect from
<quote>localhost</quote>.
Modify it to reflect your setup if you will be connecting from
another machine or as a different user.</para>
<para>Run the <filename>mysql</filename> command-line client and
enter:</para>
<screen> <prompt>mysql&gt;</prompt> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE,
DROP,REFERENCES ON bugs.* TO bugs@localhost
IDENTIFIED BY '<replaceable>$db_pass</replaceable>';
<prompt>mysql&gt;</prompt> FLUSH PRIVILEGES</screen>
<note>
<para>If you are using MySQL 4, you need to add
the <computeroutput>LOCK TABLES</computeroutput> and
<computeroutput>CREATE TEMPORARY TABLES</computeroutput> permissions
to the list.
</para>
</note>
</section> </section>
</section> </section>
<section> <section>
<title>Configuring Bugzilla</title> <title>checksetup.pl</title>
<para> <para>
Once checksetup.pl has run successfully, Bugzilla should start up. Next, rerun <filename>checksetup.pl</filename>. It reconfirms
Proceed to the correct URL and log in with the administrator account that all the modules are present, and notices the altered
you defined in the last checksetup.pl run. localconfig file, which it assumes you have edited to your
satisfaction. It compiles the UI templates,
connects to the database using the 'bugs'
user you created and the password you defined, and creates the
'bugs' database and the tables therein.
</para> </para>
<para> <para>
You should run through the parameters on the Edit Parameters page After that, it asks for details of an administrator account. Bugzilla
(link in the footer) and set them all to appropriate values. can have multiple administrators - you can create more later - but
They key parameters are documented in <xref linkend="parameters" />. it needs one to start off with.
Enter the email address of an administrator, his or her full name,
and a suitable Bugzilla password.
</para> </para>
</section>
</section>
<section id="http"> <para>
<title>HTTP Server Configuration</title> <filename>checksetup.pl</filename> will then finish. You may rerun
<filename>checksetup.pl</filename> at any time if you wish.
<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>
</section>
<para>The plan for this section is to eventually document the specifics of how to lock
down permissions on individual web servers. <section id="http">
<title>Web server</title>
<para>Configure your web server according to the instructions in the
appropriate section. The Bugzilla Team recommends Apache.
</para> </para>
<section id="http-apache"> <section id="http-apache">
<title>Apache <productname>httpd</productname></title> <title>Apache <productname>httpd</productname></title>
<para>You will have to make sure that Apache is properly <para>Load <filename>httpd.conf</filename> in your editor.</para>
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> are allowed to override Apache's normal access
permissions or else important password information may be exposed to the
Internet.
</para>
<para>You need to configure Apache to run .cgi files outside the <para>Uncomment (or add) the following line.
This configures Apache to run .cgi files outside the
<filename class="directory">cgi-bin</filename> directory. <filename class="directory">cgi-bin</filename> directory.
Open your </para>
<filename>httpd.conf</filename> file and make sure the
following line exists and is uncommented:</para> <programlisting> AddHandler cgi-script .cgi</programlisting>
<programlisting>
AddHandler cgi-script .cgi
</programlisting>
<para>To allow <filename>.htaccess</filename> files to override <para>Apache uses <computeroutput>&lt;Directory&gt;</computeroutput>
permissions and .cgi files to run in the Bugzilla directory, make sure directives to permit fine-grained permission setting.
the following two lines are in a <computeroutput>Directory</computeroutput> Add the following two lines to a
directive that applies to the Bugzilla directory on your system <computeroutput>&lt;Directory&gt;</computeroutput> directive that
(either the Bugzilla directory or one of its parents). applies either to the Bugzilla directory or one of its parents
(e.g. the <computeroutput>&lt;Directory /var/www/html&gt;</computeroutput>
directive).
This allows Bugzilla's <filename>.htaccess</filename> files to
override global permissions, and allows .cgi files to run in the
Bugzilla directory.
</para> </para>
<programlisting>
Options +ExecCGI
AllowOverride Limit
</programlisting>
<para>You should modify the &lt;DirectoryIndex&gt; parameter for <programlisting> Options +ExecCGI +FollowSymLinks
the Apache virtual host running your Bugzilla installation to AllowOverride Limit</programlisting>
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>
<note> <para>Add <filename>index.cgi</filename> to the end
<para>For more information on Apache and its directives, see the of the <computeroutput>DirectoryIndex</computeroutput>
glossary entry on <xref linkend="gloss-apache"/>. line.</para>
<para><filename>checksetup.pl</filename> can set tighter permissions
on Bugzilla's files and directories if it knows what user the
webserver runs as. Look for the <computeroutput>User</computeroutput>
line in <filename>httpd.conf</filename>, and place that value in
the <replaceable>$webservergroup</replaceable> variable in
<filename>localconfig</filename>. Then rerun
<filename>checksetup.pl</filename>.
</para> </para>
</note>
</section> </section>
<section id="http-iis"> <section id="http-iis">
...@@ -892,8 +732,8 @@ AllowOverride Limit ...@@ -892,8 +732,8 @@ AllowOverride Limit
<para>If you need, or for some reason even want, to use Microsoft's <para>If you need, or for some reason even want, to use Microsoft's
<productname>Internet Information Services</productname> or <productname>Internet Information Services</productname> or
<productname>Personal Web Server</productname> you should be able <productname>Personal Web Server</productname> you should be able
to. You will need to configure them to know how to run CGI scripts, to. You will need to configure them to know how to run CGI scripts.
however. This is described in Microsoft Knowledge Base article This is described in Microsoft Knowledge Base article
<ulink url="http://support.microsoft.com/support/kb/articles/Q245/2/25.asp">Q245225</ulink> <ulink url="http://support.microsoft.com/support/kb/articles/Q245/2/25.asp">Q245225</ulink>
for <productname>Internet Information Services</productname> and for <productname>Internet Information Services</productname> and
<ulink url="http://support.microsoft.com/support/kb/articles/Q231/9/98.asp">Q231998</ulink> <ulink url="http://support.microsoft.com/support/kb/articles/Q231/9/98.asp">Q231998</ulink>
...@@ -929,19 +769,19 @@ AllowOverride Limit ...@@ -929,19 +769,19 @@ AllowOverride Limit
</para> </para>
<programlisting> <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/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/*.pl filter_deny
ns_register_filter preauth GET /bugzilla/syncshadowdb 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/runtests.sh filter_deny
ns_register_filter preauth GET /bugzilla/data/* filter_deny ns_register_filter preauth GET /bugzilla/data/* filter_deny
ns_register_filter preauth GET /bugzilla/template/* filter_deny ns_register_filter preauth GET /bugzilla/template/* filter_deny
proc filter_deny { why } { proc filter_deny { why } {
ns_log Notice "filter_deny" ns_log Notice "filter_deny"
return "filter_return" return "filter_return"
} }
</programlisting> </programlisting>
<warning> <warning>
...@@ -969,16 +809,218 @@ proc filter_deny { why } { ...@@ -969,16 +809,218 @@ proc filter_deny { why } {
</para> </para>
</note> </note>
</section> </section>
<section id="security-access">
<title>Web Server Access Controls</title>
<para>Users of Apache can skip this section because
Bugzilla ships with <filename>.htaccess</filename> files which
restrict access in the manner required.
Users of other webservers, read on.
</para>
<para>There are several files in the Bugzilla directory
that should not be accessible from the web. You need to configure
your webserver so they they aren't. Not doing this may reveal
sensitive information such as database passwords.
</para>
<itemizedlist spacing="compact">
<listitem>
<para>In the main Bugzilla directory, you should:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Block:
<simplelist type="inline">
<member><filename>*.pl</filename></member>
<member><filename>*localconfig*</filename></member>
<member><filename>runtests.sh</filename></member>
</simplelist>
</para>
</listitem>
<listitem>
<para>But allow:
<simplelist type="inline">
<member><filename>localconfig.js</filename></member>
<member><filename>localconfig.rdf</filename></member>
</simplelist>
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>In <filename class="directory">data</filename>:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Block everything</para>
</listitem>
<listitem>
<para>But allow:
<simplelist type="inline">
<member><filename>duplicates.rdf</filename></member>
</simplelist>
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>In <filename class="directory">data/webdot</filename>:</para>
<itemizedlist spacing="compact">
<listitem>
<para>If you use a remote webdot server:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Block everything</para>
</listitem>
<listitem>
<para>But allow
<simplelist type="inline">
<member><filename>*.dot</filename></member>
</simplelist>
only for the remote webdot server</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Otherwise, if you use a local GraphViz:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Block everything</para>
</listitem>
<listitem>
<para>But allow:
<simplelist type="inline">
<member><filename>*.png</filename></member>
<member><filename>*.gif</filename></member>
<member><filename>*.jpg</filename></member>
<member><filename>*.map</filename></member>
</simplelist>
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>And if you don't use any dot:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Block everything</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>In <filename class="directory">Bugzilla</filename>:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Block everything</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>In <filename class="directory">template</filename>:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Block everything</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>You should test to make sure that the files mentioned above are
not accessible from the Internet, especially your
<filename>localconfig</filename> file which contains your database
password. To test, simply point your web browser at the file; for
example, to test mozilla.org's installation, we'd try to access
<ulink url="http://bugzilla.mozilla.org/localconfig"/>. You should
get a <errorcode>403</errorcode> <errorname>Forbidden</errorname>
error.
</para>
</section> </section>
</section>
<section id="install-config-bugzilla">
<title>Bugzilla</title>
<para>
Your Bugzilla should now be working. Access
<filename>http://&lt;your-bugzilla-server&gt;/</filename> -
you should see the Bugzilla
front page. If not, consult the Troubleshooting section,
<xref linkend="troubleshooting"/>.
</para>
<para>
Log in with the administrator account you defined in the last
<filename>checksetup.pl</filename> run. You should go through
the parameters on the Edit Parameters page
(see link in the footer) and see if there are any you wish to
change.
They key parameters are documented in <xref linkend="parameters"/>;
you should certainly alter
<command>maintainer</command> and <command>urlbase</command>;
you may also want to alter
<command>cookiepath</command> or <command>requirelogin</command>.
</para>
<para>
This would also be a good time to revisit the
<filename>localconfig</filename> file and make sure that the
names of the priorities, severities, platforms and operating systems
are those you wish to use when you start creating bugs. Remember
to rerun <filename>checksetup.pl</filename> if you change it.
</para>
<para>
Bugzilla has several optional features which require extra
configuration. You can read about those in
<xref linkend="extraconfig"/>.
</para>
</section>
</section>
<section id="extraconfig"> <section id="extraconfig">
<title>Optional Additional Configuration</title> <title>Optional Additional Configuration</title>
<para>
Bugzilla has a number of optional features. This section describes how
to configure or enable them.
</para>
<section>
<title>Bug Graphs</title>
<para>If you have installed the necessary Perl modules you
can start collecting statistics for the nifty Bugzilla
graphs.</para>
<screen><prompt>bash#</prompt> <command>crontab -e</command></screen>
<para>
This should bring up the crontab file in your editor.
Add a cron entry like this to run
<filename>collectstats.pl</filename>
daily at 5 after midnight:
</para>
<programlisting>5 0 * * * cd &lt;your-bugzilla-directory&gt; ; ./collectstats.pl</programlisting>
<para>After two days have passed you'll be able to view bug graphs from
the Reports page.</para>
</section>
<section> <section>
<title>Dependency Charts</title> <title>Dependency Charts</title>
<para>As well as the text-based dependency graphs, Bugzilla also <para>As well as the text-based dependency trees, Bugzilla also
supports dependency graphing, using a package called 'dot'. supports a graphical view of dependency relationships, using a
package called 'dot'.
Exactly how this works is controlled by the 'webdotbase' parameter, Exactly how this works is controlled by the 'webdotbase' parameter,
which can have one of three values: which can have one of three values:
</para> </para>
...@@ -1006,78 +1048,64 @@ proc filter_deny { why } { ...@@ -1006,78 +1048,64 @@ proc filter_deny { why } {
</orderedlist> </orderedlist>
</para> </para>
<para>So, to get this working, install <para>The easiest way to get this working is to install
<ulink url="http://www.graphviz.org/">GraphViz</ulink>. If you <ulink url="http://www.graphviz.org/">GraphViz</ulink>. If you
do that, you need to do that, you need to
<ulink url="http://httpd.apache.org/docs/mod/mod_imap.html">enable <ulink url="http://httpd.apache.org/docs/mod/mod_imap.html">enable
server-side image maps</ulink> in Apache. server-side image maps</ulink> in Apache.
Alternatively, you could set up a webdot server, or use the AT&amp;T Alternatively, you could set up a webdot server, or use the AT&amp;T
public webdot server (the public webdot server. This is the default for the webdotbase param,
default for the webdotbase param). Note that AT&amp;T's server won't work but it's often overloaded and slow. Note that AT&amp;T's server
won't work
if Bugzilla is only accessible using HARTS. if Bugzilla is only accessible using HARTS.
<emphasis>Editor's note: What the heck is HARTS? Google doesn't know...
</emphasis>
</para> </para>
</section> </section>
<section> <section>
<title>Bug Graphs</title> <title>The Whining Cron</title>
<para>As long as you installed the GD and Graph::Base Perl modules you <para>What good are
might as well turn on the nifty Bugzilla bug reporting graphs.</para> bugs if they're not annoying? To help make them more so you
can set up Bugzilla's automatic whining system to complain at engineers
which leave their bugs in the NEW or REOPENED state without triaging them.
</para>
<para>
<para>Add a cron entry like this to run This can be done by
<filename>collectstats.pl</filename> adding the following command as a daily crontab entry, in the same manner
daily at 5 after midnight: as explained above for bug graphs. This example runs it at 12.55am.
<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>
<para>After two days have passed you'll be able to view bug graphs from <programlisting>55 0 * * * cd &lt;your-bugzilla-directory&gt; ; ./whineatnews.pl</programlisting>
the Bug Reports page.</para>
</section> </section>
<section> <section id="patch-viewer">
<title>The Whining Cron</title> <title>Patch Viewer</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 or REOPENED state without triaging them.
</para>
<para> <para>
This can be done by Patch Viewer is the engine behind Bugzilla's graphical display of
adding the following command as a daily crontab entry (for help on that code patches. You can integrate this with copies of the
see that crontab man page): <filename>cvs</filename>, <filename>lxr</filename> and
<simplelist> <filename>bonsai</filename> tools if you have them, by giving
<member> the locations of your installation of these tools in
<computeroutput> <filename>editparams.cgi</filename>.
<command>cd &lt;your-bugzilla-directory&gt; ;
./whineatnews.pl</command>
</computeroutput>
</member>
</simplelist>
</para> </para>
<tip> <para>
<para>Depending on your system, crontab may have several manpages. Patch Viewer also optionally will use the
The following command should lead you to the most useful page for <filename>cvs</filename>, <filename>diff</filename> and
this purpose: <filename>interdiff</filename>
<programlisting> command-line utilities if they exist on the system.
man 5 crontab Interdiff can be obtained from
</programlisting> <ulink url="http://cyberelk.net/tim/patchutils/"/>.
If these programs are not in the system path, you can configure
their locations in <filename>localconfig</filename>.
</para> </para>
</tip>
</section> </section>
<section id="bzldap"> <section id="bzldap">
...@@ -1166,7 +1194,7 @@ man 5 crontab ...@@ -1166,7 +1194,7 @@ man 5 crontab
<term>LDAPBaseDN</term> <term>LDAPBaseDN</term>
<listitem> <listitem>
<para>The LDAPBaseDN parameter should be set to the location in <para>The LDAPBaseDN parameter should be set to the location in
your LDAP tree that you would like to search for e-mail addresses. your LDAP tree that you would like to search for email addresses.
Your uids should be unique under the DN specified here. Your uids should be unique under the DN specified here.
</para> </para>
<para>Ex. <quote>ou=People,o=Company</quote></para> <para>Ex. <quote>ou=People,o=Company</quote></para>
...@@ -1189,7 +1217,7 @@ man 5 crontab ...@@ -1189,7 +1217,7 @@ man 5 crontab
<term>LDAPmailattribute</term> <term>LDAPmailattribute</term>
<listitem> <listitem>
<para>The LDAPmailattribute parameter should be the name of the <para>The LDAPmailattribute parameter should be the name of the
attribute which contains the e-mail address your users will enter attribute which contains the email address your users will enter
into the Bugzilla login boxes. into the Bugzilla login boxes.
</para> </para>
<para>Ex. <quote>mail</quote></para> <para>Ex. <quote>mail</quote></para>
...@@ -1201,75 +1229,78 @@ man 5 crontab ...@@ -1201,75 +1229,78 @@ man 5 crontab
<section id="content-type"> <section id="content-type">
<title>Preventing untrusted Bugzilla content from executing malicious <title>Prevent users injecting malicious
Javascript code</title> Javascript</title>
<para>It is possible for a Bugzilla attachment to contain malicious <para>It is possible for a Bugzilla user to take advantage of character
Javascript set encoding ambiguities to inject HTML into Bugzilla comments. This
code, which would be executed in the domain of your Bugzilla, thereby could include malicious scripts.
making it possible for the attacker to e.g. steal your login cookies.
Due to internationalization concerns, we are unable to Due to internationalization concerns, we are unable to
incorporate by default the code changes necessary to fulfill the CERT incorporate by default the code changes suggested by
advisory requirements mentioned in
<ulink <ulink
url="http://www.cert.org/tech_tips/malicious_code_mitigation.html/#3"/>. url="http://www.cert.org/tech_tips/malicious_code_mitigation.html#3">
the CERT advisory</ulink> on this issue.
If your installation is for an English speaking audience only, making the If your installation is for an English speaking audience only, making the
change below will prevent this problem. change below will prevent this problem.
</para> </para>
<para>Simply locate the following line in <para>Simply locate the following line in
<filename>Bugzilla/CGI.pm</filename>: <filename>Bugzilla/CGI.pm</filename>:
<programlisting> <programlisting>$self->charset('');</programlisting>
$self->charset('');
</programlisting>
and change it to: and change it to:
<programlisting> <programlisting>$self->charset('ISO-8859-1');</programlisting>
$self->charset('ISO-8859-1');
</programlisting>
</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> </para>
</section> </section>
<section id="mod-throttle" <section id="mod-throttle"
xreflabel="Using mod_throttle to prevent Denial of Service attacks"> xreflabel="Using mod_throttle to prevent Denial of Service attacks">
<title> <title>
<filename>mod_throttle</filename> <filename>mod_throttle</filename></title>
and Security</title>
<para>It is possible for a user, by mistake or on purpose, to access <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 the database many times in a row which can result in very slow access
speeds for other users. If your Bugzilla installation is experiencing speeds for other users. If your Bugzilla installation is experiencing
this problem , you may install the Apache module this problem, you may install the Apache module
<filename>mod_throttle</filename> <filename>mod_throttle</filename>
which can limit connections by IP address. You may download this module
which can limit connections by ip-address. You may download this module
at at
<ulink url="http://www.snert.com/Software/mod_throttle/"/>. <ulink url="http://www.snert.com/Software/mod_throttle/"/>.
Follow the instructions to install into your Apache install. Follow the instructions to install into your Apache install.
<emphasis>This module only functions with the Apache web <emphasis>This module only functions with the Apache web
server!</emphasis> server!</emphasis>
You may use the The command you need is
<command>ThrottleClientIP</command> <command>ThrottleClientIP</command>. See the
<ulink url="http://www.snert.com/Software/mod_throttle/">documentation</ulink>
command provided by this module to accomplish this goal. See the
<ulink url="http://www.snert.com/Software/mod_throttle/">Module
Instructions</ulink>
for more information.</para> for more information.</para>
</section> </section>
<section id="security-networking">
<title>TCP/IP Ports</title>
<para>A single-box Bugzilla only requires port 80, plus port 25 if
you are using the optional email interface. You should firewall all
other ports and/or disable services listening on them.
</para>
</section>
<section id="security-daemon">
<title>Daemon Accounts</title>
<para>Many daemons, such as Apache's httpd and MySQL's mysqld default to
running as either <quote>root</quote> or <quote>nobody</quote>. Running
as <quote>root</quote> introduces obvious security problems, but the
problems introduced by running everything as <quote>nobody</quote> may
not be so obvious. Basically, if you're running every daemon as
<quote>nobody</quote> and one of them gets compromised, they all get
compromised. For this reason it is recommended that you create a user
account for each daemon.
</para>
</section>
</section> </section>
<section id="os-specific"> <section id="os-specific">
<title>OS Specific Installation Notes</title> <title>OS-Specific Installation Notes</title>
<para>Many aspects of the Bugzilla installation can be affected by the <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 the operating system you choose to install it on. Sometimes it can be made
...@@ -1285,7 +1316,7 @@ man 5 crontab ...@@ -1285,7 +1316,7 @@ man 5 crontab
<section id="os-win32"> <section id="os-win32">
<title>Microsoft Windows</title> <title>Microsoft Windows</title>
<para>Making Bugzilla work on windows is still a painful processes. <para>Making Bugzilla work on Windows is still a painful processes.
The Bugzilla Team is working to make it easier, but that goal is not 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 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 recommend doing so on a Unix based system such as GNU/Linux. As of this
...@@ -1298,8 +1329,8 @@ man 5 crontab ...@@ -1298,8 +1329,8 @@ man 5 crontab
<![%bz-devel;[ <![%bz-devel;[
Because this is a development version of the guide, these instructions Because this is a development version of the guide, these instructions
are subject to change without notice. In fact, the Bugzilla Team hopes 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 to have Bugzilla reasonably close to "out of
the box" compatibility by the 2.18 release. the box" compatibility with Windows by the 2.18 release.
]]> ]]>
</para> </para>
...@@ -1334,20 +1365,14 @@ C:\perl&gt; <command>ppm &lt;module name&gt;</command> ...@@ -1334,20 +1365,14 @@ C:\perl&gt; <command>ppm &lt;module name&gt;</command>
url="http://openinteract.sourceforge.net/">OpenInteract's website</ulink>. url="http://openinteract.sourceforge.net/">OpenInteract's website</ulink>.
</para> </para>
</note> </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"/>.
</para>
</tip>
</section> </section>
<section id="win32-code-changes"> <section id="win32-code-changes">
<title>Code changes required to run on win32</title> <title>Code changes required to run on win32</title>
<para>As Bugzilla still doesn't run "out of the box" on <para>As Bugzilla still doesn't run "out of the box" on
Windows, code has to be modified. This section is an attempt to Windows, code has to be modified. This section lists the required
list the required changes. changes.
</para> </para>
<section id="win32-code-checksetup"> <section id="win32-code-checksetup">
...@@ -1377,7 +1402,7 @@ my $webservergid = '8' ...@@ -1377,7 +1402,7 @@ my $webservergid = '8'
<section id="win32-code-bugmail"> <section id="win32-code-bugmail">
<title>Changes to <filename>BugMail.pm</filename></title> <title>Changes to <filename>BugMail.pm</filename></title>
<para>To make bug e-mail work on Win32 (until <para>To make bug email work on Win32 (until
<ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=84876">bug <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=84876">bug
84876</ulink> lands), the 84876</ulink> lands), the
simplest way is to have the Net::SMTP Perl module installed and simplest way is to have the Net::SMTP Perl module installed and
...@@ -1409,7 +1434,7 @@ $smtp->quit; ...@@ -1409,7 +1434,7 @@ $smtp->quit;
</programlisting> </programlisting>
<para>Don't forget to change the name of your SMTP server and the <para>Don't forget to change the name of your SMTP server and the
domain of the sending e-mail address (after the '@') in the above domain of the sending email address (after the '@') in the above
lines of code.</para> lines of code.</para>
</section> </section>
...@@ -1430,7 +1455,7 @@ $smtp->quit; ...@@ -1430,7 +1455,7 @@ $smtp->quit;
<note> <note>
<para>If using Apache on windows, you can set the <ulink <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> 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 directive in your Apache config to avoid having
to modify the first line of every script to contain your path to to modify the first line of every script to contain your path to
perl instead of <filename>/usr/bin/perl</filename>. perl instead of <filename>/usr/bin/perl</filename>.
</para> </para>
...@@ -1443,24 +1468,22 @@ $smtp->quit; ...@@ -1443,24 +1468,22 @@ $smtp->quit;
<section id="os-macosx"> <section id="os-macosx">
<title><productname>Mac OS X</productname></title> <title><productname>Mac OS X</productname></title>
<para>There are a lot of common libraries and utilities out there that <para>Apple did not include the GD library with Mac OS X. Bugzilla
Apple did not include with Mac OS X, but which run perfectly well on it. needs this for bug graphs.</para>
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 <para>You can install it using a program called
Fink, which is similar in nature to the CPAN installer, but installs Fink, which is similar in nature to the CPAN installer, but installs
common GNU utilities. Fink is available from common GNU utilities. Fink is available from
<ulink url="http://sourceforge.net/projects/fink/"/>.</para> <ulink url="http://sourceforge.net/projects/fink/"/>.</para>
<para>Follow the instructions for setting up Fink. Once it's installed, <para>Follow the instructions for setting up Fink. Once it's installed,
you'll want to use it to install the gd2 package. you'll want to use it to install the <filename>gd2</filename> package.
</para> </para>
<para>It will prompt you for a number of dependencies, type 'y' and hit <para>It will prompt you for a number of dependencies, type 'y' and hit
enter to install all of the dependencies and then watch it work. You will enter to install all of the dependencies and then watch it work. You will
then be able to use <glossterm linkend="gloss-cpan">CPAN</glossterm> to then be able to use <glossterm linkend="gloss-cpan">CPAN</glossterm> to
install the GD perl module. install the GD Perl module.
</para> </para>
<note> <note>
...@@ -1477,7 +1500,7 @@ $smtp->quit; ...@@ -1477,7 +1500,7 @@ $smtp->quit;
</para> </para>
</note> </note>
<para>Also available via Fink is expat. Once running using fink to <para>Also available via Fink is expat. After using fink to
install the expat package you will be able to install install the expat package you will be able to install
XML::Parser using CPAN. There is one caveat. Unlike recent versions of XML::Parser using CPAN. There is one caveat. Unlike recent versions of
the GD module, XML::Parser doesn't prompt for the location of the the GD module, XML::Parser doesn't prompt for the location of the
...@@ -1527,7 +1550,7 @@ $smtp->quit; ...@@ -1527,7 +1550,7 @@ $smtp->quit;
</screen> </screen>
<calloutlist> <calloutlist>
<callout arearefs="test-mailtools"> <callout arearefs="test-mailtools">
<para>for Bugzilla e-mail integration</para> <para>for Bugzilla email integration</para>
</callout> </callout>
</calloutlist> </calloutlist>
...@@ -1535,279 +1558,53 @@ $smtp->quit; ...@@ -1535,279 +1558,53 @@ $smtp->quit;
</section> </section>
<section id="security">
<title>Bugzilla Security</title>
<warning>
<para>Poorly-configured MySQL and Bugzilla installations have
given attackers full access to systems in the past. Please take these
guidelines seriously, even for Bugzilla machines hidden away behind
your firewall. 80% of all computer trespassers are insiders, not
anonymous crackers.</para>
<para>This is not meant to be a comprehensive list of every possible
security issue pertaining to the software mentioned in this section.
There is
no subsitute for reading the information written by the authors of any
software running on your system.
</para>
</warning>
<section id="security-networking">
<title>TCP/IP Ports</title>
<!-- TODO: Make this make sense (TCP/IP) -->
<para>TCP/IP defines 65,000 some ports for trafic. Of those, Bugzilla
only needs 1, or 2 if you need to use features that require e-mail such
as bug moving or the e-mail interface from contrib. You should audit
your server and make sure that you aren't listening on any ports you
don't need to be. You may also wish to use some kind of firewall
software to be sure that trafic can only be recieved on ports you
specify.
</para>
</section>
<section id="security-mysql">
<title>MySQL</title>
<para>MySQL ships by default with many settings that should be changed.
By defaults it allows anybody to connect from localhost without a
password and have full administrative capabilities. It also defaults to
not have a root password (this is <emphasis>not</emphasis> the same as
the system root). Also, many installations default to running
<application>mysqld</application> as the system root.
</para>
<orderedlist>
<listitem>
<para>Consult the documentation that came with your system for
information on making <application>mysqld</application> run as an
unprivleged user.
</para>
</listitem>
<listitem>
<para>You should also be sure to disable the anonymous user account
and set a password for the root user. This is accomplished using the
following commands:
</para>
<programlisting>
<prompt>bash$</prompt> mysql mysql
<prompt>mysql&gt;</prompt> DELETE FROM user WHERE user = '';
<prompt>mysql&gt;</prompt> UPDATE user SET password = password('<replaceable>new_password</replaceable>') WHERE user = 'root';
<prompt>mysql&gt;</prompt> FLUSH PRIVILEGES;
</programlisting>
<para>From this point forward you will need to use
<command>mysql -u root -p</command> and enter
<replaceable>new_password</replaceable> when prompted when using the
mysql client.
</para>
</listitem>
<listitem> <section id="troubleshooting">
<para>If you run MySQL on the same machine as your httpd server, you <title>Troubleshooting</title>
should consider disabling networking from within MySQL by adding
the following to your <filename>/etc/my.conf</filename>:
</para>
<programlisting>
[myslqd]
# Prevent network access to MySQL.
skip-networking
</programlisting>
</listitem>
<listitem> <para>This section gives solutions to common Bugzilla installation
<para>You may also consider running MySQL, or even all of Bugzilla problems. If none of the section headings seems to match your
in a chroot jail; however, instructions for doing that are beyond problem, read the general advice.
the scope of this document.
</para> </para>
</listitem>
</orderedlist>
</section>
<section id="security-daemon"> <section id="general-advice">
<title>Daemon Accounts</title> <title>General Advice</title>
<para>
<para>Many daemons, such as Apache's httpd and MySQL's mysqld default to If you can't get <filename>checksetup.pl</filename> to run to
running as either <quote>root</quote> or <quote>nobody</quote>. Running completion, it normally explains what's wrong and how to fix it.
as <quote>root</quote> introduces obvious security problems, but the If you can't work it out, or if it's being uncommunicative, post
problems introduced by running everything as <quote>nobody</quote> may the errors in the
not be so obvious. Basically, if you're running every daemon as <ulink url="news://news.mozilla.org/netscape.public.mozilla.webtools">netscape.public.mozilla.webtools</ulink>
<quote>nobody</quote> and one of them gets compromised, they all get newsgroup.
compromised. For this reason it is recommended that you create a user
account for each daemon.
</para> </para>
<note> <para>
<para>You will need to set the <varname>webservergroup</varname> to If you have made it all the way through
the group you created for your webserver to run as in <xref linkend="installation"/> (Installation) and
<filename>localconfig</filename>. This will allow <xref linkend="configuration"/> (Configuration) but
<command>./checksetup.pl</command> to better adjust the file accessing the Bugzilla URL doesn't work,
permissions on your Bugzilla install so as to not require making the first thing to do is to check your webserver error log. For
anything world-writable. Apache, this is often located at
<filename>/etc/logs/httpd/error_log</filename>. The error messages
you see may be self-explanatory enough to enable you to diagnose and
fix the problem. If not, see below for some commonly-encountered
errors. If that doesn't help, post the errors to the newsgroup.
</para> </para>
</note>
</section> </section>
<section id="security-access"> <section>
<title>Web Server Access Controls</title> <title>I installed a Perl module, but
<filename>checksetup.pl</filename> claims it's not installed!</title>
<para>There are many files that are placed in the Bugzilla directory
area that should not be accessable from the web. Because of the way
Bugzilla is currently laid out, the list of what should and should
not be accessible is rather complicated.
</para>
<para>Users of Apache don't need to worry about this, however, because
Bugzilla ships with .htaccess files which restrict access to all the
sensitive files in this section. Users of other webservers, read on.
</para>
<itemizedlist spacing="compact">
<listitem>
<para>In the main Bugzilla directory, you should:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Block:
<simplelist type="inline">
<member><filename>*.pl</filename></member>
<member><filename>*localconfig*</filename></member>
<member><filename>runtests.sh</filename></member>
</simplelist>
</para>
</listitem>
<listitem>
<para>But allow:
<simplelist type="inline">
<member><filename>localconfig.js</filename></member>
<member><filename>localconfig.rdf</filename></member>
</simplelist>
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>In <filename class="directory">data</filename>:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Block everything</para>
</listitem>
<listitem>
<para>But allow:
<simplelist type="inline">
<member><filename>duplicates.rdf</filename></member>
</simplelist>
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>In <filename class="directory">data/webdot</filename>:</para>
<itemizedlist spacing="compact">
<listitem>
<para>If you use a remote webdot server:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Block everything</para>
</listitem>
<listitem>
<para>But allow
<simplelist type="inline">
<member><filename>*.dot</filename></member>
</simplelist>
only for the remote webdot server</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Otherwise, if you use a local GraphViz:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Block everything</para>
</listitem>
<listitem>
<para>But allow:
<simplelist type="inline">
<member><filename>*.png</filename></member>
<member><filename>*.gif</filename></member>
<member><filename>*.jpg</filename></member>
<member><filename>*.map</filename></member>
</simplelist>
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>And if you don't use any dot:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Block everything</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>In <filename class="directory">Bugzilla</filename>:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Block everything</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>In <filename class="directory">template</filename>:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Block everything</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>You should test to make sure that the files mentioned above are
not accessible from the Internet, especially your
<filename>localconfig</filename> file which contains your database
password. To test, simply point your web browser at the file; for
example, to test mozilla.org's installation, we'd try to access
<ulink url="http://bugzilla.mozilla.org/localconfig"/>. You should
get a <errorcode>403</errorcode> <errorname>Forbidden</errorname>
error.
</para>
<caution>
<para>Not following the instructions in this section, including
testing, may result in sensitive information being globally
accessible.
</para>
</caution>
<tip> <para>
<para>You should check <xref linkend="http"/> to see if instructions You have two versions of Perl on your machine. You are installing
have been included for your web server. You should also compare those modules into one, and Bugzilla is using the other. Rerun the CPAN
instructions with this list to make sure everything is properly commands (or manual compile) using the full path to Perl from the
accounted for. top of <filename>checksetup.pl</filename>. This will make sure you
are installing the modules in the right place.
</para> </para>
</tip>
</section>
</section> </section>
<section id="troubleshooting">
<title>Troubleshooting</title>
<para>This section gives solutions to common Bugzilla installation
problems.
</para>
<section> <section>
<title>Bundle::Bugzilla makes me upgrade to Perl 5.6.1</title> <title>Bundle::Bugzilla makes me upgrade to Perl 5.6.1</title>
...@@ -1900,36 +1697,25 @@ skip-networking ...@@ -1900,36 +1697,25 @@ skip-networking
<para>This is caused by a bug in the version of <para>This is caused by a bug in the version of
<productname>File::Temp</productname> that is distributed with perl <productname>File::Temp</productname> that is distributed with perl
5.6.0. Many minor variations of this error have been reported. Examples 5.6.0. Many minor variations of this error have been reported:
can be found in <xref linkend="trouble-filetemp-errors"/>.
</para> </para>
<figure id="trouble-filetemp-errors"> <programlisting>Your vendor has not defined Fcntl macro O_NOINHERIT, used
<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. at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 208.
Your vendor has not defined Fcntl macro O_EXLOCK, used Your vendor has not defined Fcntl macro O_EXLOCK, used
at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 210. at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 210.
Your vendor has not defined Fcntl macro O_TEMPORARY, used Your vendor has not defined Fcntl macro O_TEMPORARY, used
at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 233. at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 233.</programlisting>
</programlisting>
</figure>
<para>Numerous people have reported that upgrading to version 5.6.1 <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 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 the following patch, which is also
available as a <ulink url="../xml/filetemp.patch">patch file</ulink>. available as a <ulink url="../xml/filetemp.patch">patch file</ulink>.
</para> </para>
<figure id="trouble-filetemp-patch"> <programlisting><![CDATA[--- File/Temp.pm.orig Thu Feb 6 16:26:00 2003
<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 +++ File/Temp.pm Thu Feb 6 16:26:23 2003
@@ -205,6 +205,7 @@ @@ -205,6 +205,7 @@
# eg CGI::Carp # eg CGI::Carp
...@@ -1946,9 +1732,7 @@ at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 233. ...@@ -1946,9 +1732,7 @@ at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 233.
+ local *CORE::GLOBAL::die = sub {}; + local *CORE::GLOBAL::die = sub {};
$bit = &$func(); $bit = &$func();
1; 1;
}; };]]></programlisting>
]]></programlisting>
</figure>
</section> </section>
</section> </section>
</chapter> </chapter>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment