summaryrefslogtreecommitdiffstats
path: root/docs/html/stepbystep.html
diff options
context:
space:
mode:
Diffstat (limited to 'docs/html/stepbystep.html')
-rw-r--r--docs/html/stepbystep.html1952
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 &#60;Directory&#62; 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&#62;</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&#62;</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&#62;</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&#62;
+ </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 &#60;holgerschurig@nikocity.de&#62; 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&#62;</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
+ &#60;your-bugzilla-directory&#62; ;
+ ./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
+ &#60;your-bugzilla-directory&#62; ; ./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&#62;</TT
+>
+ <B
+CLASS="COMMAND"
+>use mysql;</B
+>
+ </TT
+>
+ </TD
+></TR
+><TR
+><TD
+> <TT
+CLASS="COMPUTEROUTPUT"
+> <TT
+CLASS="PROMPT"
+>mysql&#62;</TT
+>
+ <B
+CLASS="COMMAND"
+>show tables;</B
+>
+ </TT
+>
+ </TD
+></TR
+><TR
+><TD
+> <TT
+CLASS="COMPUTEROUTPUT"
+> <TT
+CLASS="PROMPT"
+>mysql&#62;</TT
+>
+ <B
+CLASS="COMMAND"
+>select * from user;</B
+>
+ </TT
+>
+ </TD
+></TR
+><TR
+><TD
+> <TT
+CLASS="COMPUTEROUTPUT"
+> <TT
+CLASS="PROMPT"
+>mysql&#62;</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-&#62;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