diff options
Diffstat (limited to 'docs/html/stepbystep.html')
| -rw-r--r-- | docs/html/stepbystep.html | 1952 |
1 files changed, 1952 insertions, 0 deletions
diff --git a/docs/html/stepbystep.html b/docs/html/stepbystep.html new file mode 100644 index 000000000..4cbac778a --- /dev/null +++ b/docs/html/stepbystep.html @@ -0,0 +1,1952 @@ +<HTML +><HEAD +><TITLE +>Step-by-step Install</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.61 +"><LINK +REL="HOME" +TITLE="The Bugzilla Guide" +HREF="index.html"><LINK +REL="UP" +TITLE="Installation" +HREF="installation.html"><LINK +REL="PREVIOUS" +TITLE="ERRATA" +HREF="errata.html"><LINK +REL="NEXT" +TITLE="Mac OS X Installation Notes" +HREF="osx.html"></HEAD +><BODY +CLASS="SECTION" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>The Bugzilla Guide</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="errata.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 3. Installation</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="osx.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="STEPBYSTEP" +>3.2. Step-by-step Install</A +></H1 +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN478" +>3.2.1. Introduction</A +></H2 +><P +> 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. + </P +><P +> 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 <A +HREF="win32.html" +>Win32 Installation Notes</A +> for further advice + on getting Bugzilla to work on Microsoft Windows. + </P +><P +> 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). + </P +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN484" +>3.2.2. Installing the Prerequisites</A +></H2 +><DIV +CLASS="NOTE" +><P +></P +><TABLE +CLASS="NOTE" +WIDTH="100%" +BORDER="0" +><TR +><TD +WIDTH="25" +ALIGN="CENTER" +VALIGN="TOP" +><IMG +SRC="../images/note.gif" +HSPACE="5" +ALT="Note"></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +><P +>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 <A +HREF="stepbystep.html#BUNDLEBUGZILLA" +>Using Bundle::Bugzilla instead of manually installing Perl modules</A +></P +></TD +></TR +></TABLE +></DIV +><P +> The software packages necessary for the proper running of bugzilla are: + <P +></P +><OL +TYPE="1" +><LI +><P +> MySQL database server and the mysql client (3.22.5 or greater) + </P +></LI +><LI +><P +> Perl (5.004 or greater, 5.6.1 is recommended if you wish + to use Bundle::Bugzilla) + </P +></LI +><LI +><P +> DBI Perl module + </P +></LI +><LI +><P +> Data::Dumper Perl module + </P +></LI +><LI +><P +> Bundle::Mysql Perl module collection + </P +></LI +><LI +><P +> TimeDate Perl module collection + </P +></LI +><LI +><P +> GD perl module (1.8.3) (optional, for bug charting) + </P +></LI +><LI +><P +> Chart::Base Perl module (0.99c) (optional, for bug charting) + </P +></LI +><LI +><P +> DB_File Perl module (optional, for bug charting) + </P +></LI +><LI +><P +> The web server of your choice. Apache is recommended. + </P +></LI +><LI +><P +> MIME::Parser Perl module (optional, for contrib/bug_email.pl interface) + </P +></LI +></OL +> + + <DIV +CLASS="WARNING" +><P +></P +><TABLE +CLASS="WARNING" +WIDTH="100%" +BORDER="0" +><TR +><TD +WIDTH="25" +ALIGN="CENTER" +VALIGN="TOP" +><IMG +SRC="../images/warning.gif" +HSPACE="5" +ALT="Warning"></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +><P +> It is a good idea, while installing Bugzilla, to ensure it + is not <EM +>accessible</EM +> 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. + </P +></TD +></TR +></TABLE +></DIV +> + + </P +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="INSTALL-MYSQL" +>3.2.3. Installing MySQL Database</A +></H2 +><P +> Visit MySQL homepage at http://www.mysql.com/ and grab the + latest stable release of the server. Both binaries and source + are available and which you get shouldn't matter. Be aware + that many of the binary versions of MySQL store their data + files in /var which on many installations (particularly common + with linux installations) is part of a smaller root partition. + If you decide to build from sources you can easily set the + dataDir as an option to configure. + </P +><P +> If you've installed from source or non-package (RPM, deb, + etc.) binaries you'll want to make sure to add mysqld to your + init scripts so the server daemon will come back up whenever + your machine reboots. You also may want to edit those init + scripts, to make sure that mysqld will accept large packets. + By default, mysqld is set up to only accept packets up to 64K + long. This limits the size of attachments you may put on + bugs. If you add something like "-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. + </P +><DIV +CLASS="NOTE" +><P +></P +><TABLE +CLASS="NOTE" +WIDTH="100%" +BORDER="0" +><TR +><TD +WIDTH="25" +ALIGN="CENTER" +VALIGN="TOP" +><IMG +SRC="../images/note.gif" +HSPACE="5" +ALT="Note"></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +><P +> 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. + </P +></TD +></TR +></TABLE +></DIV +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="INSTALL-PERL" +>3.2.4. Perl (5.004 or greater)</A +></H2 +><P +> 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. + </P +><P +> 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. + </P +><DIV +CLASS="WARNING" +><P +></P +><TABLE +CLASS="WARNING" +WIDTH="100%" +BORDER="0" +><TR +><TD +WIDTH="25" +ALIGN="CENTER" +VALIGN="TOP" +><IMG +SRC="../images/warning.gif" +HSPACE="5" +ALT="Warning"></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +><P +>Many people complain that Perl modules will not install + for them. Most times, the error messages complain that they + are missing a file in <SPAN +CLASS="QUOTE" +>"@INC"</SPAN +>. 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 + <EM +>are</EM +> the local UNIX sysadmin, please + consult the newsgroup/mailing list for further assistance or + hire someone to help you out. + </P +></TD +></TR +></TABLE +></DIV +><DIV +CLASS="TIP" +><A +NAME="BUNDLEBUGZILLA" +></A +><P +></P +><TABLE +CLASS="TIP" +WIDTH="100%" +BORDER="0" +><TR +><TD +WIDTH="25" +ALIGN="CENTER" +VALIGN="TOP" +><IMG +SRC="../images/tip.gif" +HSPACE="5" +ALT="Tip"></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +><P +> You can skip the following Perl module installation steps by + installing "Bundle::Bugzilla" 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) + </P +><P +> <TT +CLASS="COMPUTEROUTPUT" +> <TT +CLASS="PROMPT" +>bash#</TT +> <B +CLASS="COMMAND" +>perl -MCPAN + -e 'install "Bundle::Bugzilla"'</B +> + </TT +> + </P +><P +> 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. + </P +></TD +></TR +></TABLE +></DIV +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN537" +>3.2.5. DBI Perl Module</A +></H2 +><P +> 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. + </P +><P +> 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 (02/17/99) can be found in Appendix A. + </P +><P +> 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. + </P +><P +> To use the CPAN shell to install DBI: + <DIV +CLASS="INFORMALEXAMPLE" +><A +NAME="AEN543" +></A +><P +></P +><P +> <TT +CLASS="COMPUTEROUTPUT" +> <TT +CLASS="PROMPT" +>bash#</TT +> + <B +CLASS="COMMAND" +>perl -MCPAN -e 'install "DBI"'</B +> + </TT +> + <DIV +CLASS="NOTE" +><P +></P +><TABLE +CLASS="NOTE" +WIDTH="100%" +BORDER="0" +><TR +><TD +WIDTH="25" +ALIGN="CENTER" +VALIGN="TOP" +><IMG +SRC="../images/note.gif" +HSPACE="5" +ALT="Note"></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +><P +>Replace "DBI" with the name of whichever module you wish + to install, such as Data::Dumper, TimeDate, GD, etc.</P +></TD +></TR +></TABLE +></DIV +> + </P +><P +></P +></DIV +> + To do it the hard way: + <DIV +CLASS="INFORMALEXAMPLE" +><A +NAME="AEN550" +></A +><P +></P +><P +> Untar the module tarball -- it should create its own directory + </P +><P +> CD to the directory just created, and enter the following commands: + <P +></P +><OL +TYPE="1" +><LI +><P +> <TT +CLASS="COMPUTEROUTPUT" +> <TT +CLASS="PROMPT" +>bash#</TT +> + <B +CLASS="COMMAND" +>perl Makefile.PL</B +> + </TT +> + </P +></LI +><LI +><P +> <TT +CLASS="COMPUTEROUTPUT" +> <TT +CLASS="PROMPT" +>bash#</TT +> + <B +CLASS="COMMAND" +>make</B +> + </TT +> + </P +></LI +><LI +><P +> <TT +CLASS="COMPUTEROUTPUT" +> <TT +CLASS="PROMPT" +>bash#</TT +> + <B +CLASS="COMMAND" +>make test</B +> + </TT +> + </P +></LI +><LI +><P +> <TT +CLASS="COMPUTEROUTPUT" +> <TT +CLASS="PROMPT" +>bash#</TT +> + <B +CLASS="COMMAND" +>make install</B +> + </TT +> + </P +></LI +></OL +> + If everything went ok that should be all it takes. For the vast + majority of perl modules this is all that's required. + </P +><P +></P +></DIV +> + </P +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN574" +>3.2.6. Data::Dumper Perl Module</A +></H2 +><P +> 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. + </P +><P +> Data::Dumper is used by the MySQL-related Perl modules. It can be + found on CPAN (link in Appendix A) and can be installed by following + the same four step make sequence used for the DBI module. + </P +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN578" +>3.2.7. MySQL related Perl Module Collection</A +></H2 +><P +> The Perl/MySQL interface requires a few mutually-dependent perl + modules. These modules are grouped together into the the + Msql-Mysql-modules package. This package can be found at CPAN. + After the archive file has been downloaded it should + be untarred. + </P +><P +> The MySQL modules are all built using one make file which is generated + by running: + <TT +CLASS="PROMPT" +>bash#</TT +> + <B +CLASS="COMMAND" +>perl Makefile.pl</B +> + </P +><P +> 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. + </P +><P +> 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. + </P +><P +> 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. + </P +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN587" +>3.2.8. TimeDate Perl Module Collection</A +></H2 +><P +> 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. A link + link may be found in Appendix B, Software Download Links. + 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. + </P +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN590" +>3.2.9. GD Perl Module (1.8.3)</A +></H2 +><P +> The GD library was written by Thomas Boutell a long while ago to + programatically generate images in C. Since then it's become almost a + defacto standard for programatic image construction. The Perl bindings + to it found in the GD library are used on a million web pages to generate + graphs on the fly. That's what bugzilla will be using it for so you'd + better install it if you want any of the graphing to work. + </P +><P +> Actually bugzilla uses the Graph module which relies on GD itself, + but isn't that always the way with OOP. At any rate, you can find the + GD library on CPAN (link in Appendix B, Software Download Links). + </P +><DIV +CLASS="NOTE" +><P +></P +><TABLE +CLASS="NOTE" +WIDTH="100%" +BORDER="0" +><TR +><TD +WIDTH="25" +ALIGN="CENTER" +VALIGN="TOP" +><IMG +SRC="../images/note.gif" +HSPACE="5" +ALT="Note"></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +><P +> The Perl GD library requires some other libraries that may or may not be + installed on your system, including "libpng" 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. + </P +></TD +></TR +></TABLE +></DIV +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN596" +>3.2.10. Chart::Base Perl Module (0.99c)</A +></H2 +><P +> 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 in a + directory to be listed in Appendix B, "Software Download Links". + 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. + </P +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN599" +>3.2.11. DB_File Perl Module</A +></H2 +><P +> DB_File is a module which allows Perl programs to make use of the facilities provided by + Berkeley DB version 1.x. This module is required by collectstats.pl which is used for + bug charting. If you plan to make use of bug charting, you must install this module. + </P +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN602" +>3.2.12. HTTP Server</A +></H2 +><P +> 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 "bugs" user permissions + accordingly. + </P +><P +> 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: + <TT +CLASS="COMPUTEROUTPUT" +>AddHandler cgi-script .cgi</TT +> + </P +><P +> With apache you'll also want to make sure that within the access.conf + file the line: + <TT +CLASS="COMPUTEROUTPUT" +> Options ExecCGI + </TT +> + is in the stanza that covers the directories you intend to put the bugzilla + .html and .cgi files into. + </P +><P +> If you are using a newer version of Apache, both of the above lines will be + (or will need to be) in the httpd.conf file, rather than srm.conf or + access.conf. + </P +><DIV +CLASS="WARNING" +><P +></P +><TABLE +CLASS="WARNING" +WIDTH="100%" +BORDER="0" +><TR +><TD +WIDTH="25" +ALIGN="CENTER" +VALIGN="TOP" +><IMG +SRC="../images/warning.gif" +HSPACE="5" +ALT="Warning"></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +><P +> There are two critical directories and a file that should not be a served by + the HTTP server. These are the <SPAN +CLASS="QUOTE" +>"data"</SPAN +> and <SPAN +CLASS="QUOTE" +>"shadow"</SPAN +> + directories and the + <SPAN +CLASS="QUOTE" +>"localconfig"</SPAN +> 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 <A +HREF="geninstall.html#HTACCESS" +>.htaccess files and security</A +> for details. + </P +></TD +></TR +></TABLE +></DIV +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN616" +>3.2.13. Installing the Bugzilla Files</A +></H2 +><P +> You should untar the Bugzilla files into a directory that you're + willing to make writable by the default web server user (probably + <SPAN +CLASS="QUOTE" +>"nobody"</SPAN +>). You may decide to put the files off of the main web space + for your web server or perhaps off of /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 (optionally omitting the CVS + directories if they were accidentally tarred up with the rest of Bugzilla) + and make sure you can access the files in that directory through your + web server. + </P +><DIV +CLASS="TIP" +><P +></P +><TABLE +CLASS="TIP" +WIDTH="100%" +BORDER="0" +><TR +><TD +WIDTH="25" +ALIGN="CENTER" +VALIGN="TOP" +><IMG +SRC="../images/tip.gif" +HSPACE="5" +ALT="Tip"></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +><P +> If you symlink the bugzilla directory into your Apache's + HTML heirarchy, you may receive "Forbidden" errors unless you + add the "FollowSymLinks" directive to the <Directory> entry + for the HTML root. + </P +></TD +></TR +></TABLE +></DIV +><P +> Once all the files are in a web accessible directory, make that + directory writable by your webserver's user (which may require just + making it world writable). This is a temporary step until you run + the post-install <SPAN +CLASS="QUOTE" +>"checksetup.pl"</SPAN +> script, which locks down your + installation. + </P +><P +> Lastly, you'll need to set up a symbolic link to /usr/bonsaitools/bin/perl + 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. To make future upgrades easier, you should use the symlink + approach. + <DIV +CLASS="EXAMPLE" +><A +NAME="AEN625" +></A +><P +><B +>Example 3-1. Setting up bonsaitools symlink</B +></P +><P +> Here's how you set up the Perl symlink on Linux to make Bugzilla work. + Your mileage may vary; if you are running on Solaris, you probably need to subsitute + <SPAN +CLASS="QUOTE" +>"/usr/local/bin/perl"</SPAN +> for <SPAN +CLASS="QUOTE" +>"/usr/bin/perl"</SPAN +> + below; if on certain other UNIX systems, + Perl may live in weird places like <SPAN +CLASS="QUOTE" +>"/opt/perl"</SPAN +>. As root, run these commands: + <TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><FONT +COLOR="#000000" +><PRE +CLASS="PROGRAMLISTING" +>bash# mkdir /usr/bonsaitools +bash# mkdir /usr/bonsaitools/bin +bash# ln -s /usr/bin/perl /usr/bosaitools/bin/perl + </PRE +></FONT +></TD +></TR +></TABLE +> + </P +></DIV +> + <DIV +CLASS="TIP" +><P +></P +><TABLE +CLASS="TIP" +WIDTH="100%" +BORDER="0" +><TR +><TD +WIDTH="25" +ALIGN="CENTER" +VALIGN="TOP" +><IMG +SRC="../images/tip.gif" +HSPACE="5" +ALT="Tip"></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +><P +> If you don't have root access to set this symlink up, + check out the + <A +HREF="setperl.html" +>The setperl.csh Utility</A +>, listed in <A +HREF="patches.html" +>Useful Patches and Utilities for Bugzilla</A +>. + It will change the path to perl in all your Bugzilla files for you. + </P +></TD +></TR +></TABLE +></DIV +> + </P +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN636" +>3.2.14. Setting Up the MySQL Database</A +></H2 +><P +> 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. + </P +><P +> 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. + + <DIV +CLASS="WARNING" +><P +></P +><TABLE +CLASS="WARNING" +WIDTH="100%" +BORDER="0" +><TR +><TD +WIDTH="25" +ALIGN="CENTER" +VALIGN="TOP" +><IMG +SRC="../images/warning.gif" +HSPACE="5" +ALT="Warning"></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +><P +> 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 <B +CLASS="COMMAND" +>DROP + DATABASE mysql</B +>. + </P +><P +>That would be bad.</P +></TD +></TR +></TABLE +></DIV +> + </P +><P +> Give the MySQL root user a password. MySQL passwords are + limited to 16 characters. + <P +></P +><TABLE +BORDER="0" +><TBODY +><TR +><TD +> <TT +CLASS="COMPUTEROUTPUT" +> <TT +CLASS="PROMPT" +>bash#</TT +> + <B +CLASS="COMMAND" +>mysql -u root mysql</B +> + </TT +> + </TD +></TR +><TR +><TD +> <TT +CLASS="COMPUTEROUTPUT" +> <TT +CLASS="PROMPT" +>mysql></TT +> + <B +CLASS="COMMAND" +> UPDATE user SET Password=PASSWORD ('new_password') + WHERE user='root'; + </B +> + </TT +> + </TD +></TR +><TR +><TD +> <TT +CLASS="COMPUTEROUTPUT" +> <TT +CLASS="PROMPT" +>mysql></TT +> + <B +CLASS="COMMAND" +>FLUSH PRIVILEGES;</B +> + </TT +> + </TD +></TR +></TBODY +></TABLE +><P +></P +> + 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). + </P +><P +> Next, we create the "bugs" 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 "bugs", 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. + </P +><P +> Remember to set bugs_password to some unique password. + <P +></P +><TABLE +BORDER="0" +><TBODY +><TR +><TD +> <TT +CLASS="COMPUTEROUTPUT" +> <TT +CLASS="PROMPT" +>mysql></TT +> + <B +CLASS="COMMAND" +>GRANT SELECT,INSERT,UPDATE,DELETE,INDEX, + ALTER,CREATE,DROP,REFERENCES + ON bugs.* TO bugs@localhost + IDENTIFIED BY 'bugs_password';</B +> + </TT +> + </TD +></TR +><TR +><TD +> <TT +CLASS="COMPUTEROUTPUT" +> <TT +CLASS="PROMPT" +> mysql> + </TT +> + <B +CLASS="COMMAND" +> FLUSH PRIVILEGES; + </B +> + </TT +> + </TD +></TR +></TBODY +></TABLE +><P +></P +> + </P +><P +> 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 "data" directory, and create all the MySQL + tables. + <P +></P +><TABLE +BORDER="0" +><TBODY +><TR +><TD +> <TT +CLASS="COMPUTEROUTPUT" +> <TT +CLASS="PROMPT" +>bash#</TT +> + <B +CLASS="COMMAND" +>./checksetup.pl</B +> + </TT +> + </TD +></TR +></TBODY +></TABLE +><P +></P +> + The first time you run it, it will create a file called "localconfig". + </P +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN675" +>3.2.15. Tweaking "localconfig"</A +></H2 +><P +> This file contains a variety of settings you may need to tweak including + how Bugzilla should connect to the MySQL database. + </P +><P +> The connection settings include: + <P +></P +><OL +TYPE="1" +><LI +><P +> server's host: just use "localhost" if the MySQL server is + local + </P +></LI +><LI +><P +> database name: "bugs" if you're following these directions + </P +></LI +><LI +><P +> MySQL username: "bugs" if you're following these directions + </P +></LI +><LI +><P +> Password for the "bugs" MySQL account above + </P +></LI +></OL +> + </P +><P +> You may also install .htaccess files that the Apache webserver will use + to restrict access to Bugzilla data files. See <A +HREF="geninstall.html#HTACCESS" +>.htaccess files and security</A +>. + </P +><P +> Once you are happy with the settings, re-run checksetup.pl. On this + second run, it will create the database and an administrator account + for which you will be prompted to provide information. + </P +><P +> 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. + </P +><P +> Should everything work, you should have a nearly empty copy of the bug + tracking setup. + </P +><P +> The second time around, checksetup.pl will stall if it is on a + filesystem that does not fully support file locking via flock(), such as + NFS mounts. This support is required for Bugzilla to operate safely with + multiple instances. If flock() is not fully supported, it will stall at: + <SPAN +CLASS="ERRORCODE" +>Now regenerating the shadow database for all bugs.</SPAN +> + <DIV +CLASS="NOTE" +><P +></P +><TABLE +CLASS="NOTE" +WIDTH="100%" +BORDER="0" +><TR +><TD +WIDTH="25" +ALIGN="CENTER" +VALIGN="TOP" +><IMG +SRC="../images/note.gif" +HSPACE="5" +ALT="Note"></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +><P +> 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. + <DIV +CLASS="EXAMPLE" +><A +NAME="AEN697" +></A +><P +><B +>Example 3-2. Running checksetup.pl as the web user</B +></P +><P +> Assuming your web server runs as user "apache", + and Bugzilla is installed in + "/usr/local/bugzilla", here's one way to run checksetup.pl + as the web server user. + As root, for the <EM +>second run</EM +> + of checksetup.pl, do this: + <TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><FONT +COLOR="#000000" +><PRE +CLASS="PROGRAMLISTING" +>bash# chown -R apache:apache /usr/local/bugzilla +bash# su - apache +bash# cd /usr/local/bugzilla +bash# ./checksetup.pl + </PRE +></FONT +></TD +></TR +></TABLE +> + </P +></DIV +> + </P +></TD +></TR +></TABLE +></DIV +> + </P +><DIV +CLASS="NOTE" +><P +></P +><TABLE +CLASS="NOTE" +WIDTH="100%" +BORDER="0" +><TR +><TD +WIDTH="25" +ALIGN="CENTER" +VALIGN="TOP" +><IMG +SRC="../images/note.gif" +HSPACE="5" +ALT="Note"></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +><P +> 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. + </P +></TD +></TR +></TABLE +></DIV +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN704" +>3.2.16. Setting Up Maintainers Manually (Optional)</A +></H2 +><P +> If you want to add someone else to every group by hand, you + can do it by typing the appropriate MySQL commands. Run + '<TT +CLASS="COMPUTEROUTPUT" +> mysql -u root -p bugs</TT +>' You + may need different parameters, depending on your security + settings. Then: + <P +></P +><TABLE +BORDER="0" +><TBODY +><TR +><TD +> <TT +CLASS="COMPUTEROUTPUT" +> <TT +CLASS="PROMPT" +>mysql></TT +> <B +CLASS="COMMAND" +>update + profiles set groupset=0x7fffffffffffffff where + login_name = 'XXX';</B +> </TT +> + </TD +></TR +></TBODY +></TABLE +><P +></P +> replacing XXX with the Bugzilla email address. + </P +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN713" +>3.2.17. The Whining Cron (Optional)</A +></H2 +><P +> 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): + <P +></P +><TABLE +BORDER="0" +><TBODY +><TR +><TD +> <TT +CLASS="COMPUTEROUTPUT" +> <B +CLASS="COMMAND" +>cd + <your-bugzilla-directory> ; + ./whineatnews.pl</B +> </TT +> + </TD +></TR +></TBODY +></TABLE +><P +></P +> + </P +><DIV +CLASS="TIP" +><P +></P +><TABLE +CLASS="TIP" +WIDTH="100%" +BORDER="0" +><TR +><TD +WIDTH="25" +ALIGN="CENTER" +VALIGN="TOP" +><IMG +SRC="../images/tip.gif" +HSPACE="5" +ALT="Tip"></TD +><TD +ALIGN="LEFT" +VALIGN="TOP" +><P +> Depending on your system, crontab may have several manpages. + The following command should lead you to the most useful + page for this purpose: + <TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><FONT +COLOR="#000000" +><PRE +CLASS="PROGRAMLISTING" +> man 5 crontab + </PRE +></FONT +></TD +></TR +></TABLE +> + </P +></TD +></TR +></TABLE +></DIV +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN723" +>3.2.18. Bug Graphs (Optional)</A +></H2 +><P +> As long as you installed the GD and Graph::Base Perl modules + you might as well turn on the nifty bugzilla bug reporting + graphs. + </P +><P +> Add a cron entry like this to run collectstats daily at 5 + after midnight: + <P +></P +><TABLE +BORDER="0" +><TBODY +><TR +><TD +> <TT +CLASS="COMPUTEROUTPUT" +> <TT +CLASS="PROMPT" +>bash#</TT +> <B +CLASS="COMMAND" +>crontab + -e</B +> </TT +> + </TD +></TR +><TR +><TD +> <TT +CLASS="COMPUTEROUTPUT" +> 5 0 * * * cd + <your-bugzilla-directory> ; ./collectstats.pl + </TT +> + </TD +></TR +></TBODY +></TABLE +><P +></P +> + </P +><P +> After two days have passed you'll be able to view bug graphs + from the Bug Reports page. + </P +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="AEN735" +>3.2.19. Securing MySQL</A +></H2 +><P +> 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. + </P +><P +> Most MySQL installs have "interesting" default security parameters: + <P +></P +><TABLE +BORDER="0" +><TBODY +><TR +><TD +>mysqld defaults to running as root</TD +></TR +><TR +><TD +>it defaults to allowing external network connections</TD +></TR +><TR +><TD +>it has a known port number, and is easy to detect</TD +></TR +><TR +><TD +>it defaults to no passwords whatsoever</TD +></TR +><TR +><TD +>it defaults to allowing "File_Priv"</TD +></TR +></TBODY +></TABLE +><P +></P +> + </P +><P +> 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. + </P +><P +> To see your permissions do: + <P +></P +><TABLE +BORDER="0" +><TBODY +><TR +><TD +> <TT +CLASS="COMPUTEROUTPUT" +> <TT +CLASS="PROMPT" +>bash#</TT +> + <B +CLASS="COMMAND" +>mysql -u root -p</B +> + </TT +> + </TD +></TR +><TR +><TD +> <TT +CLASS="COMPUTEROUTPUT" +> <TT +CLASS="PROMPT" +>mysql></TT +> + <B +CLASS="COMMAND" +>use mysql;</B +> + </TT +> + </TD +></TR +><TR +><TD +> <TT +CLASS="COMPUTEROUTPUT" +> <TT +CLASS="PROMPT" +>mysql></TT +> + <B +CLASS="COMMAND" +>show tables;</B +> + </TT +> + </TD +></TR +><TR +><TD +> <TT +CLASS="COMPUTEROUTPUT" +> <TT +CLASS="PROMPT" +>mysql></TT +> + <B +CLASS="COMMAND" +>select * from user;</B +> + </TT +> + </TD +></TR +><TR +><TD +> <TT +CLASS="COMPUTEROUTPUT" +> <TT +CLASS="PROMPT" +>mysql></TT +> + <B +CLASS="COMMAND" +>select * from db;</B +> + </TT +> + </TD +></TR +></TBODY +></TABLE +><P +></P +> + </P +><P +> To fix the gaping holes: + <P +></P +><TABLE +BORDER="0" +><TBODY +><TR +><TD +>DELETE FROM user WHERE User='';</TD +></TR +><TR +><TD +>UPDATE user SET Password=PASSWORD('new_password') WHERE user='root';</TD +></TR +><TR +><TD +> FLUSH PRIVILEGES;</TD +></TR +></TBODY +></TABLE +><P +></P +> + </P +><P +> If you're not running "mit-pthreads" you can use: + <P +></P +><TABLE +BORDER="0" +><TBODY +><TR +><TD +>GRANT USAGE ON *.* TO bugs@localhost;</TD +></TR +><TR +><TD +>GRANT ALL ON bugs.* TO bugs@localhost;</TD +></TR +><TR +><TD +>REVOKE DROP ON bugs.* FROM bugs@localhost;</TD +></TR +><TR +><TD +>FLUSH PRIVILEGES;</TD +></TR +></TBODY +></TABLE +><P +></P +> + </P +><P +> 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: + <P +></P +><TABLE +BORDER="0" +><TBODY +><TR +><TD +>GRANT USAGE ON *.* TO bugs@bounce.hop.com;</TD +></TR +><TR +><TD +>GRANT ALL ON bugs.* TO bugs@bounce.hop.com;</TD +></TR +><TR +><TD +>REVOKE DROP ON bugs.* FROM bugs@bounce.hop.com;</TD +></TR +><TR +><TD +>FLUSH PRIVILEGES;</TD +></TR +></TBODY +></TABLE +><P +></P +> + </P +><P +> Use .htaccess files with the Apache webserver to secure your + bugzilla install. See <A +HREF="geninstall.html#HTACCESS" +>.htaccess files and security</A +> + </P +><P +> Consider also: + <P +></P +><OL +TYPE="1" +><LI +><P +> 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. + </P +></LI +><LI +><P +> using the --user= option to mysqld to run it as an unprivileged + user. + </P +></LI +><LI +><P +> starting MySQL in a chroot jail + </P +></LI +><LI +><P +> running the httpd in a "chrooted" jail + </P +></LI +><LI +><P +> making sure the MySQL passwords are different from the OS + passwords (MySQL "root" has nothing to do with system "root"). + </P +></LI +><LI +><P +> running MySQL on a separate untrusted machine + </P +></LI +><LI +><P +> making backups ;-) + </P +></LI +></OL +> + </P +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="errata.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="osx.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>ERRATA</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="installation.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Mac OS X Installation Notes</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file |