mirror of https://github.com/tLDP/LDP
1530 lines
58 KiB
XML
1530 lines
58 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>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>
|
|
<command>maintainer</command>:
|
|
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>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
<command>urlbase</command>:
|
|
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>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
<command>usebuggroups</command>:
|
|
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 "usebuggroups" to "on"
|
|
<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>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
<command>usebuggroupsentry</command>:
|
|
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>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
<command>shadowdb</command>:
|
|
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. 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, 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.
|
|
<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>
|
|
|
|
<para>If you use the "shadowdb" option, it is only natural that you
|
|
should turn the "queryagainstshadowdb" option on as well. Otherwise
|
|
you are replicating data into a shadow database for no reason!</para>
|
|
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
<command>shutdownhtml</command>:
|
|
|
|
If you need to shut down Bugzilla to perform administration, enter
|
|
some descriptive HTML here and anyone who tries to use Bugzilla will
|
|
receive a page to that effect. Obviously, editparams.cgi will
|
|
still be accessible so you can remove the HTML and re-enable Bugzilla.
|
|
:-)
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
<command>passwordmail</command>:
|
|
|
|
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>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
<command>useqacontact</command>:
|
|
|
|
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>
|
|
</step>
|
|
<step>
|
|
<para>
|
|
<command>usestatuswhiteboard</command>:
|
|
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>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
<command>whinedays</command>:
|
|
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>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
<command>commenton*</command>:
|
|
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.
|
|
<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>
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
<command>supportwatchers</command>:
|
|
|
|
Turning on this option allows users to ask to receive copies of
|
|
all a particular other user's bug email. This is, of
|
|
course, subject to the groupset restrictions on the bug; if the
|
|
<quote>watcher</quote>
|
|
would not normally be allowed to view a bug, the watcher cannot get
|
|
around the system by setting herself up to watch the bugs of someone
|
|
with bugs outside her privileges. They would still only receive email
|
|
updates for those bugs she could normally view.</para>
|
|
</step>
|
|
</procedure>
|
|
</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=0x7ffffffffffffff where login_name =
|
|
"(user's login name)";
|
|
</command>
|
|
</member>
|
|
</simplelist>
|
|
</para>
|
|
|
|
<para>Yes, that is
|
|
<emphasis>fourteen</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.
|
|
<warning>
|
|
<para>Don't disable the administrator account!</para>
|
|
</warning>
|
|
|
|
<note>
|
|
<para>The user can still submit bugs via
|
|
the e-mail gateway, if you set it up, even if the disabled text
|
|
field is filled in. The e-mail gateway should
|
|
<emphasis>not</emphasis>
|
|
be enabled for secure installations of Bugzilla.</para>
|
|
</note>
|
|
</para>
|
|
</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 UNCOMFIRMED 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>
|
|
</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
|
|
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></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.conf</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 comprimised, they all get
|
|
comprimised. 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>
|
|
<title>What to Edit</title>
|
|
<para>
|
|
There are two different ways of editing of Bugzilla's templates,
|
|
and which you use depends mainly on how you upgrade Bugzilla. The
|
|
template directory structure is that there's a top level directory,
|
|
<filename>template</filename>, which contains a directory for
|
|
each installed localisation. 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>
|
|
The first method of making customisations is to directly edit the
|
|
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>
|
|
|
|
<para>
|
|
If you use this method, your installation will break if CVS conflicts
|
|
occur.
|
|
</para>
|
|
|
|
<para>
|
|
The other method is to copy the templates 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
|
|
to continue using your own templates, or make the effort to merge your
|
|
changes into the new versions by hand.
|
|
</para>
|
|
|
|
<para>
|
|
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
|
|
previous stable release's release notes.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
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>
|
|
</section>
|
|
|
|
<section>
|
|
<title>How To Edit Templates</title>
|
|
|
|
<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>. However, you should particularly remember (for security
|
|
reasons) to always HTML filter things which come from the database or
|
|
user input, to prevent cross-site scripting attacks.
|
|
</para>
|
|
|
|
<para>
|
|
However, 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 fail to do this, 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 "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 "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>
|
|
|
|
<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/developerguide.html">Developers'
|
|
Guide</ulink>.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
|
|
<section>
|
|
<title>Template Formats</title>
|
|
|
|
<para>
|
|
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>&format=simple</filename> to a buglist.cgi
|
|
URL on your Bugzilla installation.) This
|
|
mechanism, called template 'formats', is extensible.
|
|
</para>
|
|
|
|
<para>
|
|
To see if a CGI supports multiple output formats, grep the
|
|
CGI for "ValidateOutputFormat". 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 you 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 "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 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>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/create/create.html.tmpl</command> and
|
|
<command>bug/create/comment.txt.tmpl</command>:
|
|
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-<formatname>.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>, 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 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, if any, local changes have been made</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>There are also three different methods 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>Which options are available to you may depend on how large a jump
|
|
you are making and/or your network configuration.
|
|
</para>
|
|
|
|
<para>Revisions are normally released to fix security vulnerabilities
|
|
and are distinguished by an increase in the third number. For example,
|
|
when 2.16.2 was released, it was a revision to 2.16.1.
|
|
</para>
|
|
|
|
<para>Point releases are normally released when the Bugzilla team feels
|
|
that there has been a significant amount of progress made between the
|
|
last point release and the current time. These are often proceeded by a
|
|
stabilization period and release candidates, however the use of
|
|
development versions or release candidates is beyond the scope of this
|
|
document. Point releases can be distinguished by an increase in the
|
|
second number, or minor version. For example, 2.16.2 is a newer point
|
|
release than 2.14.5.
|
|
</para>
|
|
|
|
<para>The examples in this section are written as if you were updating
|
|
to version 2.16.2. The procedures are the same regardless if you are
|
|
updating to a new point release or a new revision. However, the chance
|
|
of running into trouble increases when upgrading to a new point release,
|
|
escpecially if you've made local changes.
|
|
</para>
|
|
|
|
<para>These examples also assume that your Bugzilla installation is at
|
|
<filename>/var/www/html/bugzilla</filename>. If that is not the case,
|
|
simply substitute the proper paths where appropriate.
|
|
</para>
|
|
|
|
<example id="upgrade-cvs">
|
|
<title>Upgrading using CVS</title>
|
|
|
|
<para>Every release of Bugzilla, whether it is a revision or a point
|
|
release, is tagged in CVS. Also, every tarball we have distributed
|
|
since version 2.12 has been primed for using CVS. This does, however,
|
|
require that you are able to access cvs-mirror.mozilla.org on port
|
|
2401.
|
|
|
|
<tip>
|
|
<para>If you can do this, updating using CVS is probably the most
|
|
painless method, especially if you have a lot of local changes.
|
|
</para>
|
|
</tip>
|
|
</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: <command>anonymous</command>
|
|
bash$ <command>cvs -q update -r BUGZILLA-2_16_2 -dP</command>
|
|
P checksetup.pl
|
|
P collectstats.pl
|
|
P globals.pl
|
|
P docs/rel_notes.txt
|
|
P template/en/default/list/quips.html.tmpl
|
|
</programlisting>
|
|
|
|
<para>
|
|
<caution>
|
|
<para>If a line in the output from <command>cvs update</command>
|
|
begins with a <computeroutput>C</computeroutput> 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>
|
|
|
|
<note>
|
|
<para>You also need to run <command>./checksetup.pl</command>
|
|
before your Bugzilla upgrade will be complete.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
</example>
|
|
|
|
<example 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 download the latest tarball. This is the most
|
|
difficult option to use, especially if you have local changes.
|
|
</para>
|
|
|
|
<programlisting>
|
|
bash$ <command>cd /var/www/html</command>
|
|
bash$ <command>wget ftp://ftp.mozilla.org/pub/webtools/bugzilla-2.16.2.tar.gz</command>
|
|
<emphasis>Output omitted</emphasis>
|
|
bash$ <command>tar xzvf bugzilla-2.16.2.tar.gz</command>
|
|
bugzilla-2.16.2/
|
|
bugzilla-2.16.2/.cvsignore
|
|
bugzilla-2.16.2/1x1.gif
|
|
<emphasis>Output truncated</emphasis>
|
|
bash$ <command>cd bugzilla-2.16.2</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.16.2 bugzilla</command>
|
|
bash$ <command>cd bugzilla</command>
|
|
bash$ <command>./checksetup.pl</command>
|
|
<emphasis>Output omitted</emphasis>
|
|
</programlisting>
|
|
|
|
<para>
|
|
<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. Also, the period at the
|
|
beginning of the <command>./checksetup.pl</command> is important and
|
|
can not be omitted.
|
|
</para>
|
|
</warning>
|
|
|
|
<note>
|
|
<para>You will now have to reapply any changes you have made to your
|
|
local installation manually.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
</example>
|
|
|
|
<example id="upgrade-patches">
|
|
<title>Upgrading using patches</title>
|
|
|
|
<para>The Bugzilla team will normally make a patch file available for
|
|
revisions to go from the most recent revision to the new one. You could
|
|
also read the release notes and grab the patches attached to the
|
|
mentioned bug, but it is safer to use the released patch file as
|
|
sometimes patches get changed before they get checked in (for minor
|
|
spelling fixes and the like). It is also theorectically possible to
|
|
scour the fixed bug list and pick and choose which patches to apply
|
|
from a point release, but this is not recommended either as what you'll
|
|
end up with is a hodge podge Bugzilla that isn't really any version.
|
|
This would also make it more difficult to upgrade in the future.
|
|
</para>
|
|
|
|
<programlisting>
|
|
bash$ <command>cd /var/www/html/bugzilla</command>
|
|
bash$ <command>wget ftp://ftp.mozilla.org/pub/webtools/bugzilla-2.16.1-to-2.16.2.diff.gz</command>
|
|
<emphasis>Output omitted</emphasis>
|
|
bash$ <command>gunzip bugzilla-2.16.1-to-2.16.2.diff.gz</command>
|
|
bash$ <command>patch -p1 < bugzilla-2.16.1-to-2.16.2.diff</command>
|
|
patching file checksetup.pl
|
|
patching file collectstats.pl
|
|
patching file globals.pl
|
|
</programlisting>
|
|
|
|
<para>
|
|
<caution>
|
|
<para>If you do this, beware that this doesn't change the entires in
|
|
your <filename id="dir">CVS</filename> directory so it may make
|
|
updates using CVS (<xref linkend="upgrade-cvs"/>) more difficult in the
|
|
future.
|
|
</para>
|
|
</caution>
|
|
</para>
|
|
</example>
|
|
|
|
</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:
|
|
-->
|
|
|