summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--docs/en/xml/administration.xml1089
-rw-r--r--docs/en/xml/installation.xml506
2 files changed, 903 insertions, 692 deletions
diff --git a/docs/en/xml/administration.xml b/docs/en/xml/administration.xml
index b7897215d..583042520 100644
--- a/docs/en/xml/administration.xml
+++ b/docs/en/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>&lt;div&gt;</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>&lt;div&gt;</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/en/xml/installation.xml b/docs/en/xml/installation.xml
index 03fed5f3b..6f8dc0536 100644
--- a/docs/en/xml/installation.xml
+++ b/docs/en/xml/installation.xml
@@ -1,5 +1,5 @@
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
-<!-- $Id: installation.xml,v 1.145 2008/04/04 06:48:15 mozilla%colinogilvie.co.uk Exp $ -->
+<!-- $Id: installation.xml,v 1.153 2008/04/04 06:48:23 lpsolit%gmail.com Exp $ -->
<chapter id="installing-bugzilla">
<title>Installing Bugzilla</title>
@@ -473,12 +473,6 @@
</para>
</listitem>
- <listitem>
- <para>
- Apache::DBI
- (&min-apache-dbi-ver;) for mod_perl2
- </para>
- </listitem>
</orderedlist>
</para>
@@ -655,13 +649,9 @@
<para>Bugzilla also requires a more up-to-date version of the CGI
perl module to be installed, version &min-mp-cgi-ver; as opposed to &min-cgi-ver;
</para>
-
- <para>Finally, Bugzilla also requires <literal>Apache::DBI</literal>
- (&min-apache-dbi-ver;) to be installed as well.</para>
</section>
</section>
-
<section id="configuration">
<title>Configuration</title>
@@ -707,9 +697,18 @@
hosting account), you will need to leave
<emphasis>webservergroup</emphasis> empty, ignoring the warnings
that <filename>checksetup.pl</filename> will subsequently display
- every time it in run.
+ every time it is run.
</para>
+ <caution>
+ <para>
+ If you are using suexec, you should use your own primary group
+ for <emphasis>webservergroup</emphasis> rather than leaving it
+ empty, and see the additional directions in the suexec section
+ <xref linkend="suexec" />.
+ </para>
+ </caution>
+
<para>
The other options in the <filename>localconfig</filename> file
are documented by their accompanying comments. If you have a slightly
@@ -1114,7 +1113,7 @@
</warning>
<programlisting>
- PerlSwitches -I/var/www/html/bugzilla -w -T
+ PerlSwitches -I/var/www/html/bugzilla -I/var/www/html/bugzilla/lib -w -T
PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl
</programlisting>
</step>
@@ -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&amp;T
- public webdot server. This is the default for the webdotbase param,
- but it's often overloaded and slow. Note that AT&amp;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>
@@ -1812,6 +1540,15 @@ AddType application/rdf+xml .rdf</screen>
The following instructions assume that you are using version
5.8.1 of ActiveState.
</para>
+
+ <note>
+ <para>
+ These instructions are for 32-bit versions of Windows. If you are
+ using a 64-bit version of Windows, you will need to install 32-bit
+ Perl in order to install the 32-bit modules as described below.
+ </para>
+ </note>
+
</section>
<section id="win32-perl-modules">
@@ -1835,9 +1572,16 @@ C:\perl&gt; <command>ppm install &lt;module name&gt;</command>
</para>
<programlisting>
-<command>ppm repository add landfill http://www.landfill.bugzilla.org/ppm/</command>
+<command>ppm repo add landfill http://www.landfill.bugzilla.org/ppm/</command>
</programlisting>
-
+ <note>
+ <para>
+ In versions prior to 5.8.8 build 819 of PPM the command is
+ <programlisting>
+<command>ppm repository add landfill http://www.landfill.bugzilla.org/ppm/</command>
+ </programlisting>
+ </para>
+ </note>
<note>
<para>
The PPM repository stores modules in 'packages' that may have
@@ -2136,10 +1880,12 @@ pid-file=/home/foo/mymysql/the.pid
<section>
<title>Perl</title>
- <para>On the extremely rare chance that you don't have Perl on
+ <para>
+ On the extremely rare chance that you don't have Perl on
the machine, you will have to build the sources
yourself. The following commands should get your system
- installed with your own personal version of Perl:</para>
+ installed with your own personal version of Perl:
+ </para>
<screen>
<prompt>bash$</prompt>
@@ -2154,139 +1900,23 @@ pid-file=/home/foo/mymysql/the.pid
<command>make &amp;&amp; make test &amp;&amp; make install</command>
</screen>
- <para>Once you have Perl installed into a directory (probably
- in <filename class="directory">~/perl/bin</filename>), you'll have to
- change the locations on the scripts, which is detailed later on
- this page.</para>
+ <para>
+ Once you have Perl installed into a directory (probably
+ in <filename class="directory">~/perl/bin</filename>), you will need to
+ install the Perl Modules, described below.
+ </para>
</section>
<section id="install-perlmodules-nonroot">
<title>Perl Modules</title>
- <para>Installing the Perl modules as a non-root user is probably the
- hardest part of the process. There are two different methods: a
- completely independant Perl with its own modules, or personal
- modules using the current (root installed) version of Perl. The
- independant method takes up quite a bit of disk space, but is
- less complex, while the mixed method only uses as much space as the
- modules themselves, but takes more work to setup.</para>
-
- <section>
- <title>The Independant Method</title>
-
- <para>The independant method requires that you install your own
- personal version of Perl, as detailed in the previous section. Once
- installed, you can start the CPAN shell with the following
- command:</para>
-
- <para>
- <screen>
- <prompt>bash$</prompt>
- <command>/home/foo/perl/bin/perl -MCPAN -e 'shell'</command>
- </screen>
- </para>
-
- <para>And then:</para>
-
- <para>
- <screen>
- <prompt>cpan&gt;</prompt>
- <command>install Bundle::Bugzilla</command>
- </screen>
- </para>
-
- <para>With this method, module installation will usually go a lot
- smoother, but if you have any hang-ups, you can consult the next
- section.</para>
- </section>
-
- <section>
- <title>The Mixed Method</title>
-
- <para>First, you'll need to configure CPAN to
- install modules in your home directory. The CPAN FAQ says the
- following on this issue:</para>
-
- <para>
- <programlisting>
-5) I am not root, how can I install a module in a personal directory?
-
- You will most probably like something like this:
-
- o conf makepl_arg "LIB=~/myperl/lib \
- INSTALLMAN1DIR=~/myperl/man/man1 \
- INSTALLMAN3DIR=~/myperl/man/man3"
- install Sybase::Sybperl
-
- You can make this setting permanent like all "o conf" settings with "o conf commit".
-
- You will have to add ~/myperl/man to the MANPATH environment variable and also tell your Perl programs to
- look into ~/myperl/lib, e.g. by including
-
- use lib "$ENV{HOME}/myperl/lib";
-
- or setting the PERL5LIB environment variable.
-
- Another thing you should bear in mind is that the UNINST parameter should never be set if you are not root.</programlisting>
- </para>
-
- <para>So, you will need to create a Perl directory in your home
- directory, as well as the <filename class="directory">lib</filename>,
- <filename class="directory">man</filename>,
- <filename class="directory">man/man1</filename>, and
- <filename class="directory">man/man3</filename> directories in that
- Perl directory. Set the MANPATH variable and PERL5LIB variable, so
- that the installation of the modules goes smoother. (Setting
- UNINST=0 in your "make install" options, on the CPAN first-time
- configuration, is also a good idea.)</para>
-
- <para>After that, go into the CPAN shell:</para>
-
- <para>
- <screen>
- <prompt>bash$</prompt>
- <command>perl -MCPAN -e 'shell'</command>
- </screen>
- </para>
-
- <para>From there, you will need to type in the above "o conf" command
- and commit the changes. Then you can run through the installation:</para>
-
- <para>
- <screen>
- <prompt>cpan&gt;</prompt>
- <command>install Bundle::Bugzilla</command>
- </screen>
- </para>
-
- <para>Most of the module installation process should go smoothly. However,
- you may have some problems with Template. When you first start, you will
- want to try to install Template with the XS Stash options on. If this
- doesn't work, it may spit out C compiler error messages and croak back
- to the CPAN shell prompt. So, redo the install, and turn it off. (In fact,
- say no to all of the Template questions.) It may also start failing on a
- few of the tests. If the total tests passed is a reasonable figure (90+%),
- force the install with the following command:</para>
-
- <para>
- <screen>
- <prompt>cpan&gt;</prompt>
- <command>force install Template</command>
- </screen>
- </para>
-
- <para>You may also want to install the other optional modules:</para>
-
- <screen>
- <prompt>cpan&gt;</prompt>
- <command>install GD</command>
- <prompt>cpan&gt;</prompt>
- <command>install Chart::Base</command>
- <prompt>cpan&gt;</prompt>
- <command>install MIME::Parser</command>
- </screen>
-
- </section>
+ <para>
+ Installing the Perl modules as a non-root user is accomplished by
+ running the <filename>install-module.pl</filename>
+ script. For more details on this script, see
+ <ulink url="api/install-module.html"><filename>install-module.pl</filename>
+ documentation</ulink>
+ </para>
</section>
<section>
@@ -2331,30 +1961,16 @@ pid-file=/home/foo/mymysql/the.pid
<section>
<title>Bugzilla</title>
- <para>If you had to install Perl modules as a non-root user
- (<xref linkend="install-perlmodules-nonroot" />) or to non-standard
- directories, you will need to change the scripts, setting the correct
- location of the Perl modules:</para>
-
<para>
- <programlisting>perl -pi -e
- 's@use strict\;@use strict\; use lib \"/home/foo/perl/lib\"\;@'
- *cgi *pl Bug.pm processmail syncshadowdb</programlisting>
-
- Change <filename class="directory">/home/foo/perl/lib</filename> to
- your personal Perl library directory. You can probably skip this
- step if you are using the independant method of Perl module
- installation.
- </para>
-
- <para>When you run <command>./checksetup.pl</command> to create
+ When you run <command>./checksetup.pl</command> to create
the <filename>localconfig</filename> file, it will list the Perl
modules it finds. If one is missing, go back and double-check the
- module installation from the CPAN shell, then delete the
- <filename>localconfig</filename> file and try again.</para>
+ module installation from <xref linkend="install-perlmodules-nonroot"/>,
+ then delete the <filename>localconfig</filename> file and try again.
+ </para>
<warning>
- <para>The one option in <filename>localconfig</filename> you
+ <para>One option in <filename>localconfig</filename> you
might have problems with is the web server group. If you can't
successfully browse to the <filename>index.cgi</filename> (like
a Forbidden error), you may have to relax your permissions,
@@ -2363,6 +1979,26 @@ pid-file=/home/foo/mymysql/the.pid
limited access to shell accounts may lessen the security risk,
but use at your own risk.</para>
</warning>
+
+ <section id="suexec">
+ <title>suexec or shared hosting</title>
+
+ <para>If you are running on a system that uses suexec (most shared
+ hosting environments do this), you will need to set the
+ <emphasis>webservergroup</emphasis> value in <filename>localconfig</filename>
+ to match <emphasis>your</emphasis> primary group, rather than the one
+ the web server runs under. You will need to run the following
+ shell commands after running <command>./checksetup.pl</command>,
+ every time you run it (or modify <filename>checksetup.pl</filename>
+ to do them for you via the system() command).
+ <programlisting> for i in docs graphs images js skins; do find $i -type d -exec chmod o+rx {} \; ; done
+ for i in jpg gif css js png html rdf xul; do find . -name \*.$i -exec chmod o+r {} \; ; done
+ find . -name .htaccess -exec chmod o+r {} \;
+ chmod o+x . data data/webdot</programlisting>
+ Pay particular attention to the number of semicolons and dots.
+ They are all important. A future version of Bugzilla will
+ hopefully be able to do this for you out of the box.</para>
+ </section>
</section>
</section>