From d8caf6045d10344c431918128e3803ca497565f3 Mon Sep 17 00:00:00 2001 From: "gerv%gerv.net" <> Date: Sun, 28 Jul 2002 05:00:17 +0000 Subject: Merging new docs from 2.16 branch. --- docs/html/stepbystep.html | 2070 +++++++++++++++++++-------------------------- 1 file changed, 847 insertions(+), 1223 deletions(-) (limited to 'docs/html/stepbystep.html') diff --git a/docs/html/stepbystep.html b/docs/html/stepbystep.html index ef605ba91..6d4de5a21 100644 --- a/docs/html/stepbystep.html +++ b/docs/html/stepbystep.html @@ -13,11 +13,11 @@ REL="UP" TITLE="Installation" HREF="installation.html">PrevChapter 3. InstallationChapter 4. InstallationNext

3.2. Step-by-step Install

4.1. Step-by-step Install

3.2.1. Introduction

Installation of bugzilla is pretty straightforward, particularly if your - machine already has MySQL and the MySQL-related perl packages installed. - If those aren't installed yet, then that's the first order of business. The - other necessary ingredient is a web server set up to run cgi scripts. - While using Apache for your webserver is not required, it is recommended. -

4.1.1. Introduction

Bugzilla has been successfully installed under Solaris, Linux, - and Win32. The peculiarities of installing on Win32 (Microsoft - Windows) are not included in this section of the Guide; please - check out the Bugzilla has been successfully installed under Solaris, Linux, + and Win32. Win32 is not yet officially supported, but many people + have got it working fine. + Please see the + Win32 Installation Notes for further advice - on getting Bugzilla to work on Microsoft Windows. -

The Bugzilla Guide is contained in the "docs/" folder in your - Bugzilla distribution. It is available in plain text - (docs/txt), HTML (docs/html), or SGML source (docs/sgml). -

+ for further advice on getting Bugzilla to work on Microsoft + Windows.

3.2.2. Installing the Prerequisites

4.1.2. Package List

If you want to skip these manual installation steps for - the CPAN dependencies listed below, and are running the very - most recent version of Perl and MySQL (both the executables - and development libraries) on your system, check out - Bundle::Bugzilla in If you are running the very most recent + version of Perl and MySQL (both the executables and development + libraries) on your system, you can skip these manual installation + steps for the Perl modules by using Bundle::Bugzilla; see + Using Bundle::Bugzilla instead of manually installing Perl modules

. +

The software packages necessary for the proper running of bugzilla are: -

The software packages necessary for the proper running of + Bugzilla (with download links) are: +

  1. MySQL database server and the mysql client (3.22.5 or greater) -

    MySQL database server + (3.22.5 or greater) +

  2. Perl + (5.005 or greater, 5.6.1 is recommended if you wish to + use Bundle::Bugzilla) +

  3. Perl Modules (minimum version): +

    1. Template + (v2.07) +

    2. AppConfig + + (v1.52) +

    3. Text::Wrap + (v2001.0131) +

    4. File::Spec + + (v0.8.2) +

    5. Perl (5.004 or greater, 5.6.1 is recommended if you wish - to use Bundle::Bugzilla) -

      Data::Dumper + + (any) +

    6. DBI Perl module -

      DBD::mysql + + (v1.2209) +

    7. Data::Dumper Perl module -

      DBI + (v1.13) +

    8. Bundle::Mysql Perl module collection -

      Date::Parse + + (any) +

    9. TimeDate Perl module collection -

      CGI::Carp + (any) +

    + and, optionally: +

    1. GD perl module (1.8.3) (optional, for bug charting) -

      GD + (v1.19) for bug charting +

    2. Chart::Base Perl module (0.99c) (optional, for bug charting) -

      Chart::Base + + (v0.99c) for bug charting +

    3. DB_File Perl module (optional, for bug charting) -

      XML::Parser + (any) for the XML interface +

    4. The web server of your choice. Apache is recommended. -

      MIME::Parser + (any) for the email interface +

    +

  4. MIME::Parser Perl module (optional, for contrib/bug_email.pl interface) -

    The web server of your choice. + Apache + is highly recommended. +

