зеркало из https://github.com/mozilla/pjs.git
1239 строки
48 KiB
Plaintext
1239 строки
48 KiB
Plaintext
<!-- <!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 for specific platforms, please submit them to
|
|
<ulink url="mailto://mozilla-webtools@mozilla.org">
|
|
mozilla-webtools@mozilla.org</ulink>
|
|
</para>
|
|
</note>
|
|
|
|
<para>To secure your installation:
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Ensure you are running at least MysQL version 3.22.32 or newer.
|
|
Earlier versions had notable security holes and (from a security
|
|
point of view) poor default configuration choices.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>There is no substitute for understanding the tools on your
|
|
system!</emphasis>
|
|
|
|
Read
|
|
<ulink url="http://www.mysql.com/doc/P/r/Privilege_system.html">
|
|
The MySQL Privilege System</ulink>
|
|
until you can recite it from memory!</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Lock down /etc/inetd.conf. Heck, disable inet entirely on this
|
|
box. It should only listen to port 25 for Sendmail and port 80 for
|
|
Apache.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Do not run Apache as
|
|
<quote>nobody</quote>
|
|
|
|
. This will require very lax permissions in your Bugzilla
|
|
directories. Run it, instead, as a user with a name, set via your
|
|
httpd.conf file.
|
|
<note>
|
|
<para>
|
|
<quote>nobody</quote>
|
|
|
|
is a real user on UNIX systems. Having a process run as user id
|
|
<quote>nobody</quote>
|
|
|
|
is absolutely no protection against system crackers versus using
|
|
any other user account. As a general security measure, I recommend
|
|
you create unique user ID's for each daemon running on your system
|
|
and, if possible, use "chroot" to jail that process away from the
|
|
rest of your system.</para>
|
|
</note>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Ensure you have adequate access controls for the
|
|
$BUGZILLA_HOME/data/ directory, as well as the
|
|
$BUGZILLA_HOME/localconfig file.
|
|
The localconfig file stores your "bugs" database account password.
|
|
In addition, some
|
|
files under $BUGZILLA_HOME/data/ store sensitive information.
|
|
</para>
|
|
|
|
<para>Bugzilla provides default .htaccess files to protect the most
|
|
common Apache installations. However, you should verify these are
|
|
adequate according to the site-wide security policy of your web
|
|
server, and ensure that the .htaccess files are allowed to
|
|
"override" default permissions set in your Apache configuration
|
|
files. Covering Apache security is beyond the scope of this Guide;
|
|
please consult the Apache documentation for details.</para>
|
|
|
|
<para>If you are using a web server that does not support the
|
|
.htaccess control method,
|
|
<emphasis>you are at risk!</emphasis>
|
|
|
|
After installing, check to see if you can view the file
|
|
"localconfig" in your web browser (e.g.:
|
|
<ulink url="http://bugzilla.mozilla.org/localconfig">
|
|
http://bugzilla.mozilla.org/localconfig</ulink>
|
|
|
|
). If you can read the contents of this file, your web server has
|
|
not secured your bugzilla directory properly and you must fix this
|
|
problem before deploying Bugzilla. If, however, it gives you a
|
|
"Forbidden" error, then it probably respects the .htaccess
|
|
conventions and you are good to go.</para>
|
|
|
|
<para>When you run checksetup.pl, the script will attempt to modify
|
|
various permissions on files which Bugzilla uses. If you do not have
|
|
a webservergroup set in the localconfig file, then Bugzilla will have
|
|
to make certain files world readable and/or writable.
|
|
<emphasis>THIS IS INSECURE!</emphasis>
|
|
|
|
. This means that anyone who can get access to your system can do
|
|
whatever they want to your Bugzilla installation.</para>
|
|
|
|
<note>
|
|
<para>This also means that if your webserver runs all cgi scripts
|
|
as the same user/group, anyone on the system who can run cgi
|
|
scripts will be able to take control of your Bugzilla
|
|
installation.</para>
|
|
</note>
|
|
|
|
<para>On Apache, you can use .htaccess files to protect access to
|
|
these directories, as outlined in
|
|
<ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=57161">Bug
|
|
57161</ulink>
|
|
|
|
for the localconfig file, and
|
|
<ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=65572">Bug
|
|
65572</ulink>
|
|
|
|
for adequate protection in your data/ directory.</para>
|
|
|
|
<para>Note the instructions which follow are Apache-specific. If you
|
|
use IIS, Netscape, or other non-Apache web servers, please consult
|
|
your system documentation for how to secure these files from being
|
|
transmitted to curious users.</para>
|
|
|
|
<para>Place the following text into a file named ".htaccess",
|
|
readable by your web server, in your $BUGZILLA_HOME/data directory.
|
|
<literallayout><Files comments> allow from all </Files>
|
|
deny from all</literallayout>
|
|
</para>
|
|
|
|
<para>Place the following text into a file named ".htaccess",
|
|
readable by your web server, in your $BUGZILLA_HOME/ directory.
|
|
<literallayout><Files localconfig> deny from all </Files>
|
|
allow from all</literallayout>
|
|
</para>
|
|
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
</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>A plain Bugzilla is fairly easy to upgrade from one version to a
|
|
newer one. Always read the release notes to see if there are any issues
|
|
that you might need to take note of. It is recommended that you take a
|
|
backup of your database and your entire Bugzilla installation before attempting an
|
|
upgrade. You can upgrade a 'clean' installation by untarring a new
|
|
tarball over the old installation. If you are upgrading from 2.12 or
|
|
later, and have cvs installed, you can type <filename>cvs -z3 update</filename>,
|
|
and resolve conflicts if there are any.
|
|
</para>
|
|
|
|
<para>However, things get a bit more complicated if you've made
|
|
changes to Bugzilla's code. In this case, you may have to re-make or
|
|
reapply those changes. One good method is to take a diff of your customised
|
|
version against the original, so you can survey all that you've changed.
|
|
Hopefully, templatisation will reduce the need for
|
|
this in the future.</para>
|
|
|
|
<para>From version 2.8 onwards, Bugzilla databases can be automatically
|
|
carried forward during an upgrade. However, because the developers of
|
|
Bugzilla are constantly adding new
|
|
tables, columns and fields, you'll probably get SQL errors if you just
|
|
update the code and attempt to use Bugzilla. Always run the
|
|
<filename>checksetup.pl</filename>
|
|
script whenever you upgrade your installation.</para>
|
|
|
|
<para>If you are running Bugzilla version 2.8 or lower, and wish to
|
|
upgrade to the latest version, please consult the file,
|
|
"UPGRADING-pre-2.8" in the Bugzilla root directory after untarring the
|
|
archive.</para>
|
|
</section>
|
|
|
|
<!-- 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.sgml" "book" "chapter")
|
|
sgml-shorttag:t
|
|
sgml-tag-region-if-active:t
|
|
End:
|
|
-->
|
|
|