3122ddc5fa
git-svn-id: svn://10.0.0.236/branches/BUGZILLA-2_16-BRANCH@191488 18797224-902f-48f8-a5cc-f745e15eee43
1890 lines
72 KiB
XML
1890 lines
72 KiB
XML
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
|
|
<chapter id="administration">
|
|
<title>Administering Bugzilla</title>
|
|
|
|
<section id="parameters">
|
|
<title>Bugzilla Configuration</title>
|
|
|
|
<para>
|
|
Bugzilla is configured by changing various parameters, accessed
|
|
from the "Edit parameters" link in the page footer. Here are
|
|
some of the key parameters on that page. You should run down this
|
|
list and set them appropriately after installing Bugzilla.
|
|
</para>
|
|
|
|
<indexterm>
|
|
<primary>checklist</primary>
|
|
</indexterm>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
maintainer
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
The maintainer parameter is the email address of the person
|
|
responsible for maintaining this Bugzilla installation.
|
|
The address need not be that of a valid Bugzilla account.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
urlbase
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This parameter defines the fully qualified domain name and web
|
|
server path to your Bugzilla installation.
|
|
</para>
|
|
|
|
<para>
|
|
For example, if your Bugzilla query page is
|
|
<filename>http://www.foo.com/bugzilla/query.cgi</filename>,
|
|
set your <quote>urlbase</quote>
|
|
to <filename>http://www.foo.com/bugzilla/</filename>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
usebuggroups
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This dictates whether or not to implement group-based security for
|
|
Bugzilla. If set, Bugzilla bugs can have an associated 'group',
|
|
defining which users are allowed to see and edit the
|
|
bug.
|
|
</para>
|
|
|
|
<para>
|
|
Set <quote>usebuggroups</quote> to <quote>on</quote>
|
|
<emphasis>only</emphasis> if you may wish to restrict access
|
|
to particular bugs to certain groups of users. I suggest leaving
|
|
this parameter <emphasis>off</emphasis>
|
|
while initially testing your Bugzilla.
|
|
</para>
|
|
|
|
<para>
|
|
For more information see <xref linkend="groups"/>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
usebuggroupsentry
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Bugzilla Products can have a group associated with them, so that
|
|
certain users can only see bugs in certain products. When this
|
|
parameter is set to <quote>on</quote>, this places all
|
|
newly-created bugs in the group for their product immediately.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
shadowdb
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
You run into an interesting problem when Bugzilla reaches a
|
|
high level of continuous activity. MySQL supports only table-level
|
|
write locking. What this means is that if someone needs to make a
|
|
change to a bug, they will lock the entire table until the operation
|
|
is complete. Locking for write also blocks reads until the write is
|
|
complete. Note that more recent versions of mysql support row level
|
|
locking using different table types. These types are slower than the
|
|
standard type, and Bugzilla does not yet take advantage of features
|
|
such as transactions which would justify this speed decrease. The
|
|
Bugzilla team are, however, happy to hear about any experiences with
|
|
row level locking and Bugzilla.
|
|
</para>
|
|
|
|
<para>
|
|
The <quote>shadowdb</quote> parameter was designed to get around
|
|
this limitation. While only a single user is allowed to write to
|
|
a table at a time, reads can continue unimpeded on a read-only
|
|
shadow copy of the database. Although your database size will
|
|
double, a shadow database can cause an enormous performance
|
|
improvement when implemented on extremely high-traffic Bugzilla
|
|
databases.
|
|
</para>
|
|
|
|
<para>
|
|
As a guide, on reasonably old hardware, mozilla.org began needing
|
|
<quote>shadowdb</quote> when they reached around 40,000 Bugzilla
|
|
users with several hundred Bugzilla bug changes and comments per day.
|
|
</para>
|
|
|
|
<para>
|
|
The value of the parameter defines the name of the shadow bug
|
|
database. Set "shadowdb" to e.g. "bug_shadowdb" if you will be
|
|
running a *very* large installation of Bugzilla.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
Enabling "shadowdb" can adversely affect the stability of your
|
|
installation of Bugzilla. You should regularly check that your
|
|
database is in sync. It is often advisable to force a shadow
|
|
database sync nightly via <quote>cron</quote>.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
If you use the <quote>shadowdb</quote> option, it is only natural
|
|
that you should turn the <quote>queryagainstshadowdb</quote>
|
|
option on as well. Otherwise you are replicating data into a shadow
|
|
database for no reason!
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
shutdownhtml
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
If you need to shut down Bugzilla to perform administration, enter
|
|
some descriptive text (with embedded HTML codes, if you'd like)
|
|
into this box. Anyone who tries to use Bugzilla (including admins)
|
|
will receive a page displaying this text. Users can neither log in
|
|
nor log out while shutdownhtml is enabled.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
Although regular log-in capability is disabled while 'shutdownhtml'
|
|
is enabled, safeguards are in place to protect the unfortunate
|
|
admin who loses connection to Bugzilla. Should this happen to you,
|
|
go directly to the <filename>editparams.cgi</filename> (by typing
|
|
the URL in manually, if necessary). Doing this will prompt you to
|
|
log in, and your name/password will be accepted here (but nowhere
|
|
else).
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
passwordmail
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Every time a user creates an account, the text of
|
|
this parameter (with substitutions) is sent to the new user along with
|
|
their password message.
|
|
</para>
|
|
|
|
<para>
|
|
Add any text you wish to the "passwordmail" parameter box. For
|
|
instance, many people choose to use this box to give a quick training
|
|
blurb about how to use Bugzilla at your site.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
movebugs
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This option is an undocumented feature to allow moving bugs
|
|
between separate Bugzilla installations. You will need to understand
|
|
the source code in order to use this feature. Please consult
|
|
<filename>movebugs.pl</filename> in your Bugzilla source tree for
|
|
further documentation, such as it is.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
useqacontact
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This allows you to define an email address for each component,
|
|
in addition to that of the default owner, who will be sent
|
|
carbon copies of incoming bugs.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
usestatuswhiteboard
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This defines whether you wish to have a free-form, overwritable field
|
|
associated with each bug. The advantage of the Status Whiteboard is
|
|
that it can be deleted or modified with ease, and provides an
|
|
easily-searchable field for indexing some bugs that have some trait
|
|
in common.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
whinedays
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Set this to the number of days you want to let bugs go
|
|
in the NEW or REOPENED state before notifying people they have
|
|
untouched new bugs. If you do not plan to use this feature, simply do
|
|
not set up the whining cron job described in the installation
|
|
instructions, or set this value to "0" (never whine).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
commenton*
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
All these fields allow you to dictate what changes can pass
|
|
without comment, and which must have a comment from the
|
|
person who changed them. Often, administrators will allow
|
|
users to add themselves to the CC list, accept bugs, or
|
|
change the Status Whiteboard without adding a comment as to
|
|
their reasons for the change, yet require that most other
|
|
changes come with an explanation.
|
|
</para>
|
|
|
|
<para>
|
|
Set the "commenton" options according to your site policy. It
|
|
is a wise idea to require comments when users resolve, reassign, or
|
|
reopen bugs at the very least.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
It is generally far better to require a developer comment
|
|
when resolving bugs than not. Few things are more annoying to bug
|
|
database users than having a developer mark a bug "fixed" without
|
|
any comment as to what the fix was (or even that it was truly
|
|
fixed!)
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
supportwatchers
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Turning on this option allows users to ask to receive copies
|
|
of bug mail sent to another user. Watching a user with
|
|
different group permissions is not a way to 'get around' the
|
|
system; copied emails are still subject to the normal groupset
|
|
permissions of a bug, and <quote>watchers</quote> will only be
|
|
copied on emails from bugs they would normally be allowed to view.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
sendmailnow
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
When Bugzilla is using Sendmail older than 8.12, turning this option
|
|
off will improve performance by not waiting for Sendmail to actually
|
|
send mail. If Sendmail 8.12 or later is being used, there is
|
|
nothing to gain by turning this off. If another MTA is being used,
|
|
such as Postfix, then this option *must* be turned on (even if you
|
|
are using the fake sendmail executable that Postfix provides).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</section>
|
|
|
|
<section id="useradmin">
|
|
<title>User Administration</title>
|
|
|
|
<section id="defaultuser">
|
|
<title>Creating the Default User</title>
|
|
|
|
<para>When you first run checksetup.pl after installing Bugzilla, it
|
|
will prompt you for the administrative username (email address) and
|
|
password for this "super user". If for some reason you delete
|
|
the "super user" account, re-running checksetup.pl will again prompt
|
|
you for this username and password.</para>
|
|
|
|
<tip>
|
|
<para>If you wish to add more administrative users, you must use the
|
|
MySQL interface. Run "mysql" from the command line, and use these
|
|
commands:
|
|
<simplelist>
|
|
<member>
|
|
<prompt>mysql></prompt>
|
|
<command>use bugs;</command>
|
|
</member>
|
|
|
|
<member>
|
|
<prompt>mysql></prompt>
|
|
|
|
<command>
|
|
update profiles set groupset=0x7fffffffffffffff where login_name =
|
|
"(user's login name)";
|
|
</command>
|
|
</member>
|
|
</simplelist>
|
|
</para>
|
|
|
|
<para>Yes, that is
|
|
<emphasis>fifteen</emphasis>
|
|
|
|
<quote>f</quote>
|
|
|
|
's. A whole lot of f-ing going on if you want to create a new
|
|
administator.</para>
|
|
</tip>
|
|
</section>
|
|
|
|
<section id="manageusers">
|
|
<title>Managing Other Users</title>
|
|
|
|
<section id="createnewusers">
|
|
<title>Creating new users</title>
|
|
|
|
<para>Your users can create their own user accounts by clicking the
|
|
"New Account" link at the bottom of each page (assuming they
|
|
aren't logged in as someone else already.) However, should you
|
|
desire to create user accounts ahead of time, here is how you do
|
|
it.</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>After logging in, click the "Users" link at the footer of
|
|
the query page, and then click "Add a new user".</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Fill out the form presented. This page is self-explanatory.
|
|
When done, click "Submit".</para>
|
|
|
|
<note>
|
|
<para>Adding a user this way will
|
|
<emphasis>not</emphasis>
|
|
|
|
send an email informing them of their username and password.
|
|
While useful for creating dummy accounts (watchers which
|
|
shuttle mail to another system, for instance, or email
|
|
addresses which are a mailing list), in general it is
|
|
preferable to log out and use the
|
|
<quote>New Account</quote>
|
|
|
|
button to create users, as it will pre-populate all the
|
|
required fields and also notify the user of her account name
|
|
and password.</para>
|
|
</note>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
|
|
<section id="modifyusers">
|
|
<title>Modifying Users</title>
|
|
|
|
<para>To see a specific user, search for their login name
|
|
in the box provided on the "Edit Users" page. To see all users,
|
|
leave the box blank.</para>
|
|
|
|
<para>You can search in different ways the listbox to the right
|
|
of the text entry box. You can match by
|
|
case-insensitive substring (the default),
|
|
regular expression, or a
|
|
<emphasis>reverse</emphasis>
|
|
regular expression match, which finds every user name which does NOT
|
|
match the regular expression. (Please see
|
|
the <command>man regexp</command>
|
|
manual page for details on regular expression syntax.)
|
|
</para>
|
|
|
|
<para>Once you have found your user, you can change the following
|
|
fields:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Login Name</emphasis>:
|
|
This is generally the user's full email address. However, if you
|
|
have are using the emailsuffix Param, this may just be the user's
|
|
login name. Note that users can now change their login names
|
|
themselves (to any valid email address.)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Real Name</emphasis>: The user's real name. Note that
|
|
Bugzilla does not require this to create an account.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Password</emphasis>:
|
|
You can change the user's password here. Users can automatically
|
|
request a new password, so you shouldn't need to do this often.
|
|
If you want to disable an account, see Disable Text below.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Disable Text</emphasis>:
|
|
If you type anything in this box, including just a space, the
|
|
user is prevented from logging in, or making any changes to
|
|
bugs via the web interface.
|
|
The HTML you type in this box is presented to the user when
|
|
they attempt to perform these actions, and should explain
|
|
why the account was disabled.
|
|
</para>
|
|
<para>
|
|
Users with disabled accounts will continue to receive
|
|
mail from Bugzilla; furthermore, they will not be able
|
|
to log in themselves to change their own preferences and
|
|
stop it. If you want an account (disabled or active) to
|
|
stop receiving mail, add the account name (one account
|
|
per line) to the file <filename>data/nomail</filename>.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Even users whose accounts have been disabled can still
|
|
submit bugs via the e-mail gateway, if one exists.
|
|
The e-mail gateway should <emphasis>not</emphasis> be
|
|
enabled for secure installations of Bugzilla.
|
|
</para>
|
|
</note>
|
|
<warning>
|
|
<para>
|
|
Don't disable all the administrator accounts!
|
|
</para>
|
|
</warning>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis><groupname></emphasis>:
|
|
If you have created some groups, e.g. "securitysensitive", then
|
|
checkboxes will appear here to allow you to add users to, or
|
|
remove them from, these groups.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>canconfirm</emphasis>:
|
|
This field is only used if you have enabled the "unconfirmed"
|
|
status. If you enable this for a user,
|
|
that user can then move bugs from "Unconfirmed" to a "Confirmed"
|
|
status (e.g.: "New" status).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>creategroups</emphasis>:
|
|
This option will allow a user to create and destroy groups in
|
|
Bugzilla.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>editbugs</emphasis>:
|
|
Unless a user has this bit set, they can only edit those bugs
|
|
for which they are the assignee or the reporter. Even if this
|
|
option is unchecked, users can still add comments to bugs.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>editcomponents</emphasis>:
|
|
This flag allows a user to create new products and components,
|
|
as well as modify and destroy those that have no bugs associated
|
|
with them. If a product or component has bugs associated with it,
|
|
those bugs must be moved to a different product or component
|
|
before Bugzilla will allow them to be destroyed.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>editkeywords</emphasis>:
|
|
If you use Bugzilla's keyword functionality, enabling this
|
|
feature allows a user to create and destroy keywords. As always,
|
|
the keywords for existing bugs containing the keyword the user
|
|
wishes to destroy must be changed before Bugzilla will allow it
|
|
to die.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>editusers</emphasis>:
|
|
This flag allows a user to do what you're doing right now: edit
|
|
other users. This will allow those with the right to do so to
|
|
remove administrator privileges from other users or grant them to
|
|
themselves. Enable with care.</para>
|
|
</listitem>
|
|
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>tweakparams</emphasis>:
|
|
This flag allows a user to change Bugzilla's Params
|
|
(using <filename>editparams.cgi</filename>.)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis><productname></emphasis>:
|
|
This allows an administrator to specify the products in which
|
|
a user can see bugs. The user must still have the
|
|
"editbugs" privilege to edit bugs in these products.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="programadmin">
|
|
<title>Product, Component, Milestone, and Version Administration</title>
|
|
|
|
<section id="products">
|
|
<title>Products</title>
|
|
|
|
<para>
|
|
<glossterm linkend="gloss-product" baseform="product">
|
|
Products</glossterm>
|
|
|
|
are the broadest category in Bugzilla, and tend to represent real-world
|
|
shipping products. E.g. if your company makes computer games,
|
|
you should have one product per game, perhaps a "Common" product for
|
|
units of technology used in multiple games, and maybe a few special
|
|
products (Website, Administration...)</para>
|
|
|
|
<para>Many of Bugzilla's settings are configurable on a per-product
|
|
basis. The number of "votes" available to users is set per-product,
|
|
as is the number of votes
|
|
required to move a bug automatically from the UNCONFIRMED status to the
|
|
NEW status.</para>
|
|
|
|
<para>To create a new product:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Select "products" from the footer</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Select the "Add" link in the bottom right</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Enter the name of the product and a description. The
|
|
Description field may contain HTML.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>Don't worry about the "Closed for bug entry", "Maximum Votes
|
|
per person", "Maximum votes a person can put on a single bug",
|
|
"Number of votes a bug in this Product needs to automatically get out
|
|
of the UNCONFIRMED state", and "Version" options yet. We'll cover
|
|
those in a few moments.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="components">
|
|
<title>Components</title>
|
|
|
|
<para>Components are subsections of a Product. E.g. the computer game
|
|
you are designing may have a "UI"
|
|
component, an "API" component, a "Sound System" component, and a
|
|
"Plugins" component, each overseen by a different programmer. It
|
|
often makes sense to divide Components in Bugzilla according to the
|
|
natural divisions of responsibility within your Product or
|
|
company.</para>
|
|
|
|
<para>
|
|
Each component has a owner and (if you turned it on in the parameters),
|
|
a QA Contact. The owner should be the primary person who fixes bugs in
|
|
that component. The QA Contact should be the person who will ensure
|
|
these bugs are completely fixed. The Owner, QA Contact, and Reporter
|
|
will get email when new bugs are created in this Component and when
|
|
these bugs change. Default Owner and Default QA Contact fields only
|
|
dictate the
|
|
<emphasis>default assignments</emphasis>;
|
|
these can be changed on bug submission, or at any later point in
|
|
a bug's life.</para>
|
|
|
|
<para>To create a new Component:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Select the "Edit components" link from the "Edit product"
|
|
page</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Select the "Add" link in the bottom right.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Fill out the "Component" field, a short "Description",
|
|
the "Initial Owner" and "Initial QA Contact" (if enabled.)
|
|
The Component and Description fields may contain HTML;
|
|
the "Initial Owner" field must be a login name
|
|
already existing in the database.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
|
|
<section id="versions">
|
|
<title>Versions</title>
|
|
|
|
<para>Versions are the revisions of the product, such as "Flinders
|
|
3.1", "Flinders 95", and "Flinders 2000". Version is not a multi-select
|
|
field; the usual practice is to select the most recent version with
|
|
the bug.
|
|
</para>
|
|
|
|
<para>To create and edit Versions:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>From the "Edit product" screen, select "Edit Versions"</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>You will notice that the product already has the default
|
|
version "undefined". Click the "Add" link in the bottom right.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Enter the name of the Version. This field takes text only.
|
|
Then click the "Add" button.</para>
|
|
</listitem>
|
|
|
|
</orderedlist>
|
|
</section>
|
|
|
|
<section id="milestones">
|
|
<title>Milestones</title>
|
|
|
|
<para>Milestones are "targets" that you plan to get a bug fixed by. For
|
|
example, you have a bug that you plan to fix for your 3.0 release, it
|
|
would be assigned the milestone of 3.0.</para>
|
|
|
|
<note>
|
|
<para>Milestone options will only appear for a Product if you turned
|
|
on the "usetargetmilestone" Param in the "Edit Parameters" screen.
|
|
</para>
|
|
</note>
|
|
|
|
<para>To create new Milestones, set Default Milestones, and set
|
|
Milestone URL:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Select "Edit milestones" from the "Edit product" page.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Select "Add" in the bottom right corner.
|
|
text</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Enter the name of the Milestone in the "Milestone" field. You
|
|
can optionally set the "sortkey", which is a positive or negative
|
|
number (-255 to 255) that defines where in the list this particular
|
|
milestone appears. This is because milestones often do not
|
|
occur in alphanumeric order For example, "Future" might be
|
|
after "Release 1.2". Select "Add".</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>From the Edit product screen, you can enter the URL of a
|
|
page which gives information about your milestones and what
|
|
they mean. </para>
|
|
|
|
<tip>
|
|
<para>If you want your milestone document to be restricted so
|
|
that it can only be viewed by people in a particular Bugzilla
|
|
group, the best way is to attach the document to a bug in that
|
|
group, and make the URL the URL of that attachment.</para>
|
|
</tip>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="voting">
|
|
<title>Voting</title>
|
|
|
|
<para>Voting allows users to be given a pot of votes which they can allocate
|
|
to bugs, to indicate that they'd like them fixed.
|
|
This allows developers to gauge
|
|
user need for a particular enhancement or bugfix. By allowing bugs with
|
|
a certain number of votes to automatically move from "UNCONFIRMED" to
|
|
"NEW", users of the bug system can help high-priority bugs garner
|
|
attention so they don't sit for a long time awaiting triage.</para>
|
|
|
|
<para>To modify Voting settings:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Navigate to the "Edit product" screen for the Product you
|
|
wish to modify</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Maximum Votes per person</emphasis>:
|
|
Setting this field to "0" disables voting.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Maximum Votes a person can put on a single
|
|
bug"</emphasis>:
|
|
It should probably be some number lower than the
|
|
"Maximum votes per person". Don't set this field to "0" if
|
|
"Maximum votes per person" is non-zero; that doesn't make
|
|
any sense.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Number of votes a bug in this product needs to
|
|
automatically get out of the UNCONFIRMED state</emphasis>:
|
|
Setting this field to "0" disables the automatic move of
|
|
bugs from UNCONFIRMED to NEW.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Once you have adjusted the values to your preference, click
|
|
"Update".</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
|
|
<section id="groups">
|
|
<title>Groups and Group Security</title>
|
|
|
|
<para>Groups allow the administrator
|
|
to isolate bugs or products that should only be seen by certain people.
|
|
There are two types of group - Generic Groups, and Product-Based Groups.
|
|
</para>
|
|
|
|
<para>
|
|
Product-Based Groups are matched with products, and allow you to restrict
|
|
access to bugs on a per-product basis. They are enabled using the
|
|
usebuggroups Param. Turning on the usebuggroupsentry
|
|
Param will mean bugs automatically get added to their product group when
|
|
filed.
|
|
</para>
|
|
|
|
<para>
|
|
Generic Groups have no special relationship to products;
|
|
you create them, and put bugs in them
|
|
as required. One example of the use of Generic Groups
|
|
is Mozilla's "Security" group,
|
|
into which security-sensitive bugs are placed until fixed. Only the
|
|
Mozilla Security Team are members of this group.
|
|
</para>
|
|
|
|
<para>To create Generic Groups:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Select the "groups"
|
|
link in the footer.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Take a moment to understand the instructions on the "Edit
|
|
Groups" screen, then select the "Add Group" link.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Fill out the "New Name", "New Description", and
|
|
"New User RegExp" fields. "New User RegExp" allows you to automatically
|
|
place all users who fulfill the Regular Expression into the new group.
|
|
When you have finished, click "Add".</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>To use Product-Based Groups:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Turn on "usebuggroups" and "usebuggroupsentry" in the "Edit
|
|
Parameters" screen.</para>
|
|
|
|
<warning>
|
|
<para>XXX is this still true?
|
|
"usebuggroupsentry" has the capacity to prevent the
|
|
administrative user from directly altering bugs because of
|
|
conflicting group permissions. If you plan on using
|
|
"usebuggroupsentry", you should plan on restricting
|
|
administrative account usage to administrative duties only. In
|
|
other words, manage bugs with an unpriveleged user account, and
|
|
manage users, groups, Products, etc. with the administrative
|
|
account.</para>
|
|
</warning>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>In future, when you create a Product, a matching group will be
|
|
automatically created. If you need to add a Product Group to
|
|
a Product which was created before you turned on usebuggroups,
|
|
then simply create a new group, as outlined above, with the
|
|
same name as the Product.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<warning>
|
|
<para>Bugzilla currently has a limit of 64 groups per installation. If
|
|
you have more than about 50 products, you should consider
|
|
running multiple Bugzillas. Ask in the newsgroup for other
|
|
suggestions for working around this restriction.</para>
|
|
</warning>
|
|
|
|
<para>
|
|
Note that group permissions are such that you need to be a member
|
|
of <emphasis>all</emphasis> the groups a bug is in, for whatever
|
|
reason, to see that bug.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
By default, bugs can also be seen by the Assignee, the Reporter, and
|
|
by everyone on the CC List, regardless of whether or not the bug would
|
|
typically be viewable by them. Visibility to the Reporter and CC List can
|
|
be overridden (on a per-bug basis) by bringing up the bug, finding the
|
|
section that starts with <quote>Users in the roles selected below...</quote>
|
|
and un-checking the box next to either 'Reporter' or 'CC List' (or both).
|
|
</para>
|
|
</note>
|
|
</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>
|
|
</warning>
|
|
|
|
<note>
|
|
<para>These instructions must, of necessity, be somewhat vague since
|
|
Bugzilla runs on so many different platforms. If you have refinements
|
|
of these directions, please submit a bug to &bzg-bugs;.
|
|
</para>
|
|
</note>
|
|
|
|
<warning>
|
|
<para>This is not meant to be a comprehensive list of every possible
|
|
security issue regarding the tools 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... 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>Make sure you are running at least version 3.22.32 of MySQL
|
|
as earlier versions had notable security holes.
|
|
</para>
|
|
</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>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></prompt> DELETE FROM user WHERE user = '';
|
|
<prompt>mysql></prompt> UPDATE user SET password = password('<replaceable>new_password</replaceable>') WHERE user = 'root';
|
|
<prompt>mysql></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.cnf</filename>:
|
|
</para>
|
|
<programlisting>
|
|
[myslqd]
|
|
# Prevent network access to MySQL.
|
|
skip-networking
|
|
</programlisting>
|
|
</listitem>
|
|
|
|
<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>
|
|
</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.
|
|
</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>
|
|
</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 layed out, the list of what should and should
|
|
not be accessible is rather complicated. A new installation method
|
|
is currently in the works which should solve this by allowing files
|
|
that shouldn't be accessible from the web to be placed in directory
|
|
outside the webroot. See
|
|
<ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=44659">bug
|
|
44659</ulink> for more information.
|
|
</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>
|
|
<member><filename>processmail</filename></member>
|
|
<member><filename>syncshadowdb</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>
|
|
|
|
<tip>
|
|
<para>Bugzilla ships with the ability to generate
|
|
<filename>.htaccess</filename> files instructing Apache which files
|
|
should and should not be accessible.
|
|
</para>
|
|
</tip>
|
|
|
|
<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>
|
|
|
|
</section>
|
|
|
|
<section id="cust-templates">
|
|
<title>Template Customisation</title>
|
|
|
|
<para>
|
|
One of the large changes for 2.16 was the templatisation of the
|
|
entire user-facing UI, using the
|
|
<ulink url="http://www.template-toolkit.org">Template Toolkit</ulink>.
|
|
Administrators can now configure the look and feel of Bugzilla without
|
|
having to edit Perl files or face the nightmare of massive merge
|
|
conflicts when they upgrade to a newer version in the future.
|
|
</para>
|
|
|
|
<para>
|
|
Templatisation also makes localised versions of Bugzilla possible,
|
|
for the first time. In the future, a Bugzilla installation may
|
|
have templates installed for multiple localisations, and select
|
|
which ones to use based on the user's browser language setting.
|
|
</para>
|
|
|
|
<section id="template-directory">
|
|
<title>Template Directory Structure</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.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</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.
|
|
</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
|
|
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
|
|
to continue using your own templates, or make the effort to merge your
|
|
changes into the new versions by hand.
|
|
</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
|
|
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
|
|
previous stable release's release notes.
|
|
</para>
|
|
|
|
<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.
|
|
</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.
|
|
</para>
|
|
</warning>
|
|
</section>
|
|
|
|
<section id="template-edit">
|
|
<title>How To Edit Templates</title>
|
|
|
|
<note>
|
|
<para>
|
|
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'
|
|
Guide</ulink>.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
The syntax of the Template Toolkit language is beyond the scope of
|
|
this guide. It's reasonably easy to pick up by looking at the current
|
|
templates; or, you can read the manual, available on the
|
|
<ulink url="http://www.template-toolkit.org">Template Toolkit home
|
|
page</ulink>.
|
|
</para>
|
|
|
|
<para>
|
|
One thing you should take particular care about is the need
|
|
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 <, and the data was not intended to be HTML, they need to be
|
|
converted to entity form, ie &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>
|
|
|
|
<para>
|
|
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 &, 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>. 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
|
|
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>
|
|
|
|
</section>
|
|
|
|
|
|
<section id="template-formats">
|
|
<title>Template Formats</title>
|
|
|
|
<para>
|
|
Some CGIs 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). If you would like to
|
|
retrieve a certain format, you can use the &format=<format>
|
|
(such as simple or complex) in the URL. (Try this out
|
|
by appending <filename>&format=simple</filename> to a buglist.cgi
|
|
URL on your Bugzilla installation.) The mechanism that provides this
|
|
feature is extensible.
|
|
</para>
|
|
|
|
<para>
|
|
To see if a CGI supports multiple output formats, grep the
|
|
CGI for <quote>ValidateOutputFormat</quote>. If it's not present,
|
|
adding multiple format support isn't too hard; see how it's done in
|
|
other CGIs.
|
|
</para>
|
|
|
|
<para>
|
|
To make a new format template for a CGI which supports this,
|
|
open a current template for
|
|
that CGI and take note of the INTERFACE comment (if present.) This
|
|
comment defines what variables are passed into this template. If
|
|
there isn't one, I'm afraid you'll have to read the template and
|
|
the code to find out what information you get.
|
|
</para>
|
|
|
|
<para>
|
|
Write your template in whatever markup or text style is appropriate.
|
|
</para>
|
|
|
|
<para>
|
|
You now need to decide what content type you want your template
|
|
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 your content type.
|
|
This tag will be part of the template filename.
|
|
</para>
|
|
|
|
<para>
|
|
Save the template as <filename><stubname>-<formatname>.<contenttypetag>.tmpl</filename>.
|
|
Try out the template by calling the CGI as
|
|
<filename><cginame>.cgi?format=<formatname></filename> .
|
|
</para>
|
|
</section>
|
|
|
|
|
|
<section>
|
|
<title>Particular Templates</title>
|
|
|
|
<para>
|
|
There are a few templates you may be particularly interested in
|
|
customising for your installation.
|
|
</para>
|
|
|
|
<para>
|
|
<command>index.html.tmpl</command>:
|
|
This is the Bugzilla front page.
|
|
</para>
|
|
|
|
<para>
|
|
<command>global/header.html.tmpl</command>:
|
|
This defines the header that goes on all Bugzilla pages.
|
|
The header includes the banner, which is what appears to users
|
|
and is probably what you want to edit instead. However the
|
|
header also includes the HTML HEAD section, so you could for
|
|
example add a stylesheet or META tag by editing the header.
|
|
</para>
|
|
|
|
<para>
|
|
<command>global/banner.html.tmpl</command>:
|
|
This contains the <quote>banner</quote>, 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 customise this to give your
|
|
installation a distinctive look and feel. It is recommended you
|
|
preserve the Bugzilla version number in some form so the version
|
|
you are running can be determined, and users know what docs to read.
|
|
</para>
|
|
|
|
<para>
|
|
<command>global/footer.html.tmpl</command>:
|
|
This defines the footer that goes on all Bugzilla pages. Editing
|
|
this is another way to quickly get a distinctive look and feel for
|
|
your Bugzilla installation.
|
|
</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
|
|
bugs.
|
|
</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.
|
|
</para>
|
|
|
|
<para>
|
|
An example of this is the mozilla.org
|
|
<ulink url="http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl&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-<formatname>.html.tmpl</filename>,
|
|
and in it, add widgets for each piece of information you'd like
|
|
collected - such as a build number, or set of steps to reproduce.
|
|
</para>
|
|
|
|
<para>
|
|
Then, create a template like
|
|
<filename>custom/bug/create/comment.txt.tmpl</filename>, and call it
|
|
<filename>comment-<formatname>.txt.tmpl</filename>. This
|
|
template should reference the form fields you have created using
|
|
the syntax <filename>[% form.<fieldname> %]</filename>. 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 enter_bug template had a field
|
|
<programlisting><input type="text" name="buildid" size="30"></programlisting>
|
|
and then your comment.txt.tmpl had
|
|
<programlisting>BuildID: [% form.buildid %]</programlisting>
|
|
then
|
|
<programlisting>BuildID: 20020303</programlisting>
|
|
would appear in the initial checkin comment.
|
|
</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="upgrading">
|
|
<title>Upgrading to New Releases</title>
|
|
|
|
<para>
|
|
Upgrading Bugzilla is something we all want to do from time to time,
|
|
be it to get new features or pick up the latest security fix. How easy
|
|
it is to update depends on a few factors:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
If the new version is a revision or a new point release
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
How many local changes (if any) have been made
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<section id="upgrading-version-defns">
|
|
<title>Version Definitions</title>
|
|
|
|
<para>
|
|
Bugzilla displays the version you are using at the top of most
|
|
pages you load. It will look something like '2.16.7' or '2.18rc3'
|
|
or '2.19.1+'. The first number in this series is the Major Version.
|
|
This does not change very often (that is to say, almost never);
|
|
Bugzilla was 1.x.x when it was first created, and went to 2.x.x
|
|
when it was re-written in perl in Sept 1998. If/When the major version
|
|
is changed to 3.x.x, it will signify a significant structural change
|
|
and will be accompanied by much fanfare and many instructions on
|
|
how to upgrade, including a revision to this page. :)
|
|
</para>
|
|
|
|
<para>
|
|
The second number in the version is called the 'minor number', and
|
|
a release that changes the minor number is called a 'point release'.
|
|
An even number in this position (2.14, 2.16, 2.18, 2.20, etc.)
|
|
represents a stable version, while an odd number (2.17, 2.19, etc.)
|
|
represents a development version. In the past, stable point releases
|
|
were feature-based, coming when certain enhancements had been
|
|
completed, or the Bugzilla development team felt that enough
|
|
progress had been made overall. As of version 2.18, however,
|
|
Bugzilla has moved to a time-based release schedule; current plans
|
|
are to create a stable point release every 6 months or so after
|
|
2.18 is deployed.
|
|
</para>
|
|
|
|
<para>
|
|
The third number in the Bugzilla version represents a bugfix version.
|
|
Bugfix Revisions are normally released only to address security
|
|
vulnerabilities; in the future, it is likely that the Bugzilla
|
|
development team will back-port bugfixes in a new point release to
|
|
the old point release for a limited period. Once enough of these
|
|
bugfixes have accumulated (or a new security vulnerability is
|
|
identified and closed), a bugfix release will be made. As an
|
|
example, 2.16.6 was a bugfix release, and improved on 2.16.5.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
When reading version numbers, everything separated by a point ('.')
|
|
should be read as a single number. It is <emphasis>not</emphasis>
|
|
the same as decimal. 2.14 is newer than 2.8 because minor version
|
|
14 is greater than minor version 8. 2.24.11 would be newer than
|
|
2.24.9 (because bugfix 11 is greater than bugfix 9. This is
|
|
confusing to some people who aren't used to dealing with software.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section id="upgrading-methods">
|
|
<title>Upgrading - Methods and Procedure</title>
|
|
<para>
|
|
There are three different ways to upgrade your installation.
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
Using CVS (<xref linkend="upgrade-cvs"/>)
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Downloading a new tarball (<xref linkend="upgrade-tarball"/>)
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Applying the relevant patches (<xref linkend="upgrade-patches"/>)
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>
|
|
Each of these options has its own pros and cons; the one that's
|
|
right for you depends on how long it has been since you last
|
|
installed, the degree to which you have customized your installation,
|
|
and/or your network configuration. (Some discussion of the various
|
|
methods of updating compared with degree and methods of local
|
|
customization can be found in <xref linkend="template-method"/>.)
|
|
</para>
|
|
|
|
<para>
|
|
The larger the jump you are trying to make, the more difficult it
|
|
is going to be to upgrade if you have made local customizations.
|
|
Upgrading from 2.18 to 2.18.1 should be fairly painless even if
|
|
you are heavily customized, but going from 2.14 to 2.18 is going
|
|
to mean a fair bit of work re-writing your local changes to use
|
|
the new files, logic, templates, etc. If you have done no local
|
|
changes at all, however, then upgrading should be approximately
|
|
the same amount of work regardless of how long it has been since
|
|
your version was released.
|
|
</para>
|
|
|
|
<warning>
|
|
<para>
|
|
Upgrading is a one-way process. You should backup your database
|
|
and current Bugzilla directory before attempting the upgrade. If
|
|
you wish to revert to the old Bugzilla version for any reason, you
|
|
will have to restore from these backups.
|
|
</para>
|
|
</warning>
|
|
|
|
<para>
|
|
The examples in the following sections are written as though the
|
|
user were updating to version 2.18.1, but the procedures are the
|
|
same regardless of whether one is updating to a new point release
|
|
or simply trying to obtain a new bugfix release. Also, in the
|
|
examples the user's Bugzilla installation is found at
|
|
<filename>/var/www/html/bugzilla</filename>. If that is not the
|
|
same as the location of your Bugzilla installation, simply
|
|
substitute the proper paths where appropriate.
|
|
</para>
|
|
|
|
<section id="upgrade-cvs">
|
|
<title>Upgrading using CVS</title>
|
|
|
|
<para>
|
|
Every release of Bugzilla, whether it is a point release or a bugfix,
|
|
is tagged in CVS. Also, every tarball that has been distributed since
|
|
version 2.12 has been created in such a way that it can be used with
|
|
CVS once it is unpacked. Doing so, however, requires that you are able
|
|
to access cvs-mirror.mozilla.org on port 2401, which may not be an
|
|
option or a possibility for some users, especially those behind a
|
|
highly restrictive firewall.
|
|
</para>
|
|
|
|
<tip>
|
|
<para>
|
|
If you can, updating using CVS is probably the most painless
|
|
method, especially if you have a lot of local changes.
|
|
</para>
|
|
</tip>
|
|
|
|
<para>
|
|
The following shows the sequence of commands needed to update a
|
|
Bugzilla installation via CVS, and a typical series of results.
|
|
</para>
|
|
|
|
<programlisting>
|
|
bash$ <command>cd /var/www/html/bugzilla</command>
|
|
bash$ <command>cvs login</command>
|
|
Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401/cvsroot
|
|
CVS password: <emphasis>('anonymous', or just leave it blank)</emphasis>
|
|
bash$ <command>cvs -q update -r BUGZILLA-2_18_1 -dP</command>
|
|
P checksetup.pl
|
|
P collectstats.pl
|
|
P globals.pl
|
|
P docs/rel_notes.txt
|
|
P template/en/default/list/quips.html.tmpl
|
|
<emphasis>(etc.)</emphasis>
|
|
</programlisting>
|
|
|
|
<caution>
|
|
<para>
|
|
If a line in the output from <command>cvs update</command> begins
|
|
with a <computeroutput>C</computeroutput>, then that represents a
|
|
file with local changes that CVS was unable to properly merge. You
|
|
need to resolve these conflicts manually before Bugzilla (or at
|
|
least the portion using that file) will be usable.
|
|
</para>
|
|
</caution>
|
|
</section>
|
|
|
|
<section id="upgrade-tarball">
|
|
<title>Upgrading using the tarball</title>
|
|
|
|
<para>
|
|
If you are unable (or unwilling) to use CVS, another option that's
|
|
always available is to obtain the latest tarball from the <ulink
|
|
url="http://www.bugzilla.org/download/">Download Page</ulink> and
|
|
create a new Bugzilla installation from that.
|
|
</para>
|
|
|
|
<para>
|
|
This sequence of commands shows how to get the tarball from the
|
|
command-line; it is also possible to download it from the site
|
|
directly in a web browser. If you go that route, save the file
|
|
to the <filename class="directory">/var/www/html</filename>
|
|
directory (or its equivalent, if you use something else) and
|
|
omit the first three lines of the example.
|
|
</para>
|
|
|
|
<programlisting>
|
|
bash$ <command>cd /var/www/html</command>
|
|
bash$ <command>wget ftp://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.18.1.tar.gz</command>
|
|
<emphasis>(Output omitted)</emphasis>
|
|
bash$ <command>tar xzvf bugzilla-2.18.1.tar.gz</command>
|
|
bugzilla-2.18.1/
|
|
bugzilla-2.18.1/.cvsignore
|
|
bugzilla-2.18.1/1x1.gif
|
|
<emphasis>(Output truncated)</emphasis>
|
|
bash$ <command>cd bugzilla-2.18.1</command>
|
|
bash$ <command>cp ../bugzilla/localconfig* .</command>
|
|
bash$ <command>cp -r ../bugzilla/data .</command>
|
|
bash$ <command>cd ..</command>
|
|
bash$ <command>mv bugzilla bugzilla.old</command>
|
|
bash$ <command>mv bugzilla-2.18.1 bugzilla</command>
|
|
</programlisting>
|
|
|
|
<warning>
|
|
<para>
|
|
The <command>cp</command> commands both end with periods which
|
|
is a very important detail, it tells the shell that the destination
|
|
directory is the current working directory.
|
|
</para>
|
|
</warning>
|
|
|
|
<para>
|
|
This upgrade method will give you a clean install of Bugzilla with the
|
|
same version as the tarball. That's fine if you don't have any local
|
|
customizations that you want to maintain, but if you do then you will
|
|
need to reapply them by hand to the appropriate files.
|
|
</para>
|
|
|
|
<para>
|
|
It's worth noting that since 2.12, the Bugzilla tarballs come
|
|
CVS-ready, so if you decide at a later date that you'd rather use
|
|
CVS as an upgrade method, your code will already be set up for it.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="upgrade-patches">
|
|
<title>Upgrading using patches</title>
|
|
|
|
<para>
|
|
If you are doing a bugfix upgrade -- that is, one where only the
|
|
last number of the revision changes, such as from 2.16.6 to 2.16.7
|
|
-- then you have the option of obtaining and applying a patch file
|
|
from the <ulink
|
|
url="http://www.bugzilla.org/download/">Download Page</ulink>.
|
|
This file is made available by the <ulink
|
|
url="http://www.bugzilla.org/developers/profiles.html">Bugzilla
|
|
Development Team</ulink>, and is a collection of all the bug fixes
|
|
and security patches that have been made since the last bugfix
|
|
release. If you are planning to upgrade via patches, it is safer
|
|
to grab this developer-made patch file than to read the patch
|
|
notes and apply all (or even just some of) the patches oneself,
|
|
as sometimes patches on bugs get changed before they get checked in.
|
|
</para>
|
|
|
|
<para>
|
|
As above, this example starts with obtaining the file via the
|
|
command line. If you have already downloaded it, you can omit the
|
|
first two commands.
|
|
</para>
|
|
|
|
<programlisting>
|
|
bash$ <command>cd /var/www/html/bugzilla</command>
|
|
bash$ <command>wget ftp://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.18.0-to-2.18.1.diff.gz</command>
|
|
<emphasis>(Output omitted)</emphasis>
|
|
bash$ <command>gunzip bugzilla-2.18.0-to-2.18.1.diff.gz</command>
|
|
bash$ <command>patch -p1 < bugzilla-2.18.0-to-2.18.1.diff</command>
|
|
patching file checksetup.pl
|
|
patching file collectstats.pl
|
|
patching file globals.pl
|
|
<emphasis>(etc.)</emphasis>
|
|
</programlisting>
|
|
|
|
<warning>
|
|
<para>
|
|
Be aware that upgrading from a patch file does not change the
|
|
entries in your <filename class="directory">CVS</filename> directory.
|
|
This could make it more difficult to upgrade using CVS
|
|
(<xref linkend="upgrade-cvs"/>) in the future.
|
|
</para>
|
|
</warning>
|
|
|
|
</section>
|
|
</section>
|
|
|
|
<section id="upgrading-completion">
|
|
<title>Completing Your Upgrade</title>
|
|
|
|
<para>
|
|
Regardless of which upgrade method you choose, you will need to
|
|
run <command>./checksetup.pl</command> before your Bugzilla
|
|
upgrade will be complete.
|
|
</para>
|
|
|
|
<programlisting>
|
|
bash$ <command>cd bugzilla</command>
|
|
bash$ <command>./checksetup.pl</command>
|
|
</programlisting>
|
|
|
|
<warning>
|
|
<para>
|
|
The period at the beginning of the command
|
|
<command>./checksetup.pl</command> is important and can not
|
|
be omitted.
|
|
</para>
|
|
</warning>
|
|
|
|
<para>
|
|
If you have done a lot of local modifications, it wouldn't hurt
|
|
to run the Bugzilla Testing suite. This is not a required step,
|
|
but it isn't going to hurt anything, and might help point out
|
|
some areas that could be improved. (More information on the
|
|
test suite can be had by following this link to the appropriate
|
|
section in the <ulink
|
|
url="http://www.bugzilla.org/docs/developer.html#testsuite">Developers'
|
|
Guide</ulink>.)
|
|
</para>
|
|
|
|
</section>
|
|
</section>
|
|
|
|
<!-- Integrating Bugzilla with Third-Party Tools -->
|
|
&integration;
|
|
|
|
</chapter>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-always-quote-attributes:t
|
|
sgml-auto-insert-required-elements:t
|
|
sgml-balanced-tag-edit:t
|
|
sgml-exposed-tags:nil
|
|
sgml-general-insert-case:lower
|
|
sgml-indent-data:t
|
|
sgml-indent-step:2
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
sgml-minimize-attributes:nil
|
|
sgml-namecase-general:t
|
|
sgml-omittag:t
|
|
sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
|
|
sgml-shorttag:t
|
|
sgml-tag-region-if-active:t
|
|
End:
|
|
-->
|
|
|