<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>
+ <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>
<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>
+ <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>
+ <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>
-
- <para>For more information see <xref linkend="groups"/>.</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 <quote>usebuggroups</quote> to <quote>on</quote>
+ <emphasis>only</emphasis> if you may wish to restrict access
+ to particular bugs to certain groups of users. I suggest leaving
+ this parameter <emphasis>off</emphasis>
+ while initially testing your Bugzilla.
+ </para>
+
+ <para>
+ For more information see <xref linkend="groups"/>.
+ </para>
</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>
+ <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>
+ <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, 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.
+ As a guide, on reasonably old hardware, mozilla.org began needing
+ <quote>shadowdb</quote> when they reached around 40,000 Bugzilla
+ users with several hundred Bugzilla bug changes and comments per day.
+ </para>
+
+ <para>
+ The value of the parameter defines the name of the shadow bug
+ database. Set "shadowdb" to e.g. "bug_shadowdb" if you will be
+ running a *very* large installation of Bugzilla.
+ </para>
+
<note>
- <para>Enabling "shadowdb" can adversely affect the stability of
- your installation of Bugzilla. You should regularly check that your
- database is in sync. It is often advisable to force a shadow
- database sync nightly via
- <quote>cron</quote>.
+ <para>
+ 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>
-
+ <para>
+ If you use the <quote>shadowdb</quote> option, it is only natural
+ that you should turn the <quote>queryagainstshadowdb</quote>
+ option on as well. Otherwise you are replicating data into a shadow
+ database for no reason!
+ </para>
</step>
<step>
<para>
- <command>shutdownhtml</command>:
+ <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.
- :-)
+ If you need to shut down Bugzilla to perform administration, enter
+ some descriptive text (with embedded HTML codes, if you'd like)
+ into this box. Anyone who tries to use Bugzilla (including admins)
+ will receive a page displaying this text. Users can neither log in
+ nor log out while shutdownhtml is enabled.
</para>
+
+ <note>
+ <para>
+ Although regular log-in capability is disabled while 'shutdownhtml'
+ is enabled, safeguards are in place to protect the unfortunate
+ admin who loses connection to Bugzilla. Should this happen to you,
+ go directly to the <filename>editparams.cgi</filename> (by typing
+ the URL in manually, if necessary). Doing this will prompt you to
+ log in, and your name/password will be accepted here (but nowhere
+ else).
+ </para>
+ </note>
</step>
<step>
<para>
- <command>passwordmail</command>:
+ <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>
+ 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>
+ <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>:
+ <command>movebugs</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>
+ 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>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.
+ <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>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>
+ <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>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.
+ <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.
+ </para>
+
<note>
- <para>It is generally far better to require a developer comment
- when resolving bugs than not. Few things are more annoying to bug
- database users than having a developer mark a bug "fixed" without
- any comment as to what the fix was (or even that it was truly
- fixed!)</para>
+ <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>
+ <command>supportwatchers</command>:
+
+ Turning on this option allows users to ask to receive copies
+ of bug mail sent to another user. Watching a user with
+ different group permissions is not a way to 'get around' the
+ system; copied emails are still subject to the normal groupset
+ permissions of a bug, and <quote>watchers</quote> will only be
+ copied on emails from bugs they would normally be allowed to view.
+ </para>
</step>
</procedure>
</section>