<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
-<!-- $Id: installation.xml,v 1.153 2008/04/04 06:48:23 lpsolit%gmail.com Exp $ -->
+<!-- $Id: installation.xml,v 1.146 2008/04/04 06:48:16 justdave%bugzilla.org Exp $ -->
<chapter id="installing-bugzilla">
<title>Installing Bugzilla</title>
</para>
</listitem>
+ <listitem>
+ <para>
+ Apache::DBI
+ (&min-apache-dbi-ver;) for mod_perl2
+ </para>
+ </listitem>
</orderedlist>
</para>
<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>
</warning>
<programlisting>
- PerlSwitches -I/var/www/html/bugzilla -I/var/www/html/bugzilla/lib -w -T
+ PerlSwitches -I/var/www/html/bugzilla -w -T
PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl
</programlisting>
</step>
</section>
</section>
+
<section id="extraconfig">
<title>Optional Additional Configuration</title>
</note>
</section>
+ <section>
+ <title>Dependency Charts</title>
+
+ <para>As well as the text-based dependency trees, Bugzilla also
+ supports a graphical view of dependency relationships, using a
+ package called 'dot'.
+ Exactly how this works is controlled by the 'webdotbase' parameter,
+ which can have one of three values:
+ </para>
+
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ A complete file path to the command 'dot' (part of
+ <ulink url="http://www.graphviz.org/">GraphViz</ulink>)
+ will generate the graphs locally
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A URL prefix pointing to an installation of the webdot package will
+ generate the graphs remotely
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A blank value will disable dependency graphing.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+
+ <para>The easiest way to get this working is to install
+ <ulink url="http://www.graphviz.org/">GraphViz</ulink>. If you
+ do that, you need to
+ <ulink url="http://httpd.apache.org/docs/mod/mod_imap.html">enable
+ server-side image maps</ulink> in Apache.
+ Alternatively, you could set up a webdot server, or use the AT&T
+ public webdot server. This is the default for the webdotbase param,
+ but it's often overloaded and slow. Note that AT&T's server
+ won't work
+ if Bugzilla is only accessible using HARTS.
+ <emphasis>Editor's note: What the heck is HARTS? Google doesn't know...
+ </emphasis>
+ </para>
+ </section>
+
<section id="installation-whining-cron">
<title>The Whining Cron</title>
</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>
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">
</para>
<programlisting>
-<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>
+ </programlisting>
+
<note>
<para>
The PPM repository stores modules in 'packages' that may have
<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>
<command>make && make test && make install</command>
</screen>
- <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>
+ <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>
</section>
<section id="install-perlmodules-nonroot">
<title>Perl Modules</title>
- <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>
+ <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></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></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></prompt>
+ <command>force install Template</command>
+ </screen>
+ </para>
+
+ <para>You may also want to install the other optional modules:</para>
+
+ <screen>
+ <prompt>cpan></prompt>
+ <command>install GD</command>
+ <prompt>cpan></prompt>
+ <command>install Chart::Base</command>
+ <prompt>cpan></prompt>
+ <command>install MIME::Parser</command>
+ </screen>
+
+ </section>
</section>
<section>
<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>
- When you run <command>./checksetup.pl</command> to create
+ <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
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 <xref linkend="install-perlmodules-nonroot"/>,
- then delete the <filename>localconfig</filename> file and try again.
- </para>
+ module installation from the CPAN shell, then delete the
+ <filename>localconfig</filename> file and try again.</para>
<warning>
- <para>One option in <filename>localconfig</filename> you
+ <para>The 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,
projects / thirdparty / bugzilla.git / commitdiff
