From ed4cd1fcff0454c33a9ca66a71a2c7803742c812 Mon Sep 17 00:00:00 2001
From: "lpsolit%gmail.com" <>
Date: Thu, 7 Feb 2008 03:58:55 +0000
Subject: [PATCH] Bug 390603: Configuration paramaters documentation needs
updating - Patch by Sam Folk-Williams <sam.folkwilliams@gmail.com>
r/a=LpSolit
---
docs/xml/administration.xml | 1089 ++++++++++++++++++++++++++---------
docs/xml/installation.xml | 274 +--------
2 files changed, 833 insertions(+), 530 deletions(-)
diff --git a/docs/xml/administration.xml b/docs/xml/administration.xml
index b7897215d..583042520 100644
--- a/docs/xml/administration.xml
+++ b/docs/xml/administration.xml
@@ -7,322 +7,897 @@
<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.
+ from the "Parameters" link in the Administration page (the
+ Administration page can be found by clicking the "Administration"
+ link in the footer). The parameters are divided into several categories,
+ accessed via the menu on the left. Following is a description of the
+ different categories and important parameters within those categories.
</para>
- <indexterm>
- <primary>checklist</primary>
- </indexterm>
+ <section id="param-requiredsettings">
+ <title>Required Settings</title>
- <variablelist>
- <varlistentry>
- <term>
- maintainer
- </term>
- <listitem>
- <para>
- The maintainer parameter is the email address of the person
- responsible for maintaining this Bugzilla installation.
- The address need not be that of a valid Bugzilla account.
- </para>
- </listitem>
- </varlistentry>
+ <para>
+ The core required parameters for any Bugzilla installation are set
+ here. These parameters must be set before a new Bugzilla installation
+ can be used. Administrators should review this list before
+ deploying a new Bugzilla installation.
+ </para>
- <varlistentry>
- <term>
- urlbase
- </term>
- <listitem>
- <para>
- This parameter defines the fully qualified domain name and web
- server path to your Bugzilla installation.
- </para>
+ <indexterm>
+ <primary>checklist</primary>
+ </indexterm>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ maintainer
+ </term>
+ <listitem>
+ <para>
+ Email address of the person
+ responsible for maintaining this Bugzilla installation.
+ The address need not be that of a valid Bugzilla account.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ urlbase
+ </term>
+ <listitem>
+ <para>
+ Defines the fully qualified domain name and web
+ server path to this Bugzilla installation.
+ </para>
+ <para>
+ For example, if the Bugzilla query page is
+ <filename>http://www.foo.com/bugzilla/query.cgi</filename>,
+ the <quote>urlbase</quote> should be set
+ to <filename>http://www.foo.com/bugzilla/</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ docs_urlbase
+ </term>
+ <listitem>
+ <para>
+ Defines the fully qualified domain name and web
+ server path to the Bugzilla documentation.
+ </para>
+ <para>
+ For example, if the "Bugzilla Configuration" page
+ of the documentation is
+ <filename>http://www.foo.com/bugzilla/docs/html/parameters.html</filename>,
+ set the <quote>docs_urlbase</quote>
+ to <filename>http://www.foo.com/bugzilla/docs/html/</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ sslbase
+ </term>
+ <listitem>
+ <para>
+ Defines the fully qualified domain name and web
+ server path for HTTPS (SSL) connections to this Bugzilla installation.
+ </para>
+ <para>
+ For example, if the Bugzilla main page is
+ <filename>https://www.foo.com/bugzilla/index.cgi</filename>,
+ the <quote>sslbase</quote> should be set
+ to <filename>https://www.foo.com/bugzilla/</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ ssl
+ </term>
+ <listitem>
+ <para>
+ Determines when Bugzilla will force HTTPS (SSL) connections, using
+ the URL defined in <command>sslbase</command>.
+ Options include "always", "never", and "authenticated sessions".
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ cookiedomain
+ </term>
+ <listitem>
+ <para>
+ Defines the domain for Bugzilla cookies. This is typically left blank.
+ If there are multiple hostnames that point to the same webserver, which
+ require the same cookie, then this parameter can be utilized. For
+ example, If your website is at
+ <filename>https://www.foo.com/</filename>, setting this to
+ <filename>.foo.com/</filename> will also allow
+ <filename>bar.foo.com/</filename> to access Bugzilla cookies.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ cookiepath
+ </term>
+ <listitem>
+ <para>
+ Defines a path, relative to the web server root, that Bugzilla
+ cookies will be restricted to. For example, if the
+ <command>urlbase</command> is set to
+ <filename>http://www.foo.com/bugzilla/</filename>, the
+ <command>cookiepath</command> should be set to
+ <filename>/bugzilla/</filename>. Setting it to "/" will allow all sites
+ served by this web server or virtual host to read Bugzilla cookies.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ timezone
+ </term>
+ <listitem>
+ <para>
+ Timezone of server. The timezone is displayed with timestamps. If
+ this parameter is left blank, the timezone is not displayed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ utf8
+ </term>
+ <listitem>
+ <para>
+ Determines whether to use UTF-8 (Unicode) encoding for all text in
+ Bugzilla. New installations should set this to true to avoid character
+ encoding problems. Existing databases should set this to true only
+ after the data has been converted from existing legacy character
+ encoding to UTF-8, using the
+ <filename>contrib/recode.pl</filename> script.
+ </para>
+ <note>
+ <para>
+ If you turn this parameter from "off" to "on", you must re-run
+ <filename>checksetup.pl</filename> immediately afterward.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ shutdownhtml
+ </term>
+ <listitem>
+ <para>
+ If there is any text in this field, this Bugzilla installation will
+ be completely disabled and this text will appear instead of all
+ Bugzilla pages for all users, including Admins. Used in the event
+ of site maintenance or outage situations.
+ </para>
+ <note>
+ <para>
+ Although regular log-in capability is disabled while
+ <command>shutdownhtml</command>
+ is enabled, safeguards are in place to protect the unfortunate
+ admin who loses connection to Bugzilla. Should this happen to you,
+ go directly to the <filename>editparams.cgi</filename> (by typing
+ the URL in manually, if necessary). Doing this will prompt you to
+ log in, and your name/password will be accepted here (but nowhere
+ else).
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ announcehtml
+ </term>
+ <listitem>
+ <para>
+ Any text in this field will be displayed at the top of every HTML
+ page in this Bugzilla installation. The text is not wrapped in any
+ tags. For best results, wrap the text in a <quote><div></quote>
+ tag. Any style attributes from the CSS can be applied. For example,
+ to make the text green inside of a red box, add <quote>id=message</quote>
+ to the <quote><div></quote> tag.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ proxy_url
+ </term>
+ <listitem>
+ <para>
+ If this Bugzilla installation is behind a proxy, enter the proxy
+ information here to enable Bugzilla to access the Internet. Bugzilla
+ requires Internet access to utilize the
+ <command>upgrade_notification</command> parameter (below). If the
+ proxy requires authentication, use the syntax:
+ <filename>http://user:pass@proxy_url/</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ upgrade_notification
+ </term>
+ <listitem>
+ <para>
+ Enable or disable a notification on the homepage of this Bugzilla
+ installation when a newer version of Bugzilla is available. This
+ notification is only visible to administrators. Choose "disabled",
+ to turn off the notification. Otherwise, choose which version of
+ Bugzilla you want to be notified about: "development_snapshot" is the
+ latest release on the trunk; "latest_stable_release" is the most
+ recent release available on the most recent stable branch;
+ "stable_branch_release" the most recent release on the branch
+ this installation is based on.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </section>
+
+ <section id="param-admin-policies">
+ <title>Administrative Policies</title>
+ <para>
+ This page contains parameters for basic administrative functions.
+ Options include whether to allow the deletion of bugs and users, whether
+ to allow users to change their email address, and whether to allow
+ user watching (one user receiving all notifications of a selected
+ other user).
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ supportwatchers
+ </term>
+ <listitem>
+ <para>
+ Turning on this option allows users to ask to receive copies
+ of bug mail sent to another user. Watching a user with
+ different group permissions is not a way to 'get around' the
+ system; copied emails are still subject to the normal groupset
+ permissions of a bug, and <quote>watchers</quote> will only be
+ copied on emails from bugs they would normally be allowed to view.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </section>
+
+ <section id="param-user-authentication">
+ <title>User Authentication</title>
<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>.
+ This page contains the settings that control how this Bugzilla
+ installation will do its authentication. Choose what authentication
+ mechanism to use (the Bugzilla database, or an external source such
+ as LDAP), and set basic behavioral parameters. For example, choose
+ whether to require users to login to browse bugs, the management
+ of authentication cookies, and the regular expression used to
+ validate email addresses. Some parameters are highlighted below.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- makeproductgroups
- </term>
- <listitem>
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ emailregexp
+ </term>
+ <listitem>
+ <para>
+ Defines the regular expression used to validate email addresses
+ used for login names. The default attempts to match fully
+ qualified email addresses (i.e. 'user@example.com'). Some
+ Bugzilla installations allow only local user names (i.e 'user'
+ instead of 'user@example.com'). In that case, the
+ <command>emailsuffix</command> parameter should be used to define
+ the email domain.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ emailsuffix
+ </term>
+ <listitem>
+ <para>
+ This string is appended to login names when actually sending
+ email to a user. For example,
+ If <command>emailregexp</command> has been set to allow
+ local usernames,
+ then this parameter would contain the email domain for all users
+ (i.e. '@example.com').
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </section>
+
+ <section id="param-attachments">
+ <title>Attachments</title>
<para>
- This dictates whether or not to automatically create groups
- when new products are created.
+ This page allows for setting restrictions and other parameters
+ regarding attachments to bugs. For example, control size limitations
+ and whether to allow uploading of remote files via a URI.
</para>
- </listitem>
- </varlistentry>
+ </section>
- <varlistentry>
- <term>
- useentrygroupdefault
- </term>
- <listitem>
+ <section id="param-bug-change-policies">
+ <title>Bug Change Policies</title>
<para>
- Bugzilla products can have a group associated with them, so that
- certain users can only see bugs in certain products. When this
- parameter is set to <quote>on</quote>, this
- 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.
+ Set policy on default behavior for bug change events. For example,
+ choose which status to set a bug to when it is marked as a duplicate,
+ and choose whether to allow bug reporters to set the priority or
+ target milestone. Also allows for configuration of what changes
+ should require the user to make a comment, described below.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- mail_delivery_method
- </term>
- <listitem>
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ commenton*
+ </term>
+ <listitem>
+ <para>
+ All these fields allow you to dictate what changes can pass
+ without comment, and which must have a comment from the
+ person who changed them. Often, administrators will allow
+ users to add themselves to the CC list, accept bugs, or
+ change the Status Whiteboard without adding a comment as to
+ their reasons for the change, yet require that most other
+ changes come with an explanation.
+ </para>
+
+ <para>
+ Set the "commenton" options according to your site policy. It
+ is a wise idea to require comments when users resolve, reassign, or
+ reopen bugs at the very least.
+ </para>
+
+ <note>
+ <para>
+ It is generally far better to require a developer comment
+ when resolving bugs than not. Few things are more annoying to bug
+ database users than having a developer mark a bug "fixed" without
+ any comment as to what the fix was (or even that it was truly
+ fixed!)
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ noresolveonopenblockers
+ </term>
+ <listitem>
+ <para>
+ This option will prevent users from resolving bugs as FIXED if
+ they have unresolved dependencies. Only the FIXED resolution
+ is affected. Users will be still able to resolve bugs to
+ resolutions other than FIXED if they have unresolved dependent
+ bugs.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </section>
+
+ <section id="param-bugfields">
+ <title>Bug Fields</title>
<para>
- This is used to specify how email is sent, or if it is sent at
- all. There are several options included for different MTAs,
- along with two additional options that disable email sending.
- "testfile" does not send mail, but instead saves it in
- <filename>data/mailer.testfile</filename> for later review.
- "none" disables email sending entirely.
+ The parameters in this section determine the default settings of
+ several Bugzilla fields for new bugs, and also control whether
+ certain fields are used. For example, choose whether to use the
+ "target milestone" field or the "status whiteboard" field.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- shadowdb
- </term>
- <listitem>
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ useqacontact
+ </term>
+ <listitem>
+ <para>
+ This allows you to define an email address for each component,
+ in addition to that of the default assignee, who will be sent
+ carbon copies of incoming bugs.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ usestatuswhiteboard
+ </term>
+ <listitem>
+ <para>
+ This defines whether you wish to have a free-form, overwritable field
+ associated with each bug. The advantage of the Status Whiteboard is
+ that it can be deleted or modified with ease, and provides an
+ easily-searchable field for indexing some bugs that have some trait
+ in common.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </section>
+
+ <section id="param-bugmoving">
+ <title>Bug Moving</title>
<para>
- You run into an interesting problem when Bugzilla reaches a
- high level of continuous activity. MySQL supports only table-level
- write locking. What this means is that if someone needs to make a
- change to a bug, they will lock the entire table until the operation
- is complete. Locking for write also blocks reads until the write is
- complete. Note that more recent versions of mysql support row level
- locking using different table types. These types are slower than the
- standard type, and Bugzilla does not yet take advantage of features
- such as transactions which would justify this speed decrease. The
- Bugzilla team are, however, happy to hear about any experiences with
- row level locking and Bugzilla.
+ This page controls whether this Bugzilla installation allows certain
+ users to move bugs to an external database. If bug moving is enabled,
+ there are a number of parameters that control bug moving behaviors.
+ For example, choose which users are allowed to move bugs, the location
+ of the external database, and the default product and component that
+ bugs moved <emphasis>from</emphasis> other bug databases to this
+ Bugzilla installation are assigned to.
</para>
+ </section>
+
+ <section id="param-dependency-graphs">
+ <title>Dependency Graphs</title>
<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.
+ This page has one parameter that sets the location of a Web Dot
+ server, or of the Web Dot binary on the local system, that is used
+ to generate dependency graphs. Web Dot is a CGI program that creates
+ images from <filename>.dot</filename> graphic description files. If
+ no Web Dot server or binary is specified, then dependency graphs will
+ be disabled.
</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.
+ </section>
+
+ <section id="param-group-security">
+ <title>Group Security</title>
+ <para>
+ Bugzilla allows for the creation of different groups, with the
+ ability to restrict the visibility of bugs in a group to a set of
+ specific users. Specific products can also be associated with
+ groups, and users restricted to only see products in their groups.
+ Several parameters are described in more detail below. Most of the
+ configuration of groups and their relationship to products is done
+ on the "Groups" and "Product" pages of the "Administration" area.
+ The options on this page control global default behavior.
+ For more information on Groups and Group Security, see
+ <xref linkend="groups"/>
+ </para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ makeproductgroups
+ </term>
+ <listitem>
+ <para>
+ Determines whether or not to automatically create groups
+ when new products are created. If this is on, the groups will be
+ used for querying bugs.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ useentrygroupdefault
+ </term>
+ <listitem>
+ <para>
+ Bugzilla products can have a group associated with them, so that
+ certain users can only see bugs in certain products. When this
+ parameter is set to <quote>on</quote>, this
+ 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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ querysharegroup
+ </term>
+ <listitem>
+ <para>
+ The name of the group of users who are allowed to share saved
+ searches with one another. For more information on using
+ saved searches, see <xref linkend="savedsearches"/>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </section>
+
+ <section id="bzldap">
+ <title>LDAP Authentication</title>
+
+ <para>LDAP authentication is a module for Bugzilla's plugin
+ authentication architecture. This page contains all the parameters
+ necessary to configure Bugzilla for use with LDAP authentication.
</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.
+ The existing authentication
+ scheme for Bugzilla uses email addresses as the primary user ID, and a
+ password to authenticate that user. All places within Bugzilla that
+ require a user ID (e.g assigning a bug) use the email
+ address. The LDAP authentication builds on top of this scheme, rather
+ than replacing it. The initial log-in is done with a username and
+ password for the LDAP directory. Bugzilla tries to bind to LDAP using
+ those credentials and, if successful, tries to map this account to a
+ Bugzilla account. If an LDAP mail attribute is defined, the value of this
+ attribute is used, otherwise the "emailsuffix" parameter is appended to LDAP
+ username to form a full email address. If an account for this address
+ already exists in the Bugzilla installation, it will log in to that account.
+ If no account for that email address exists, one is created at the time
+ of login. (In this case, Bugzilla will attempt to use the "displayName"
+ or "cn" attribute to determine the user's full name.) After
+ authentication, all other user-related tasks are still handled by email
+ address, not LDAP username. For example, bugs are still assigned by
+ email address and users are still queried by email address.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- shutdownhtml
- </term>
- <listitem>
+ <caution>
+ <para>Because the Bugzilla account is not created until the first time
+ a user logs in, a user who has not yet logged is unknown to Bugzilla.
+ This means they cannot be used as an assignee or QA contact (default or
+ otherwise), added to any CC list, or any other such operation. One
+ possible workaround is the <filename>bugzilla_ldapsync.rb</filename>
+ script in the
+ <glossterm linkend="gloss-contrib">
+ <filename class="directory">contrib</filename></glossterm>
+ directory. Another possible solution is fixing
+ <ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=201069">bug
+ 201069</ulink>.
+ </para>
+ </caution>
+
+ <para>Parameters required to use LDAP Authentication:</para>
+
+ <variablelist>
+ <varlistentry id="param-user_verify_class_for_ldap">
+ <term>user_verify_class</term>
+ <listitem>
+ <para>If you want to list <quote>LDAP</quote> here,
+ make sure to have set up the other parameters listed below.
+ Unless you have other (working) authentication methods listed as
+ well, you may otherwise not be able to log back in to Bugzilla once
+ you log out.
+ If this happens to you, you will need to manually edit
+ <filename>data/params</filename> and set user_verify_class to
+ <quote>DB</quote>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="param-LDAPserver">
+ <term>LDAPserver</term>
+ <listitem>
+ <para>This parameter should be set to the name (and optionally the
+ port) of your LDAP server. If no port is specified, it assumes
+ the default LDAP port of 389.
+ </para>
+ <para>Ex. <quote>ldap.company.com</quote>
+ or <quote>ldap.company.com:3268</quote>
+ </para>
+ <para>You can also specify a LDAP URI, so as to use other
+ protocols, such as LDAPS or LDAPI. If port was not specified in
+ the URI, the default is either 389 or 636 for 'LDAP' and 'LDAPS'
+ schemes respectively.
+ </para>
+ <para>Ex. <quote>ldap://ldap.company.com</quote>,
+ <quote>ldaps://ldap.company.com</quote> or
+ <quote>ldapi://%2fvar%2flib%2fldap_sock</quote>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="param-LDAPbinddn">
+ <term>LDAPbinddn [Optional]</term>
+ <listitem>
+ <para>Some LDAP servers will not allow an anonymous bind to search
+ the directory. If this is the case with your configuration you
+ should set the LDAPbinddn parameter to the user account Bugzilla
+ should use instead of the anonymous bind.
+ </para>
+ <para>Ex. <quote>cn=default,cn=user:password</quote></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="param-LDAPBaseDN">
+ <term>LDAPBaseDN</term>
+ <listitem>
+ <para>The LDAPBaseDN parameter should be set to the location in
+ your LDAP tree that you would like to search for email addresses.
+ Your uids should be unique under the DN specified here.
+ </para>
+ <para>Ex. <quote>ou=People,o=Company</quote></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="param-LDAPuidattribute">
+ <term>LDAPuidattribute</term>
+ <listitem>
+ <para>The LDAPuidattribute parameter should be set to the attribute
+ which contains the unique UID of your users. The value retrieved
+ from this attribute will be used when attempting to bind as the
+ user to confirm their password.
+ </para>
+ <para>Ex. <quote>uid</quote></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="param-LDAPmailattribute">
+ <term>LDAPmailattribute</term>
+ <listitem>
+ <para>The LDAPmailattribute parameter should be the name of the
+ attribute which contains the email address your users will enter
+ into the Bugzilla login boxes.
+ </para>
+ <para>Ex. <quote>mail</quote></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </section>
+
+ <section id="bzradius">
+ <title>RADIUS Authentication</title>
+
<para>
- If you need to shut down Bugzilla to perform administration, enter
- some descriptive text (with embedded HTML codes, if you'd like)
- into this box. Anyone who tries to use Bugzilla (including admins)
- will receive a page displaying this text. Users can neither log in
- nor log out while shutdownhtml is enabled.
+ RADIUS authentication is a module for Bugzilla's plugin
+ authentication architecture. This page contains all the parameters
+ necessary for configuring Bugzilla to use RADIUS authentication.
</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).
+ Most caveats that apply to LDAP authentication apply to RADIUS
+ authentication as well. See <xref linkend="bzldap"/> for details.
</para>
</note>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- movebugs
- </term>
- <listitem>
- <para>
- This option is an undocumented feature to allow moving bugs
- between separate Bugzilla installations. You will need to understand
- the source code in order to use this feature. Please consult
- <filename>movebugs.pl</filename> in your Bugzilla source tree for
- further documentation, such as it is.
- </para>
- </listitem>
- </varlistentry>
+ <para>Parameters required to use RADIUS Authentication:</para>
+
+ <variablelist>
+ <varlistentry id="param-user_verify_class_for_radius">
+ <term>user_verify_class</term>
+ <listitem>
+ <para>If you want to list <quote>RADIUS</quote> here,
+ make sure to have set up the other parameters listed below.
+ Unless you have other (working) authentication methods listed as
+ well, you may otherwise not be able to log back in to Bugzilla once
+ you log out.
+ If this happens to you, you will need to manually edit
+ <filename>data/params</filename> and set user_verify_class to
+ <quote>DB</quote>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="param-RADIUS_server">
+ <term>RADIUS_server</term>
+ <listitem>
+ <para>This parameter should be set to the name (and optionally the
+ port) of your RADIUS server.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="param-RADIUS_secret">
+ <term>RADIUS_secret</term>
+ <listitem>
+ <para>This parameter should be set to the RADIUS server's secret.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="param-RADIUS_email_suffix">
+ <term>RADIUS_email_suffix</term>
+ <listitem>
+ <para>Bugzilla needs an e-mail address for each user account.
+ Therefore, it needs to determine the e-mail address corresponding
+ to a RADIUS user.
+ Bugzilla offers only a simple way to do this: it can concatenate
+ a suffix to the RADIUS user name to convert it into an e-mail
+ address.
+ You can specify this suffix in the RADIUS_email_suffix parameter.
+ </para>
+ <para>If this simple solution does not work for you, you'll
+ probably need to modify
+ <filename>Bugzilla/Auth/Verify/RADIUS.pm</filename> to match your
+ requirements.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
- <varlistentry>
- <term>
- useqacontact
- </term>
- <listitem>
+ </section>
+
+ <section id="param-email">
+ <title>Email</title>
<para>
- This allows you to define an email address for each component,
- in addition to that of the default assignee, who will be sent
- carbon copies of incoming bugs.
+ This page contains all of the parameters for configuring how
+ Bugzilla deals with the email notifications it sends. See below
+ for a summary of important options.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- globalwatcher
- </term>
- <listitem>
- <para>
- This allows you to define specific users who will
- receive notification each time a new bug in entered, or when
- an existing bug changes, according to the normal groupset
- permissions. It may be useful for sending notifications to a
- mailing-list, for instance.
- </para>
- </listitem>
- </varlistentry>
+ <variablelist>
- <varlistentry>
- <term>
- usestatuswhiteboard
- </term>
- <listitem>
- <para>
- This defines whether you wish to have a free-form, overwritable field
- associated with each bug. The advantage of the Status Whiteboard is
- that it can be deleted or modified with ease, and provides an
- easily-searchable field for indexing some bugs that have some trait
- in common.
- </para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term>
+ mail_delivery_method
+ </term>
+ <listitem>
+ <para>
+ This is used to specify how email is sent, or if it is sent at
+ all. There are several options included for different MTAs,
+ along with two additional options that disable email sending.
+ "Test" does not send mail, but instead saves it in
+ <filename>data/mailer.testfile</filename> for later review.
+ "None" disables email sending entirely.
+ </para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>
- whinedays
- </term>
- <listitem>
+ <varlistentry>
+ <term>
+ sendmailnow
+ </term>
+ <listitem>
+ <para>
+ When Bugzilla is using Sendmail older than 8.12, turning this option
+ off will improve performance by not waiting for Sendmail to actually
+ send mail. If Sendmail 8.12 or later is being used, there is
+ nothing to gain by turning this off. If another MTA is being used,
+ such as Postfix, then this option *must* be turned on (even if you
+ are using the fake sendmail executable that Postfix provides).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ whinedays
+ </term>
+ <listitem>
+ <para>
+ Set this to the number of days you want to let bugs go
+ in the NEW or REOPENED state before notifying people they have
+ untouched new bugs. If you do not plan to use this feature, simply
+ do not set up the whining cron job described in the installation
+ instructions, or set this value to "0" (never whine).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ globalwatcher
+ </term>
+ <listitem>
+ <para>
+ This allows you to define specific users who will
+ receive notification each time a new bug in entered, or when
+ an existing bug changes, according to the normal groupset
+ permissions. It may be useful for sending notifications to a
+ mailing-list, for instance.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </section>
+
+ <section id="param-patchviewer">
+ <title>Patch Viewer</title>
<para>
- Set this to the number of days you want to let bugs go
- in the NEW or REOPENED state before notifying people they have
- untouched new bugs. If you do not plan to use this feature, simply
- do not set up the whining cron job described in the installation
- instructions, or set this value to "0" (never whine).
+ This page contains configuration parameters for the CVS server,
+ Bonsai server and LXR server that Bugzilla will use to enable the
+ features of the Patch Viewer. Bonsai is a tool that enables queries
+ to a CVS tree. LXR is a tool that can cross reference and index source
+ code.
</para>
- </listitem>
- </varlistentry>
+ </section>
- <varlistentry>
- <term>
- commenton*
- </term>
- <listitem>
+ <section id="param-querydefaults">
+ <title>Query Defaults</title>
<para>
- All these fields allow you to dictate what changes can pass
- without comment, and which must have a comment from the
- person who changed them. Often, administrators will allow
- users to add themselves to the CC list, accept bugs, or
- change the Status Whiteboard without adding a comment as to
- their reasons for the change, yet require that most other
- changes come with an explanation.
+ This page controls the default behavior of Bugzilla in regards to
+ several aspects of querying bugs. Options include what the default
+ query options are, what the "My Bugs" page returns, whether users
+ can freely add bugs to the quip list, and how many duplicate bugs are
+ needed to add a bug to the "most frequently reported" list.
</para>
+ </section>
+ <section id="param-shadowdatabase">
+ <title>Shadow Database</title>
<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.
+ This page controls whether a shadow database is used, and all the
+ parameters associated with the shadow database. Versions of Bugzilla
+ prior to 3.2 used the MyISAM table type, which supports
+ only table-level write locking. With MyISAM, any time someone is making a change to
+ a bug, the entire table is locked until the write operation is complete.
+ Locking for write also blocks reads until the write is complete.
+ </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.
</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!)
+ As of version 3.2, Bugzilla no longer uses the MyISAM table type.
+ Instead, InnoDB is used, which can do transaction-based locking.
+ Therefore, the limitations the Shadow Database feature was designed
+ to workaround no longer exist.
</para>
</note>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>
- supportwatchers
- </term>
- <listitem>
- <para>
- Turning on this option allows users to ask to receive copies
- of bug mail sent to another user. Watching a user with
- different group permissions is not a way to 'get around' the
- system; copied emails are still subject to the normal groupset
- permissions of a bug, and <quote>watchers</quote> will only be
- copied on emails from bugs they would normally be allowed to view.
- </para>
- </listitem>
- </varlistentry>
+ </section>
- <varlistentry>
- <term>
- noresolveonopenblockers
- </term>
- <listitem>
+ <section id="admin-usermatching">
+ <title>User Matching</title>
<para>
- This option will prevent users from resolving bugs as FIXED if
- they have unresolved dependencies. Only the FIXED resolution
- is affected. Users will be still able to resolve bugs to
- resolutions other than FIXED if they have unresolved dependent
- bugs.
+ The settings on this page control how users are selected and queried
+ when adding a user to a bug. For example, users need to be selected
+ when choosing who the bug is assigned to, adding to the CC list or
+ selecting a QA contact. With the "usemenuforusers" parameter, it is
+ possible to configure Bugzilla to
+ display a list of users in the fields instead of an empty text field.
+ This should only be used in Bugzilla installations with a small number
+ of users. If users are selected via a text box, this page also
+ contains parameters for how user names can be queried and matched
+ when entered.
</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- sendmailnow
- </term>
- <listitem>
- <para>
- When Bugzilla is using Sendmail older than 8.12, turning this option
- off will improve performance by not waiting for Sendmail to actually
- send mail. If Sendmail 8.12 or later is being used, there is
- nothing to gain by turning this off. If another MTA is being used,
- such as Postfix, then this option *must* be turned on (even if you
- are using the fake sendmail executable that Postfix provides).
- </para>
- </listitem>
- </varlistentry>
+ </section>
- </variablelist>
</section>
<section id="useradmin">
diff --git a/docs/xml/installation.xml b/docs/xml/installation.xml
index 1d4b8cbe4..526fa7c9e 100644
--- a/docs/xml/installation.xml
+++ b/docs/xml/installation.xml
@@ -1,5 +1,5 @@
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
-<!-- $Id: installation.xml,v 1.152 2008/01/24 22:35:16 lpsolit%gmail.com Exp $ -->
+<!-- $Id: installation.xml,v 1.153 2008/02/06 21:58:55 lpsolit%gmail.com Exp $ -->
<chapter id="installing-bugzilla">
<title>Installing Bugzilla</title>
@@ -652,7 +652,6 @@
</section>
</section>
-
<section id="configuration">
<title>Configuration</title>
@@ -1318,7 +1317,6 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
</section>
</section>
-
<section id="extraconfig">
<title>Optional Additional Configuration</title>
@@ -1373,54 +1371,6 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
</note>
</section>
- <section>
- <title>Dependency Charts</title>
-
- <para>As well as the text-based dependency trees, Bugzilla also
- supports a graphical view of dependency relationships, using a
- package called 'dot'.
- Exactly how this works is controlled by the 'webdotbase' parameter,
- which can have one of three values:
- </para>
-
- <para>
- <orderedlist>
- <listitem>
- <para>
- A complete file path to the command 'dot' (part of
- <ulink url="http://www.graphviz.org/">GraphViz</ulink>)
- will generate the graphs locally
- </para>
- </listitem>
- <listitem>
- <para>
- A URL prefix pointing to an installation of the webdot package will
- generate the graphs remotely
- </para>
- </listitem>
- <listitem>
- <para>
- A blank value will disable dependency graphing.
- </para>
- </listitem>
- </orderedlist>
- </para>
-
- <para>The easiest way to get this working is to install
- <ulink url="http://www.graphviz.org/">GraphViz</ulink>. If you
- do that, you need to
- <ulink url="http://httpd.apache.org/docs/mod/mod_imap.html">enable
- server-side image maps</ulink> in Apache.
- Alternatively, you could set up a webdot server, or use the AT&T
- public webdot server. This is the default for the webdotbase param,
- but it's often overloaded and slow. Note that AT&T's server
- won't work
- if Bugzilla is only accessible using HARTS.
- <emphasis>Editor's note: What the heck is HARTS? Google doesn't know...
- </emphasis>
- </para>
- </section>
-
<section id="installation-whining-cron">
<title>The Whining Cron</title>
@@ -1485,229 +1435,7 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
</para>
</note>
</section>
-
- <section id="patch-viewer">
- <title>Patch Viewer</title>
-
- <para>
- Patch Viewer is the engine behind Bugzilla's graphical display of
- code patches. You can integrate this with copies of the
- <filename>cvs</filename>, <filename>lxr</filename> and
- <filename>bonsai</filename> tools if you have them, by giving
- the locations of your installation of these tools in
- <filename>editparams.cgi</filename>.
- </para>
- <para>
- Patch Viewer also optionally will use the
- <filename>cvs</filename>, <filename>diff</filename> and
- <filename>interdiff</filename>
- command-line utilities if they exist on the system.
- Interdiff can be obtained from
- <ulink url="http://cyberelk.net/tim/patchutils/"/>.
- If these programs are not in the system path, you can configure
- their locations in <filename>localconfig</filename>.
- </para>
-
-
- </section>
-
- <section id="bzradius">
- <title>RADIUS Authentication</title>
-
- <para>RADIUS authentication is a module for Bugzilla's plugin
- authentication architecture.
- Most caveats that apply to LDAP authentication apply to RADIUS
- authentication as well.
- </para>
-
- <para>Parameters required to use RADIUS Authentication:</para>
-
- <variablelist>
- <varlistentry id="param-user_verify_class_for_radius">
- <term>user_verify_class</term>
- <listitem>
- <para>If you want to list <quote>RADIUS</quote> here,
- make sure to have set up the other parameters listed below.
- Unless you have other (working) authentication methods listed as
- well, you may otherwise not be able to log back in to Bugzilla once
- you log out.
- If this happens to you, you will need to manually edit
- <filename>data/params</filename> and set user_verify_class to
- <quote>DB</quote>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="param-RADIUS_server">
- <term>RADIUS_server</term>
- <listitem>
- <para>This parameter should be set to the name (and optionally the
- port) of your RADIUS server.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="param-RADIUS_secret">
- <term>RADIUS_secret</term>
- <listitem>
- <para>This parameter should be set to the RADIUS server's secret.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="param-RADIUS_email_suffix">
- <term>RADIUS_email_suffix</term>
- <listitem>
- <para>Bugzilla needs an e-mail address for each user account.
- Therefore, it needs to determine the e-mail address corresponding
- to a RADIUS user.
- Bugzilla offers only a simple way to do this: it can concatenate
- a suffix to the RADIUS user name to convert it into an e-mail
- address.
- You can specify this suffix in the RADIUS_email_suffix parameter.
- </para>
- <para>If this simple solution does not work for you, you'll
- probably need to modify
- <filename>Bugzilla/Auth/Verify/RADIUS.pm</filename> to match your
- requirements.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </section>
-
- <section id="bzldap">
- <title>LDAP Authentication</title>
-
- <para>LDAP authentication is a module for Bugzilla's plugin
- authentication architecture.
- </para>
-
- <para>
- The existing authentication
- scheme for Bugzilla uses email addresses as the primary user ID, and a
- password to authenticate that user. All places within Bugzilla where
- you need to deal with user ID (e.g assigning a bug) use the email
- address. The LDAP authentication builds on top of this scheme, rather
- than replacing it. The initial log in is done with a username and
- password for the LDAP directory. Bugzilla tries to bind to LDAP using
- those credentials, and if successful, try to map this account to a
- Bugzilla account. If a LDAP mail attribute is defined, the value of this
- attribute is used, otherwise emailsuffix parameter is appended to LDAP
- username to form a full email address. If an account for this address
- already exists in your Bugzilla system, it will log in to that account.
- If no account for that email address exists, one is created at the time
- of login. (In this case, Bugzilla will attempt to use the "displayName"
- or "cn" attribute to determine the user's full name.) After
- authentication, all other user-related tasks are still handled by email
- address, not LDAP username. You still assign bugs by email address, query
- on users by email address, etc.
- </para>
-
- <caution>
- <para>Because the Bugzilla account is not created until the first time
- a user logs in, a user who has not yet logged is unknown to Bugzilla.
- This means they cannot be used as an assignee or QA contact (default or
- otherwise), added to any cc list, or any other such operation. One
- possible workaround is the <filename>bugzilla_ldapsync.rb</filename>
- script in the
- <glossterm linkend="gloss-contrib"><filename class="directory">contrib</filename></glossterm> directory. Another possible solution is fixing
- <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=201069">bug
- 201069</ulink>.
- </para>
- </caution>
-
- <para>Parameters required to use LDAP Authentication:</para>
-
- <variablelist>
- <varlistentry id="param-user_verify_class_for_ldap">
- <term>user_verify_class</term>
- <listitem>
- <para>If you want to list <quote>LDAP</quote> here,
- make sure to have set up the other parameters listed below.
- Unless you have other (working) authentication methods listed as
- well, you may otherwise not be able to log back in to Bugzilla once
- you log out.
- If this happens to you, you will need to manually edit
- <filename>data/params</filename> and set user_verify_class to
- <quote>DB</quote>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="param-LDAPserver">
- <term>LDAPserver</term>
- <listitem>
- <para>This parameter should be set to the name (and optionally the
- port) of your LDAP server. If no port is specified, it assumes
- the default LDAP port of 389.
- </para>
- <para>Ex. <quote>ldap.company.com</quote>
- or <quote>ldap.company.com:3268</quote>
- </para>
- <para>You can also specify a LDAP URI, so as to use other
- protocols, such as LDAPS or LDAPI. If port was not specified in
- the URI, the default is either 389 or 636 for 'LDAP' and 'LDAPS'
- schemes respectively.
- </para>
- <para>Ex. <quote>ldap://ldap.company.com</quote>,
- <quote>ldaps://ldap.company.com</quote> or
- <quote>ldapi://%2fvar%2flib%2fldap_sock</quote>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="param-LDAPbinddn">
- <term>LDAPbinddn [Optional]</term>
- <listitem>
- <para>Some LDAP servers will not allow an anonymous bind to search
- the directory. If this is the case with your configuration you
- should set the LDAPbinddn parameter to the user account Bugzilla
- should use instead of the anonymous bind.
- </para>
- <para>Ex. <quote>cn=default,cn=user:password</quote></para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="param-LDAPBaseDN">
- <term>LDAPBaseDN</term>
- <listitem>
- <para>The LDAPBaseDN parameter should be set to the location in
- your LDAP tree that you would like to search for email addresses.
- Your uids should be unique under the DN specified here.
- </para>
- <para>Ex. <quote>ou=People,o=Company</quote></para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="param-LDAPuidattribute">
- <term>LDAPuidattribute</term>
- <listitem>
- <para>The LDAPuidattribute parameter should be set to the attribute
- which contains the unique UID of your users. The value retrieved
- from this attribute will be used when attempting to bind as the
- user to confirm their password.
- </para>
- <para>Ex. <quote>uid</quote></para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="param-LDAPmailattribute">
- <term>LDAPmailattribute</term>
- <listitem>
- <para>The LDAPmailattribute parameter should be the name of the
- attribute which contains the email address your users will enter
- into the Bugzilla login boxes.
- </para>
- <para>Ex. <quote>mail</quote></para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </section>
-
<section id="apache-addtype">
<title>Serving Alternate Formats with the right MIME type</title>
--
2.24.1