diff options
Diffstat (limited to 'docs/en/xml/installation.xml')
-rw-r--r-- | docs/en/xml/installation.xml | 506 |
1 files changed, 71 insertions, 435 deletions
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&T - public webdot server. This is the default for the webdotbase param, - but it's often overloaded and slow. Note that AT&T's server - won't work - if Bugzilla is only accessible using HARTS. - <emphasis>Editor's note: What the heck is HARTS? Google doesn't know... - </emphasis> - </para> - </section> - <section id="installation-whining-cron"> <title>The Whining Cron</title> @@ -1485,229 +1435,7 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s </para> </note> </section> - - <section id="patch-viewer"> - <title>Patch Viewer</title> - - <para> - Patch Viewer is the engine behind Bugzilla's graphical display of - code patches. You can integrate this with copies of the - <filename>cvs</filename>, <filename>lxr</filename> and - <filename>bonsai</filename> tools if you have them, by giving - the locations of your installation of these tools in - <filename>editparams.cgi</filename>. - </para> - <para> - Patch Viewer also optionally will use the - <filename>cvs</filename>, <filename>diff</filename> and - <filename>interdiff</filename> - command-line utilities if they exist on the system. - Interdiff can be obtained from - <ulink url="http://cyberelk.net/tim/patchutils/"/>. - If these programs are not in the system path, you can configure - their locations in <filename>localconfig</filename>. - </para> - - - </section> - - <section id="bzradius"> - <title>RADIUS Authentication</title> - - <para>RADIUS authentication is a module for Bugzilla's plugin - authentication architecture. - Most caveats that apply to LDAP authentication apply to RADIUS - authentication as well. - </para> - - <para>Parameters required to use RADIUS Authentication:</para> - - <variablelist> - <varlistentry id="param-user_verify_class_for_radius"> - <term>user_verify_class</term> - <listitem> - <para>If you want to list <quote>RADIUS</quote> here, - make sure to have set up the other parameters listed below. - Unless you have other (working) authentication methods listed as - well, you may otherwise not be able to log back in to Bugzilla once - you log out. - If this happens to you, you will need to manually edit - <filename>data/params</filename> and set user_verify_class to - <quote>DB</quote>. - </para> - </listitem> - </varlistentry> - - <varlistentry id="param-RADIUS_server"> - <term>RADIUS_server</term> - <listitem> - <para>This parameter should be set to the name (and optionally the - port) of your RADIUS server. - </para> - </listitem> - </varlistentry> - - <varlistentry id="param-RADIUS_secret"> - <term>RADIUS_secret</term> - <listitem> - <para>This parameter should be set to the RADIUS server's secret. - </para> - </listitem> - </varlistentry> - - <varlistentry id="param-RADIUS_email_suffix"> - <term>RADIUS_email_suffix</term> - <listitem> - <para>Bugzilla needs an e-mail address for each user account. - Therefore, it needs to determine the e-mail address corresponding - to a RADIUS user. - Bugzilla offers only a simple way to do this: it can concatenate - a suffix to the RADIUS user name to convert it into an e-mail - address. - You can specify this suffix in the RADIUS_email_suffix parameter. - </para> - <para>If this simple solution does not work for you, you'll - probably need to modify - <filename>Bugzilla/Auth/Verify/RADIUS.pm</filename> to match your - requirements. - </para> - </listitem> - </varlistentry> - </variablelist> - - </section> - - <section id="bzldap"> - <title>LDAP Authentication</title> - - <para>LDAP authentication is a module for Bugzilla's plugin - authentication architecture. - </para> - - <para> - The existing authentication - scheme for Bugzilla uses email addresses as the primary user ID, and a - password to authenticate that user. All places within Bugzilla where - you need to deal with user ID (e.g assigning a bug) use the email - address. The LDAP authentication builds on top of this scheme, rather - than replacing it. The initial log in is done with a username and - password for the LDAP directory. Bugzilla tries to bind to LDAP using - those credentials, and if successful, try to map this account to a - Bugzilla account. If a LDAP mail attribute is defined, the value of this - attribute is used, otherwise emailsuffix parameter is appended to LDAP - username to form a full email address. If an account for this address - already exists in your Bugzilla system, it will log in to that account. - If no account for that email address exists, one is created at the time - of login. (In this case, Bugzilla will attempt to use the "displayName" - or "cn" attribute to determine the user's full name.) After - authentication, all other user-related tasks are still handled by email - address, not LDAP username. You still assign bugs by email address, query - on users by email address, etc. - </para> - - <caution> - <para>Because the Bugzilla account is not created until the first time - a user logs in, a user who has not yet logged is unknown to Bugzilla. - This means they cannot be used as an assignee or QA contact (default or - otherwise), added to any cc list, or any other such operation. One - possible workaround is the <filename>bugzilla_ldapsync.rb</filename> - script in the - <glossterm linkend="gloss-contrib"><filename class="directory">contrib</filename></glossterm> directory. Another possible solution is fixing - <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=201069">bug - 201069</ulink>. - </para> - </caution> - - <para>Parameters required to use LDAP Authentication:</para> - - <variablelist> - <varlistentry id="param-user_verify_class_for_ldap"> - <term>user_verify_class</term> - <listitem> - <para>If you want to list <quote>LDAP</quote> here, - make sure to have set up the other parameters listed below. - Unless you have other (working) authentication methods listed as - well, you may otherwise not be able to log back in to Bugzilla once - you log out. - If this happens to you, you will need to manually edit - <filename>data/params</filename> and set user_verify_class to - <quote>DB</quote>. - </para> - </listitem> - </varlistentry> - - <varlistentry id="param-LDAPserver"> - <term>LDAPserver</term> - <listitem> - <para>This parameter should be set to the name (and optionally the - port) of your LDAP server. If no port is specified, it assumes - the default LDAP port of 389. - </para> - <para>Ex. <quote>ldap.company.com</quote> - or <quote>ldap.company.com:3268</quote> - </para> - <para>You can also specify a LDAP URI, so as to use other - protocols, such as LDAPS or LDAPI. If port was not specified in - the URI, the default is either 389 or 636 for 'LDAP' and 'LDAPS' - schemes respectively. - </para> - <para>Ex. <quote>ldap://ldap.company.com</quote>, - <quote>ldaps://ldap.company.com</quote> or - <quote>ldapi://%2fvar%2flib%2fldap_sock</quote> - </para> - </listitem> - </varlistentry> - - <varlistentry id="param-LDAPbinddn"> - <term>LDAPbinddn [Optional]</term> - <listitem> - <para>Some LDAP servers will not allow an anonymous bind to search - the directory. If this is the case with your configuration you - should set the LDAPbinddn parameter to the user account Bugzilla - should use instead of the anonymous bind. - </para> - <para>Ex. <quote>cn=default,cn=user:password</quote></para> - </listitem> - </varlistentry> - - <varlistentry id="param-LDAPBaseDN"> - <term>LDAPBaseDN</term> - <listitem> - <para>The LDAPBaseDN parameter should be set to the location in - your LDAP tree that you would like to search for email addresses. - Your uids should be unique under the DN specified here. - </para> - <para>Ex. <quote>ou=People,o=Company</quote></para> - </listitem> - </varlistentry> - - <varlistentry id="param-LDAPuidattribute"> - <term>LDAPuidattribute</term> - <listitem> - <para>The LDAPuidattribute parameter should be set to the attribute - which contains the unique UID of your users. The value retrieved - from this attribute will be used when attempting to bind as the - user to confirm their password. - </para> - <para>Ex. <quote>uid</quote></para> - </listitem> - </varlistentry> - - <varlistentry id="param-LDAPmailattribute"> - <term>LDAPmailattribute</term> - <listitem> - <para>The LDAPmailattribute parameter should be the name of the - attribute which contains the email address your users will enter - into the Bugzilla login boxes. - </para> - <para>Ex. <quote>mail</quote></para> - </listitem> - </varlistentry> - </variablelist> - - </section> - <section id="apache-addtype"> <title>Serving Alternate Formats with the right MIME type</title> @@ -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> <command>ppm install <module name></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 && make test && 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></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> + <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> |