diff options
Diffstat (limited to 'docs/sgml/installation.sgml')
| -rw-r--r-- | docs/sgml/installation.sgml | 1025 |
1 files changed, 1000 insertions, 25 deletions
diff --git a/docs/sgml/installation.sgml b/docs/sgml/installation.sgml index f29ba953d..03ff0bd8d 100644 --- a/docs/sgml/installation.sgml +++ b/docs/sgml/installation.sgml @@ -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 <Directory> 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 <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. + <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 <your-bugzilla-directory> ; ./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 <your-bugzilla-directory> ; ./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 <terry@mozilla.org>. + </PARA> + <PARA> + 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). + </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> |