-

It is a good idea, while installing Bugzilla, to ensure it - is not accessible by other machines - on the Internet. Your machine may be vulnerable to attacks - while you are installing. In other words, ensure there is - some kind of firewall between you and the rest of the - Internet. Many installation steps require an active - Internet connection to complete, but you must take care to - ensure that at no point is your machine vulnerable to an - attack. -

It is a good idea, while installing Bugzilla, to ensure that there + is some kind of firewall between you and the rest of the Internet, + because your machine may be insecure for periods during the install. + Many + installation steps require an active Internet connection to complete, + but you must take care to ensure that at no point is your machine + vulnerable to an attack.

-

Linux-Mandrake 8.0, the author's test system, includes - every required and optional library for Bugzilla. The - easiest way to install them is by using the - Linux-Mandrake 8.0 includes every + required and optional library for Bugzilla. The easiest way to + install them is by using the + urpmi utility. If you follow these - commands, you should have everything you need for - Bugzilla, and + + utility. If you follow these commands, you should have everything you + need for Bugzilla, and + checksetup.pl should - not complain about any missing libraries. You may already - have some of these installed.

+ + should not complain about any missing libraries. You may already have + some of these installed.

urpmi perl-mysql + urpmi perl-chart + urpmi perl-gd + urpmi perl-MailTools + + (for Bugzilla email integration)urpmi apache-modules +
bash# + + urpmi - perl-mysql
bash# + + urpmi - perl-chart
bash# + + urpmi - perl-gd
bash# + + urpmi - perl-MailTools (for Bugzilla email - integration)
bash# + + urpmi - apache-modules
-

3.2.3. Installing MySQL Database

4.1.3. MySQL

Visit MySQL homepage at Visit the MySQL homepage at + www.mysql.com and grab the latest stable release of the server. Many of the binary versions of MySQL store their data files in /var which is often part of a smaller root partition. If you decide to build from sources you can easily set the dataDir as an option to configure. +> + to grab and install the latest stable release of the server.

If you install from source or non-package (RPM, deb, etc.) - binaries you need to add - mysqld to your - init scripts so the server daemon will come back up whenever - your machine reboots. Further discussion of UNIX init - sequences are beyond the scope of this guide. -

You should have your init script start - mysqld with the ability to accept - large packets. By default, mysqld - only accepts packets up to 64K long. This limits the size - of attachments you may put on bugs. If you add -O - max_allowed_packet=1M to the command that starts - Many of the binary + versions of MySQL store their data files in + mysqld (or - /var. + On some Unix systems, this is part of a smaller root partition, + and may not have room for your bug database. You can set the data + directory as an option to safe_mysqld), then you will be able - to have attachments up to about 1 megabyte.

configure + if you build MySQL from source yourself.

If you install from something other than an RPM or Debian + package, you will need to add mysqld - + to your init scripts so the server daemon will come back up whenever + your machine reboots. Further discussion of UNIX init sequences are + beyond the scope of this guide.

If you plan on running Bugzilla and MySQL on the same - machine, consider using the Change your init script to start + mysqld + with the ability to accept large packets. By default, + mysqld + only accepts packets up to 64K long. This limits the size of + attachments you may put on bugs. If you add + -O max_allowed_packet=1M + to the command that starts + mysqld + (or safe_mysqld), + then you will be able to have attachments up to about 1 megabyte. + There is a Bugzilla parameter for maximum attachment size; + you should configure it to match the value you choose here.

If you plan on running Bugzilla and MySQL on the same machine, + consider using the + --skip-networking - option in the init script. This enhances security by - preventing network access to MySQL. -

3.2.4. Perl (5.004 or greater)

