1133 lines
42 KiB
XML
1133 lines
42 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>makeproductgroups</command>:
|
|
This dictates whether or not to automatically create groups
|
|
when new products are created.
|
|
</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>
|
|
<command>useentrygroupdefault</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
|
|
causes the initial group controls on newly created products
|
|
to place all newly-created bugs in the group
|
|
having the same name as the product immediately.
|
|
After a product is initially created, the group controls
|
|
can be further adjusted without interference by
|
|
this mechanism.</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. Note that more recent versions of mysql support row level
|
|
locking using different table types. These types are slower than the
|
|
standard type, and Bugzilla does not yet take advantage of features
|
|
such as transactions which would justify this speed decrease. The
|
|
Bugzilla team are, however, happy to hear about any experiences with
|
|
row level locking and Bugzilla.</para>
|
|
|
|
<para>The <quote>shadowdb</quote>
|
|
parameter was designed to get around this limitation. While only a
|
|
single user is allowed to write to a table at a time, reads can
|
|
continue unimpeded on a read-only shadow copy of the database.
|
|
Although your database size will double, a shadow database can cause
|
|
an enormous performance improvement when implemented on extremely
|
|
high-traffic Bugzilla databases.</para>
|
|
|
|
<para>
|
|
As a guide, on reasonably old hardware, mozilla.org began needing
|
|
<quote>shadowdb</quote>
|
|
when they reached around 40,000 Bugzilla users with several hundred
|
|
Bugzilla bug changes and comments per day.</para>
|
|
|
|
<para>The value of the parameter defines the name of the
|
|
shadow bug database. You will need to set the host and port settings
|
|
from the params page, and set up replication in your database server
|
|
so that updates reach this readonly mirror. Consult your database
|
|
documentation for more detail.</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>movebugs</command>:
|
|
|
|
This option is an undocumented feature to allow moving bugs
|
|
between separate Bugzilla installations. You will need to understand
|
|
the source code in order to use this feature. Please consult
|
|
<filename>movebugs.pl</filename> in your Bugzilla source tree for
|
|
further documentation, such as it is.
|
|
</para>
|
|
</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, add them to
|
|
the "admin" group and, optionally, add edit the tweakparams, editusers,
|
|
creategroups, editcomponents, and editkeywords groups to add the
|
|
entire admin group to those groups.
|
|
</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 all the administrator accounts!</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="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 earliest version known to have
|
|
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>
|
|
</listitem>
|
|
</orderedlist>
|
|
</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="quips">
|
|
<title>Quips</title>
|
|
|
|
<para>
|
|
Quips are small text messages that can be configured to appear
|
|
next to search results. A Bugzilla installation can have its own specific
|
|
quips. Whenever a quip needs to be displayed, a random selection
|
|
is made from the pool of already existing quips.
|
|
</para>
|
|
|
|
<para>
|
|
Quips are controlled by the <emphasis>enablequips</emphasis> parameter.
|
|
It has several possible values: on, approved, frozen or off.
|
|
In order to enable quips approval you need to set this parameter
|
|
to "approved". In this way, users are free to submit quips for
|
|
addition but an administrator must explicitly approve them before
|
|
they are actually used.
|
|
</para>
|
|
|
|
<para>
|
|
In order to see the user interface for the quips, it is enough to click
|
|
on a quip when it is displayed together with the search results. Or
|
|
it can be seen directly in the browser by visiting the quips.cgi URL
|
|
(prefixed with the usual web location of the Bugzilla installation).
|
|
Once the quip interface is displayed, it is enough to click the
|
|
"view and edit the whole quip list" in order to see the administration
|
|
page. A page with all the quips available in the database will
|
|
be displayed.
|
|
</para>
|
|
|
|
<para>
|
|
Next to each tip there is a checkbox, under the
|
|
"Approved" column. Quips who have this checkbox checked are
|
|
already approved and will appear next to the search results.
|
|
The ones that have it unchecked are still preserved in the
|
|
database but they will not appear on search results pages.
|
|
User submitted quips have initially the checkbox unchecked.
|
|
</para>
|
|
|
|
<para>
|
|
Also, there is a delete link next to each quip,
|
|
which can be used in order to permanently delete a quip.
|
|
</para>
|
|
</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.
|
|
The association between products and groups is controlled from
|
|
the product edit page under <quote>Edit Group Controls.</quote>
|
|
</para>
|
|
|
|
<para>
|
|
If the makeproductgroups param is on, a new group will be automatically
|
|
created for every new product. It is primarily available for backward
|
|
compatibility with older sites.
|
|
</para>
|
|
<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. Similarly, you must be a member
|
|
of <emphasis>all</emphasis> of the entry groups for a product
|
|
to add bugs to a product and you must be a member
|
|
of <emphasis>all</emphasis> of the canedit groups for a product
|
|
in order to make <emphasis>any</emphasis> change to bugs in that
|
|
product.
|
|
</para>
|
|
<section>
|
|
<title>Creating Groups</title>
|
|
<para>To create Groups:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Select the <quote>groups</quote>
|
|
link in the footer.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Take a moment to understand the instructions on the <quote>Edit
|
|
Groups</quote> screen, then select the <quote>Add Group</quote> link.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Fill out the <quote>Group</quote>, <quote>Description</quote>,
|
|
and <quote>User RegExp</quote> fields.
|
|
<quote>User RegExp</quote> allows you to automatically
|
|
place all users who fulfill the Regular Expression into the new group.
|
|
When you have finished, click <quote>Add</quote>.</para>
|
|
<para>Users whose email addresses match the regular expression
|
|
will automatically be members of the group as long as their
|
|
email addresses continue to match the regular expression.</para>
|
|
<note>
|
|
<para>This is a change from 2.16 where the regular expression
|
|
resulted in a user acquiring permanent membership in a group.
|
|
To remove a user from a group the user was in due to a regular
|
|
expression in version 2.16 or earlier, the user must be explicitly
|
|
removed from the group.</para>
|
|
</note>
|
|
<warning>
|
|
<para>If specifying a domain in the regexp, make sure you end
|
|
the regexp with a $. Otherwise, when granting access to
|
|
"@mycompany\.com", you will allow access to
|
|
'badperson@mycompany.com.cracker.net'. You need to use
|
|
'@mycompany\.com$' as the regexp.</para>
|
|
</warning>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If you plan to use this group to directly control
|
|
access to bugs, check the "use for bugs" box. Groups
|
|
not used for bugs are still useful because other groups
|
|
can include the group as a whole.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>After you add your new group, edit the new group. On the
|
|
edit page, you can specify other groups that should be included
|
|
in this group and which groups should be permitted to add and delete
|
|
users from this group.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
</section>
|
|
<section>
|
|
<title>Assigning Users to Groups</title>
|
|
<para>Users can become a member of a group in several ways.</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>The user can be explicitly placed in the group by editing
|
|
the user's own profile</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The group can include another group of which the user is
|
|
a member.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The user's email address can match a regular expression
|
|
that the group specifies to automatically grant membership to
|
|
the group.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Assigning Group Controls to Products</title>
|
|
<para>
|
|
On the product edit page, there is a page to edit the
|
|
<quote>Group Controls</quote>
|
|
for a product. This allows you to
|
|
configure how a group relates to the product.
|
|
Groups may be applicable, default,
|
|
and mandatory as well as used to control entry
|
|
or used to make bugs in the product
|
|
totally read-only unless the group restrictions are met.
|
|
</para>
|
|
|
|
<para>
|
|
For each group, it is possible to specify if membership in that
|
|
group is...
|
|
</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
required for bug entry,
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Not applicable to this product(NA),
|
|
a possible restriction for a member of the
|
|
group to place on a bug in this product(Shown),
|
|
a default restriction for a member of the
|
|
group to place on a bug in this product(Default),
|
|
or a mandatory restriction to be placed on bugs
|
|
in this product(Mandatory).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Not applicable by non-members to this product(NA),
|
|
a possible restriction for a non-member of the
|
|
group to place on a bug in this product(Shown),
|
|
a default restriction for a non-member of the
|
|
group to place on a bug in this product(Default),
|
|
or a mandatory restriction to be placed on bugs
|
|
in this product when entered by a non-member(Mandatory).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
required in order to make <emphasis>any</emphasis> change
|
|
to bugs in this product <emphasis>including comments.</emphasis>
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<para>These controls are often described in this order, so a
|
|
product that requires a user to be a member of group "foo"
|
|
to enter a bug and then requires that the bug stay resticted
|
|
to group "foo" at all times and that only members of group "foo"
|
|
can edit the bug even if they otherwise could see the bug would
|
|
have its controls summarized by...</para>
|
|
<programlisting>
|
|
foo: ENTRY, MANDATORY/MANDATORY, CANEDIT
|
|
</programlisting>
|
|
|
|
</section>
|
|
<section>
|
|
<title>Common Applications of Group Controls</title>
|
|
<section>
|
|
<title>General User Access With Security Group</title>
|
|
<para>To permit any user to file bugs in each product (A, B, C...)
|
|
and to permit any user to submit those bugs into a security
|
|
group....</para>
|
|
<programlisting>
|
|
Product A...
|
|
security: SHOWN/SHOWN
|
|
Product B...
|
|
security: SHOWN/SHOWN
|
|
Product C...
|
|
security: SHOWN/SHOWN
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>General User Access With A Security Product</title>
|
|
<para>To permit any user to file bugs in a Security product
|
|
while keeping those bugs from becoming visible to anyone
|
|
outside the securityworkers group unless a member of the
|
|
securityworkers group removes that restriction....</para>
|
|
<programlisting>
|
|
Product Security...
|
|
securityworkers: DEFAULT/MANDATORY
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>Product Isolation With Common Group</title>
|
|
<para>To permit users of product A to access the bugs for
|
|
product A, users of product B to access product B, and support
|
|
staff to access both, 3 groups are needed</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Support: Contains members of the support staff.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>AccessA: Contains users of product A and the Support group.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>AccessB: Contains users of product B and the Support group.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<para>Once these 3 groups are defined, the products group controls
|
|
can be set to..</para>
|
|
<programlisting>
|
|
Product A...
|
|
AccessA: ENTRY, MANDATORY/MANDATORY
|
|
Product B...
|
|
AccessB: ENTRY, MANDATORY/MANDATORY
|
|
</programlisting>
|
|
<para>Optionally, the support group could be permitted to make
|
|
bugs inaccessible to the users and could be permitted to publish
|
|
bugs relevant to all users in a common product that is read-only
|
|
to anyone outside the support group. That configuration could
|
|
be...</para>
|
|
<programlisting>
|
|
Product A...
|
|
AccessA: ENTRY, MANDATORY/MANDATORY
|
|
Support: SHOWN/NA
|
|
Product B...
|
|
AccessB: ENTRY, MANDATORY/MANDATORY
|
|
Support: SHOWN/NA
|
|
Product Common...
|
|
Support: ENTRY, DEFAULT/MANDATORY, CANEDIT
|
|
</programlisting>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="upgrading">
|
|
<title>Upgrading to New Releases</title>
|
|
|
|
<warning>
|
|
<para>Upgrading is a one-way process. You should backup your database
|
|
and current Bugzilla directory before attempting the upgrade. If you wish
|
|
to revert to the old Bugzilla version for any reason, you will have to
|
|
restore from these backups.
|
|
</para>
|
|
</warning>
|
|
|
|
<para>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.
|
|
It is also theoretically 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>
|
|
</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:
|
|
-->
|
|
|