3.6. Win32 Installation Notes

This section covers installation on Microsoft Windows 95, 98, ME, NT, and 2000. Bugzilla works fine on Win32 platforms, but please remember that the Bugzilla team and the author of the Guide neither endorse nor support installation on Microsoft Windows. Bugzilla installs and runs best and easiest on UNIX-like operating systems, and that is the way it will stay for the foreseeable future. The Bugzilla team is considering supporting Win32 for the 2.16 release and later.

The easiest way to install Bugzilla on Intel-archiecture machines is to install some variant of GNU/Linux, then follow the UNIX installation instructions in this Guide. If you have any influence in the platform choice for running this system, please choose GNU/Linux instead of Microsoft Windows.

3.6.1. Win32 Installation: Step-by-step

Note

You should be familiar with, and cross-reference, the rest of the Bugzilla Installation section while performing your Win32 installation.

Making Bugzilla work on Microsoft Windows is no picnic. Support for Win32 has improved dramatically in the last few releases, but, if you choose to proceed, you should be a very skilled Windows Systems Administrator with strong troubleshooting abilities, a high tolerance for pain, and moderate perl skills. Bugzilla on NT requires hacking source code and implementing some advanced utilities. What follows is the recommended installation procedure for Win32; additional suggestions are provided in Appendix A.

  1. Install Apache Web Server for Windows, and copy the Bugzilla files somewhere Apache can serve them. Please follow all the instructions referenced in Bugzilla Installation regarding your Apache configuration, particularly instructions regarding the "AddHandler" parameter and "ExecCGI".

    Note

    You may also use Internet Information Server or Personal Web Server for this purpose. However, setup is quite different. If ActivePerl doesn't seem to handle your file associations correctly (for .cgi and .pl files), please consult Appendix A.

    If you are going to use IIS, if on Windows NT you must be updated to at least Service Pack 4. Windows 2000 ships with a sufficient version of IIS.

  2. Install ActivePerl for Windows. Check http://aspn.activestate.com/ASPN/Downloads/ActivePerl for a current compiled binary.

    Please also check the following links to fully understand the status of ActivePerl on Win32: Perl Porting, and Perl on Win32 FAQ

  3. Use ppm from your perl\bin directory to install the following packs: DBI, DBD-Mysql, TimeDate, Chart, Date-Calc, Date-Manip, GD, AppConfig, and Template. You may need to extract them from .zip format using Winzip or other unzip program first. Most of these additional ppm modules can be downloaded from ActiveState, but AppConfig and Template should be obtained from OpenInteract using the instructions on the Template Toolkit web site.

    The syntax for ppm is: C:> ppm <modulename>

    ActiveState's 5.6Plus directory also contains an AppConfig ppm, so you might see the following error when trying to install the version at OpenInteract:

    Error installing package 'AppConfig': Read a PPD for 'AppConfig', but it is not intended for this build of Perl (MSWin32-x86-multi-thread)

    If so, download both the tarball and the ppd directly from OpenInteract, then run ppm from within the same directory to which you downloaded those files and install the package by referencing the ppd file explicitly via in the install command, f.e.:

  4. Install MySQL for NT.

    Note

    You can download MySQL for Windows NT from MySQL.com. Some find it helpful to use the WinMySqlAdmin utility, included with the download, to set up the database.

  5. Setup MySQL

    1. C:> C:\mysql\bin\mysql -u root mysql

    2. mysql> DELETE FROM user WHERE Host='localhost' AND User='';

    3. mysql> UPDATE user SET Password=PASSWORD ('new_password') WHERE user='root';

      "new_password", above, indicates whatever password you wish to use for your "root" user.

    4. mysql> GRANT SELECT, INSERT, UPDATE, DELETE, INDEX, ALTER, CREATE, DROP, REFERENCES ON bugs.* to bugs@localhost IDENTIFIED BY 'bugs_password';

      "bugs_password", above, indicates whatever password you wish to use for your "bugs" user.

    5. mysql> FLUSH PRIVILEGES;

    6. mysql> create database bugs;

    7. mysql> exit;

    8. C:> C:\mysql\bin\mysqladmin -u root -p reload

  6. Edit checksetup.pl in your Bugzilla directory. Change this line:

    
my $webservergid = getgrnam($my_webservergroup);
    	    

    to

    
my $webservergid = $my_webservergroup;
    	    
    or the name of the group you wish to own the files explicitly:
    
