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 @@
<!ENTITY administration SYSTEM "administration.xml">
<!ENTITY using SYSTEM "using.xml">
<!ENTITY integration SYSTEM "integration.xml">
<!ENTITY future SYSTEM "future.xml">
<!ENTITY index SYSTEM "index.xml">
<!ENTITY customization SYSTEM "customization.xml">
<!ENTITY patches SYSTEM "patches.xml">
<!ENTITY variants SYSTEM "variants.xml">
<!ENTITY introduction SYSTEM "introduction.xml">
<!ENTITY revhistory SYSTEM "revhistory.xml">
<!ENTITY modules SYSTEM "modules.xml">
<!-- Things to change for a stable release:
* bz-ver to current stable
......@@ -32,9 +30,9 @@
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-date "2004-01-15">
<!ENTITY bz-date "2004-01-24">
<!ENTITY % bz-devel "INCLUDE">
<!ENTITY bz "http://www.bugzilla.org/">
......@@ -54,7 +52,7 @@
<!ENTITY min-dbd-mysql-ver "2.1010">
<!ENTITY min-dbi-ver "1.32">
<!ENTITY min-date-format-ver "2.21">
<!ENTITY min-cgi-ver "2.88">
<!ENTITY min-cgi-ver "2.93">
<!-- Optional modules -->
<!ENTITY min-gd-ver "1.20">
<!ENTITY min-gd-graph-ver "any">
......@@ -136,12 +134,6 @@
<!-- About This Guide -->
&about;
<!-- Introduction -->
&introduction;
<!-- Using Bugzilla -->
&using;
<!-- Installing Bugzilla -->
&installation;
......@@ -151,12 +143,18 @@
<!-- Customizing Bugzilla -->
&customization;
<!-- Using Bugzilla -->
&using;
<!-- Appendix: The Frequently Asked Questions -->
&faq;
<!-- Appendix: Custom Patches -->
&patches;
<!-- Appendix: Manually Installing Perl Modules -->
&modules;
<!-- Appendix: GNU Free Documentation License -->
&gfdl;
......
docs/en/xml/about.xml
View file @ 98be5699
......@@ -6,8 +6,11 @@
<section id="copyright">
<title>Copyright Information</title>
<para>This document is copyright (c) 2000-2004 by the various
Bugzilla contributors who wrote it.</para>
<blockquote>
<attribution>Copyright (c) 2000-2004 The Bugzilla Team</attribution>
<para>
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation
......@@ -45,10 +48,10 @@
</para>
<para>
Although the Bugzilla development team has taken great care to
ensure that all exploitable bugs or options have been
fixed, security holes surely exist. Great care should be taken both in
ensure that all exploitable bugs have been fixed, security holes surely
exist in any piece of code. Great care should be taken both in
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
your security needs are met.
</para>
......@@ -68,16 +71,36 @@
</para>
<para>
The latest version of this guide can always be found at <ulink
url="http://www.bugzilla.org"/>, or checked out via CVS.
(Please follow the <ulink url="http://www.mozilla.org/cvs.html">Mozilla
url="http://www.bugzilla.org"/>, or checked out via CVS by
following the <ulink url="http://www.mozilla.org/cvs.html">Mozilla
CVS</ulink> instructions and check out the
<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.
</para>
<para>
The Bugzilla Guide is currently only available in English.
If you would like to volunteer to translate it, please contact
The Bugzilla Guide, or a section of it, is also available in
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>.
</para>
</section>
......@@ -113,7 +136,7 @@
</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">
netscape.public.mozilla.webtools</ulink>
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"> -->
<chapter id="customization">
<title>Customizing 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>
<title>Customising Bugzilla</title>
<section id="cust-templates">
<title>Template Customization</title>
......@@ -54,78 +18,45 @@
<xref linkend="template-http-accept"/>.
</para>
<section id="template-directory">
<title>Template Directory Structure</title>
<section>
<title>What to Edit</title>
<para>
The template directory structure starts with top level directory
named <filename>template</filename>, which contains a directory
for each installed localization. The next level defines the
language used in the templates. Bugzilla comes with English
templates, so the directory name is <filename>en</filename>,
and we will discuss <filename>template/en</filename> throughout
the documentation. Below <filename>template/en</filename> is the
<filename>default</filename> directory, which contains all the
standard templates shipped with Bugzilla.
</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.
The template directory structure is that there's a top level directory,
<filename>template</filename>, which contains a directory for
each installed localization. The default English templates are
therefore in <filename>en</filename>. Underneath that, there
is the <filename>default</filename> directory and optionally the
<filename>custom</filename> directory. The <filename>default</filename>
directory contains all the templates shipped with Bugzilla, whereas
the <filename>custom</filename> directory does not exist at first and
must be created if you want to use it.
</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
templates found in <filename>template/en/default</filename>.
This is probably the best way to go about it if you are going to
be upgrading Bugzilla through CVS, because if you then execute
a <command>cvs update</command>, any changes you have made will
be merged automagically with the updated versions.
templates in <filename>template/en/default</filename>. This is
probably the best method for small changes if you are going to use
the CVS method of upgrading, because if you then execute a
<command>cvs update</command>, any template fixes will get
automagically merged into your modified versions.
</para>
<note>
<para>
If you use this method, and CVS conflicts occur during an
update, the conflicted templates (and possibly other parts
of your installation) will not work until they are resolved.
If you use this method, your installation will break if CVS conflicts
occur.
</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>
The second method of customization should be used if you
use the overwriting method of upgrade, because otherwise
your changes will be lost. This method may also be better if
The other method is to copy the templates to be modified into a
mirrored directory
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
changes, because it is guaranteed that the contents of this directory
will not be touched during an upgrade, and you can then decide whether
......@@ -134,9 +65,9 @@
</para>
<para>
Using this method, your installation may break if incompatible
changes are made to the template interface. Such changes should
be documented in the release notes, provided you are using a
If you use this method, your installation may break if incompatible
changes are made to the template interface. If such changes are made
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
need to deal with this one yourself, although if possible the changes
will be mentioned before they occur in the deprecations section of the
......@@ -145,25 +76,21 @@
<note>
<para>
Regardless of which method you choose, it is recommended that
you run <command>./checksetup.pl</command> after creating or
editing any templates in the <filename>template/en/default</filename>
directory, and after editing any templates in the
<filename>custom</filename> directory.
Don't directly edit the compiled templates in
<filename class="directory">data/template/*</filename> - your
changes will be lost when Template Toolkit recompiles them.
</para>
</note>
<warning>
<para>
It is <emphasis>required</emphasis> that you run
<command>./checksetup.pl</command> after creating a new
template in the <filename>custom</filename> directory. Failure
to do so will raise an incomprehensible error message.
<note>
<para>It is recommended that you run <command>./checksetup.pl</command>
after any template edits, especially if you've created a new file in
the <filename class="directory">custom</filename> directory.
</para>
</warning>
</note>
</section>
<section id="template-edit">
<section>
<title>How To Edit Templates</title>
<note>
......@@ -171,7 +98,7 @@
If you are making template changes that you intend on submitting back
for inclusion in standard Bugzilla, you should read the relevant
sections of the
<ulink url="http://www.bugzilla.org/docs/developer.html">Developers'
<ulink url="http://www.bugzilla.org/developerguide.html">Developers'
Guide</ulink>.
</para>
</note>
......@@ -189,7 +116,7 @@
to properly HTML filter data that has been passed into the template.
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
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
your installation to cross-site scripting attacks.
</para>
......@@ -198,18 +125,16 @@
Also note that Bugzilla adds a few filters of its own, that are not
in standard Template Toolkit. In particular, the 'url_quote' filter
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
on), including the HTML-special characters, so there's never a need to
HTML filter afterwards.
</para>
<para>
Editing templates is a good way of doing a <quote>poor man's custom
fields</quote>.
Editing templates is a good way of doing a "poor man's custom fields".
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>,
then you can just
a free-form text entry box for "Build Identifier", then you can just
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.
</para>
......@@ -217,29 +142,22 @@
</section>
<section id="template-formats">
<title>Template Formats and Types</title>
<section>
<title>Template Formats</title>
<para>
Some CGI's have the ability to use more than one template. For example,
<filename>buglist.cgi</filename> can output itself as RDF, or as two
formats of HTML (complex and simple). The mechanism that provides this
feature is extensible.
Some CGIs have the ability to use more than one template. For
example, buglist.cgi can output bug lists as RDF or two
different forms of HTML (complex and simple). (Try this out
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>
Bugzilla can support different types of output, which again can have
multiple formats. In order to request a certain type, you can append
the &amp;ctype=&lt;contenttype&gt; (such as rdf or html) to the
<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
To see if a CGI supports multiple output formats, grep the
CGI for "GetFormat". If it's not present, adding
multiple format support isn't too hard - see how it's done in
other CGIs, e.g. config.cgi.
</para>
......@@ -258,32 +176,22 @@
<para>
You now need to decide what content type you want your template
served as. The content types are defined in the
<filename>Bugzilla/Constants.pm</filename> file in the
<filename>contenttypes</filename>
constant. If your content type is not there, add it. Remember
the three- or four-letter tag assigned to your content type.
served as. Open up the <filename>localconfig</filename> file and find the
<filename>$contenttypes</filename>
variable. If your content type is not there, add it. Remember
the three- or four-letter tag assigned to you content type.
This tag will be part of the template filename.
</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>
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
<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>
</section>
<section id="template-specific">
<section>
<title>Particular Templates</title>
<para>
......@@ -307,8 +215,7 @@
<para>
<command>global/banner.html.tmpl</command>:
This contains the <quote>banner</quote>, the part of the header
that appears
This contains the "banner", the part of the header that appears
at the top of all Bugzilla pages. The default banner is reasonably
barren, so you'll probably want to customize this to give your
installation a distinctive look and feel. It is recommended you
......@@ -324,26 +231,6 @@
</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>:
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
......@@ -351,75 +238,47 @@
</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/comment.txt.tmpl</command>:
You may not wish to go to the effort of creating custom fields in
Bugzilla, yet you want to make sure that each bug report contains
a number of pieces of important information for which there is not
a special field. The bug entry system has been designed in an
extensible fashion to enable you to add arbitrary HTML widgets,
such as drop-down lists or textboxes, to the bug entry page
and have their values appear formatted in the initial comment.
A hidden field that indicates the format should be added inside
the form in order to make the template functional. Its value should
be the suffix of the template filename. For example, if the file
is called <filename>create-cust.html.tmpl</filename>, then
<programlisting>&lt;input type="hidden" name="format" value="cust"&gt;</programlisting>
should be used inside the form.
</para>
<para>
An example of this is the mozilla.org
<ulink url="http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl&amp;format=guided">guided
bug submission form</ulink>. The code for this comes with the Bugzilla
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
You may wish to get bug submitters to give certain bits of structured
information, each in a separate input widget, for which there is not a
field in the database. The bug entry system has been designed in an
extensible fashion to enable you to define arbitrary fields and widgets,
and have their values appear formatted in the initial
Description, rather than in database fields. An example of this
is the mozilla.org
<ulink url="http://bugzilla.mozilla.org/enter_bug.cgi?format=guided">guided
bug submission form</ulink>.
</para>
<para>
To make this work, create a custom template for
<filename>enter_bug.cgi</filename> (the default template, on which you
could base it, is <filename>create.html.tmpl</filename>),
and either call it <filename>create.html.tmpl</filename> or use a format and
call it <filename>create-&lt;formatname&gt;.html.tmpl</filename>.
Put it in the <filename class="directory">custom/bug/create</filename>
directory. In it, add widgets for each piece of information you'd like
collected - such as a build number, or set of steps to reproduce.
</para>
<para>
Then, create a template like
<filename>custom/bug/create/comment.txt.tmpl</filename>, and call it
<filename>comment-&lt;formatname&gt;.txt.tmpl</filename>. This
template should reference the form fields you have created using
the syntax <filename>[% form.&lt;fieldname&gt; %]</filename>. When a
bug report is
<filename>custom/bug/create/comment.txt.tmpl</filename>, also named
after your format if you are using one, which
references the form fields you have created. When a bug report is
submitted, the initial comment attached to the bug report will be
formatted according to the layout of this template.
</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>
and then your comment.txt.tmpl had
<programlisting>BuildID: [% form.buildid %]</programlisting>
then something like
then
<programlisting>BuildID: 20020303</programlisting>
would appear in the initial comment.
would appear in the initial checkin comment.
</para>
</section>
......@@ -434,99 +293,78 @@
url="http://www.bugzilla.org/download.html#localizations"/>. Instructions
for submitting new languages are also available from that location.
</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 id="cust-hooks">
<title>The Bugzilla Extension Mechanism</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>
<title>Template Hooks</title>
<para>
Extensions are a way for extensions to Bugzilla to insert code
into the standard Bugzilla templates and source files
without modifying these files themselves. The extension mechanism
defines a consistent API for extending the standard templates and source files
in a way that cleanly separates standard code from extension code.
Hooks reduce merge conflicts and make it easier to write extensions that work
across multiple versions of Bugzilla, making upgrading a Bugzilla installation
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.
Template hooks are a way for extensions to Bugzilla to insert code
into the standard Bugzilla templates without modifying the template files
themselves. The hooks mechanism defines a consistent API for extending
the standard templates in a way that cleanly separates standard code
from extension code. Hooks reduce merge conflicts and make it easier
to write extensions that work across multiple versions of Bugzilla,
making upgrading a Bugzilla installation with installed extensions easier.
</para>
<para>
There are two main types of hooks: code hooks and template hooks. Code
hooks allow extensions to invoke code at specific points in various
source files, while template hooks allow extensions to add elements to
the Bugzilla user interface.
A template hook is just a named place in a standard template file
where extension template files for that hook get processed. Each hook
has a corresponding directory in the Bugzilla directory tree. Hooking an
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>
A hook is just a named place in a standard source or template file
where extension source code or template files for that hook get processed.
Each extension has a corresponding directory in the Bugzilla directory
tree (<filename>BUGZILLA_ROOT/extensions/extension_name</filename>). Hooking
an extension source file or template to a hook is as simple as putting
the extension file into extension's template or code directory.
When Bugzilla processes the source file or template and reaches 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.
To use hooks to extend a Bugzilla template, first make sure there is
a hook at the appropriate place within the template you want to extend.
Hooks appear in the standard Bugzilla templates as a single directive
in the format
<literal role="code">[% Hook.process("<varname>name</varname>") %]</literal>,
where <varname>name</varname> is the unique (within that template)
name of the hook.
</para>
<para>
Template hooks appear in the standard Bugzilla templates as a
single directive in the format
<literal role="code">[% Hook.process("<varname>name</varname>") %]</literal>,
where <varname>name</varname> is the unique name of the hook.
If you aren't sure which template you want to extend or just want
to browse the 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 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>
If you aren't sure what you want to extend or just want to browse the
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>.
<filename>BUGZILLA_ROOT/template/en/extension/hook/PATH_TO_STANDARD_TEMPLATE/STANDARD_TEMPLATE_NAME/HOOK_NAME/</filename>
</para>
<para>
If there is no hook at the appropriate place within the Bugzilla
source file or template you want to extend,
If there is no hook at the appropriate place within the Bugzilla template
you want to extend,
<ulink url="http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&amp;component=User%20Interface">file
a bug requesting one</ulink>, specifying:
</para>
<simplelist>
<member>the source or template file for which you are
requesting a hook;</member>
<member>the template for which you are requesting a hook;</member>
<member>
where in the file you would like the hook to be placed
(line number/position for latest version of the file in CVS
where in the template you would like the hook to be placed
(line number/position for latest version of template in CVS
or description of location);
</member>
<member>the purpose of the hook;</member>
......@@ -535,8 +373,9 @@
<para>
The Bugzilla reviewers will promptly review each hook request,
name the hook, add it to the template or source file, and check
the new version of the template into CVS.
name the hook, add it to the template, check the new version
of the template into CVS, and create the corresponding directory in
<filename>BUGZILLA_ROOT/template/en/extension/hook/</filename>.
</para>
<para>
......@@ -552,13 +391,13 @@
<para>
After making sure the hook you need exists (or getting it added if not),
add your extension to the directory within the Bugzilla
extensions tree corresponding to the hook.
add your extension template to the directory within the Bugzilla
directory tree corresponding to the hook.
</para>
<para>
That's it! Now, when the source file or template containing the hook
is processed, your extension file will be processed at the point
That's it! Now, when the standard template containing the hook
is processed, your extension template will be processed at the point
where the hook appears.
</para>
......@@ -589,9 +428,14 @@
...]]></programlisting>
<para>
The corresponding extension file for this hook is
<filename>BUGZILLA_ROOT/extensions/projman/template/en/hook/global/useful-links-edit.html.tmpl</filename>.
You then create that template file and add the following constant:
The corresponding directory for this hook is
<filename>BUGZILLA_ROOT/template/en/extension/hook/global/useful-links.html.tmpl/edit/</filename>.
</para>
<para>
You put a template named
<filename>projman-edit-projects.html.tmpl</filename>
into that directory with the following content:
</para>
<programlisting><![CDATA[...[% ', <a href="edit-projects.cgi">projects</a>' IF user.groups.projman_admins %]]]></programlisting>
......@@ -602,74 +446,67 @@
</para>
<para>
Now, let us say your extension adds a custom "project_manager" field
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.
Notes:
</para>
<itemizedlist>
<listitem>
<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>
</listitem>
<itemizedlist>
<listitem>
<para>
If your extension includes entirely new templates in addition to
extensions of standard templates, it should store those new
templates in its
<filename>BUGZILLA_ROOT/extensions/template/en/</filename>
directory. Extension template directories, like the
extensions of standard templates, it should install those new
templates into an extension-specific subdirectory of the
<filename>BUGZILLA_ROOT/template/en/extension/</filename>
directory. The <filename>extension/</filename> directory, like the
<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.
</para>
<para>
The template processor looks for templates first in 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
<filename>default/</filename> directory (i.e. the standard Bugzilla
templates). Thus, installation-specific templates override both
default and extension templates.
templates). Thus extension templates can override standard 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>
</listitem>
<listitem>
<para>
If you are looking to customize Bugzilla, you can also take advantage
of template hooks. To do so, create a directory in
Installation customizers can also take advantage of hooks when adding
code to a Bugzilla template. To do so, create directories in
<filename>BUGZILLA_ROOT/template/en/custom/hook/</filename>
that corresponds to the hook you wish to use, then place your
customization templates into those directories. For example,
if you wanted to use the hook "end" in
<filename>global/useful-links.html.tmpl</filename>, you would
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.
equivalent to the directories in
<filename>BUGZILLA_ROOT/template/en/extension/hook/</filename>
for the hooks you want to use, then place your customization templates
into those directories.
</para>
<para>
Obviously this method of customizing Bugzilla only lets you add code
to the standard source files and templates; you cannot change the
existing code. Nevertheless, for those customizations that only add
code, this method can reduce conflicts when merging changes,
making upgrading your customized Bugzilla installation easier.
to the standard templates; you cannot change the existing code.
Nevertheless, for those customizations that only add code, this method
can reduce conflicts when merging changes, making upgrading
your customized Bugzilla installation easier.
</para>
</listitem>
</itemizedlist>
......@@ -699,32 +536,22 @@
</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
code. This gives the administrator complete control over exactly who is
allowed to do what. The relevant method is called
<filename>check_can_change_field()</filename>,
and is found in <filename>Bug.pm</filename> in your
Bugzilla/ directory. If you open that file and search for
<quote>sub check_can_change_field</quote>, you'll find it.
allowed to do what. The relevant function is called
<filename>CheckCanChangeField()</filename>,
and is found in <filename>process_bug.cgi</filename> in your
Bugzilla directory. If you open that file and grep for
"sub CheckCanChangeField", you'll find it.
</para>
<para>
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.
Certain marked sections should not be changed - these are
the <quote>plumbing</quote> which makes the rest of the function work.
In between those sections, you'll find snippets of code like:
<programlisting> # Allow the assignee to change anything.
how it works, and give you an idea of how to make changes to it. Certain
marked sections should not be changed - these are the "plumbing" which
makes the rest of the function work. In between those sections, you'll
find snippets of code like:
<programlisting> # Allow the owner to change anything.
if ($ownerid eq $whoid) {
return 1;
}</programlisting>
......@@ -733,11 +560,11 @@
<para>
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
<quote>Allow anyone to change comments.</quote> If you don't want the
Reporter to have any special rights on bugs they have filed, just
remove the entire section that deals with the Reporter.
"Allow anyone to change comments." And if you want the reporter to have
no special rights on bugs they have filed, just remove the entire section
which refers to him.
</para>
<para>
......@@ -756,12 +583,8 @@
}
}</programlisting>
This says that only users in the group "quality_assurance" can change
the QA Contact field of a bug.
</para>
<para>
Getting more weird:
<programlisting><![CDATA[ if (($field eq "priority") &&
the QA Contact field of a bug. Getting more weird:
<programlisting> if (($field eq "priority") &&
(Bugzilla->user->email =~ /.*\@example\.com$/))
{
if ($oldvalue eq "P1") {
......@@ -770,26 +593,377 @@
else {
return 0;
}
}]]></programlisting>
}</programlisting>
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
old value of the field was "P1". Not very useful, but illustrative.
</para>
<warning>
<para>
If you are modifying <filename>process_bug.cgi</filename> in any
way, do not change the code that is bounded by DO_NOT_CHANGE blocks.
Doing so could compromise security, or cause your installation to
stop working entirely.
For a list of possible field names, look in
<filename>data/versioncache</filename> for the list called
<filename>@::log_columns</filename>. If you need help writing custom
rules for your organization, ask in the newsgroup.
</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>
For a list of possible field names, look at the bugs table in the
database. If you need help writing custom rules for your organization,
ask in the newsgroup.
<prompt>bash#</prompt>
<command>mysql</command>
<parameter>-u root</parameter>
</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>
<!-- Integrating Bugzilla with Third-Party Tools -->
......
docs/en/xml/gfdl.xml
View file @ 98be5699
......@@ -16,7 +16,7 @@
</blockquote>
<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
written document "free" in the sense of freedom: to assure everyone the
......@@ -41,7 +41,7 @@
</section>
<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
notice placed by the copyright holder saying it can be distributed under
......@@ -101,7 +101,7 @@
</section>
<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
commercially or noncommercially, provided that this License, the
......@@ -118,7 +118,7 @@
</section>
<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
100, and the Document's license notice requires Cover Texts, you must
......@@ -157,7 +157,7 @@
</section>
<section label="4" id="gfdl-4">
<title>MODIFICATIONS</title>
<title>Modifications</title>
<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
......@@ -287,7 +287,7 @@
</section>
<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
this License, under the terms defined in section 4 above for modified
......@@ -313,7 +313,7 @@
</section>
<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
documents released under this License, and replace the individual copies
......@@ -329,7 +329,7 @@
</section>
<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
separate and independent documents or works, in or on a volume of a
......@@ -348,7 +348,7 @@
</section>
<section label="8" id="gfdl-8">
<title>TRANSLATION</title>
<title>Translation</title>
<para>Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
......@@ -363,7 +363,7 @@
</section>
<section label="9" id="gfdl-9">
<title>TERMINATION</title>
<title>Termination</title>
<para>You may not copy, modify, sublicense, or distribute the Document
except as expressly provided for under this License. Any other attempt to
......@@ -375,7 +375,7 @@
</section>
<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
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"> -->
<!-- $Id: installation.xml,v 1.58 2008/04/04 06:46:48 kiko%async.com.br Exp $ -->
<chapter id="installation">
<!-- $Id: installation.xml,v 1.59 2008/04/04 06:46:49 gerv%gerv.net Exp $ -->
<chapter id="installing-bugzilla">
<title>Installing Bugzilla</title>
<section id="installation">
<title>Installation</title>
<section id="stepbystep">
<title>Step-by-step Install</title>
<note>
<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
operating systems including almost all Unix clones and
<productname class="registered">Microsoft Windows</productname>. Many
operating systems have utilities that make installation easier or quirks
that make it harder. We have tried to collect that information in
<xref linkend="os-specific"/>, so unless you are on Linux,
be sure to check out that section before
you start your installation.
<para>The Bugzilla server software is usually installed on Linux or
Solaris.
If you are installing on another OS, check <xref linkend="os-specific"/>
before you start your installation to see if there are any special
instructions.
</para>
<note>
<para>Windows is one of those operating systems that has many quirks
and is not yet officially supported by the Bugzilla team. If you wish
to install Bugzilla on Windows, be sure to see
<xref linkend="os-win32"/>.
<para>
As an alternative to following these instructions, you may wish to
try Arne Schirmacher's unofficial and unsupported
<ulink url="http://www.softwaretesting.de/article/view/33/1/8/">Bugzilla
Installer</ulink>, which installs Bugzilla and all its prerequisites
on Linux or Solaris systems.
</para>
</note>
<warning>
<para>While installing Bugzilla, it is a good idea to ensure that there
is some kind of configurable firewall between you and the rest of the
Internet
as your machine may be insecure for periods during the install. Many
installation steps require an active Internet connection to complete,
but you must take care to ensure that at no point is your machine
vulnerable to an attack.</para>
</warning>
<para>This guide assumes that you have administrative access to the
Bugzilla machine. It not possible to
install and run Bugzilla itself without administrative access except
in the very unlikely event that every single prerequisite is
already installed.
</para>
<para>This guide assumes that you already have your operating system
installed, network configured, and have administrative access to the
machine onto which you are installing Bugzilla. It is possible to
install and run Bugzilla itself without administrative access, but you
have to
either make sure all the required software is installed or get somebody
with administrative access to install it for you.
<warning>
<para>The installation process may make your machine insecure for
short periods of time. Make sure there is a firewall between you
and the Internet.
</para>
</warning>
<para>
You are strongly recommended to make a backup of your system
before installing Bugzilla (and at regular intervals thereafter :-).
</para>
<para>Here's a basic step-by-step list:
<para>In outline, the installation proceeds as follows:
</para>
<procedure>
......@@ -67,15 +67,15 @@
</para>
</step>
<step>
<para><link linkend="install-bzfiles">Put Bugzilla in the Webspace</link>
<para><link linkend="install-bzfiles">Install Bugzilla</link>
</para>
</step>
<step>
<para><link linkend="install-perlmodules">Install Perl Modules</link>
<para><link linkend="install-perlmodules">Install Perl modules</link>
</para>
</step>
<step>
<para><link linkend="install-setupdatabase">Setup the MySQL Database</link>
<para>Configure all of the above.
</para>
</step>
</procedure>
......@@ -83,24 +83,25 @@
<section id="install-perl">
<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.
If your OS doesn't come with it, Perl can be got in source form
from <ulink url="http://www.perl.com"/>.
There are also binary versions available for many platforms, most of which
are linked to from perl.com.
Although Bugzilla runs with perl &min-perl-ver;,
it's a good idea to be up to the very latest version
if you can when running Bugzilla. As of this writing, that is Perl
version &newest-perl-ver;.</para>
If you don't have it and your OS doesn't provide official packages,
visit <ulink url="http://www.perl.com"/>.
Although Bugzilla runs with Perl &min-perl-ver;,
it's a good idea to be using the latest stable version.
As of this writing, that is Perl &newest-perl-ver;.</para>
</section>
<section id="install-mysql">
<title>MySQL</title>
<para>If your OS doesn't come with it or provide official packages,
visit the MySQL homepage at
<ulink url="http://www.mysql.com"/>
to grab and install the latest stable release of the server.
<para>Installed Version Test: <filename>mysql -V</filename></para>
<para>
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>
<note>
......@@ -108,277 +109,125 @@
versions of MySQL store their data files in
<filename class="directory">/var</filename>.
On some Unix systems, this is part of a smaller root partition,
and may not have room for your bug database. You can set the data
directory as an option to <filename>configure</filename>
if you build MySQL from source yourself.</para>
and may not have room for your bug database. To change the data
directory, you have to build MySQL from source yourself, and
set it as an option to <filename>configure</filename>.</para>
</note>
<para>If you install from something other than a packaging/installation
system (such as .rpm, .dep, .exe, or .msi) you will need to configure
your system so the MySQL server daemon will come back up whenever
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...
system (such as .rpm, .dep, .exe, or .msi) make sure the MySQL server
is started when the machine boots.
</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 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
is capable of running <glossterm linkend="gloss-cgi">CGI</glossterm>
scripts will work. <xref linkend="http"/> has more information about
configuring web servers to work with Bugzilla.
scripts will work.
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>
<note>
<para>We strongly recommend Apache as the web server to use. The
Bugzilla Guide installation instructions, in general, assume you are
using Apache. If you have got Bugzilla working using another webserver,
please share your experiences with us by filing a bug in &bzg-bugs;.
<para>
If you don't have Apache and your OS doesn't provide official packages,
visit <ulink url="http://httpd.apache.org/"/>.
</para>
</note>
</section>
<section id="install-bzfiles">
<title>Bugzilla</title>
<para>You should untar the Bugzilla files into a directory that you're
willing to make writable by the default web server user (probably
<quote>nobody</quote>).
You may decide to put the files in the main web space for your
<para>
Download a Bugzilla tarball (or check it out from CVS) and place
it in a suitable directory, writable by the default web server user
(probably <quote>nobody</quote>).
Good locations are either directly in the main web space for your
web server or perhaps in
<filename>/usr/local</filename>
with a symbolic link in the web space that points to the Bugzilla
directory.</para>
<tip>
<para>If you symlink the bugzilla directory into your Apache's
<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>
with a symbolic link from the web space.
</para>
<caution>
<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
<option>ScriptAlias</option> directive of Apache).
<option>ScriptAlias</option> directive of Apache.
</para>
</caution>
<para>Once all the files are in a web accessible directory, make that
directory writable by your webserver's user. This is a temporary step
until you run the post-install
until you run the
<filename>checksetup.pl</filename>
script, which locks down your installation.</para>
</section>
<section>
<title>
<filename>checksetup.pl</filename>
</title>
<section id="install-perlmodules">
<title>Perl Modules</title>
<para>Next, run the magic checksetup.pl script.
This is designed to check whether you have all of the right
Perl modules in the correct
versions, and that Bugzilla is generally set up correctly.
<para>Bugzilla's installation process is based
on a script called <filename>checksetup.pl</filename>.
The first thing it checks is whether you have appropriate
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>
Eventually,
it will make sure Bugzilla files and directories have reasonable
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.
At this point, you need to <filename>su</filename> to root. You should
remain as root until the end of the install. Then run:
</para>
<screen>
<prompt>bash#</prompt> ./checksetup.pl
</screen>
<screen><prompt>bash#</prompt> ./checksetup.pl</screen>
<para>
The first time you run it with all the correct modules installed,
it will create a file called
<filename>localconfig</filename>.</para>
<!-- We really need a "module-check" switch for checksetup,
which we can use here to make it really clear when they've got
all the modules. -->
<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>MySQL username:
<quote>bugs_user</quote>
if you're following these directions</para>
</listitem>
<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>
<filename>checksetup.pl</filename> will print out a list of the
required and optional Perl modules, together with the versions
(if any) installed on your machine.
The list of required modules is reasonably long; however, you
may already have several of them installed.
</para>
<para>Perl modules can be found using
<glossterm linkend="gloss-cpan">CPAN</glossterm> on Unix based systems or
<glossterm linkend="gloss-ppm">PPM</glossterm> on Win32.
<para>
There is a meta-module called Bundle::Bugzilla,
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>Good instuctions can be found for using each of these services on
their respective websites. The basics can be found in
<xref linkend="install-perlmodules-cpan"/> for CPAN and
<xref linkend="win32-perlmodules"/> for PPM.
<para>
The preferred way of installing Perl modules is via CPAN on Unix,
or PPM on Windows (see <xref linkend="win32-perlmodules"/>). These
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>
<example id="install-perlmodules-cpan">
<title>Installing perl modules with CPAN</title>
<para>The easy way:
<screen>
<prompt>bash#</prompt> perl -MCPAN -e 'install "&lt;modulename&gt;"'
</screen>
</para>
<screen><prompt>bash#</prompt> perl -MCPAN -e 'install "&lt;modulename&gt;"'</screen>
<para>Or the hard way:
<screen>
<prompt>bash#</prompt> tar xzvf &lt;module&gt;.tar.gz <co id="cpan-moduletar"/>
<prompt>bash#</prompt> cd &lt;module&gt; <co id="cpan-moduledir"/>
<prompt>bash#</prompt> perl Makefile.PL
<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>
If you using Bundle::Bugzilla, invoke the magic CPAN command on it.
Otherwise, you need to work down the
list of modules that <filename>checksetup.pl</filename> says are
required, in the order given, invoking the command on each.
</para>
</example>
<tip>
<para>Many people complain that Perl modules will not install for
......@@ -395,35 +244,41 @@ set-variable = max_allowed_packet=1M
for further assistance or hire someone to help you out.</para>
</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>
<listitem>
<para>
<link linkend="install-modules-bundle-bugzilla">Bundle::Bugzilla</link>
(Will allow you to skip the rest)
AppConfig (&min-appconfig-ver;)
</para>
</listitem>
<listitem>
<para>
CGI (&min-cgi-ver;)
</para>
</listitem>
<listitem>
<para>
<link linkend="install-modules-cgi">CGI</link>
(&min-cgi-ver;)
Data::Dumper (&min-data-dumper-ver;)
</para>
</listitem>
<listitem>
<para>
<link linkend="install-modules-date-format">Date::Format</link>
(&min-date-format-ver;)
Date::Format (&min-date-format-ver;)
</para>
</listitem>
<listitem>
<para>
<link linkend="install-modules-dbi">DBI</link>
(&min-dbi-ver;)
DBI (&min-dbi-ver;)
</para>
</listitem>
......@@ -436,34 +291,31 @@ set-variable = max_allowed_packet=1M
<listitem>
<para>
<link linkend="install-file-spec">File::Spec</link>
(&min-file-spec-ver;)
File::Spec (&min-file-spec-ver;)
</para>
</listitem>
<listitem>
<para>
<link linkend="install-modules-file-temp">File::Temp</link>
(&min-file-temp-ver;)
File::Temp (&min-file-temp-ver;)
</para>
</listitem>
<listitem>
<para>
<link linkend="install-modules-template">Template Toolkit</link>
<link linkend="install-modules-template">Template</link>
(&min-template-ver;)
</para>
</listitem>
<listitem>
<para>
<link linkend="install-modules-text-wrap">Text::Wrap</link>
(&min-text-wrap-ver;)
Text::Wrap (&min-text-wrap-ver;)
</para>
</listitem>
</orderedlist>
and, optionally:
Optional Perl modules:
<orderedlist>
<listitem>
<para>
......@@ -481,13 +333,6 @@ set-variable = max_allowed_packet=1M
<listitem>
<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>
(&min-gd-graph-ver;) for bug charting
</para>
......@@ -502,8 +347,8 @@ set-variable = max_allowed_packet=1M
<listitem>
<para>
<link linkend="install-modules-mime-parser">MIME::Parser</link>
(&min-mime-parser-ver;) for the email interface
<link linkend="install-modules-xml-parser">XML::Parser</link>
(&min-xml-parser-ver;) for the XML interface
</para>
</listitem>
......@@ -513,145 +358,31 @@ set-variable = max_allowed_packet=1M
(&min-patchreader-ver;) for pretty HTML view of patches
</para>
</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>
<screen>
<prompt>bash#</prompt> <command>perl -MCPAN -eshell</command> <co id="bundle-cpanconfig"/>
cpan shell -- CPAN exploration and modules installation (v1.63)
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.
<listitem>
<para>
<link linkend="install-modules-mime-parser">MIME::Parser</link>
(&min-mime-parser-ver;) for the optional email interface
</para>
<literallayout>
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.
</listitem>
</orderedlist>
</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">
<title>MySQL-related modules</title>
<para>The Perl/MySQL interface requires a few mutually-dependent Perl
modules. These modules are grouped together into the the
Msql-Mysql-modules package.</para>
<title>DBD::mysql</title>
<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
questions the provided default will be adequate, but when asked if your
desired target is the MySQL or mSQL packages, you should
select the MySQL related ones. Later you will be asked if you wish to
select the MySQL-related ones. Later you will be asked if you wish to
provide backwards compatibility with the older MySQL packages; you
should answer YES to this question. The default is NO.</para>
<para>A host of 'localhost' should be fine and a testing user of 'test'
with a null password should find itself with sufficient access to run
tests on the 'test' database which MySQL created upon installation.
<para>A host of 'localhost' should be fine. A testing user of 'test',
with a null password, should have sufficient access to run
tests on the 'test' database which MySQL creates upon installation.
</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 id="install-modules-template">
......@@ -662,228 +393,337 @@ ReadLine support enabled
that it is recommended you use the high speed XS Stash of the Template
Toolkit, in order to achieve best performance.
</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 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">
<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>
<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
<classname>libpng</classname>
and
<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
missing a required library.</para>
</note>
<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.
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>
</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 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
abilities. It can be installed in the usual fashion after it has been
fetched from CPAN.
<para>The Chart::Base module is only required if you want graphical
reports.
Note that earlier versions that 0.99c used GIFs, which are no longer
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 -->
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/Chart/"/>
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/Chart.zip"/>
</literallayout>
<para>The GD::Graph module is only required if you want graphical
reports.
</para>
</section>
<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 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>
script. You only need it if you are going to be importing bugs (such as
for bug moving). XML::Parser requires that the
<para>The XML::Parser module is only required if you want to import
XML bugs using the <filename>importxml.pl</filename>
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.
</para>
</section>
<!-- TODO: XML::Parser - the only PPM I see is XML-Parser-EasyTree.zip;
I'm not sure if it's the same thing or not. -->
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/XML-Parser/"/>
Documentation: <ulink url="http://www.perldoc.com/perl5.6.1/lib/XML/Parser.html"/>
</literallayout>
<section id="install-modules-mime-parser">
<title>MIME::Parser (&min-mime-parser-ver;)</title>
<para>The MIME::Parser module is only required if you want to use the
email interface
located in the <filename class="directory">contrib</filename> directory.
</para>
</section>
<section id="install-modules-gd-graph">
<title>GD::Graph (&min-gd-graph-ver;) [optional]</title>
<section id="install-modules-patchreader">
<title>PatchReader (&min-patchreader-ver;)</title>
<para>In addition to GD listed above, the reporting interface of Bugzilla
needs to have the GD::Graph module installed.
<para>The PatchReader module is only required if you want to use
Patch Viewer, a
Bugzilla feature to show code patches in your web browser in a more
readable form.
</para>
</section>
</section>
</section>
<section id="configuration">
<title>Configuration</title>
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/GDGraph/"/>
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/GDGraph.zip"/>
Documentation: <ulink url="http://search.cpan.org/dist/GDGraph/Graph.pm"/>
</literallayout>
<warning>
<para>Poorly-configured MySQL and Bugzilla installations have
given attackers full access to systems in the past. Please take the
security parts of these guidelines seriously, even for Bugzilla
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 id="install-modules-gd-text-align">
<title>GD::Text::Align (&min-gd-text-align-ver;) [optional]</title>
<section id="mysql">
<title>MySQL</title>
<para>GD::Text::Align, as the name implies, is used to draw aligned
strings of text. It is needed by the reporting interface.
<section id="security-mysql">
<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>
</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 id="install-modules-mime-parser">
<title>MIME::Parser (&min-mime-parser-ver;) [optional]</title>
<section id="install-setupdatabase">
<title>Allow large attachments</title>
<para>MIME::Parser is only needed if you want to use the e-mail interface
located in the <filename class="directory">contrib</filename> directory.
<para>You need to configure MySQL to accept large packets, if you
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>
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/dist/MIME-tools/"/>
PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/6xx-builds-only/MIME-tools.zip"/>
Documentation: <ulink url="http://search.cpan.org/dist/MIME-tools/lib/MIME/Parser.pm"/>
</literallayout>
<screen> [mysqld]
# Allow packets up to 1M
set-variable = max_allowed_packet=1M</screen>
</section>
<section id="install-modules-patchreader">
<title>PatchReader (&min-patchreader-ver;) [optional]</title>
<para>PatchReader is only needed if you want to use Patch Viewer, a
Bugzilla feature to format patches in a pretty HTML fashion. There are a
number of optional parameters you can configure Patch Viewer with as well,
including cvsroot, cvsroot_get, lxr_root, bonsai_url, lxr_url, and
lxr_root. Patch Viewer also optionally will use cvs, diff and interdiff
utilities if they exist on the system (interdiff can be found in the
patchutils package at <ulink url="http://cyberelk.net/tim/patchutils/"/>.
These programs' locations can be configured in localconfig.
</para>
<literallayout>
CPAN Download Page: <ulink url="http://search.cpan.org/author/JKEISER/PatchReader/"/>
Documentation: <ulink url="http://www.johnkeiser.com/mozilla/Patch_Viewer.html"/>
</literallayout>
<section id="install-setupdatabase-adduser">
<title>Add a user to MySQL</title>
<para>You need to add a new MySQL user for
Bugzilla to use. (It's not safe to have Bugzilla use the MySQL root
account.) The following instructions assume the defaults in
<filename>localconfig</filename>;
if you changed those, you need to modify the
SQL command appropriately. You will need the
<replaceable>$db_pass</replaceable> password you set in
<filename>localconfig</filename> in
<xref linkend="localconfig"/>.
</para>
<para>We use an SQL <command>GRANT</command> command to create a
<quote>bugs</quote>
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>
<title>Configuring Bugzilla</title>
<title>checksetup.pl</title>
<para>
Once checksetup.pl has run successfully, Bugzilla should start up.
Proceed to the correct URL and log in with the administrator account
you defined in the last checksetup.pl run.
Next, rerun <filename>checksetup.pl</filename>. It reconfirms
that all the modules are present, and notices the altered
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>
You should run through the parameters on the Edit Parameters page
(link in the footer) and set them all to appropriate values.
They key parameters are documented in <xref linkend="parameters" />.
After that, it asks for details of an administrator account. Bugzilla
can have multiple administrators - you can create more later - but
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>
</section>
</section>
<section id="http">
<title>HTTP Server Configuration</title>
<para>The Bugzilla Team recommends Apache when using Bugzilla, however, any web server
that can be configured to run <glossterm linkend="gloss-cgi">CGI</glossterm> scripts
should be able to handle Bugzilla. No matter what web server you choose, but
especially if you choose something other than Apache, you should be sure to read
<xref linkend="security-access"/>.
<para>
<filename>checksetup.pl</filename> will then finish. You may rerun
<filename>checksetup.pl</filename> at any time if you wish.
</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>
<section id="http-apache">
<title>Apache <productname>httpd</productname></title>
<para>You will have to make sure that Apache is properly
configured to run the Bugzilla CGI scripts. You also need to make sure
that the <filename>.htaccess</filename> files created by
<command>./checksetup.pl</command> are allowed to override Apache's normal access
permissions or else important password information may be exposed to the
Internet.
</para>
<para>Load <filename>httpd.conf</filename> in your editor.</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.
Open your
<filename>httpd.conf</filename> file and make sure the
following line exists and is uncommented:</para>
<programlisting>
AddHandler cgi-script .cgi
</programlisting>
</para>
<programlisting> AddHandler cgi-script .cgi</programlisting>
<para>To allow <filename>.htaccess</filename> files to override
permissions and .cgi files to run in the Bugzilla directory, make sure
the following two lines are in a <computeroutput>Directory</computeroutput>
directive that applies to the Bugzilla directory on your system
(either the Bugzilla directory or one of its parents).
<para>Apache uses <computeroutput>&lt;Directory&gt;</computeroutput>
directives to permit fine-grained permission setting.
Add the following two lines to a
<computeroutput>&lt;Directory&gt;</computeroutput> directive that
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>
<programlisting>
Options +ExecCGI
AllowOverride Limit
</programlisting>
<para>You should modify the &lt;DirectoryIndex&gt; parameter for
the Apache virtual host running your Bugzilla installation to
allow <filename>index.cgi</filename> as the index page for a
directory, as well as the usual <filename>index.html</filename>,
<filename>index.htm</filename>, and so forth. </para>
<programlisting> Options +ExecCGI +FollowSymLinks
AllowOverride Limit</programlisting>
<note>
<para>For more information on Apache and its directives, see the
glossary entry on <xref linkend="gloss-apache"/>.
<para>Add <filename>index.cgi</filename> to the end
of the <computeroutput>DirectoryIndex</computeroutput>
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>
</note>
</section>
<section id="http-iis">
......@@ -892,8 +732,8 @@ AllowOverride Limit
<para>If you need, or for some reason even want, to use Microsoft's
<productname>Internet Information Services</productname> or
<productname>Personal Web Server</productname> you should be able
to. You will need to configure them to know how to run CGI scripts,
however. This is described in Microsoft Knowledge Base article
to. You will need to configure them to know how to run CGI scripts.
This is described in Microsoft Knowledge Base article
<ulink url="http://support.microsoft.com/support/kb/articles/Q245/2/25.asp">Q245225</ulink>
for <productname>Internet Information Services</productname> and
<ulink url="http://support.microsoft.com/support/kb/articles/Q231/9/98.asp">Q231998</ulink>
......@@ -929,19 +769,19 @@ AllowOverride Limit
</para>
<programlisting>
ns_register_filter preauth GET /bugzilla/localconfig filter_deny
ns_register_filter preauth GET /bugzilla/localconfig~ filter_deny
ns_register_filter preauth GET /bugzilla/\#localconfig\# filter_deny
ns_register_filter preauth GET /bugzilla/*.pl filter_deny
ns_register_filter preauth GET /bugzilla/syncshadowdb filter_deny
ns_register_filter preauth GET /bugzilla/runtests.sh filter_deny
ns_register_filter preauth GET /bugzilla/data/* filter_deny
ns_register_filter preauth GET /bugzilla/template/* filter_deny
proc filter_deny { why } {
ns_register_filter preauth GET /bugzilla/localconfig filter_deny
ns_register_filter preauth GET /bugzilla/localconfig~ filter_deny
ns_register_filter preauth GET /bugzilla/\#localconfig\# filter_deny
ns_register_filter preauth GET /bugzilla/*.pl filter_deny
ns_register_filter preauth GET /bugzilla/syncshadowdb filter_deny
ns_register_filter preauth GET /bugzilla/runtests.sh filter_deny
ns_register_filter preauth GET /bugzilla/data/* filter_deny
ns_register_filter preauth GET /bugzilla/template/* filter_deny
proc filter_deny { why } {
ns_log Notice "filter_deny"
return "filter_return"
}
}
</programlisting>
<warning>
......@@ -969,16 +809,218 @@ proc filter_deny { why } {
</para>
</note>
</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 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">
<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>
<title>Dependency Charts</title>
<para>As well as the text-based dependency graphs, Bugzilla also
supports dependency graphing, using a package called 'dot'.
<para>As well as the text-based dependency trees, Bugzilla also
supports a graphical view of dependency relationships, using a
package called 'dot'.
Exactly how this works is controlled by the 'webdotbase' parameter,
which can have one of three values:
</para>
......@@ -1006,78 +1048,64 @@ proc filter_deny { why } {
</orderedlist>
</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
do that, you need to
<ulink url="http://httpd.apache.org/docs/mod/mod_imap.html">enable
server-side image maps</ulink> in Apache.
Alternatively, you could set up a webdot server, or use the AT&amp;T
public webdot server (the
default for the webdotbase param). Note that AT&amp;T's server won't work
public webdot server. This is the default for the webdotbase param,
but it's often overloaded and slow. Note that AT&amp;T's server
won't work
if Bugzilla is only accessible using HARTS.
<emphasis>Editor's note: What the heck is HARTS? Google doesn't know...
</emphasis>
</para>
</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
might as well turn on the nifty Bugzilla bug reporting graphs.</para>
<para>What good are
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
<filename>collectstats.pl</filename>
daily at 5 after midnight:
<simplelist>
<member>
<computeroutput>
<prompt>bash#</prompt>
<command>crontab -e</command>
</computeroutput>
</member>
<member>
<computeroutput>5 0 * * * cd &lt;your-bugzilla-directory&gt; ;
./collectstats.pl</computeroutput>
</member>
</simplelist>
This can be done by
adding the following command as a daily crontab entry, in the same manner
as explained above for bug graphs. This example runs it at 12.55am.
</para>
<para>After two days have passed you'll be able to view bug graphs from
the Bug Reports page.</para>
<programlisting>55 0 * * * cd &lt;your-bugzilla-directory&gt; ; ./whineatnews.pl</programlisting>
</section>
<section>
<title>The Whining Cron</title>
<section id="patch-viewer">
<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>
This can be done by
adding the following command as a daily crontab entry (for help on that
see that crontab man page):
<simplelist>
<member>
<computeroutput>
<command>cd &lt;your-bugzilla-directory&gt; ;
./whineatnews.pl</command>
</computeroutput>
</member>
</simplelist>
Patch Viewer is the engine behind Bugzilla's graphical display of
code patches. You can integrate this with copies of the
<filename>cvs</filename>, <filename>lxr</filename> and
<filename>bonsai</filename> tools if you have them, by giving
the locations of your installation of these tools in
<filename>editparams.cgi</filename>.
</para>
<tip>
<para>Depending on your system, crontab may have several manpages.
The following command should lead you to the most useful page for
this purpose:
<programlisting>
man 5 crontab
</programlisting>
<para>
Patch Viewer also optionally will use the
<filename>cvs</filename>, <filename>diff</filename> and
<filename>interdiff</filename>
command-line utilities if they exist on the system.
Interdiff can be obtained from
<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>
</tip>
</section>
<section id="bzldap">
......@@ -1166,7 +1194,7 @@ man 5 crontab
<term>LDAPBaseDN</term>
<listitem>
<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.
</para>
<para>Ex. <quote>ou=People,o=Company</quote></para>
......@@ -1189,7 +1217,7 @@ man 5 crontab
<term>LDAPmailattribute</term>
<listitem>
<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.
</para>
<para>Ex. <quote>mail</quote></para>
......@@ -1201,75 +1229,78 @@ man 5 crontab
<section id="content-type">
<title>Preventing untrusted Bugzilla content from executing malicious
Javascript code</title>
<title>Prevent users injecting malicious
Javascript</title>
<para>It is possible for a Bugzilla attachment to contain malicious
Javascript
code, which would be executed in the domain of your Bugzilla, thereby
making it possible for the attacker to e.g. steal your login cookies.
<para>It is possible for a Bugzilla user to take advantage of character
set encoding ambiguities to inject HTML into Bugzilla comments. This
could include malicious scripts.
Due to internationalization concerns, we are unable to
incorporate by default the code changes necessary to fulfill the CERT
advisory requirements mentioned in
incorporate by default the code changes suggested by
<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
change below will prevent this problem.
</para>
<para>Simply locate the following line in
<filename>Bugzilla/CGI.pm</filename>:
<programlisting>
$self->charset('');
</programlisting>
<programlisting>$self->charset('');</programlisting>
and change it to:
<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.
<programlisting>$self->charset('ISO-8859-1');</programlisting>
</para>
</section>
<section id="mod-throttle"
xreflabel="Using mod_throttle to prevent Denial of Service attacks">
<title>
<filename>mod_throttle</filename>
and Security</title>
<filename>mod_throttle</filename></title>
<para>It is possible for a user, by mistake or on purpose, to access
the database many times in a row which can result in very slow access
speeds for other users. If your Bugzilla installation is experiencing
this problem , you may install the Apache module
this problem, you may install the Apache module
<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
<ulink url="http://www.snert.com/Software/mod_throttle/"/>.
Follow the instructions to install into your Apache install.
<emphasis>This module only functions with the Apache web
server!</emphasis>
You may use the
<command>ThrottleClientIP</command>
command provided by this module to accomplish this goal. See the
<ulink url="http://www.snert.com/Software/mod_throttle/">Module
Instructions</ulink>
The command you need is
<command>ThrottleClientIP</command>. See the
<ulink url="http://www.snert.com/Software/mod_throttle/">documentation</ulink>
for more information.</para>
</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 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
the operating system you choose to install it on. Sometimes it can be made
......@@ -1285,7 +1316,7 @@ man 5 crontab
<section id="os-win32">
<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
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
......@@ -1298,8 +1329,8 @@ man 5 crontab
<![%bz-devel;[
Because this is a development version of the guide, these instructions
are subject to change without notice. In fact, the Bugzilla Team hopes
they do as we would like to have Bugzilla resonabally close to "out of
the box" compatibility by the 2.18 release.
to have Bugzilla reasonably close to "out of
the box" compatibility with Windows by the 2.18 release.
]]>
</para>
......@@ -1334,20 +1365,14 @@ C:\perl&gt; <command>ppm &lt;module name&gt;</command>
url="http://openinteract.sourceforge.net/">OpenInteract's website</ulink>.
</para>
</note>
<tip>
<para>A complete list of modules that can be installed using ppm can
be found at <ulink url="http://www.activestate.com/PPMPackages/5.6plus"/>.
</para>
</tip>
</section>
<section id="win32-code-changes">
<title>Code changes required to run on win32</title>
<para>As Bugzilla still doesn't run "out of the box" on
Windows, code has to be modified. This section is an attempt to
list the required changes.
Windows, code has to be modified. This section lists the required
changes.
</para>
<section id="win32-code-checksetup">
......@@ -1377,7 +1402,7 @@ my $webservergid = '8'
<section id="win32-code-bugmail">
<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
84876</ulink> lands), the
simplest way is to have the Net::SMTP Perl module installed and
......@@ -1409,7 +1434,7 @@ $smtp->quit;
</programlisting>
<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>
</section>
......@@ -1430,7 +1455,7 @@ $smtp->quit;
<note>
<para>If using Apache on windows, you can set the <ulink
url="http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource">ScriptInterpreterSource</ulink>
directive in your Apache config, if you don't do this, you'll have
directive in your Apache config to avoid having
to modify the first line of every script to contain your path to
perl instead of <filename>/usr/bin/perl</filename>.
</para>
......@@ -1443,24 +1468,22 @@ $smtp->quit;
<section id="os-macosx">
<title><productname>Mac OS X</productname></title>
<para>There are a lot of common libraries and utilities out there that
Apple did not include with Mac OS X, but which run perfectly well on it.
The GD library, which Bugzilla needs to do bug graphs, is one of
these.</para>
<para>Apple did not include the GD library with Mac OS X. Bugzilla
needs this for bug graphs.</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
common GNU utilities. Fink is available from
<ulink url="http://sourceforge.net/projects/fink/"/>.</para>
<para>Follow the instructions for setting up Fink. Once it's installed,
you'll want to use it to install the gd2 package.
you'll want to use it to install the <filename>gd2</filename> package.
</para>
<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
then be able to use <glossterm linkend="gloss-cpan">CPAN</glossterm> to
install the GD perl module.
install the GD Perl module.
</para>
<note>
......@@ -1477,7 +1500,7 @@ $smtp->quit;
</para>
</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
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
......@@ -1527,7 +1550,7 @@ $smtp->quit;
</screen>
<calloutlist>
<callout arearefs="test-mailtools">
<para>for Bugzilla e-mail integration</para>
<para>for Bugzilla email integration</para>
</callout>
</calloutlist>
......@@ -1535,279 +1558,53 @@ $smtp->quit;
</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>
<para>If you run MySQL on the same machine as your httpd server, you
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>
<section id="troubleshooting">
<title>Troubleshooting</title>
<listitem>
<para>You may also consider running MySQL, or even all of Bugzilla
in a chroot jail; however, instructions for doing that are beyond
the scope of this document.
<para>This section gives solutions to common Bugzilla installation
problems. If none of the section headings seems to match your
problem, read the general advice.
</para>
</listitem>
</orderedlist>
</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.
<section id="general-advice">
<title>General Advice</title>
<para>
If you can't get <filename>checksetup.pl</filename> to run to
completion, it normally explains what's wrong and how to fix it.
If you can't work it out, or if it's being uncommunicative, post
the errors in the
<ulink url="news://news.mozilla.org/netscape.public.mozilla.webtools">netscape.public.mozilla.webtools</ulink>
newsgroup.
</para>
<note>
<para>You will need to set the <varname>webservergroup</varname> to
the group you created for your webserver to run as in
<filename>localconfig</filename>. This will allow
<command>./checksetup.pl</command> to better adjust the file
permissions on your Bugzilla install so as to not require making
anything world-writable.
<para>
If you have made it all the way through
<xref linkend="installation"/> (Installation) and
<xref linkend="configuration"/> (Configuration) but
accessing the Bugzilla URL doesn't work,
the first thing to do is to check your webserver error log. For
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>
</note>
</section>
<section id="security-access">
<title>Web Server Access Controls</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>
<section>
<title>I installed a Perl module, but
<filename>checksetup.pl</filename> claims it's not installed!</title>
<tip>
<para>You should check <xref linkend="http"/> to see if instructions
have been included for your web server. You should also compare those
instructions with this list to make sure everything is properly
accounted for.
<para>
You have two versions of Perl on your machine. You are installing
modules into one, and Bugzilla is using the other. Rerun the CPAN
commands (or manual compile) using the full path to Perl from the
top of <filename>checksetup.pl</filename>. This will make sure you
are installing the modules in the right place.
</para>
</tip>
</section>
</section>
<section id="troubleshooting">
<title>Troubleshooting</title>
<para>This section gives solutions to common Bugzilla installation
problems.
</para>
<section>
<title>Bundle::Bugzilla makes me upgrade to Perl 5.6.1</title>
......@@ -1900,36 +1697,25 @@ skip-networking
<para>This is caused by a bug in the version of
<productname>File::Temp</productname> that is distributed with perl
5.6.0. Many minor variations of this error have been reported. Examples
can be found in <xref linkend="trouble-filetemp-errors"/>.
5.6.0. Many minor variations of this error have been reported:
</para>
<figure id="trouble-filetemp-errors">
<title>Other File::Temp error messages</title>
<programlisting>
Your vendor has not defined Fcntl macro O_NOINHERIT, used
<programlisting>Your vendor has not defined Fcntl macro O_NOINHERIT, used
at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 208.
Your vendor has not defined Fcntl macro O_EXLOCK, used
at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 210.
Your vendor has not defined Fcntl macro O_TEMPORARY, used
at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 233.
</programlisting>
</figure>
at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 233.</programlisting>
<para>Numerous people have reported that upgrading to version 5.6.1
or higher solved the problem for them. A less involved fix is to apply
the patch in <xref linkend="trouble-filetemp-patch"/>. The patch is also
the following patch, which is also
available as a <ulink url="../xml/filetemp.patch">patch file</ulink>.
</para>
<figure id="trouble-filetemp-patch">
<title>Patch for File::Temp in Perl 5.6.0</title>
<programlisting><![CDATA[
--- File/Temp.pm.orig Thu Feb 6 16:26:00 2003
<programlisting><![CDATA[--- File/Temp.pm.orig Thu Feb 6 16:26:00 2003
+++ File/Temp.pm Thu Feb 6 16:26:23 2003
@@ -205,6 +205,7 @@
# eg CGI::Carp
......@@ -1946,9 +1732,7 @@ at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 233.
+ local *CORE::GLOBAL::die = sub {};
$bit = &$func();
1;
};
]]></programlisting>
</figure>
};]]></programlisting>
</section>
</section>
</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