From 2fe7a96c48369e9ad19d61a5b851f6f6baccbd35 Mon Sep 17 00:00:00 2001 From: "justdave%bugzilla.org" <> Date: Fri, 4 Apr 2008 11:48:16 +0000 Subject: Bug 105366: add documentation for running Bugzilla under suexec r=mkanat, colin --- docs/en/xml/installation.xml | 475 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 434 insertions(+), 41 deletions(-) (limited to 'docs/en') diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml index 6f8dc0536..27f57d040 100644 --- a/docs/en/xml/installation.xml +++ b/docs/en/xml/installation.xml @@ -1,5 +1,5 @@ - + Installing Bugzilla @@ -473,6 +473,12 @@ + + + Apache::DBI + (&min-apache-dbi-ver;) for mod_perl2 + + @@ -649,9 +655,13 @@ 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; + + Finally, Bugzilla also requires Apache::DBI + (&min-apache-dbi-ver;) to be installed as well. +
Configuration @@ -1113,7 +1123,7 @@ - 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 @@ -1317,6 +1327,7 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
+
Optional Additional Configuration @@ -1371,6 +1382,54 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
+
+ Dependency Charts + + 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: + + + + + + + A complete file path to the command 'dot' (part of + GraphViz) + will generate the graphs locally + + + + + A URL prefix pointing to an installation of the webdot package will + generate the graphs remotely + + + + + A blank value will disable dependency graphing. + + + + + + The easiest way to get this working is to install + GraphViz. If you + do that, you need to + enable + server-side image maps 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. + Editor's note: What the heck is HARTS? Google doesn't know... + + +
+
The Whining Cron @@ -1435,7 +1494,229 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
+ +
+ Patch Viewer + + + Patch Viewer is the engine behind Bugzilla's graphical display of + code patches. You can integrate this with copies of the + cvs, lxr and + bonsai tools if you have them, by giving + the locations of your installation of these tools in + editparams.cgi. + + + Patch Viewer also optionally will use the + cvs, diff and + interdiff + command-line utilities if they exist on the system. + Interdiff can be obtained from + . + If these programs are not in the system path, you can configure + their locations in localconfig. + + + +
+ +
+ RADIUS Authentication + + RADIUS authentication is a module for Bugzilla's plugin + authentication architecture. + Most caveats that apply to LDAP authentication apply to RADIUS + authentication as well. + + + Parameters required to use RADIUS Authentication: + + + + user_verify_class + + If you want to list RADIUS 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 + data/params and set user_verify_class to + DB. + + + + + + RADIUS_server + + This parameter should be set to the name (and optionally the + port) of your RADIUS server. + + + + + + RADIUS_secret + + This parameter should be set to the RADIUS server's secret. + + + + + + RADIUS_email_suffix + + 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. + + If this simple solution does not work for you, you'll + probably need to modify + Bugzilla/Auth/Verify/RADIUS.pm to match your + requirements. + + + + + +
+ +
+ LDAP Authentication + + LDAP authentication is a module for Bugzilla's plugin + authentication architecture. + + + + 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. + + + + 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 bugzilla_ldapsync.rb + script in the + contrib directory. Another possible solution is fixing + bug + 201069. + + + + Parameters required to use LDAP Authentication: + + + + user_verify_class + + If you want to list LDAP 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 + data/params and set user_verify_class to + DB. + + + + + + LDAPserver + + 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. + + Ex. ldap.company.com + or ldap.company.com:3268 + + 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. + + Ex. ldap://ldap.company.com, + ldaps://ldap.company.com or + ldapi://%2fvar%2flib%2fldap_sock + + + + + + LDAPbinddn [Optional] + + 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. + + Ex. cn=default,cn=user:password + + + + + LDAPBaseDN + + 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. + + Ex. ou=People,o=Company + + + + + LDAPuidattribute + + 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. + + Ex. uid + + + + + LDAPmailattribute + + The LDAPmailattribute parameter should be the name of the + attribute which contains the email address your users will enter + into the Bugzilla login boxes. + + Ex. mail + + + + +
+
Serving Alternate Formats with the right MIME type @@ -1540,15 +1821,6 @@ AddType application/rdf+xml .rdf The following instructions assume that you are using version 5.8.1 of ActiveState. - - - - 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. - - -
@@ -1572,16 +1844,9 @@ C:\perl> ppm install <module name> -ppm repo add landfill http://www.landfill.bugzilla.org/ppm/ - - - - In versions prior to 5.8.8 build 819 of PPM the command is - ppm repository add landfill http://www.landfill.bugzilla.org/ppm/ - - - + + The PPM repository stores modules in 'packages' that may have @@ -1880,12 +2145,10 @@ pid-file=/home/foo/mymysql/the.pid
Perl - - On the extremely rare chance that you don't have Perl on + 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: - + installed with your own personal version of Perl: bash$ @@ -1900,23 +2163,139 @@ pid-file=/home/foo/mymysql/the.pid make && make test && make install - - Once you have Perl installed into a directory (probably - in ~/perl/bin), you will need to - install the Perl Modules, described below. - + Once you have Perl installed into a directory (probably + in ~/perl/bin), you'll have to + change the locations on the scripts, which is detailed later on + this page.
Perl Modules - - Installing the Perl modules as a non-root user is accomplished by - running the install-module.pl - script. For more details on this script, see - install-module.pl - documentation - + 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. + +
+ The Independant Method + + 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: + + + + bash$ + /home/foo/perl/bin/perl -MCPAN -e 'shell' + + + + And then: + + + + cpan> + install Bundle::Bugzilla + + + + With this method, module installation will usually go a lot + smoother, but if you have any hang-ups, you can consult the next + section. +
+ +
+ The Mixed Method + + First, you'll need to configure CPAN to + install modules in your home directory. The CPAN FAQ says the + following on this issue: + + + +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. + + + So, you will need to create a Perl directory in your home + directory, as well as the lib, + man, + man/man1, and + man/man3 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.) + + After that, go into the CPAN shell: + + + + bash$ + perl -MCPAN -e 'shell' + + + + From there, you will need to type in the above "o conf" command + and commit the changes. Then you can run through the installation: + + + + cpan> + install Bundle::Bugzilla + + + + 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: + + + + cpan> + force install Template + + + + You may also want to install the other optional modules: + + + cpan> + install GD + cpan> + install Chart::Base + cpan> + install MIME::Parser + + +
@@ -1961,16 +2340,30 @@ pid-file=/home/foo/mymysql/the.pid
Bugzilla + If you had to install Perl modules as a non-root user + () or to non-standard + directories, you will need to change the scripts, setting the correct + location of the Perl modules: + - When you run ./checksetup.pl to create + perl -pi -e + 's@use strict\;@use strict\; use lib \"/home/foo/perl/lib\"\;@' + *cgi *pl Bug.pm processmail syncshadowdb + + Change /home/foo/perl/lib to + your personal Perl library directory. You can probably skip this + step if you are using the independant method of Perl module + installation. + + + When you run ./checksetup.pl to create the localconfig file, it will list the Perl modules it finds. If one is missing, go back and double-check the - module installation from , - then delete the localconfig file and try again. - + module installation from the CPAN shell, then delete the + localconfig file and try again. - One option in localconfig you + The one option in localconfig you might have problems with is the web server group. If you can't successfully browse to the index.cgi (like a Forbidden error), you may have to relax your permissions, -- cgit v1.2.3-24-g4f1b