Any machine that doesn't have perl on it is a sad machine - indeed. Perl for *nix systems can be gotten in source form - from http://www.perl.com. Although Bugzilla runs with most - post-5.004 versions of Perl, it's a good idea to be up to the - very latest version if you can when running Bugzilla. As of - this writing, that is perl version 5.6.1. -

Perl is now a far cry from the the single compiler/interpreter - binary it once was. It includes a great many required modules - and quite a few other support files. If you're not up to or - not inclined to build perl from source, you'll want to install - it on your machine using some sort of packaging system (be it - RPM, deb, or what have you) to ensure a sane install. In the - subsequent sections you'll be installing quite a few perl - modules; this can be quite ornery if your perl installation - isn't up to snuff. -

4.1.4. Perl

Many people complain that Perl modules will not install - for them. Most times, the error messages complain that they - are missing a file in "@INC". Virtually every - time, this is due to permissions being set too restrictively - for you to compile Perl modules or not having the necessary - Perl development libraries installed on your system.. - Consult your local UNIX systems administrator for help - solving these permissions issues; if you - are the local UNIX sysadmin, please - consult the newsgroup/mailing list for further assistance or - hire someone to help you out. -

Any machine that doesn't have Perl on it is a sad machine indeed. + Perl can be got in source form from + perl.com for the rare + *nix systems which don't have it. + Although Bugzilla runs with all post-5.005 + versions of Perl, it's a good idea to be up to the very latest version + if you can when running Bugzilla. As of this writing, that is Perl + version 5.6.1.

You can skip the following Perl module installation steps by - installing You can skip the following Perl module installation steps by + installing + Bundle::Bugzilla from - + + from + CPAN, which - includes them. All Perl module installation steps require - you have an active Internet connection. If you wish to use - Bundle::Bugzilla, however, you must be using the latest - version of Perl (at this writing, version 5.6.1) -

, + which installs all required modules for you.

bash# + + perl -MCPAN - -e 'install "Bundle::Bugzilla"'perl -MCPAN -e 'install "Bundle::Bugzilla"' - -

Bundle::Bugzilla doesn't include GD, Chart::Base, or - MIME::Parser, which are not essential to a basic Bugzilla - install. If installing this bundle fails, you should - install each module individually to isolate the problem. -

Bundle::Bugzilla doesn't include GD, Chart::Base, or + MIME::Parser, which are not essential to a basic Bugzilla install. If + installing this bundle fails, you should install each module + individually to isolate the problem.

3.2.5. DBI Perl Module

The DBI module is a generic Perl module used by other database related - Perl modules. For our purposes it's required by the MySQL-related - modules. As long as your Perl installation was done correctly the - DBI module should be a breeze. It's a mixed Perl/C module, but Perl's - MakeMaker system simplifies the C compilation greatly. -

4.1.5. Perl Modules

Like almost all Perl modules DBI can be found on the Comprehensive Perl - Archive Network (CPAN) at http://www.cpan.org. The CPAN servers have a - real tendency to bog down, so please use mirrors. The current location - at the time of this writing can be found in Appendix B. -

Quality, general Perl module installation instructions can be found on - the CPAN website, but the easy thing to do is to just use the CPAN shell - which does all the hard work for you. +> + All Perl modules can be found on the + Comprehensive Perl + Archive Network (CPAN). The + CPAN servers have a real tendency to bog down, so please use mirrors. +

Quality, general Perl module installation instructions can be + found on the CPAN website, but the easy thing to do is to just use the + CPAN shell which does all the hard work for you. + To use the CPAN shell to install a module:

To use the CPAN shell to install DBI: -

- To do it the hard way: -

3.2.6. Data::Dumper Perl Module