my $webservergid = 'Administrators'
    	    

  7. Run checksetup.pl from the Bugzilla directory.

  8. Edit localconfig to suit your requirements. Set $db_pass to your "bugs_password" from step 5.d, and $webservergroup to "8".

    Note

    Not sure on the "8" for $webservergroup above. If it's wrong, please send corrections.

  9. Edit defparams.pl to suit your requirements. Particularly, set DefParam("maintainer") and DefParam("urlbase") to match your install.

    Note

    This is yet another step I'm not sure of, since the maintainer of this documentation does not maintain Bugzilla on NT. If you can confirm or deny that this step is required, please let me know.

  10. Note

    There are several alternatives to Sendmail that will work on Win32. The one mentioned here is a suggestion, not a requirement. Some other mail packages that can work include BLAT, Windmail, Mercury Sendmail, and the CPAN Net::SMTP Perl module (available in .ppm). Every option requires some hacking of the Perl scripts for Bugzilla to make it work. The option here simply requires the least.

    1. Download NTsendmail, available from www.ntsendmail.com. You must have a "real" mail server which allows you to relay off it in your $ENV{"NTsendmail"} (which you should probably place in globals.pl)

    2. Put ntsendmail.pm into your .\perl\lib directory.

    3. Add to globals.pl:

      
# these settings configure the NTsendmail process
      use NTsendmail;
      $ENV{"NTsendmail"}="your.smtpserver.box";
      $ENV{"NTsendmail_debug"}=1;
      $ENV{"NTsendmail_max_tries"}=5;
      	      

      Note

      Some mention to also edit $db_pass in globals.pl to be your "bugs_password". Although this may get you around some problem authenticating to your database, since globals.pl is not normally restricted by .htaccess, your database password is exposed to whoever uses your web server.

    4. Find and comment out all occurences of "open(SENDMAIL" in your Bugzilla directory. Then replace them with:
      
# new sendmail functionality
      my $mail=new NTsendmail;
      my $from="bugzilla\@your.machine.name.tld";
      my $to=$login;
      my $subject=$urlbase;
      $mail->send($from,$to,$subject,$msg);
      		

      Note

      Some have found success using the commercial product, Windmail. You could try replacing your sendmail calls with:
      
