Skip to content

bugzilla
bugzilla
Commit 2fe7a96c authored by justdave%bugzilla.org's avatar justdave%bugzilla.org
Browse files
Options

Bug 105366: add documentation for running Bugzilla under suexec

r=mkanat, colin
parent 7da0141a
Hide whitespace changes
Inline Side-by-side
Showing with 434 additions and 41 deletions
docs/en/xml/installation.xml
View file @ 2fe7a96c
<!-- <!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>
......@@ -473,6 +473,12 @@
</para>
</listitem>
<listitem>
<para>
Apache::DBI
(&min-apache-dbi-ver;) for mod_perl2
</para>
</listitem>
</orderedlist>
</para>
......@@ -649,9 +655,13 @@
<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>
......@@ -1113,7 +1123,7 @@
</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>
......@@ -1317,6 +1327,7 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
</section>
</section>
<section id="extraconfig">
<title>Optional Additional Configuration</title>
......@@ -1371,6 +1382,54 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
</note>
</section>
<section>
<title>Dependency Charts</title>
<para>As well as the text-based dependency trees, Bugzilla also
supports a graphical view of dependency relationships, using a
package called 'dot'.
Exactly how this works is controlled by the 'webdotbase' parameter,
which can have one of three values:
</para>
<para>
<orderedlist>
<listitem>
<para>
A complete file path to the command 'dot' (part of
<ulink url="http://www.graphviz.org/">GraphViz</ulink>)
will generate the graphs locally
</para>
</listitem>
<listitem>
<para>
A URL prefix pointing to an installation of the webdot package will
generate the graphs remotely
</para>
</listitem>
<listitem>
<para>
A blank value will disable dependency graphing.
</para>
</listitem>
</orderedlist>
</para>
<para>The easiest way to get this working is to install
<ulink url="http://www.graphviz.org/">GraphViz</ulink>. If you
do that, you need to
<ulink url="http://httpd.apache.org/docs/mod/mod_imap.html">enable
server-side image maps</ulink> in Apache.
Alternatively, you could set up a webdot server, or use the AT&amp;T
public webdot server. This is the default for the webdotbase param,
but it's often overloaded and slow. Note that AT&amp;T's server
won't work
if Bugzilla is only accessible using HARTS.
<emphasis>Editor's note: What the heck is HARTS? Google doesn't know...
</emphasis>
</para>
</section>
<section id="installation-whining-cron">
<title>The Whining Cron</title>
......@@ -1435,7 +1494,229 @@ 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>
......@@ -1540,15 +1821,6 @@ 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">
......@@ -1572,16 +1844,9 @@ C:\perl&gt; <command>ppm install &lt;module name&gt;</command>
</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
......@@ -1880,12 +2145,10 @@ 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>
......@@ -1900,23 +2163,139 @@ pid-file=/home/foo/mymysql/the.pid
<command>make &amp;&amp; make test &amp;&amp; make install</command>
</screen>
<para>
Once you have Perl installed into a directory (probably
in <filename class="directory">~/perl/bin</filename>), you 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&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>
......@@ -1961,16 +2340,30 @@ 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>
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,
......
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