diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 595 |
1 files changed, 9 insertions, 586 deletions
@@ -1,592 +1,15 @@ -This is Bugzilla. See <http://www.mozilla.org/bugs/>. - ===================== BUGZILLA 2.12 RELEASE ===================== - - * Release Notes for Bugzilla 2.12 are available at docs/rel_notes.txt. - - * The new 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. The majority -of the contents of this file is now considered to be largely deprecated and will -go away in the 2.14 release. - ========== - DISCLAIMER - ========== - - 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. - - 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. - - - =========== - CONVENTIONS - =========== - - - Throughout this README and "The Bugzilla Guide" in the docs/ folder, -we use some writing conventions. Bourne shell prompts are used -generically to indicate any shell. - - File Names file.extension - Directory Names directory/ - Commands to be typed <shell> command - Prompt of user command under bash shell: bash$ - Prompt of root user command under bash shell: bash# - Prompt of user command under tcsh shell: tcsh$ - Environment Variables VARIABLE - Emphasized word *word* - - - ============ - INSTALLATION - ============ - - -0. Introduction - - Installation of bugzilla is pretty straightforward, particularly if your -machine already has MySQL and the MySQL-related perl packages installed. -If those aren't installed yet, then that's the first order of business. The -other necessary ingredient is a web server set up to run cgi scripts. -While using Apache for your webserver is not required, it is recommended. - - Bugzilla has been successfully installed under Solaris, Linux, and -Win32. The peculiarities of installing on Win32 (Win98+/NT/2K) are not -included in this README; please consult the Bugzilla Guide for more -detailed Win32 installation instructions. - - 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). - - -1. Installing the Prerequisites - - The software packages necessary for the proper running of bugzilla are: - - 1. MySQL database server and the mysql client (3.22.5 or greater) - 2. Perl (5.004 or greater) - 3. DBI Perl module - 4. Data::Dumper Perl module - 5. DBD::mySQL - 6. TimeDate Perl module collection - 7. GD perl module (1.8.3) (optional, for bug charting) - 8. Chart::Base Perl module (0.99c) (optional, for bug charting) - 9. DB_File Perl module (optional, for bug charting) - 10. The web server of your choice. Apache is recommended. - - For the contrib/bug_email.pl interface, you also need: - 11. MIME::Parser Perl module - - You must also run Bugzilla on a filesystem that supports file locking via -flock(). This is necessary for Bugzilla to operate safely with multiple -instances. - - It is a good idea, while installing Bugzilla, to ensure it is not -accessible from the Internet. The machine may be vulnerable to attacks -while you are installing. - -1.1. Getting and setting up MySQL database (3.22.5 or greater) - - 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. - - 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. - - 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. - -1.2. Perl (5.004 or greater) - - Any machine that doesn't have perl on it is a sad machine indeed. Perl -for *nix systems can be gotten in source form from http://www.perl.com. - - 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. - - - SHORTCUT: 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. - - bash# perl -MCPAN -e 'install "Bundle::Bugzilla"' - - Bundle::Bugzilla doesn't include GD, Chart::Base, or MIME::Parser, -which are not essential to a basic Bugzilla install. If installing -this bundle fails, you should install each module individually to -isolate the problem. - - -1.3. DBI Perl module - - The DBI module is a generic Perl module used by other database related -Perl modules. For our purposes it's required by the MySQL-related -modules. As long as your Perl installation was done correctly the -DBI module should be a breeze. It's a mixed Perl/C module, but Perl's -MakeMaker system simplifies the C compilation greatly. - - 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. - - Quality, general Perl module installation instructions can be found on -the CPAN website, but the easy thing to do is to just use the CPAN shell -which does all the hard work for you. - -To use the CPAN shell to install DBI: - - bash# perl -MCPAN -e 'install "DBI"' -(replace DBI with the name of the module you wish to install, Data::Dumper, -etc...) - -To do it the hard way: - - 1. Untar the module tarball -- it should create its own directory - 2. Enter the following commands: - perl Makefile.PL - make - make test - make install - - If everything went ok that should be all it takes. For the vast -majority of perl modules this is all that's required. - -1.4 Data::Dumper Perl module - - The Data::Dumper module provides data structure persistence for Perl -(similar to Java's serialization). It comes with later sub-releases of -Perl 5.004, but a re-installation just to be sure it's available won't -hurt anything. - - Data::Dumper is used by the MySQL related Perl modules. It can be -found on CPAN (link in Appendix A) and can be installed by following -the same four step make sequence used for the DBI module. - -1.5. MySQL related Perl module collection - - 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 (link -in Appendix A). After the archive file has been downloaded it should -be untarred. - - The MySQL modules are all build using one make file which is generated -by running: - - perl Makefile.PL - - 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. - - 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. - - 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. - -1.6. TimeDate Perl module collection - - Many of the more common date/time/calendar related Perl modules have -been grouped into a bundle similar to the MySQL modules bundle. This -bundle is stored on the CPAN under the name TimeDate. 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. - -1.7. GD Perl module (1.8.3) - - The GD library was written by Thomas Boutell a long while ago to -programatically generate images in C. Since then it's become 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. - 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 A). - - The latest version of the GD library can be found at: - - http://www.boutell.com/gd/ - -1.8. Chart::Base Perl module (0.99c) - - The Chart module provides bugzilla with on-the-fly charting -abilities. It can be installed in the usual fashion after it has been -fetched from CPAN where it is found as the Chart-x.x... tarball in a -directory to be listed in Appendix A. Note that as with the GD perl -module, only the specific versions listed above will work. Earlier -versions used GIF's, which are no longer supported by the latest -versions of GD. - -1.9. DB_File Perl module - - 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. - -1.10. HTTP server - You have a freedom of choice here - Apache, Netscape or any other -server on UNIX would do. You can easily run the web server on a different -machine than MySQL, but need to adjust the MySQL "bugs" user permissions -accordingly. - - 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: - - AddHandler cgi-script .cgi - - With apache you'll also want to make sure that within the access.conf -file the line: - - Options ExecCGI - -is in the stanza that covers the directories you intend to put the -bugzilla .html and .cgi files into. - -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. - -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. - -2. Installing the Bugzilla Files - - 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. - - 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 <Directory> entry -for the HTML root. +* This README is no longer used to house installation instructions. Instead, +it contains pointers to where you may find the information you need. - 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. - - 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. - -3. Setting Up the MySQL database - - After you've gotten all the software installed and working you're ready -to start preparing the database for its life as a the back end to a high -quality bug tracker. - - First, you'll want to fix MySQL permissions to allow access from -Bugzilla. For the purpose of this README, the Bugzilla username -will be "bugs", and will have minimal permissions. Bugzilla has -not undergone a thorough security audit. It may be possible for -a system cracker to somehow trick Bugzilla into executing a command -such as "; DROP DATABASE mysql". - - That would be bad. - - Give the MySQL root user a password. MySQL passwords are -limited to 16 characters. - - bash$ mysql -u root mysql - mysql> UPDATE user SET Password=PASSWORD ('new_password') - WHERE user='root'; - mysql> FLUSH PRIVILEGES; - - 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). - - 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. - - Remember to set bugs_password to some unique password. - - mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX, - ALTER,CREATE,DROP,REFERENCES - ON bugs.* TO bugs@localhost - IDENTIFIED BY 'bugs_password'; - mysql> FLUSH PRIVILEGES; - - 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. - - bash$ ./checksetup.pl - - The first time you run it, it will create a file called "localconfig". - - -4. Tweaking localconfig - - This file contains a variety of settings you may need to tweak including -how Bugzilla should connect to the MySQL database. - - The connection settings include: - - 1. server's host: just use "localhost" if the MySQL server is - local - 2. database name: "bugs" if you're following these directions - 3. MySQL username: "bugs" if you're following these directions - 4. Password for the "bugs" MySQL account in item 3. - - 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. - - When logged into an administrator account once Bugzilla is running, -if you go to the query page (off of the bugzilla main menu), you'll -find an 'edit parameters' option that is filled with editable treats. - - Should everything work, you should have a nearly empty copy of the bug -tracking setup. - - 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: - - "Now regenerating the shadow database for all bugs." - - 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. - -5. Setting Up Maintainers Manually (Optional) - - If you want to add someone else to every group by hand, you can do it -by typing the appropriate MySQL commands. Run 'mysql -u root -p bugs' -(you may need different parameters, depending on your security settings -according to section 3, above). Then: - - mysql> update profiles set groupset=0x7fffffffffffffff - where login_name = 'XXX'; - -replacing XXX with the Bugzilla email address. - -6. Setting Up the Whining Cron Job (Optional) - - 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): - - cd <your-bugzilla-directory> ; ./whineatnews.pl - -7. Bug Graphs (Optional) - - As long as you installed the GD and Graph::Base Perl modules you might -as well turn on the nifty bugzilla bug reporting graphs. - - bash# crontab -e - Adding this entry runs collectstats daily at 5 after midnight: - 5 0 * * * cd <your-bugzilla-directory> ; ./collectstats.pl - - After two days have passed you'll be able to view bug graphs from the -Bug Reports page. - -8. Real security for MySQL - - 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. - - MySQL has "interesting" default security parameters: - mysqld defaults to running as root - it defaults to allowing external network connections - it has a known port number, and is easy to detect - it defaults to no passwords whatsoever - it defaults to allowing "File_Priv" -This means anyone from anywhere on the internet can not only drop the -database with one SQL command, and they can write as root to the system. - - To see your permissions do: - > mysql -u root -p - use mysql; - show tables; - select * from user; - select * from db; - - To fix the gaping holes: - DELETE FROM user WHERE User=''; - UPDATE user SET Password=PASSWORD('new_password') WHERE user='root'; - FLUSH PRIVILEGES; - - If you're not running "mit-pthreads" you can use: - GRANT USAGE ON *.* TO bugs@localhost; - GRANT ALL ON bugs.* TO bugs@localhost; - REVOKE DROP ON bugs.* FROM bugs@localhost; - FLUSH PRIVILEGES; - - 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: - GRANT USAGE ON *.* TO bugs@bounce.hop.com; - GRANT ALL ON bugs.* TO bugs@bounce.hop.com; - REVOKE DROP ON bugs.* FROM bugs@bounce.hop.com; - FLUSH PRIVILEGES; - - Consider also: - o 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. - - o using the --user= option to mysqld to run it as an unprivileged - user. - - o starting MySQL in a chroot jail - - o running the httpd in a jail - - o making sure the MySQL passwords are different from the OS - passwords (MySQL "root" has nothing to do with system "root"). - - o running MySQL on a separate untrusted machine - - o making backups ;-) - - - ----------[ Appendices ]----------------------- - -Appendix A. Required Software Download Links - - All of these sites are current as of February 17, 1999. Hopefully -they'll stay current for a while. - -MySQL: http://www.mysql.org - -Perl: http://www.perl.org - -CPAN: http://www.cpan.org - -DBI Perl module: ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/DBI/ - -Data::Dumper module: - ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/Data/ - -MySQL related Perl modules: - ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/Mysql/ - -TimeDate Perl module collection: - ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/Date/ - -GD Perl module: ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/GD/ - -Chart::Base module: - ftp://ftp.cpan.org/pub/perl/CPAN/modules/by-module/Chart/ - - -Appendix B. Modifying Your Running System - - 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?!) - - 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! - - 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. - - -Appendix C. Upgrading from previous versions of Bugzilla - - 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. - - -Appendix D. History - - This document was originally adapted from the Bonsai installation -instructions by Terry Weissman <terry@mozilla.org>. - - The February 25, 1999 re-write of this page was done by Ry4an Brase -<ry4an@ry4an.org>, 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). - - 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. +* Installation instructions are now found in docs/, with a variety of document +types available. Please refer to these documents when installing, configuring, +and maintaining your Bugzilla installation. A helpful starting point is +docs/txt/Bugzilla-Guide.txt, or with a web browser at docs/html/index.html. + +* Release Notes for Bugzilla 2.12 are available at docs/rel_notes.txt. - Comments from people using this document for the first time are -especially welcomed. +* If you wish to contribute to the documentation, please read docs/README.docs. |