summaryrefslogtreecommitdiffstats
path: root/docs/xml/installation.xml
diff options
context:
space:
mode:
Diffstat (limited to 'docs/xml/installation.xml')
-rw-r--r--docs/xml/installation.xml1025
1 files changed, 1000 insertions, 25 deletions
diff --git a/docs/xml/installation.xml b/docs/xml/installation.xml
index f29ba953d..03ff0bd8d 100644
--- a/docs/xml/installation.xml
+++ b/docs/xml/installation.xml
@@ -5,31 +5,941 @@
<SECTION id="README.unix">
<TITLE>UNIX Installation</TITLE>
- <NOTE>
- <PARA>
- Please consult the README included with the Bugzilla distribution
- as the current canonical source for UNIX installation instructions.
- We do, however, have some installation notes for errata from the README.
- </PARA>
- </NOTE>
-
- <NOTE>
- <PARA>
- If you are installing Bugzilla on S.u.S.e. Linux, or some other
- distributions with "paranoid" security options, it is possible
- that the checksetup.pl script may fail with the error:
- <ERRORNAME>cannot chdir(/var/spool/mqueue): Permission denied</ERRORNAME>
- This is because your
- /var/spool/mqueue directory has a mode of "drwx------". Type
- <COMMAND>chmod 755 /var/spool/mqueue</COMMAND> as root to fix this problem.
- </PARA>
- </NOTE>
-
- <NOTE>
- <PARA>
-
- </PARA>
- </NOTE>
+ <SECTION>
+ <TITLE>ERRATA</TITLE>
+ <NOTE>
+ <PARA>
+ If you are installing Bugzilla on S.u.S.e. Linux, or some other
+ distributions with "paranoid" security options, it is possible
+ that the checksetup.pl script may fail with the error:
+ <ERRORNAME>cannot chdir(/var/spool/mqueue): Permission denied</ERRORNAME>
+ This is because your
+ /var/spool/mqueue directory has a mode of "drwx------". Type
+ <COMMAND>chmod 755 /var/spool/mqueue</COMMAND> as root to fix this problem.
+ </PARA>
+ </NOTE>
+
+ <NOTE>
+ <PARA>
+ Release Notes for Bugzilla 2.12 are available at docs/rel_notes.txt
+ </PARA>
+ </NOTE>
+
+ <NOTE>
+ <PARA>
+ The preferred documentation for Bugzilla is available in docs/, with
+ a variety of document types available. Please refer to these documents when
+ installing, configuring, and maintaining your Bugzilla installation.
+ </PARA>
+ </NOTE>
+
+ <WARNING>
+ <PARA>
+ Bugzilla is not a package where you can just plop it in a directory,
+ twiddle a few things, and you're off. Installing Bugzilla assumes you
+ know your variant of UNIX or Microsoft Windows well, are familiar with the
+ command line, and are comfortable compiling and installing a plethora
+ of third-party utilities. To install Bugzilla on Win32 requires
+ fair Perl proficiency, and if you use a webserver other than Apache you
+ should be intimately familiar with the security mechanisms and CGI
+ environment thereof.
+ </PARA>
+ </WARNING>
+
+ <WARNING>
+ <PARA>
+ Bugzilla has not undergone a complete security review. Security holes
+ may exist in the code. Great care should be taken both in the installation
+ and usage of this software. Carefully consider the implications of
+ installing other network services with Bugzilla.
+ </PARA>
+ </WARNING>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>Step-by-step Install</TITLE>
+ <SECTION>
+ <TITLE>Introduction</TITLE>
+ <PARA>
+ 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.
+ </PARA>
+
+ <PARA>
+ Bugzilla has been successfully installed under Solaris, Linux, and
+ Win32. The peculiarities of installing on Win32 (Win98+/NT/2K) are not
+ included in this section of the Guide; please check out the "Win32 Installation Instructions"
+ for further advice on getting Bugzilla to work on Microsoft Windows.
+ </PARA>
+
+ <PARA>
+ The Bugzilla Guide is contained in the "docs/" folder. It is available
+ in plain text (docs/txt), HTML (docs/html), or SGML source (docs/sgml).
+ </PARA>
+ </SECTION>
+ <SECTION>
+ <TITLE>Installing the Prerequisites</TITLE>
+
+ <PARA>
+ The software packages necessary for the proper running of bugzilla are:
+ <ORDEREDLIST>
+ <LISTITEM>
+ <PARA>
+ MySQL database server and the mysql client (3.22.5 or greater)
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Perl (5.004 or greater)
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ DBI Perl module
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Data::Dumper Perl module
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ DBD::mySQL
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ TimeDate Perl module collection
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ GD perl module (1.8.3) (optional, for bug charting)
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Chart::Base Perl module (0.99c) (optional, for bug charting)
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ DB_File Perl module (optional, for bug charting)
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ The web server of your choice. Apache is recommended.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ MIME::Parser Perl module (optional, for contrib/bug_email.pl interface)
+ </PARA>
+ </LISTITEM>
+ </ORDEREDLIST>
+ <NOTE>
+ <PARA>
+ You must run Bugzilla on a filesystem that supports file locking via
+ flock(). This is necessary for Bugzilla to operate safely with multiple
+ instances.
+ </PARA>
+ </NOTE>
+ <WARNING>
+ <PARA>
+ It is a good idea, while installing Bugzilla, to ensure it is not
+ <EMPHASIS>accessible</EMPHASIS> 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.
+ </PARA>
+ </WARNING>
+
+ </PARA>
+ </SECTION>
+ <SECTION>
+ <TITLE>Installing MySQL Database</TITLE>
+ <PARA>
+ Visit MySQL homepage at http://www.mysql.org/ 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.
+ </PARA>
+ <PARA>
+ 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.
+ </PARA>
+ <NOTE>
+ <PARA>
+ 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.
+ </PARA>
+ </NOTE>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>Perl (5.004 or greater)</TITLE>
+ <PARA>
+ 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.
+ </PARA>
+ <PARA>
+ Perl is now a far cry from the the single compiler/interpreter binary it
+ once was. It now 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.
+ </PARA>
+ <TIP>
+ <PARA>
+ 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.
+ </PARA>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>perl -MCPAN -e 'install "Bundle::Bugzilla"'</COMMAND>
+ </COMPUTEROUTPUT>
+ </PARA>
+ <PARA>
+ 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.
+ </PARA>
+ </TIP>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>DBI Perl Module</TITLE>
+ <PARA>
+ 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.
+ </PARA>
+ <PARA>
+ 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.
+ </PARA>
+ <PARA>
+ 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.
+ </PARA>
+ <PARA>
+ To use the CPAN shell to install DBI:
+ <INFORMALEXAMPLE>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>perl -MCPAN -e 'install "DBI"'</COMMAND>
+ </COMPUTEROUTPUT>
+ <NOTE>
+ <PARA>Replace "DBI" with the name of whichever module you wish
+ to install, such as Data::Dumper, TimeDate, GD, etc.</PARA>
+ </NOTE>
+ </PARA>
+ </INFORMALEXAMPLE>
+ To do it the hard way:
+ <INFORMALEXAMPLE>
+ <PARA>
+ Untar the module tarball -- it should create its own directory
+ </PARA>
+ <PARA>
+ CD to the directory just created, and enter the following commands:
+ <ORDEREDLIST>
+ <LISTITEM>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>perl Makefile.PL</COMMAND>
+ </COMPUTEROUTPUT>
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>make</COMMAND>
+ </COMPUTEROUTPUT>
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>make test</COMMAND>
+ </COMPUTEROUTPUT>
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>make install</COMMAND>
+ </COMPUTEROUTPUT>
+ </PARA>
+ </LISTITEM>
+ </ORDEREDLIST>
+ If everything went ok that should be all it takes. For the vast
+ majority of perl modules this is all that's required.
+ </PARA>
+ </INFORMALEXAMPLE>
+ </PARA>
+ </SECTION>
+ <SECTION>
+ <TITLE>Data::Dumper Perl Module</TITLE>
+ <PARA>
+ 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.
+ </PARA>
+ <PARA>
+ 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.
+ </PARA>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>MySQL related Perl Module Collection</TITLE>
+ <PARA>
+ 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.
+ </PARA>
+ <PARA>
+ The MySQL modules are all built using one make file which is generated
+ by running:
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>perl Makefile.pl</COMMAND>
+ </PARA>
+ <PARA>
+ 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.
+ </PARA>
+ <PARA>
+ When asked if your desired target is the MySQL or mSQL packages
+ selected the MySQL related ones. Later you will be asked if you wish
+ to provide backwards compatibility with the older MySQL packages; you
+ must answer YES to this question. The default will be no, and if you
+ select it things won't work later.
+ </PARA>
+ <PARA>
+ 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.
+ </PARA>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>TimeDate Perl Module Collection</TITLE>
+ <PARA>
+ 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 (hopefully
+ current) link can be found in Appendix A. 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.
+ </PARA>
+ </SECTION>
+ <SECTION>
+ <TITLE>GD Perl Module (1.8.3)</TITLE>
+ <PARA>
+ 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.
+ </PARA>
+ <PARA>
+ 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 "Required Software").
+ </PARA>
+ <NOTE>
+ <PARA>
+ 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.
+ </PARA>
+ </NOTE>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>Chart::Base Perl Module (0.99c)</TITLE>
+ <PARA>
+ 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 "Required Software". Note that as with the GD perl
+ module, only the specific versions listed above (or newer) will work. Earlier
+ versions used GIF's, which are no longer supported by the latest
+ versions of GD.
+ </PARA>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>DB_File Perl Module</TITLE>
+ <PARA>
+ 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.
+ </PARA>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>HTTP Server</TITLE>
+ <PARA>
+ 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.
+ </PARA>
+ <PARA>
+ 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:
+ <COMPUTEROUTPUT>AddHandler cgi-script .cgi</COMPUTEROUTPUT>
+ </PARA>
+ <PARA>
+ With apache you'll also want to make sure that within the access.conf
+ file the line:
+ <COMPUTEROUTPUT>
+ Options ExecCGI
+ </COMPUTEROUTPUT>
+ is in the stanza that covers the directories you intend to put the bugzilla
+ .html and .cgi files into.
+ </PARA>
+ <PARA>
+ 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.
+ </PARA>
+ <WARNING>
+ <PARA>
+ There are two critical directories and a file that should not be a served by
+ the HTTP server. These are the 'data' and 'shadow' 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 your HTTP server configuration manual on how
+ to do this. If you use quips (at the top of the buglist pages) you will want
+ the 'data/comments' file to still be served. This file contains those quips.
+ </PARA>
+ </WARNING>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>Installing the Bugzilla Files</TITLE>
+ <PARA>
+ 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 /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.
+ </PARA>
+ <TIP>
+ <PARA>
+ HINT: 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 &lt;Directory&gt; entry
+ for the HTML root.
+ </PARA>
+ </TIP>
+ <PARA>
+ 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 "checksetup.pl" script, which locks down your
+ installation.
+ </PARA>
+ <PARA>
+ Lastly, you'll need to set up a symbolic link from /usr/bonsaitools/bin
+ to 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.
+ <TIP>
+ <PARA>
+ If you don't have root access to set this symlink up, check out the
+ "setperl.csh" utility, listed in the Patches section of this
+ Guide. It will change the path to perl in all your Bugzilla files for
+ you.
+ </PARA>
+ </TIP>
+ </PARA>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>Setting Up the MySQL Database</TITLE>
+ <PARA>
+ 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.
+ </PARA>
+ <PARA>
+ 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".
+ </PARA>
+ <PARA>
+ That would be bad.
+ </PARA>
+ <PARA>
+ Give the MySQL root user a password. MySQL passwords are
+ limited to 16 characters.
+ <SIMPLELIST>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>mysql -u root mysql</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>
+ UPDATE user SET Password=PASSWORD ('new_password')
+ WHERE user='root';
+ </COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>FLUSH PRIVILEGES;</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ </SIMPLELIST>
+ 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).
+ </PARA>
+ <PARA>
+ 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.
+ </PARA>
+ <PARA>
+ Remember to set bugs_password to some unique password.
+ <SIMPLELIST>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,
+ ALTER,CREATE,DROP,REFERENCES
+ ON bugs.* TO bugs@localhost
+ IDENTIFIED BY 'bugs_password';</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>
+ mysql>
+ </PROMPT>
+ <COMMAND>
+ FLUSH PRIVILEGES;
+ </COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ </SIMPLELIST>
+ </PARA>
+ <PARA>
+ Next, run the magic checksetup.pl script. (Many thanks to Holger
+ Schurig &lt;holgerschurig@nikocity.de&gt; 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.
+ <SIMPLELIST>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>./checksetup.pl</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ </SIMPLELIST>
+ The first time you run it, it will create a file called "localconfig".
+ </PARA>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>Tweaking "localconfig"</TITLE>
+ <PARA>
+ This file contains a variety of settings you may need to tweak including
+ how Bugzilla should connect to the MySQL database.
+ </PARA>
+ <PARA>
+ The connection settings include:
+ <ORDEREDLIST>
+ <LISTITEM>
+ <PARA>
+ server's host: just use "localhost" if the MySQL server is
+ local
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ database name: "bugs" if you're following these directions
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ MySQL username: "bugs" if you're following these directions
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ Password for the "bugs" MySQL account above
+ </PARA>
+ </LISTITEM>
+ </ORDEREDLIST>
+ </PARA>
+ <PARA>
+ 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.
+ </PARA>
+ <PARA>
+ 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.
+ </PARA>
+ <PARA>
+ Should everything work, you should have a nearly empty copy of the bug
+ tracking setup.
+ </PARA>
+ <PARA>
+ 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:
+ <ERRORCODE>Now regenerating the shadow database for all bugs.</ERRORCODE>
+ <NOTE>
+ <PARA>
+ The second time you run checksetup.pl, it is recommended you be the same
+ user as your web server runs under, and that you be sure you have set the
+ "webservergroup" parameter in localconfig to match the web server's group
+ name, if any. Under some systems, otherwise, checksetup.pl will goof up
+ your file permissions and make them unreadable to your web server.
+ </PARA>
+ </NOTE>
+ </PARA>
+ <NOTE>
+ <PARA>
+ 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.
+ </PARA>
+ </NOTE>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>Setting Up Maintainers Manuall (Optional)</TITLE>
+ <PARA>
+ If you want to add someone else to every group by hand, you can do it
+ by typing the appropriate MySQL commands. Run '<COMPUTEROUTPUT>
+ mysql -u root -p bugs</COMPUTEROUTPUT>'
+ (you may need different parameters, depending on your security settings
+ according to section 3, above). Then:
+ <SIMPLELIST>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>update profiles set groupset=0x7fffffffffffffff
+ where login_name = 'XXX';</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ </SIMPLELIST>
+ replacing XXX with the Bugzilla email address.
+ </PARA>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>The Whining Cron (Optional)</TITLE>
+ <PARA>
+ By now you've got 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):
+ <SIMPLELIST>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <COMMAND>cd &lt;your-bugzilla-directory&gt; ; ./whineatnews.pl</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ </SIMPLELIST>
+ </PARA>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>Bug Graphs (Optional)</TITLE>
+ <PARA>
+ As long as you installed the GD and Graph::Base Perl modules you might
+ as well turn on the nifty bugzilla bug reporting graphs.
+ </PARA>
+ <PARA>
+ Add a cron entry like this to run collectstats daily at 5 after midnight:
+ <SIMPLELIST>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>crontab -e</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ 5 0 * * * cd &lt;your-bugzilla-directory&gt; ; ./collectstats.pl
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ </SIMPLELIST>
+ </PARA>
+ <PARA>
+ After two days have passed you'll be able to view bug graphs from the
+ Bug Reports page.
+ </PARA>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>Securing MySQL</TITLE>
+ <PARA>
+ If you followed the README 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.
+ </PARA>
+ <PARA>
+ Most MySQL installs have "interesting" default security parameters:
+ <SIMPLELIST>
+ <MEMBER>mysqld defaults to running as root</MEMBER>
+ <MEMBER>it defaults to allowing external network connections</MEMBER>
+ <MEMBER>it has a known port number, and is easy to detect</MEMBER>
+ <MEMBER>it defaults to no passwords whatsoever</MEMBER>
+ <MEMBER>it defaults to allowing "File_Priv"</MEMBER>
+ </SIMPLELIST>
+ </PARA>
+ <PARA>
+ 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.
+ </PARA>
+ <PARA>
+ To see your permissions do:
+ <SIMPLELIST>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>bash#</PROMPT>
+ <COMMAND>mysql -u root -p</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>use mysql;</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>show tables;</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>select * from user;</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ <MEMBER>
+ <COMPUTEROUTPUT>
+ <PROMPT>mysql></PROMPT>
+ <COMMAND>select * from db;</COMMAND>
+ </COMPUTEROUTPUT>
+ </MEMBER>
+ </SIMPLELIST>
+ </PARA>
+ <PARA>
+ To fix the gaping holes:
+ <SIMPLELIST>
+ <MEMBER>DELETE FROM user WHERE User='';</MEMBER>
+ <MEMBER>UPDATE user SET Password=PASSWORD('new_password') WHERE user='root';</MEMBER>
+ <MEMBER> FLUSH PRIVILEGES;</MEMBER>
+ </SIMPLELIST>
+ </PARA>
+ <PARA>
+ If you're not running "mit-pthreads" you can use:
+ <SIMPLELIST>
+ <MEMBER>GRANT USAGE ON *.* TO bugs@localhost;</MEMBER>
+ <MEMBER>GRANT ALL ON bugs.* TO bugs@localhost;</MEMBER>
+ <MEMBER>REVOKE DROP ON bugs.* FROM bugs@localhost;</MEMBER>
+ <MEMBER>FLUSH PRIVILEGES;</MEMBER>
+ </SIMPLELIST>
+ </PARA>
+ <PARA>
+ 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:
+ <SIMPLELIST>
+ <MEMBER>GRANT USAGE ON *.* TO bugs@bounce.hop.com;</MEMBER>
+ <MEMBER>GRANT ALL ON bugs.* TO bugs@bounce.hop.com;</MEMBER>
+ <MEMBER>REVOKE DROP ON bugs.* FROM bugs@bounce.hop.com;</MEMBER>
+ <MEMBER>FLUSH PRIVILEGES;</MEMBER>
+ </SIMPLELIST>
+ </PARA>
+ <PARA>
+ Consider also:
+ <ORDEREDLIST>
+ <LISTITEM>
+ <PARA>
+ 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.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ using the --user= option to mysqld to run it as an unprivileged
+ user.
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ starting MySQL in a chroot jail
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ running the httpd in a "chrooted" jail
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ making sure the MySQL passwords are different from the OS
+ passwords (MySQL "root" has nothing to do with system "root").
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ running MySQL on a separate untrusted machine
+ </PARA>
+ </LISTITEM>
+ <LISTITEM>
+ <PARA>
+ making backups ;-)
+ </PARA>
+ </LISTITEM>
+ </ORDEREDLIST>
+ </PARA>
+ </SECTION>
+
+ <SECTION>
+ <TITLE>Installation General Notes</TITLE>
+ <SECTION>
+ <TITLE>Modifying Your Running System</TITLE>
+ <PARA>
+ Bugzilla optimizes database lookups by storing all relatively static
+ information in the versioncache file, located in the data/ subdirectory
+ under your installation directory (we said before it needs to be writable,
+ right?!)
+ </PARA>
+ <PARA>
+ If you make a change to the structural data in your database (the
+ versions table for example), or to the "constants" encoded in
+ defparams.pl, you will need to remove the cached content from the data
+ directory (by doing a "rm data/versioncache"), or your changes won't show
+ up!
+ </PARA>
+ <PARA>
+ That file gets automatically regenerated whenever it's more than an
+ hour old, so Bugzilla will eventually notice your changes by itself, but
+ generally you want it to notice right away, so that you can test things.
+ </PARA>
+ </SECTION>
+ <SECTION>
+ <TITLE>Upgrading From Previous Versions</TITLE>
+ <PARA>
+ The developers of Bugzilla are constantly adding new tables, columns and
+ fields. You'll get SQL errors if you just update the code. The strategy
+ to update is to simply always run the checksetup.pl script whenever
+ you upgrade your installation of Bugzilla. If you want to see what has
+ changed, you can read the comments in that file, starting from the end.
+ </PARA>
+ </SECTION>
+ <SECTION>
+ <TITLE>UNIX Installation Instructions History</TITLE>
+ <PARA>
+ This document was originally adapted from the Bonsai installation
+ instructions by Terry Weissman &lt;terry@mozilla.org&gt;.
+ </PARA>
+ <PARA>
+ The February 25, 1999 re-write of this page was done by Ry4an Brase
+ &lt;ry4an@ry4an.org&gt;, with some edits by Terry Weissman, Bryce Nesbitt,
+ Martin Pool, & Dan Mosedale (But don't send bug reports to them!
+ Report them using bugzilla, at http://bugzilla.mozilla.org/enter_bug.cgi ,
+ project Webtools, component Bugzilla).
+ </PARA>
+ <PARA>
+ This document was heavily modified again Wednesday, March 07 2001 to
+ reflect changes for Bugzilla 2.12 release by Matthew P. Barnson. The
+ securing MySQL section should be changed to become standard procedure
+ for Bugzilla installations.
+ </PARA>
+ <PARA>
+ Finally, the README in its entirety was marked up in SGML and included into
+ the Guide on April 24, 2001.
+ </PARA>
+ <PARA>
+ Comments from people using this Guide for the first time are particularly welcome.
+ </PARA>
+ </SECTION>
+ </SECTION>
+
+ </SECTION>
</SECTION>
<SECTION id="README.windows">
@@ -320,6 +1230,71 @@
</BLOCKQUOTE>
</PARA>
</TIP>
+ <TIP>
+ <PARA>"Brian" had this to add, about upgrading to Bugzilla 2.12 from previous versions:</PARA>
+ <BLOCKQUOTE>
+ <PARA>
+ Hi - I am updating bugzilla to 2.12 so I can tell you what I did (after I
+ deleted the current dir and copied the files in).
+ </PARA>
+ <PARA>
+ In checksetup.pl, I did the following...
+ </PARA>
+ <PROCEDURE>
+ <STEP>
+ <PROGRAMLISTING>
+my $webservergid = getgrnam($my_webservergroup);
+ </PROGRAMLISTING>
+ <PARA>to</PARA>
+ <PROGRAMLISTING>
+my $webservergid = 'Administrators'
+ </PROGRAMLISTING>
+ </STEP>
+ <STEP>
+ <PARA>
+ I then ran checksetup.pl
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ I removed all the encrypt()
+ <EXAMPLE>
+ <TITLE>Removing encrypt() for Windows NT installations</TITLE>
+ <PARA>
+ Replace this:
+ <PROGRAMLISTING>
+SendSQL("SELECT encrypt(" . SqlQuote($enteredpwd) . ", " .
+ SqlQuote(substr($realcryptpwd, 0, 2)) . ")");
+my $enteredcryptpwd = FetchOneColumn();
+ </PROGRAMLISTING>
+ with this:
+ <PROGRAMLISTING>
+my $enteredcryptpwd = $enteredpwd
+ </PROGRAMLISTING>
+ in cgi.pl.
+ </PARA>
+ </EXAMPLE>
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ I renamed processmail to processmail.pl
+ </PARA>
+ </STEP>
+ <STEP>
+ <PARA>
+ I altered the sendmail statements to windmail:
+ <PROGRAMLISTING>
+open SENDMAIL, "|\"C:/General/Web/tools/Windmail 4.0 Beta/windmail\" -t > mail.log";
+ </PROGRAMLISTING>
+ </PARA>
+ <PARA>
+ The quotes around the dir is for the spaces. mail.log is for the output
+ </PARA>
+ </STEP>
+ </PROCEDURE>
+ </BLOCKQUOTE>
+ </TIP>
</SECTION>
</SECTION>
</CHAPTER>