open SENDMAIL, "|\"C:/General/Web/tools/Windmail 4.0 Beta/windmail\" -t > mail.log";
      		  
      or something to that effect.

  11. Change all references in all files from processmail to processmail.pl, and rename processmail to processmail.pl.

    Note

    Many think this may be a change we want to make for main-tree Bugzilla. It's painless for the UNIX folks, and will make the Win32 people happier.

    Note

    Some people have suggested using the Net::SMTP Perl module instead of NTsendmail or the other options listed here. You can change processmail.pl to make this work.
    
    
    my $smtp = Net::SMTP->new('<Name of your SMTP server>');   #connect to SMTP server
    $smtp->mail('<your name>@<you smpt server>');# use the sender's adress here
    $smtp->to($tolist); # recipient's address
    $smtp->data();  # Start the mail
    $smtp->datasend($msg);
    $smtp->dataend();   # Finish sending the mail
    $smtp->quit;    # Close the SMTP connection
    $logstr = "$logstr; mail sent to $tolist $cclist";
    }
    
    
    
    here is a test mail program for Net::SMTP:
    
    
    use Net::SMTP;
     my $smtp = Net::SMTP->new('<Name of your SMTP server', Timeout => 30, Debug
    => 1, ); # connect to SMTP server
                     $smtp->auth;
                    $smtp->mail('you@yourcompany.com');# use the sender's adress
    here
                    $smtp->to('someotherAddress@someotherdomain.com'); #
    recipient's address
                    $smtp->data();  # Start the mail
                    $smtp->datasend('test');
                    $smtp->dataend();   # Finish sending the mail
                    $smtp->quit;    # Close the SMTP connection
    exit;
    
    
    

  12. Note

    This step is optional if you are using IIS or another web server which only decides on an interpreter based upon the file extension (.pl), rather than the "shebang" line (#/usr/bonsaitools/bin/perl)

    Modify the path to perl on the first line (#!) of all files to point to your Perl installation, and add "perl" to the beginning of all Perl system calls that use a perl script as an argument. This may take you a while. There is a "setperl.csh" utility to speed part of this procedure, available in the Useful Patches and Utilities for Bugzilla section of The Bugzilla Guide. However, it requires the Cygwin GNU-compatible environment for Win32 be set up in order to work. See http://www.cygwin.com/ for details on obtaining Cygwin.

  13. Modify the invocation of all system() calls in all perl scripts in your Bugzilla directory. You should specify the full path to perl for each system() call. For instance, change this line in processmail:
     
    system ("./processmail",@ARGLIST); 
    	    </programlisting> to
    	    <programlisting> 
    system ("C:\\perl\\bin\\perl", "processmail", @ARGLIST);
    	    

  14. Add binmode() calls so attachments will work (bug 62000).

    Because Microsoft Windows based systems handle binary files different than Unix based systems, you need to add the following lines to createattachment.cgi and showattachment.cgi before the require 'CGI.pl'; line.

    
    binmode(STDIN);
    binmode(STDOUT);
    
    

    Note

    According to bug 62000, the perl documentation says that you should always use binmode() when dealing with binary files, but never when dealing with text files. That seems to suggest that rather than arbitrarily putting binmode() at the beginning of the attachment files, there should be logic to determine if binmode() is needed or not.

Tip

If you are using IIS or Personal Web Server, you must add cgi relationships to Properties -> Home directory (tab) -> Application Settings (section) -> Configuration (button), such as:

 
.cgi to: <perl install directory>\perl.exe %s %s
.pl to: <perl install directory>\perl.exe %s %s
GET,HEAD,POST
	  
Change the path to Perl to match your install, of course.

3.6.2. Additional Windows Tips

Tip

From Andrew Pearson:

You can make Bugzilla work with Personal Web Server for Windows 98 and higher, as well as for IIS 4.0. Microsoft has information available at http://support.microsoft.com/support/kb/articles/Q231/9/98.ASP

Basically you need to add two String Keys in the registry at the following location:


HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\ScriptMap
	      

The keys should be called ".pl" and ".cgi", and both should have a value something like: c:/perl/bin/perl.exe "%s" "%s"

The KB article only talks about .pl, but it goes into more detail and provides a perl test script.

Tip

If attempting to run Bugzilla 2.12 or older, you will need to remove encrypt() calls from the Perl source. This is not necessary for Bugzilla 2.13 and later, which includes the current release, Bugzilla 2.16.

3.6.3. Bugzilla LDAP Integration

What follows is some late-breaking information on using the LDAP authentication options with Bugzilla. The author has not tested these (nor even formatted this section!) so please contribute feedback to the newsgroup.


Mozilla::LDAP module

The Mozilla::LDAP module allows you to use LDAP for authentication to
the Bugzilla system.  This module is not required if you are not using
LDAP.

Mozilla::LDAP (aka PerLDAP) is available for download from
http://www.mozilla.org/directory.

NOTE: The Mozilla::LDAP module requires Netscape's Directory SDK.
Follow the link for "Directory SDK for C" on that same page to
download the SDK first.  After you have installed this SDK, then
install the PerLDAP module.
----------------------------------------------------------------------

Post-Installation Checklist
----------------------------------------------------------------------
Set useLDAP to "On" **only** if you will be using an LDAP directory
for authentication.  Be very careful when setting up this parameter;
if you set LDAP authentication, but do not have a valid LDAP directory
set up, you will not be able to log back in to Bugzilla once you log
out.  (If this happens, you can get back in by manually editing the
data/params file, and setting useLDAP back to 0.)

If using LDAP, you must set the three additional parameters:

Set LDAPserver to the name (and optionally port) of your LDAP server.
If no port is specified, it defaults to the default port of 389.  (e.g
"ldap.mycompany.com" or "ldap.mycompany.com:1234")

Set LDAPBaseDN to the base DN for searching for users in your LDAP
directory.  (e.g. "ou=People,o=MyCompany")  uids must be unique under
the DN specified here.

Set LDAPmailattribute to the name of the attribute in your LDAP
directory which contains the primary email address.  On most directory
servers available, this is "mail", but you may need to change this.
----------------------------------------------------------------------

(Not sure where this bit should go, but it's important that it be in
there somewhere...)
----------------------------------------------------------------------
Using LDAP authentication for Bugzilla:

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.  This then fetches the email address from LDAP
and authenticates seamlessly in the standard Bugzilla authentication
scheme using this 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.
----------------------------------------------------------------------