diff options
Diffstat (limited to 'docs/xml')
| -rw-r--r-- | docs/xml/administration.xml | 1089 | ||||
| -rw-r--r-- | 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> |