The Data::Dumper module provides data structure persistence for Perl - (similar to Java's serialization). It comes with later sub-releases of - Perl 5.004, but a re-installation just to be sure it's available won't - hurt anything. -

Data::Dumper is used by the MySQL-related Perl modules. It - can be found on CPAN (see Appendix B) and - can be - installed by following the same four step make sequence used - for the DBI module. -

Many people complain that Perl modules will not install for + them. Most times, the error messages complain that they are missing a + file in + "@INC". + Virtually every time, this error is due to permissions being set too + restrictively for you to compile Perl modules or not having the + necessary Perl development libraries installed on your system. + Consult your local UNIX systems administrator for help solving these + permissions issues; if you + are + the local UNIX sysadmin, please consult the newsgroup/mailing list + for further assistance or hire someone to help you out.

4.1.5.2. Data::Dumper

The MakeMaker process will ask you a few questions about the desired - compilation target and your MySQL installation. For many of the questions - the provided default will be adequate. +>The Data::Dumper module provides data structure persistence for + Perl (similar to Java's serialization). It comes with later + sub-releases of Perl 5.004, but a re-installation just to be sure it's + available won't hurt anything.

4.1.5.3. MySQL-related modules

The Perl/MySQL interface requires a few mutually-dependent Perl + modules. These modules are grouped together into the the + Msql-Mysql-modules package.

The MakeMaker process will ask you a few questions about the + desired compilation target and your MySQL installation. For most of the + questions the provided default will be adequate, but when asked if your + desired target is the MySQL or mSQL packages, you should + select the MySQL related ones. Later you will be asked if you wish to + provide backwards compatibility with the older MySQL packages; you + should answer YES to this question. The default is NO.

A host of 'localhost' should be fine and a testing user of 'test' + with a null password should find itself with sufficient access to run + tests on the 'test' database which MySQL created upon installation.

When asked if your desired target is the MySQL or mSQL packages, - select the MySQL related ones. Later you will be asked if you wish - to provide backwards compatibility with the older MySQL packages; you - should answer YES to this question. The default is NO. -

A host of 'localhost' should be fine and a testing user of 'test' and - a null password should find itself with sufficient access to run tests - on the 'test' database which MySQL created upon installation. If 'make - test' and 'make install' go through without errors you should be ready - to go as far as database connectivity is concerned. -

3.2.8. TimeDate Perl Module Collection

Many of the more common date/time/calendar related Perl - modules have been grouped into a bundle similar to the MySQL - modules bundle. This bundle is stored on the CPAN under the - name TimeDate (see link: Appendix B). The - component module we're most interested in is the Date::Format - module, but installing all of them is probably a good idea - anyway. The standard Perl module installation instructions - should work perfectly for this simple package. -

4.1.5.4. TimeDate modules

Many of the more common date/time/calendar related Perl modules + have been grouped into a bundle similar to the MySQL modules bundle. + This bundle is stored on the CPAN under the name TimeDate. + The component module we're most interested in is the Date::Format + module, but installing all of them is probably a good idea anyway. +

3.2.9. GD Perl Module (1.8.3)

The GD library was written by Thomas Boutell a long while - ago to programatically generate images in C. Since then it's - become the defacto standard for programatic image - construction. The Perl bindings to it found in the GD library - are used on millions of web pages to generate graphs on the - fly. That's what bugzilla will be using it for so you must - install it if you want any of the graphing to work. -

Actually bugzilla uses the Graph module which relies on GD - itself. Isn't that always the way with object-oriented - programming? At any rate, you can find the GD library on CPAN - in Appendix B. -

4.1.5.5. GD (optional)

The GD library was written by Thomas Boutell a long while ago to + programatically generate images in C. Since then it's become the + defacto standard for programatic image construction. The Perl bindings + to it found in the GD library are used on millions of web pages to + generate graphs on the fly. That's what Bugzilla will be using it for + so you must install it if you want any of the graphing to work.

The Perl GD library requires some other libraries that may - or may not be installed on your system, including - The Perl GD library requires some other libraries that may or + may not be installed on your system, including + libpng and - + and + libgd. The full requirements are - listed in the Perl GD library README. Just realize that if - compiling GD fails, it's probably because you're missing a - required library. -

. + The full requirements are listed in the Perl GD library README. + If compiling GD fails, it's probably because you're + missing a required library.

3.2.10. Chart::Base Perl Module (0.99c)

The Chart module provides bugzilla with on-the-fly charting - abilities. It can be installed in the usual fashion after it - has been fetched from CPAN where it is found as the - Chart-x.x... tarball, linked in Appendix B. Note that - as with the GD perl module, only the version listed above, or - newer, will work. Earlier versions used GIF's, which are no - longer supported by the latest versions of GD. -

4.1.5.6. Chart::Base (optional)

The Chart module provides Bugzilla with on-the-fly charting + abilities. It can be installed in the usual fashion after it has been + fetched from CPAN. + Note that earlier versions that 0.99c used GIFs, which are no longer + supported by the latest versions of GD.

3.2.12. HTTP Server

4.1.6. HTTP Server

You have a freedom of choice here - Apache, Netscape or any - other server on UNIX would do. You can easily run the web - server on a different machine than MySQL, but need to adjust - the MySQL You have a freedom of choice here - Apache, Netscape or any other + server on UNIX would do. You can run the web server on a + different machine than MySQL, but need to adjust the MySQL + "bugs" user permissions accordingly. -

+ user permissions accordingly. +

I strongly recommend Apache as the web server to use. - The Bugzilla Guide installation instructions, in general, - assume you are using Apache. As more users use different - webservers and send me information on the peculiarities of - installing using their favorite webserver, I will provide - notes for them.

We strongly recommend Apache as the web server to use. The + Bugzilla Guide installation instructions, in general, assume you are + using Apache. If you have got Bugzilla working using another webserver, + please share your experiences with us.

-

You'll want to make sure that your web server will run any - file with the .cgi extension as a cgi and not just display it. - If you're using apache that means uncommenting the following - line in the srm.conf file: - You'll want to make sure that your web server will run any file + with the .cgi extension as a CGI and not just display it. If you're + using Apache that means uncommenting the following line in the httpd.conf + file: +

AddHandler cgi-script .cgi
-	
AddHandler cgi-script .cgi
-

With apache you'll also want to make sure that within the - access.conf file the line: - With Apache you'll also want to make sure that within the + httpd.conf file the line: +

Options ExecCGI
-AllowOverride Limit
-
Options ExecCGI AllowOverride Limit
- is in the stanza that covers the directories into which - you intend to put the bugzilla .html and .cgi files. -

AllowOverride Limit allows the use of a Deny statement in the - .htaccess file generated by checksetup.pl -

AllowOverride Limit allows the use of a Deny statement in the + .htaccess file generated by checksetup.pl

Users of newer versions of Apache will generally find both - of the above lines will be in the httpd.conf file, rather - than srm.conf or access.conf. -

Users of older versions of Apache may find the above lines + in the srm.conf and access.conf files, respecitvely.

+

There are important files and directories that should not - be a served by the HTTP server. These are most files in the - There are important files and directories that should not be a + served by the HTTP server - most files in the + "data" and + and + "shadow" directories - and the + directories and the + "localconfig" file. You should - configure your HTTP server to not serve content from these - files. Failure to do so will expose critical passwords and - other data. Please see + file. You should configure your HTTP server to not serve + these files. Failure to do so will expose critical passwords and + other data. Please see + .htaccess files and security for details - on how to do this for Apache. I appreciate notes on how to - get this same functionality using other webservers. -

+ for details on how to do this for Apache; the checksetup.pl + script should create appropriate .htaccess files for you.

3.2.13. Installing the Bugzilla Files

4.1.7. Bugzilla

You should untar the Bugzilla files into a directory that - you're willing to make writable by the default web server user - (probably You should untar the Bugzilla files into a directory that you're + willing to make writable by the default web server user (probably + "nobody"). You may decide to put the - files off of the main web space for your web server or perhaps - off of ). + You may decide to put the files in the main web space for your + web server or perhaps in + /usr/local with a symbolic link in - the web space that points to the Bugzilla directory. At any - rate, just dump all the files in the same place, and make sure - you can access the files in that directory through your web - server. -

+ with a symbolic link in the web space that points to the Bugzilla + directory.

If you symlink the bugzilla directory into your Apache's - HTML heirarchy, you may receive - If you symlink the bugzilla directory into your Apache's HTML + heirarchy, you may receive + Forbidden errors unless you add the - + errors unless you add the + "FollowSymLinks" directive to the - <Directory> entry for the HTML root. -

+ directive to the <Directory> entry for the HTML root + in httpd.conf.

Once all the files are in a web accessible directory, make - that directory writable by your webserver's user. This is a - temporary step until you run the post-install - Once all the files are in a web accessible directory, make that + directory writable by your webserver's user. This is a temporary step + until you run the post-install + checksetup.pl script, which locks down your - installation. -

+ script, which locks down your installation.

Lastly, you'll need to set up a symbolic link to - Lastly, you'll need to set up a symbolic link to + /usr/bonsaitools/bin/perl for the correct - location of your perl executable (probably - + for the correct location of your Perl executable (probably + /usr/bin/perl). Otherwise you must hack - all the .cgi files to change where they look for perl, or use - The setperl.csh Utility, found in - Useful Patches and Utilities for Bugzilla. I suggest using the symlink - approach for future release compatability. -

Example 3-1. Setting up bonsaitools symlink

Here's how you set up the Perl symlink on Linux to make - Bugzilla work. Your mileage may vary. For some UNIX - operating systems, you probably need to subsitute - "/usr/local/bin/perl" for - "/usr/bin/perl" below; if on certain other - UNIX systems, Perl may live in weird places like - "/opt/perl". As root, run these commands: -

bash# mkdir /usr/bonsaitools  
-bash# mkdir /usr/bonsaitools/bin 
-bash# ln -s /usr/bin/perl /usr/bonsaitools/bin/perl
-	    
-

). + Otherwise you must hack all the .cgi files to change where they look + for Perl. This can be done using the following Perl one-liner, but + I suggest using the symlink approach to avoid upgrade hassles. +

Alternately, you can simply run this perl one-liner to - change your path to perl in all the files in your Bugzilla - installation: - +

perl -pi -e 's@#\!/usr/bonsaitools/bin/perl@#\!/usr/bin/perl@' *cgi *pl Bug.pm
-processmail syncshadowdb
-	    
perl -pi -e + 's@#\!/usr/bonsaitools/bin/perl@#\!/usr/bin/perl@' *cgi *pl Bug.pm + processmail syncshadowdb
- Change the second path to perl to match your installation. -

-

If you don't have root access to set this symlink up, - check out the - The setperl.csh Utility, listed in Useful Patches and Utilities for Bugzilla. It will change the path to perl in all your Bugzilla files for you. -

-

/usr/bin/perl
to match the location + of Perl on your machine. +

3.2.14. Setting Up the MySQL Database

4.1.8. Setting Up the MySQL Database

After you've gotten all the software installed and working you're ready - to start preparing the database for its life as a the back end to a high - quality bug tracker. -

After you've gotten all the software installed and working you're + ready to start preparing the database for its life as the back end to + a high quality bug tracker.

First, you'll want to fix MySQL permissions to allow access - from Bugzilla. For the purpose of this Installation section, - the Bugzilla username will be First, you'll want to fix MySQL permissions to allow access from + Bugzilla. For the purpose of this Installation section, the Bugzilla + username will be + "bugs", and will - have minimal permissions. - -

Bugzilla has not undergone a thorough security audit. It - may be possible for a system cracker to somehow trick - Bugzilla into executing a command such as DROP - DATABASE mysql. -

That would be bad.

+>, and will have minimal permissions.

Give the MySQL root user a password. MySQL passwords are - limited to 16 characters. -

Begin by giving the MySQL root user a password. MySQL passwords are limited + to 16 characters. +

+ +
bash# + + mysql - -u root mysql mysql -u root mysql + -
mysql> + + UPDATE user SET Password=PASSWORD ('new_password') - WHERE user='root'; UPDATE user SET Password=PASSWORD('<new_password'>) + WHERE user='root'; -
mysql> + + FLUSH - PRIVILEGES; FLUSH PRIVILEGES; -

From this point on, if you need to access - MySQL as the MySQL root user, you will need to use - + + From this point on, if you need to access MySQL as the MySQL root user, + you will need to use + mysql -u root -p and enter your - new_password. Remember that MySQL user names have nothing to - do with Unix user names (login names). -

+ + and enter <new_password>. Remember that MySQL user names have + nothing to do with Unix user names (login names).

Next, we create the Next, we use an SQL GRANT command to create a + "bugs" user, and grant - sufficient permissions for checksetup.pl, which we'll use - later, to work its magic. This also restricts the - + + user, and grant sufficient permissions for checksetup.pl, which we'll + use later, to work its magic. This also restricts the + "bugs" user to operations within a database - called + user to operations within a database called + "bugs", and only allows the account to - connect from , and only allows the account to connect from + "localhost". Modify it to reflect - your setup if you will be connecting from another machine or - as a different user. -

. + Modify it to reflect your setup if you will be connecting from + another machine or as a different user.

Remember to set bugs_password to some unique password. -

Remember to set <bugs_password> to some unique password. +

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

4.1.9. checksetup.pl

Next, run the magic checksetup.pl script. (Many thanks to - Holger Schurig <holgerschurig@nikocity.de> for writing - this script!) It will make sure Bugzilla files and directories - have reasonable permissions, set up the - Next, run the magic checksetup.pl script. (Many thanks to + Holger Schurig + for writing this script!) + This script is designed to make sure your MySQL database and other + configuration options are consistent with the Bugzilla CGI files. + It will make sure Bugzilla files and directories have reasonable + permissions, set up the + data directory, and create all the MySQL - tables. -

+ directory, and create all the MySQL tables. +

+
bash# - ./checksetup.pl -

The first time you run it, it will create a - file called localconfig. -

3.2.15. Tweaking + + The first time you run it, it will create a file called + localconfig

.

This file contains a variety of settings you may need to tweak including - how Bugzilla should connect to the MySQL database. -

This file contains a variety of settings you may need to tweak + including how Bugzilla should connect to the MySQL database.

The connection settings include: -

The connection settings include: +

  1. server's host: just use server's host: just use + "localhost" if the - MySQL server is local -

    + if the MySQL server is local

  2. database name: database name: + "bugs" if you're following - these directions -

    + if you're following these directions

  3. MySQL username: MySQL username: + "bugs" if you're following - these directions -

    + if you're following these directions

  4. Password for the Password for the + "bugs" MySQL account above -

    + MySQL account; (<bugs_password>) above

You should also install .htaccess files that the Apache - webserver will use to restrict access to Bugzilla data files. - See .htaccess files and security. -

Once you are happy with the settings, re-run - Once you are happy with the settings, + checksetup.pl. On this second run, it will - create the database and an administrator account for which - you will be prompted to provide information. -

When logged into an administrator account once Bugzilla is - running, if you go to the query page (off of the Bugzilla main - menu), you'll find an "edit parameters" option - that is filled with editable treats. -

Should everything work, you will have a nearly empty Bugzilla - database and a newly-created su to the user + your web server runs as, and re-run + localconfig - file in your Bugzilla root directory. -

The second time you run checksetup.pl, you should become - the user your web server runs as, and that you ensure that - you set the "webservergroup" parameter in localconfig to - match the web server's group name, if any. I believe, - for the next release of Bugzilla, this will be fixed so - that Bugzilla supports a "webserveruser" parameter in - localconfig as well. -

-

-

checksetup.pl
. (Note: on some security-conscious + systems, you may need to change the login shell for the webserver + account before you can do this.) + On this second run, it will create the database and an administrator + account for which you will be prompted to provide information.

The checksetup.pl script is designed so that you can run - it at any time without causing harm. You should run it - after any upgrade to Bugzilla. -

3.2.17. The Whining Cron (Optional)

By now you have a fully functional bugzilla, but what good - are bugs if they're not annoying? To help make those bugs - more annoying you can set up bugzilla's automatic whining - system. This can be done by adding the following command as a - daily crontab entry (for help on that see that crontab man - page): -

cd - <your-bugzilla-directory> ; - ./whineatnews.pl -

-

Depending on your system, crontab may have several manpages. - The following command should lead you to the most useful - page for this purpose: -

 man 5 crontab
-	  
-

The checksetup.pl script is designed so that you can run it at + any time without causing harm. You should run it after any upgrade to + Bugzilla.

3.2.18. Bug Graphs (Optional)

4.1.10. Securing MySQL

As long as you installed the GD and Graph::Base Perl modules - you might as well turn on the nifty bugzilla bug reporting - graphs. -

If you followed the installation instructions for setting up your + "bugs" and "root" user in MySQL, much of this should not apply to you. + If you are upgrading an existing installation of Bugzilla, you should + pay close attention to this section.

Add a cron entry like this to run collectstats daily at 5 - after midnight: -

bash# crontab - -e -
5 0 * * * cd - <your-bugzilla-directory> ; ./collectstats.pl - -

-

After two days have passed you'll be able to view bug graphs - from the Bug Reports page. -

3.2.19. Securing MySQL

If you followed the installation instructions for setting up - your "bugs" and "root" user in MySQL, much of this should not - apply to you. If you are upgrading an existing installation - of Bugzilla, you should pay close attention to this section. -

Most MySQL installs have "interesting" default security parameters: -

Most MySQL installs have "interesting" default security + parameters: +

This means anyone from anywhere on the internet can not only - drop the database with one SQL command, and they can write as - root to the system. -

This means anyone from anywhere on the internet can not only drop + the database with one SQL command, and they can write as root to the + system.

To see your permissions do: -

To see your permissions do: +

bash# - mysql -u root -p - -
mysql> - use mysql; - -
mysql> - show tables; - -
mysql> - select * from user; - -
mysql> - select * from db; - -

To fix the gaping holes: -

To fix the gaping holes: +

UPDATE user SET Password=PASSWORD('new_password') WHERE + user='root';FLUSH PRIVILEGES;
UPDATE user SET Password=PASSWORD('new_password') WHERE user='root';
FLUSH PRIVILEGES;

If you're not running "mit-pthreads" you can use: -

If you're not running "mit-pthreads" you can use: +

With "mit-pthreads" you'll need to modify the "globals.pl" Mysql->Connect - line to specify a specific host name instead of "localhost", and accept - external connections: -

With "mit-pthreads" you'll need to modify the "globals.pl" + Mysql->Connect line to specify a specific host name instead of + "localhost", and accept external connections: +

Use .htaccess files with the Apache webserver to secure your - bugzilla install. See .htaccess files and security -

Consider also: -

Consider also: +

  1. Turning off external networking with "--skip-networking", - unless you have "mit-pthreads", in which case you can't. - Without networking, MySQL connects with a Unix domain socket. -

    Turning off external networking with "--skip-networking", + unless you have "mit-pthreads", in which case you can't. Without + networking, MySQL connects with a Unix domain socket.

  2. using the --user= option to mysqld to run it as an unprivileged - user. -

    using the --user= option to mysqld to run it as an + unprivileged user.

  3. starting MySQL in a chroot jail -

    running MySQL in a chroot jail

  4. running the httpd in a "chrooted" jail -

    running the httpd in a chroot jail

  5. making sure the MySQL passwords are different from the OS - passwords (MySQL "root" has nothing to do with system "root"). -

    making sure the MySQL passwords are different from the OS + passwords (MySQL "root" has nothing to do with system + "root").

  6. running MySQL on a separate untrusted machine -

    running MySQL on a separate untrusted machine

  7. making backups ;-) -

    making backups ;-)

Optional Additional Configuration
Mac OS X Installation Notes