Skip to content

bugzilla
bugzilla
Commit 56de8331 authored by lpsolit%gmail.com's avatar lpsolit%gmail.com
Browse files
Options

Bug 390603: Configuration paramaters documentation needs updating - Patch by Sam…

Bug 390603: Configuration paramaters documentation needs updating - Patch by Sam Folk-Williams <sam.folkwilliams@gmail.com> r/a=LpSolit
parent e3e887d3
Hide whitespace changes
Inline Side-by-side
Showing with 903 additions and 692 deletions
docs/en/xml/administration.xml
View file @ 56de8331
...@@ -7,322 +7,897 @@ ...@@ -7,322 +7,897 @@
<para> <para>
Bugzilla is configured by changing various parameters, accessed Bugzilla is configured by changing various parameters, accessed
from the "Edit parameters" link in the page footer. Here are from the "Parameters" link in the Administration page (the
some of the key parameters on that page. You should run down this Administration page can be found by clicking the "Administration"
list and set them appropriately after installing Bugzilla. 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> </para>
<indexterm> <section id="param-requiredsettings">
<primary>checklist</primary> <title>Required Settings</title>
</indexterm>
<variablelist> <para>
<varlistentry> The core required parameters for any Bugzilla installation are set
<term> here. These parameters must be set before a new Bugzilla installation
maintainer can be used. Administrators should review this list before
</term> deploying a new Bugzilla installation.
<listitem> </para>
<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>
<varlistentry> <indexterm>
<term> <primary>checklist</primary>
urlbase </indexterm>
</term>
<listitem> <variablelist>
<para>
This parameter defines the fully qualified domain name and web <varlistentry>
server path to your Bugzilla installation. <term>
</para> 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> <para>
For example, if your Bugzilla query page is This page contains the settings that control how this Bugzilla
<filename>http://www.foo.com/bugzilla/query.cgi</filename>, installation will do its authentication. Choose what authentication
set your <quote>urlbase</quote> mechanism to use (the Bugzilla database, or an external source such
to <filename>http://www.foo.com/bugzilla/</filename>. 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> </para>
</listitem>
</varlistentry>
<varlistentry> <variablelist>
<term>
makeproductgroups <varlistentry>
</term> <term>
<listitem> 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> <para>
This dictates whether or not to automatically create groups This page allows for setting restrictions and other parameters
when new products are created. regarding attachments to bugs. For example, control size limitations
and whether to allow uploading of remote files via a URI.
</para> </para>
</listitem> </section>
</varlistentry>
<varlistentry> <section id="param-bug-change-policies">
<term> <title>Bug Change Policies</title>
useentrygroupdefault
</term>
<listitem>
<para> <para>
Bugzilla products can have a group associated with them, so that Set policy on default behavior for bug change events. For example,
certain users can only see bugs in certain products. When this choose which status to set a bug to when it is marked as a duplicate,
parameter is set to <quote>on</quote>, this and choose whether to allow bug reporters to set the priority or
causes the initial group controls on newly created products target milestone. Also allows for configuration of what changes
to place all newly-created bugs in the group should require the user to make a comment, described below.
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> </para>
</listitem>
</varlistentry>
<varlistentry> <variablelist>
<term>
mail_delivery_method <varlistentry>
</term> <term>
<listitem> 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> <para>
This is used to specify how email is sent, or if it is sent at The parameters in this section determine the default settings of
all. There are several options included for different MTAs, several Bugzilla fields for new bugs, and also control whether
along with two additional options that disable email sending. certain fields are used. For example, choose whether to use the
"testfile" does not send mail, but instead saves it in "target milestone" field or the "status whiteboard" field.
<filename>data/mailer.testfile</filename> for later review.
"none" disables email sending entirely.
</para> </para>
</listitem>
</varlistentry>
<varlistentry> <variablelist>
<term>
shadowdb <varlistentry>
</term> <term>
<listitem> 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> <para>
You run into an interesting problem when Bugzilla reaches a This page controls whether this Bugzilla installation allows certain
high level of continuous activity. MySQL supports only table-level users to move bugs to an external database. If bug moving is enabled,
write locking. What this means is that if someone needs to make a there are a number of parameters that control bug moving behaviors.
change to a bug, they will lock the entire table until the operation For example, choose which users are allowed to move bugs, the location
is complete. Locking for write also blocks reads until the write is of the external database, and the default product and component that
complete. Note that more recent versions of mysql support row level bugs moved <emphasis>from</emphasis> other bug databases to this
locking using different table types. These types are slower than the Bugzilla installation are assigned to.
standard type, and Bugzilla does not yet take advantage of features
such as transactions which would justify this speed decrease. The
Bugzilla team are, however, happy to hear about any experiences with
row level locking and Bugzilla.
</para> </para>
</section>
<section id="param-dependency-graphs">
<title>Dependency Graphs</title>
<para> <para>
The <quote>shadowdb</quote> parameter was designed to get around This page has one parameter that sets the location of a Web Dot
this limitation. While only a single user is allowed to write to server, or of the Web Dot binary on the local system, that is used
a table at a time, reads can continue unimpeded on a read-only to generate dependency graphs. Web Dot is a CGI program that creates
shadow copy of the database. Although your database size will images from <filename>.dot</filename> graphic description files. If
double, a shadow database can cause an enormous performance no Web Dot server or binary is specified, then dependency graphs will
improvement when implemented on extremely high-traffic Bugzilla be disabled.
databases.
</para> </para>
</section>
<para>
As a guide, on reasonably old hardware, mozilla.org began needing <section id="param-group-security">
<quote>shadowdb</quote> when they reached around 40,000 Bugzilla <title>Group Security</title>
users with several hundred Bugzilla bug changes and comments per day. <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>
<para> <para>
The value of the parameter defines the name of the shadow bug The existing authentication
database. You will need to set the host and port settings from scheme for Bugzilla uses email addresses as the primary user ID, and a
the params page, and set up replication in your database server password to authenticate that user. All places within Bugzilla that
so that updates reach this readonly mirror. Consult your database require a user ID (e.g assigning a bug) use the email
documentation for more detail. 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> </para>
</listitem>
</varlistentry>
<varlistentry> <caution>
<term> <para>Because the Bugzilla account is not created until the first time
shutdownhtml a user logs in, a user who has not yet logged is unknown to Bugzilla.
</term> This means they cannot be used as an assignee or QA contact (default or
<listitem> 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> <para>
If you need to shut down Bugzilla to perform administration, enter RADIUS authentication is a module for Bugzilla's plugin
some descriptive text (with embedded HTML codes, if you'd like) authentication architecture. This page contains all the parameters
into this box. Anyone who tries to use Bugzilla (including admins) necessary for configuring Bugzilla to use RADIUS authentication.
will receive a page displaying this text. Users can neither log in
nor log out while shutdownhtml is enabled.
</para> </para>
<note> <note>
<para> <para>
Although regular log-in capability is disabled while 'shutdownhtml' Most caveats that apply to LDAP authentication apply to RADIUS
is enabled, safeguards are in place to protect the unfortunate authentication as well. See <xref linkend="bzldap"/> for details.
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> </para>
</note> </note>
</listitem>
</varlistentry>
<varlistentry> <para>Parameters required to use RADIUS Authentication:</para>
<term>
movebugs <variablelist>
</term> <varlistentry id="param-user_verify_class_for_radius">
<listitem> <term>user_verify_class</term>
<para> <listitem>
This option is an undocumented feature to allow moving bugs <para>If you want to list <quote>RADIUS</quote> here,
between separate Bugzilla installations. You will need to understand make sure to have set up the other parameters listed below.
the source code in order to use this feature. Please consult Unless you have other (working) authentication methods listed as
<filename>movebugs.pl</filename> in your Bugzilla source tree for well, you may otherwise not be able to log back in to Bugzilla once
further documentation, such as it is. you log out.
</para> If this happens to you, you will need to manually edit
</listitem> <filename>data/params</filename> and set user_verify_class to
</varlistentry> <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> </section>
<term>
useqacontact <section id="param-email">
</term> <title>Email</title>
<listitem>
<para> <para>
This allows you to define an email address for each component, This page contains all of the parameters for configuring how
in addition to that of the default assignee, who will be sent Bugzilla deals with the email notifications it sends. See below
carbon copies of incoming bugs. for a summary of important options.
</para> </para>
</listitem>
</varlistentry>
<varlistentry> <variablelist>
<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>
<varlistentry> <varlistentry>
<term> <term>
usestatuswhiteboard mail_delivery_method
</term> </term>
<listitem> <listitem>
<para> <para>
This defines whether you wish to have a free-form, overwritable field This is used to specify how email is sent, or if it is sent at
associated with each bug. The advantage of the Status Whiteboard is all. There are several options included for different MTAs,
that it can be deleted or modified with ease, and provides an along with two additional options that disable email sending.
easily-searchable field for indexing some bugs that have some trait "Test" does not send mail, but instead saves it in
in common. <filename>data/mailer.testfile</filename> for later review.
</para> "None" disables email sending entirely.
</listitem> </para>
</varlistentry> </listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term> <term>
whinedays sendmailnow
</term> </term>
<listitem> <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> <para>
Set this to the number of days you want to let bugs go This page contains configuration parameters for the CVS server,
in the NEW or REOPENED state before notifying people they have Bonsai server and LXR server that Bugzilla will use to enable the
untouched new bugs. If you do not plan to use this feature, simply features of the Patch Viewer. Bonsai is a tool that enables queries
do not set up the whining cron job described in the installation to a CVS tree. LXR is a tool that can cross reference and index source
instructions, or set this value to "0" (never whine). code.
</para> </para>
</listitem> </section>
</varlistentry>
<varlistentry> <section id="param-querydefaults">
<term> <title>Query Defaults</title>
commenton*
</term>
<listitem>
<para> <para>
All these fields allow you to dictate what changes can pass This page controls the default behavior of Bugzilla in regards to
without comment, and which must have a comment from the several aspects of querying bugs. Options include what the default
person who changed them. Often, administrators will allow query options are, what the "My Bugs" page returns, whether users
users to add themselves to the CC list, accept bugs, or can freely add bugs to the quip list, and how many duplicate bugs are
change the Status Whiteboard without adding a comment as to needed to add a bug to the "most frequently reported" list.
their reasons for the change, yet require that most other
changes come with an explanation.
</para> </para>
</section>
<section id="param-shadowdatabase">
<title>Shadow Database</title>
<para> <para>
Set the "commenton" options according to your site policy. It This page controls whether a shadow database is used, and all the
is a wise idea to require comments when users resolve, reassign, or parameters associated with the shadow database. Versions of Bugzilla
reopen bugs at the very least. 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> </para>
<note> <note>
<para> <para>
It is generally far better to require a developer comment As of version 3.2, Bugzilla no longer uses the MyISAM table type.
when resolving bugs than not. Few things are more annoying to bug Instead, InnoDB is used, which can do transaction-based locking.
database users than having a developer mark a bug "fixed" without Therefore, the limitations the Shadow Database feature was designed
any comment as to what the fix was (or even that it was truly to workaround no longer exist.
fixed!)
</para> </para>
</note> </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> <section id="admin-usermatching">
<term> <title>User Matching</title>
noresolveonopenblockers
</term>
<listitem>
<para> <para>
This option will prevent users from resolving bugs as FIXED if The settings on this page control how users are selected and queried
they have unresolved dependencies. Only the FIXED resolution when adding a user to a bug. For example, users need to be selected
is affected. Users will be still able to resolve bugs to when choosing who the bug is assigned to, adding to the CC list or
resolutions other than FIXED if they have unresolved dependent selecting a QA contact. With the "usemenuforusers" parameter, it is
bugs. 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> </para>
</listitem>
</varlistentry>
<varlistentry> </section>
<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>
</variablelist>
</section> </section>
<section id="useradmin"> <section id="useradmin">
......
docs/en/xml/installation.xml
View file @ 56de8331
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> --> <!-- <!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"> <chapter id="installing-bugzilla">
<title>Installing Bugzilla</title> <title>Installing Bugzilla</title>
...@@ -473,12 +473,6 @@ ...@@ -473,12 +473,6 @@
</para> </para>
</listitem> </listitem>
<listitem>
<para>
Apache::DBI
(&min-apache-dbi-ver;) for mod_perl2
</para>
</listitem>
</orderedlist> </orderedlist>
</para> </para>
...@@ -655,13 +649,9 @@ ...@@ -655,13 +649,9 @@
<para>Bugzilla also requires a more up-to-date version of the CGI <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; perl module to be installed, version &min-mp-cgi-ver; as opposed to &min-cgi-ver;
</para> </para>
<para>Finally, Bugzilla also requires <literal>Apache::DBI</literal>
(&min-apache-dbi-ver;) to be installed as well.</para>
</section> </section>
</section> </section>
<section id="configuration"> <section id="configuration">
<title>Configuration</title> <title>Configuration</title>
...@@ -707,9 +697,18 @@ ...@@ -707,9 +697,18 @@
hosting account), you will need to leave hosting account), you will need to leave
<emphasis>webservergroup</emphasis> empty, ignoring the warnings <emphasis>webservergroup</emphasis> empty, ignoring the warnings
that <filename>checksetup.pl</filename> will subsequently display that <filename>checksetup.pl</filename> will subsequently display
every time it in run. every time it is run.
</para> </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> <para>
The other options in the <filename>localconfig</filename> file The other options in the <filename>localconfig</filename> file
are documented by their accompanying comments. If you have a slightly are documented by their accompanying comments. If you have a slightly
...@@ -1114,7 +1113,7 @@ ...@@ -1114,7 +1113,7 @@
</warning> </warning>
<programlisting> <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 PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl
</programlisting> </programlisting>
</step> </step>
...@@ -1318,7 +1317,6 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s ...@@ -1318,7 +1317,6 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
</section> </section>
</section> </section>
<section id="extraconfig"> <section id="extraconfig">
<title>Optional Additional Configuration</title> <title>Optional Additional Configuration</title>
...@@ -1373,54 +1371,6 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s ...@@ -1373,54 +1371,6 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
</note> </note>
</section> </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"> <section id="installation-whining-cron">
<title>The Whining Cron</title> <title>The Whining Cron</title>
...@@ -1485,229 +1435,7 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s ...@@ -1485,229 +1435,7 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
</para> </para>
</note> </note>
</section> </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"> <section id="apache-addtype">
<title>Serving Alternate Formats with the right MIME type</title> <title>Serving Alternate Formats with the right MIME type</title>
...@@ -1812,6 +1540,15 @@ AddType application/rdf+xml .rdf</screen> ...@@ -1812,6 +1540,15 @@ AddType application/rdf+xml .rdf</screen>
The following instructions assume that you are using version The following instructions assume that you are using version
5.8.1 of ActiveState. 5.8.1 of ActiveState.
</para> </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>
<section id="win32-perl-modules"> <section id="win32-perl-modules">
...@@ -1835,9 +1572,16 @@ C:\perl&gt; <command>ppm install &lt;module name&gt;</command> ...@@ -1835,9 +1572,16 @@ C:\perl&gt; <command>ppm install &lt;module name&gt;</command>
</para> </para>
<programlisting> <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> </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> <note>
<para> <para>
The PPM repository stores modules in 'packages' that may have The PPM repository stores modules in 'packages' that may have
...@@ -2136,10 +1880,12 @@ pid-file=/home/foo/mymysql/the.pid ...@@ -2136,10 +1880,12 @@ pid-file=/home/foo/mymysql/the.pid
<section> <section>
<title>Perl</title> <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 the machine, you will have to build the sources
yourself. The following commands should get your system 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> <screen>
<prompt>bash$</prompt> <prompt>bash$</prompt>
...@@ -2154,139 +1900,23 @@ pid-file=/home/foo/mymysql/the.pid ...@@ -2154,139 +1900,23 @@ pid-file=/home/foo/mymysql/the.pid
<command>make &amp;&amp; make test &amp;&amp; make install</command> <command>make &amp;&amp; make test &amp;&amp; make install</command>
</screen> </screen>
<para>Once you have Perl installed into a directory (probably <para>
in <filename class="directory">~/perl/bin</filename>), you'll have to Once you have Perl installed into a directory (probably
change the locations on the scripts, which is detailed later on in <filename class="directory">~/perl/bin</filename>), you will need to
this page.</para> install the Perl Modules, described below.
</para>
</section> </section>
<section id="install-perlmodules-nonroot"> <section id="install-perlmodules-nonroot">
<title>Perl Modules</title> <title>Perl Modules</title>
<para>Installing the Perl modules as a non-root user is probably the <para>
hardest part of the process. There are two different methods: a Installing the Perl modules as a non-root user is accomplished by
completely independant Perl with its own modules, or personal running the <filename>install-module.pl</filename>
modules using the current (root installed) version of Perl. The script. For more details on this script, see
independant method takes up quite a bit of disk space, but is <ulink url="api/install-module.html"><filename>install-module.pl</filename>
less complex, while the mixed method only uses as much space as the documentation</ulink>
modules themselves, but takes more work to setup.</para> </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>
</section> </section>
<section> <section>
...@@ -2331,30 +1961,16 @@ pid-file=/home/foo/mymysql/the.pid ...@@ -2331,30 +1961,16 @@ pid-file=/home/foo/mymysql/the.pid
<section> <section>
<title>Bugzilla</title> <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> <para>
<programlisting>perl -pi -e When you run <command>./checksetup.pl</command> to create
'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
the <filename>localconfig</filename> file, it will list the Perl the <filename>localconfig</filename> file, it will list the Perl
modules it finds. If one is missing, go back and double-check the modules it finds. If one is missing, go back and double-check the
module installation from the CPAN shell, then delete the module installation from <xref linkend="install-perlmodules-nonroot"/>,
<filename>localconfig</filename> file and try again.</para> then delete the <filename>localconfig</filename> file and try again.
</para>
<warning> <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 might have problems with is the web server group. If you can't
successfully browse to the <filename>index.cgi</filename> (like successfully browse to the <filename>index.cgi</filename> (like
a Forbidden error), you may have to relax your permissions, a Forbidden error), you may have to relax your permissions,
...@@ -2363,6 +1979,26 @@ pid-file=/home/foo/mymysql/the.pid ...@@ -2363,6 +1979,26 @@ pid-file=/home/foo/mymysql/the.pid
limited access to shell accounts may lessen the security risk, limited access to shell accounts may lessen the security risk,
but use at your own risk.</para> but use at your own risk.</para>
</warning> </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>
</section> </section>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment