diff options
Diffstat (limited to 'docs/sgml/readme.sgml')
| -rw-r--r-- | docs/sgml/readme.sgml | 496 |
1 files changed, 0 insertions, 496 deletions
diff --git a/docs/sgml/readme.sgml b/docs/sgml/readme.sgml deleted file mode 100644 index cdbd22878..000000000 --- a/docs/sgml/readme.sgml +++ /dev/null @@ -1,496 +0,0 @@ -This is Bugzilla. See <http://www.mozilla.org/bugs/>. - - - ========== - DISCLAIMER - ========== - - This is not very well packaged code. It's not packaged at all. Don't -come here expecting something you plop in a directory, twiddle a few -things, and you're off and using it. Work has to be done to get there. -We'd like to get there, but it wasn't clear when that would be, and so we -decided to let people see it first. - - 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. - - - ============ - INSTALLATION - ============ - -0. Introduction - - Installation of bugzilla is pretty straight forward, especially 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. - - Bugzilla has been successfully installed under Solaris and Linux. Windows NT -is not officially supported. There have been a few successful installations -of Bugzilla under Windows NT. Please see this article for a discussion of what -one person hacked together to get it to work. - -news://news.mozilla.org/19990913183810.SVTR29939.mta02@onebox.com - -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. MySQL related Perl module collection - 6. TimeDate Perl module collection - 7. GD perl module (1.18 or 1.19) - 8. Chart::Base Perl module (0.99 through 0.99b) - 9. The web server of your choice - - Bugzilla has quite a few prerequisites, but none of them are TCL. -Previous versions required TCL, but it no longer needed (or used). - -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. - -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. - -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 basically you'll just need to: - - 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.18 or 1.19) - - 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). Note, however, that you MUST -use version 1.18 or 1.19, because newer versions have dropped support -for GIFs in favor of PNGs, and bugzilla has not yet been updated to -deal with this. - -1.8. Chart::Base Perl module (0.99 through 0.99b) - - 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. - -1.9. 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 that makes MySQL permissions harder to manage. - - 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. - -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 -directory if it accidentally got tarred up with the rest of bugzilla) -and make sure you can get at the files in that directory through your -web server. - - 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). - - 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). -Or, you'll have to hack all the .cgi files to change where they look -for perl. - -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. Bugzilla always logs -in as user "bugs", with no password. That needs to work. MySQL -permissions are a deep, nasty complicated thing. I've just turned -them off. If you want to do that, too, then the magic is to do run -"mysql mysql", and feed it commands like this (replace all instances of -HOSTNAME with the name of the machine mysql is running on): - - DELETE FROM host; - DELETE FROM user; - INSERT INTO host VALUES - ('localhost','%','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y'); - INSERT INTO host VALUES - (HOSTNAME,'%','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y'); - INSERT INTO user VALUES - ('localhost','root','','Y','Y','Y','Y','Y','Y','Y','Y','Y', - 'Y','Y','Y','Y','Y'); - INSERT INTO user VALUES - (HOSTNAME,'','','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y', - 'Y','Y','Y'); - INSERT INTO user VALUES - (HOSTNAME,'root','','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y', - 'Y','Y','Y','Y'); - INSERT INTO user VALUES - ('localhost','','','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y', - 'Y','Y','Y','Y'); - -The number of 'Y' entries to use varies with the version of MySQL; they -keep adding columns. The list here should work with version 3.22.23b. - -This run of "mysql mysql" may need some extra parameters to deal with -whatever database permissions were set up previously. In particular, -you might have to say "mysql -uroot mysql", and give it an appropriate -password. - -For much more information about MySQL permissions, see the MySQL -documentation. - -After you've tweaked the permissions, run "mysqladmin reload" to make -sure that the database server knows to look at your new permission list. - -Or, at the mysql prompt: - -mysql> flush privileges; - -You must explictly tell mysql to reload permissions before running checksetup.pl. - -Next, you can just run the magic checksetup.pl script. (Many thanks -to Holger Schurig <holgerschurig@nikocity.de> for writing this script!) -It will make sure things have reasonable permissions, set up the "data" -directory, and create all the MySQL tables. Just run: - - ./checksetup.pl - -The first time you run it, it will create a file called "localconfig" -which you should examine and perhaps tweak a bit. Then re-run -checksetup.pl and it will do the real work. - - -At ths point, you should have a nearly empty copy of the bug tracking -setup. - -4. Tweaking the Bugzilla->MySQL Connection Data - - If you have played with MySQL permissions, rather than just opening it -wide open as described above, then you may need to tweak the Bugzilla -code to connect appropriately. - - In order for bugzilla to be able to connect to the MySQL database -you'll have to tell bugzilla where the database server is, what -database you're connecting to, and whom to connect as. Simply open up -the globals.pl file in the bugzilla directory and find the line that -begins like: - - $::db = Mysql->Connect(" - - That line does the actual database connection. The Connect method -takes four parameters which are (with appropriate values): - - 1. server's host: just use "localhost" - 2. database name: "bugs" if you're following these directions - 3. MySQL username: whatever you created for your webserver user - probably "nobody" - 4. Password for the MySQL account in item 3. - -Just fill in those values and close up globals.pl - -5. Setting up yourself as Maintainer - - Start by creating your own bugzilla account. To do so, just try to -"add a bug" from the main bugzilla menu (now available from your system -through your web browser!). You'll be prompted for logon info, and you -should enter your email address and then select 'mail me my password'. -When you get the password mail, log in with it. Don't finish entering -that new bug. - - Now, add yourself to every group. The magic checksetup.pl script -can do this for you, if you run it again now. That script will notice -if there's exactly one user in the database, and if so, add that person -to every group. - - If you want to add someone to every group by hand, you can do it by -typing the appropriate MySQL commands. Run mysql, and type: - - update profiles set groupset=0x7fffffffffffffff - where login_name = 'XXX'; - -replacing XXX with your Bugzilla email address. - -Now, if you go to the query page (off of the bugzilla main menu) where -you'll now find a 'edit parameters' option which is filled with editable -treats. - -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. Just add -the command: - - cd <your-bugzilla-directory> ; ./collectstats.pl - -as a nightly entry to your crontab and after two days have passed you'll -be able to view bug graphs from the Bug Reports page. - -8. Real security for MySQL - -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). - - Comments from people using this document for the first time are -especially welcomed. |