diff options
| author | barnboy%trilobyte.net <> | 2008-04-04 13:45:52 +0200 |
|---|---|---|
| committer | barnboy%trilobyte.net <> | 2008-04-04 13:45:52 +0200 |
| commit | e5b9f4fac1e56c36d72304c313432dc34edd80c9 (patch) | |
| tree | e750545dddb07577ecc5244fb4eacabbf0cb02c4 /docs/en/xml/installation.xml | |
| parent | 7016a5a014f8d3c87a4bdf7d1ad8286bc06a9193 (diff) | |
| download | bugzilla-e5b9f4fac1e56c36d72304c313432dc34edd80c9.tar.gz bugzilla-e5b9f4fac1e56c36d72304c313432dc34edd80c9.tar.xz | |
Updated Bugzilla Guide and README to fix bug 76156, bug 76841, and bug 26242.
The README is now gutted, pointers to Guide. Also some new sections added,
old ones fixed, and notes appended to deprecated sections I've not yet had
the heart to remove.
Diffstat (limited to 'docs/en/xml/installation.xml')
| -rw-r--r-- | docs/en/xml/installation.xml | 3320 |
1 files changed, 1301 insertions, 2019 deletions
diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml index 0373ab72c..03ff0bd8d 100644 --- a/docs/en/xml/installation.xml +++ b/docs/en/xml/installation.xml @@ -1,2040 +1,1322 @@ -<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> --> -<!-- $Id: installation.xml,v 1.1 2008/04/03 19:05:43 lpsolit%gmail.com Exp $ --> -<chapter id="installing-bugzilla"> - <title>Installing Bugzilla</title> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> - <section id="installation"> - <title>Installation</title> - - <note> - <para>If you just want to <emphasis>use</emphasis> Bugzilla, - you do not need to install it. None of this chapter is relevant to - you. Ask your Bugzilla administrator for the URL to access it from - your web browser. - </para> - </note> - - <para>The Bugzilla server software is usually installed on Linux or - Solaris. - If you are installing on another OS, check <xref linkend="os-specific"/> - before you start your installation to see if there are any special - instructions. - </para> - - <para> - As an alternative to following these instructions, you may wish to - try Arne Schirmacher's unofficial and unsupported - <ulink url="http://www.softwaretesting.de/article/view/33/1/8/">Bugzilla - Installer</ulink>, which installs Bugzilla and all its prerequisites - on Linux or Solaris systems. - </para> - - <para>This guide assumes that you have administrative access to the - Bugzilla machine. It not possible to - install and run Bugzilla itself without administrative access except - in the very unlikely event that every single prerequisite is - already installed. - </para> - - <warning> - <para>The installation process may make your machine insecure for - short periods of time. Make sure there is a firewall between you - and the Internet. - </para> - </warning> - - <para> - You are strongly recommended to make a backup of your system - before installing Bugzilla (and at regular intervals thereafter :-). - </para> - - <para>In outline, the installation proceeds as follows: - </para> - - <procedure> - <step> - <para><link linkend="install-perl">Install Perl</link> - (&min-perl-ver; or above) - </para> - </step> - <step> - <para><link linkend="install-database">Install a Database Engine</link> - </para> - </step> - <step> - <para><link linkend="install-webserver">Install a Webserver</link> - </para> - </step> - <step> - <para><link linkend="install-bzfiles">Install Bugzilla</link> - </para> - </step> - <step> - <para><link linkend="install-perlmodules">Install Perl modules</link> - </para> - </step> - <step> - <para> - <link linkend="install-MTA">Install a Mail Transfer Agent</link> - (Sendmail 8.7 or above, or an MTA that is Sendmail-compatible with at least this version) - </para> - </step> - <step> - <para>Configure all of the above. - </para> - </step> - </procedure> - - <section id="install-perl"> - <title>Perl</title> - - <para>Installed Version Test: <filename>perl -v</filename></para> - - <para>Any machine that doesn't have Perl on it is a sad machine indeed. - If you don't have it and your OS doesn't provide official packages, - visit <ulink url="http://www.perl.com"/>. - Although Bugzilla runs with Perl &min-perl-ver;, - it's a good idea to be using the latest stable version. - </para> - </section> - - <section id="install-database"> - <title>Database Engine</title> - - <para>From Bugzilla 2.20, support is included for using both the MySQL and - PostgreSQL database servers. You only require one of these systems to make - use of Bugzilla.</para> - - <section id="install-mysql"> - <title>MySQL</title> - <para>Installed Version Test: <filename>mysql -V</filename></para> - - <para> - If you don't have it and your OS doesn't provide official packages, - visit <ulink url="http://www.mysql.com"/>. You need MySQL version - &min-mysql-ver; or higher. - </para> - - <note> - <para> Many of the binary - versions of MySQL store their data files in - <filename class="directory">/var</filename>. - On some Unix systems, this is part of a smaller root partition, - and may not have room for your bug database. To change the data - directory, you have to build MySQL from source yourself, and - set it as an option to <filename>configure</filename>.</para> - </note> - - <para>If you install from something other than a packaging/installation - system, such as .rpm (Redhat Package), .deb (Debian Package), .exe - (Windows Executable), or .msi (Microsoft Installer), make sure the MySQL - server is started when the machine boots. - </para> - </section> - - <section id="install-pg"> - <title>PostgreSQL</title> - <para>Installed Version Test: <filename>psql -V</filename></para> - - <para> - If you don't have it and your OS doesn't provide official packages, - visit <ulink url="http://www.postgresql.org/"/>. You need PostgreSQL - version &min-pg-ver; or higher. - </para> - - <para>If you install from something other than a packaging/installation - system, such as .rpm (Redhat Package), .deb (Debian Package), .exe - (Windows Executable), or .msi (Microsoft Installer), make sure the - PostgreSQL server is started when the machine boots. - </para> - </section> - - </section> - - <section id="install-webserver"> - <title>Web Server</title> - - <para>Installed Version Test: view the default welcome page at - http://<your-machine>/</para> - - <para>You have freedom of choice here, pretty much any web server that - is capable of running <glossterm linkend="gloss-cgi">CGI</glossterm> - scripts will work. - However, we strongly recommend using the Apache web server - (either 1.3.x or 2.x), and - the installation instructions usually assume you are - using it. If you have got Bugzilla working using another web server, - please share your experiences with us by filing a bug in &bzg-bugs;. - </para> - - <para> - If you don't have Apache and your OS doesn't provide official packages, - visit <ulink url="http://httpd.apache.org/"/>. - </para> - - </section> - - <section id="install-bzfiles"> - <title>Bugzilla</title> - - <para> - Download a Bugzilla tarball (or check it out from CVS) and place - it in a suitable directory, accessible by the default web server user - (probably <quote>apache</quote> or <quote>www</quote>). - Good locations are either directly in the web server's document directories or - in <filename>/usr/local</filename> with a symbolic link to the web server's - document directories or an alias in the web server's configuration. - </para> - - <caution> - <para>The default Bugzilla distribution is NOT designed to be placed - in a <filename class="directory">cgi-bin</filename> directory. This - includes any directory which is configured using the - <option>ScriptAlias</option> directive of Apache. - </para> - </caution> - - <para>Once all the files are in a web accessible directory, make that - directory writable by your web server's user. This is a temporary step - until you run the - <filename>checksetup.pl</filename> - script, which locks down your installation.</para> - </section> - - <section id="install-perlmodules"> - <title>Perl Modules</title> - - <para>Bugzilla's installation process is based - on a script called <filename>checksetup.pl</filename>. - The first thing it checks is whether you have appropriate - versions of all the required - Perl modules. The aim of this section is to pass this check. - When it passes, proceed to <xref linkend="configuration"/>. - </para> - - <para> - At this point, you need to <filename>su</filename> to root. You should - remain as root until the end of the install. To check you have the - required modules, run: - </para> - - <screen><prompt>bash#</prompt> ./checksetup.pl --check-modules</screen> - - <para> - <filename>checksetup.pl</filename> will print out a list of the - required and optional Perl modules, together with the versions - (if any) installed on your machine. - The list of required modules is reasonably long; however, you - may already have several of them installed. - </para> - - <para> - There is a meta-module called Bundle::Bugzilla, - which installs all the other - modules with a single command. You should use this if you are running - Perl 5.6.1 or above. - </para> - - <para> - The preferred way of installing Perl modules is via CPAN on Unix, - or PPM on Windows (see <xref linkend="win32-perl-modules"/>). These - instructions assume you are using CPAN; if for some reason you need - to install the Perl modules manually, see - <xref linkend="install-perlmodules-manual"/>. - </para> - - <screen><prompt>bash#</prompt> perl -MCPAN -e 'install "<modulename>"'</screen> - - <para> - If you using Bundle::Bugzilla, invoke the magic CPAN command on it. - Otherwise, you need to work down the - list of modules that <filename>checksetup.pl</filename> says are - required, in the order given, invoking the command on each. - </para> - - <tip> - <para>Many people complain that Perl modules will not install for - them. Most times, the error messages complain that they are missing a - file in - <quote>@INC</quote>. - Virtually every time, this error is due to permissions being set too - restrictively for you to compile Perl modules or not having the - necessary Perl development libraries installed on your system. - Consult your local UNIX systems administrator for help solving these - permissions issues; if you - <emphasis>are</emphasis> - the local UNIX sysadmin, please consult the newsgroup/mailing list - for further assistance or hire someone to help you out.</para> - </tip> - - <note> - <para>If you are using a package-based system, and attempting to install the - Perl modules from CPAN, you may need to install the "development" packages for - MySQL and GD before attempting to install the related Perl modules. The names of - these packages will vary depending on the specific distribution you are using, - but are often called <filename><packagename>-devel</filename>.</para> - </note> - - <para> - Here is a complete list of modules and their minimum versions. - Some modules have special installation notes, which follow. - </para> - - <para>Required Perl modules: - <orderedlist> - - <listitem> - <para> - CGI &min-cgi-ver; or CGI &min-mp-cgi-ver; if using mod_perl - </para> - </listitem> - - <listitem> - <para> - Date::Format (&min-date-format-ver;) - </para> - </listitem> - - <listitem> - <para> - DBI (&min-dbi-ver;) - </para> - </listitem> - - <listitem> - <para> - <link linkend="install-modules-dbd-mysql">DBD::mysql</link> - (&min-dbd-mysql-ver;) if using MySQL - </para> - </listitem> - - <listitem> - <para> - DBD::Pg (&min-dbd-pg-ver;) if using PostgreSQL - </para> - </listitem> - - <listitem> - <para> - File::Spec (&min-file-spec-ver;) - </para> - </listitem> - - <listitem> - <para> - <link linkend="install-modules-template">Template</link> - (&min-template-ver;) - </para> - </listitem> - - <listitem> - <para> - Email::Send (&min-email-send-ver;) - </para> - </listitem> - - <listitem> - <para> - Email::MIME::Modifier (&min-email-mime-modifier-ver;) - </para> - </listitem> - </orderedlist> - - Optional Perl modules: - <orderedlist> - <listitem> - <para> - <link linkend="install-modules-gd">GD</link> - (&min-gd-ver;) for bug charting - </para> - </listitem> - - <listitem> - <para> - Template::Plugin::GD::Image - (&min-gd-ver;) for Graphical Reports - </para> - </listitem> - - <listitem> - <para> - <link linkend="install-modules-chart-base">Chart::Base</link> - (&min-chart-base-ver;) for bug charting - </para> - </listitem> - - <listitem> - <para> - <link linkend="install-modules-gd-graph">GD::Graph</link> - (&min-gd-graph-ver;) for bug charting - </para> - </listitem> - - <listitem> - <para> - <link linkend="install-modules-gd-text">GD::Text</link> - (&min-gd-text-ver;) for bug charting - </para> - </listitem> - - <listitem> - <para> - <link linkend="install-modules-xml-twig">XML::Twig</link> - (&min-xml-twig-ver;) for bug import/export - </para> - </listitem> - - <listitem> - <para> - MIME::Parser (&min-mime-parser-ver;) for bug import/export - </para> - </listitem> - - <listitem> - <para> - LWP::UserAgent - (&min-lwp-useragent-ver;) for Automatic Update Notifications - </para> - </listitem> - - <listitem> - <para> - <link linkend="install-modules-patchreader">PatchReader</link> - (&min-patchreader-ver;) for pretty HTML view of patches - </para> - </listitem> - - <listitem> - <para> - Image::Magick (&min-image-magick-ver;) for converting BMP image attachments to PNG - </para> - </listitem> - - <listitem> - <para> - Net::LDAP - (&min-net-ldap-ver;) for LDAP Authentication - </para> - </listitem> - - <listitem> - <para> - Authen::Radius - (&min-authen-radius-ver;) for RADIUS Authentication - </para> - </listitem> - - <listitem> - <para> - <link linkend="install-modules-soap-lite">SOAP::Lite</link> - (&min-soap-lite-ver;) for the web service interface - </para> - </listitem> - - <listitem> - <para> - HTML::Parser - (&min-html-parser-ver;) for More HTML in Product/Group Descriptions - </para> - </listitem> - - <listitem> - <para> - HTML::Scrubber - (&min-html-scrubber-ver;) for More HTML in Product/Group Descriptions - </para> - </listitem> - - <listitem> - <para> - Email::MIME::Attachment::Stripper - (&min-email-mime-attachment-stripper-ver;) for Inbound Email - </para> - </listitem> - - <listitem> - <para> - Email::Reply - (&min-email-reply-ver;) for Inbound Email - </para> - </listitem> - - <listitem> - <para> - mod_perl2 - (&min-mod_perl2-ver;) for mod_perl - </para> - </listitem> - - <listitem> - <para> - CGI - (&min-cgi-ver;) for mod_perl - </para> - </listitem> - - </orderedlist> - </para> - - <section id="install-modules-dbd-mysql"> - <title>DBD::mysql</title> - - <para>The installation process will ask you a few questions about the - desired compilation target and your MySQL installation. For most of the - questions the provided default will be adequate, but when asked if your - desired target is the MySQL or mSQL packages, you should - select the MySQL-related ones. Later you will be asked if you wish to - provide backwards compatibility with the older MySQL packages; you - should answer YES to this question. The default is NO.</para> - - <para>A host of 'localhost' should be fine. A testing user of 'test', - with a null password, should have sufficient access to run - tests on the 'test' database which MySQL creates upon installation. - </para> - </section> - - <section id="install-modules-template"> - <title>Template Toolkit (&min-template-ver;)</title> - - <para>When you install Template Toolkit, you'll get asked various - questions about features to enable. The defaults are fine, except - that it is recommended you use the high speed XS Stash of the Template - Toolkit, in order to achieve best performance. - </para> - </section> - - <section id="install-modules-gd"> - <title>GD (&min-gd-ver;)</title> - - <para>The GD module is only required if you want graphical reports. - </para> - - <note> - <para>The Perl GD module requires some other libraries that may or - may not be installed on your system, including - <classname>libpng</classname> - and - <classname>libgd</classname>. - The full requirements are listed in the Perl GD module README. - If compiling GD fails, it's probably because you're - missing a required library.</para> - </note> - - <tip> - <para>The version of the GD module you need is very closely tied - to the <classname>libgd</classname> version installed on your system. - If you have a version 1.x of <classname>libgd</classname> the 2.x - versions of the GD module won't work for you. - </para> - </tip> - </section> - - <section id="install-modules-chart-base"> - <title>Chart::Base (&min-chart-base-ver;)</title> - - <para>The Chart::Base module is only required if you want graphical - reports. - Note that earlier versions that 0.99c used GIFs, which are no longer - supported by the latest versions of GD.</para> - </section> - - <section id="install-modules-gd-graph"> - <title>GD::Graph (&min-gd-graph-ver;)</title> - - <para>The GD::Graph module is only required if you want graphical - reports. - </para> - </section> - - <section id="install-modules-gd-text"> - <title>GD::Text (&min-gd-text-ver;)</title> - - <para>The GD::Text module is only required if you want graphical - reports. - </para> - </section> - - <section id="install-modules-xml-twig"> - <title>XML::Twig (&min-xml-twig-ver;)</title> - - <para>The XML::Twig module is only required if you want to import - XML bugs using the <filename>importxml.pl</filename> - script. This is required to use Bugzilla's "move bugs" feature; - you may also want to use it for migrating from another bug database. - </para> - </section> - - <section id="install-modules-soap-lite"> - <title>SOAP::Lite (&min-soap-lite-ver;)</title> - <para>Installing SOAP::Lite enables your Bugzilla installation to be - accessible at a standardized Web Service interface (SOAP/XML-RPC) - by third-party applications via HTTP(S). - </para> - </section> - - <section id="install-modules-patchreader"> - <title>PatchReader (&min-patchreader-ver;)</title> - - <para>The PatchReader module is only required if you want to use - Patch Viewer, a - Bugzilla feature to show code patches in your web browser in a more - readable form. - </para> - </section> - </section> - <section id="install-MTA"> - <title>Mail Transfer Agent (MTA)</title> - - <para> - Bugzilla is dependent on the availability of an e-mail system for its - user authentication and for other tasks. - </para> - - <note> - <para> - This is not entirely true. It is possible to completely disable - email sending, or to have Bugzilla store email messages in a - file instead of sending them. However, this is mainly intended - for testing, as disabling or diverting email on a production - machine would mean that users could miss important events (such - as bug changes or the creation of new accounts). - </para> - - <para> - For more information, see the <quote>mail_delivery_method</quote> parameter - in <xref linkend="parameters" />. - </para> - </note> - - <para> - On Linux, any Sendmail-compatible MTA (Mail Transfer Agent) will - suffice. Sendmail, Postfix, qmail and Exim are examples of common - MTAs. Sendmail is the original Unix MTA, but the others are easier to - configure, and therefore many people replace Sendmail with Postfix or - Exim. They are drop-in replacements, so Bugzilla will not - distinguish between them. - </para> - - <para> - If you are using Sendmail, version 8.7 or higher is required. - If you are using a Sendmail-compatible MTA, it must be congruent with - at least version 8.7 of Sendmail. - </para> - - <para> - Consult the manual for the specific MTA you choose for detailed - installation instructions. Each of these programs will have their own - configuration files where you must configure certain parameters to - ensure that the mail is delivered properly. They are implemented - as services, and you should ensure that the MTA is in the auto-start - list of services for the machine. - </para> - - <para> - If a simple mail sent with the command-line 'mail' program - succeeds, then Bugzilla should also be fine. - </para> - - </section> - <section id="using-mod_perl-with-bugzilla"> - <title>Installing Bugzilla on mod_perl</title> - <para>It is now possible to run the Bugzilla software under <literal>mod_perl</literal> on - Apache. <literal>mod_perl</literal> has some additional requirements to that of running - Bugzilla under <literal>mod_cgi</literal> (the standard and previous way).</para> - - <para>Bugzilla requires <literal>mod_perl</literal> to be installed, which can be - obtained from <ulink url="http://perl.apache.org"/> - Bugzilla requires - version &min-mod_perl2-ver; (AKA 2.0.0-RC5) to be installed.</para> - - <para>Bugzilla also requires a more up-to-date version of the CGI - perl module to be installed, version &min-mp-cgi-ver; as opposed to &min-cgi-ver; - </para> - </section> - </section> +<CHAPTER id="installation"> + <TITLE>Installing Bugzilla</TITLE> - <section id="configuration"> - <title>Configuration</title> - - <warning> - <para> - Poorly-configured MySQL and Bugzilla installations have - given attackers full access to systems in the past. Please take the - security parts of these guidelines seriously, even for Bugzilla - machines hidden away behind your firewall. Be certain to read - <xref linkend="security"/> for some important security tips. - </para> - </warning> - - <section id="localconfig"> - <title>localconfig</title> + <SECTION id="README.unix"> + <TITLE>UNIX Installation</TITLE> + <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> - <para> - You should now run <filename>checksetup.pl</filename> again, this time - without the <literal>--check-modules</literal> switch. - </para> - <screen><prompt>bash#</prompt> ./checksetup.pl</screen> - <para> - This time, <filename>checksetup.pl</filename> should tell you that all - the correct modules are installed and will display a message about, and - write out a file called, <filename>localconfig</filename>. This file - contains the default settings for a number of Bugzilla parameters. - </para> + <NOTE> + <PARA> + Release Notes for Bugzilla 2.12 are available at docs/rel_notes.txt + </PARA> + </NOTE> - <para> - Load this file in your editor. The only value you - <emphasis>need</emphasis> to change is $db_pass, the password for - the user you will create for your database. Pick a strong - password (for simplicity, it should not contain single quote - characters) and put it here. - </para> - - <para> - You may need to change the value of - <emphasis>webservergroup</emphasis> if your web server does not - run in the "apache" group. On Debian, for example, Apache runs in - the "www-data" group. If you are going to run Bugzilla on a - machine where you do not have root access (such as on a shared web - hosting account), you will need to leave - <emphasis>webservergroup</emphasis> empty, ignoring the warnings - that <filename>checksetup.pl</filename> will subsequently display - every time it is run. - </para> + <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> - <caution> - <para> - If you are using suexec, you should use your own primary group - for <emphasis>webservergroup</emphasis> rather than leaving it - empty, and see the additional directions in the suexec section - <xref linkend="suexec" />. - </para> - </caution> - - <para> - The other options in the <filename>localconfig</filename> file - are documented by their accompanying comments. If you have a slightly - non-standard MySQL setup, you may wish to change one or more of - the other "$db_*" parameters. - </para> + <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> - <para> - You may also wish to change the names of - the priorities, severities, operating systems and platforms for your - installation. However, you can always change these after installation - has finished; if you then re-run <filename>checksetup.pl</filename>, - the changes will get picked up. - </para> - </section> - - <section id="database-engine"> - <title>Database Server</title> - <para> - This section deals with configuring your database server for use - with Bugzilla. Currently, MySQL (<xref linkend="mysql"/>) and - PostgreSQL (<xref linkend="postgresql"/>) are available. - </para> - - <section id="database-schema"> - <title>Bugzilla Database Schema</title> - - <para> - The Bugzilla database schema is available at - <ulink url="http://www.ravenbrook.com/project/p4dti/tool/cgi/bugzilla-schema/">Ravenbrook</ulink>. - This very valuable tool can generate a written description of - the Bugzilla database schema for any version of Bugzilla. It - can also generate a diff between two versions to help someone - see what has changed. - </para> - </section> - - <section id="mysql"> - <title>MySQL</title> - - <caution> - <para> - MySQL's default configuration is very insecure. - <xref linkend="security-mysql"/> has some good information for - improving your installation's security. - </para> - </caution> - - <section id="install-setupdatabase"> - <title>Allow large attachments</title> - - <para> - By default, MySQL will only accept packets up to 64Kb in size. - If you want to have attachments larger than this, you will need - to modify your <filename>/etc/my.cnf</filename> as below. - </para> - - <screen> [mysqld] - # Allow packets up to 1M - max_allowed_packet=1M</screen> - - <para> - There is also a parameter in Bugzilla called 'maxattachmentsize' - (default = 1000 Kb) that controls the maximum allowable attachment - size. Attachments larger than <emphasis>either</emphasis> the - 'max_allowed_packet' or 'maxattachmentsize' value will not be - accepted by Bugzilla. - </para> - - <note> - <para> - This does not affect Big Files, attachments that are stored directly - on disk instead of in the database. Their maximum size is - controlled using the 'maxlocalattachment' parameter. - </para> - </note> - </section> - - <section> - <title>Allow small words in full-text indexes</title> - - <para>By default, words must be at least four characters in length - in order to be indexed by MySQL's full-text indexes. This causes - a lot of Bugzilla specific words to be missed, including "cc", - "ftp" and "uri".</para> - - <para>MySQL can be configured to index those words by setting the - ft_min_word_len param to the minimum size of the words to index. - This can be done by modifying the <filename>/etc/my.cnf</filename> - according to the example below:</para> - - <screen> [mysqld] - # Allow small words in full-text indexes - ft_min_word_len=2</screen> - - <para>Rebuilding the indexes can be done based on documentation found at - <ulink url="http://www.mysql.com/doc/en/Fulltext_Fine-tuning.html"/>. - </para> - </section> - - <section id="install-setupdatabase-adduser"> - <title>Add a user to MySQL</title> - - <para> - You need to add a new MySQL user for Bugzilla to use. - (It's not safe to have Bugzilla use the MySQL root account.) - The following instructions assume the defaults in - <filename>localconfig</filename>; if you changed those, - you need to modify the SQL command appropriately. You will - need the <replaceable>$db_pass</replaceable> password you - set in <filename>localconfig</filename> in - <xref linkend="localconfig"/>. - </para> - - <para> - We use an SQL <command>GRANT</command> command to create - a <quote>bugs</quote> user. This also restricts the - <quote>bugs</quote>user to operations within a database - called <quote>bugs</quote>, and only allows the account - to connect from <quote>localhost</quote>. Modify it to - reflect your setup if you will be connecting from another - machine or as a different user. - </para> - - <para> - Run the <filename>mysql</filename> command-line client and enter: - </para> - - <screen> <prompt>mysql></prompt> GRANT SELECT, INSERT, - UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES, - CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.* - TO bugs@localhost IDENTIFIED BY '<replaceable>$db_pass</replaceable>'; - <prompt>mysql></prompt> FLUSH PRIVILEGES;</screen> - - </section> - - <section> - <title>Permit attachments table to grow beyond 4GB</title> - - <para> - By default, MySQL will limit the size of a table to 4GB. - This limit is present even if the underlying filesystem - has no such limit. To set a higher limit, follow these - instructions. - </para> - - <para> - After you have completed the rest of the installation (or at least the - database setup parts), you should run the <filename>MySQL</filename> - command-line client and enter the following, replacing <literal>$bugs_db</literal> - with your Bugzilla database name (<emphasis>bugs</emphasis> by default): - </para> - - <screen> - <prompt>mysql></prompt> use <replaceable>$bugs_db</replaceable> - <prompt>mysql></prompt> ALTER TABLE attachments - AVG_ROW_LENGTH=1000000, MAX_ROWS=20000; - </screen> - - <para> - The above command will change the limit to 20GB. Mysql will have - to make a temporary copy of your entire table to do this. Ideally, - you should do this when your attachments table is still small. - </para> - - <note> - <para> - This does not affect Big Files, attachments that are stored directly - on disk instead of in the database. - </para> - </note> - </section> - </section> + <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 id="postgresql"> - <title>PostgreSQL</title> - <section> - <title>Add a User to PostgreSQL</title> - - <para>You need to add a new user to PostgreSQL for the Bugzilla - application to use when accessing the database. The following instructions - assume the defaults in <filename>localconfig</filename>; if you - changed those, you need to modify the commands appropriately. You will - need the <replaceable>$db_pass</replaceable> password you - set in <filename>localconfig</filename> in - <xref linkend="localconfig"/>.</para> - - <para>On most systems, to create the user in PostgreSQL, you will need to - login as the root user, and then</para> - - <screen> <prompt>bash#</prompt> su - postgres</screen> - - <para>As the postgres user, you then need to create a new user: </para> - - <screen> <prompt>bash$</prompt> createuser -U postgres -dAP bugs</screen> - - <para>When asked for a password, provide the password which will be set as - <replaceable>$db_pass</replaceable> in <filename>localconfig</filename>. - The created user will have the ability to create databases and will not be - able to create new users.</para> - </section> - - <section> - <title>Configure PostgreSQL</title> + <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"> + <TITLE>Win32 (Win98+/NT/2K) Installation</TITLE> + <PARA> + These directions have <EMPHASIS>not</EMPHASIS> been extensively tested. + We need testers! Please try these out and post any changes to the + newsgroup. + </PARA> + <SECTION id="ntverified"> + <TITLE>Win32 Installation: Step-by-step</TITLE> + <NOTE> + <PARA> + You should be familiar with, and cross-reference, the UNIX README + while performing your Win32 installation. Unfortunately, Win32 + directions are not yet as detailed as those for UNIX. + </PARA> + <PARA> + The <EMPHASIS>most critical</EMPHASIS> difference for Win32 users is + the lack of support for a crypt() function in MySQL for Windows. It does not + have it! All ENCRYPT statements must be modified. + </PARA> + </NOTE> + + <PROCEDURE> + <STEP> + <PARA> + Install <ULINK URL="http://www.apache.org/">Apache Web Server</ULINK> + for Windows. + </PARA> + <NOTE> + <PARA> + You may also use Internet Information Server or Personal Web + Server for this purpose. However, setup is slightly more + difficult. If ActivePerl doesn't seem to handle your file + associations correctly (for .cgi and .pl files), please + consult the FAQ, in the "Win32" section. + </PARA> + <PARA> + If you are going to use IIS, if on Windows NT you must be updated + to at least Service Pack 4. + </PARA> + </NOTE> + </STEP> + <STEP> + <PARA> + Install <ULINK URL="http://www.activestate.com/">ActivePerl</ULINK> + </PARA> + <PARA> + Please also check the following links to fully understand the status + of ActivePerl on Win32: + <ULINK URL="http://language.perl.com/newdocs/pod/perlport.html"> + Perl Porting</ULINK>, and + <ULINK URL="http://ftp.univie.ac.at/packages/perl/ports/nt/FAQ/perlwin32faq5.html"> + Hixie Click Here</ULINK> + </PARA> + </STEP> + <STEP> + <PARA> + Use ppm from your perl\bin directory to install the following packs: DBI, + DBD-Mysql, TimeDate, Chart, Date-Calc, Date-Manip, and GD. You may need + to extract them from .zip format using Winzip or other unzip program first. + These additional ppm modules can be downloaded from ActiveState. + </PARA> + <PARA> + The syntax for ppm is: + <COMPUTEROUTPUT> + <PROMPT>C:> </PROMPT><COMMAND>ppm install <module>.ppd</COMMAND> + </COMPUTEROUTPUT> + </PARA> + <PARA> + You can find ActiveState ppm modules at + <ULINK URL="http://www.activestate.com/PPMPackages/5.6plus/"> + http://www.activestate.com/PPMPackages/5.6plus</ULINK> + </PARA> + </STEP> + <STEP> + <PARA> + Download and install the Windows GNU tools from + <ULINK URL="http://www.cygwin.com/">www.cygwin.com</ULINK>. + Make sure the GNU utilities are in your $PATH. + </PARA> + </STEP> + <STEP> + <PARA> + Install MySQL for NT. + <NOTE> + <PARA> + Your configuration file for MySQL <EMPHASIS>must</EMPHASIS> be named C:\MY.CNF. + </PARA> + </NOTE> + </PARA> + </STEP> + <STEP> + <PARA> + Setup MySQL + </PARA> + <SUBSTEPS> + <STEP> + <PARA> + <COMPUTEROUTPUT> + <PROMPT>C:> </PROMPT> + <COMMAND>C:\mysql\bin\mysql -u root mysql</COMMAND> + </COMPUTEROUTPUT> + </PARA> + </STEP> + <STEP> + <PARA> + <COMPUTEROUTPUT> + <PROMPT>mysql></PROMPT> + <COMMAND>DELETE FROM user WHERE Host='localhost' AND User='';</COMMAND> + </COMPUTEROUTPUT> + </PARA> + </STEP> + <STEP> + <PARA> + <COMPUTEROUTPUT> + <PROMPT>mysql></PROMPT> + <COMMAND>UPDATE user SET Password=PASSWORD ('new_password') + WHERE user='root';</COMMAND> + </COMPUTEROUTPUT> + </PARA> + </STEP> + <STEP> + <PARA> + <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> + </PARA> + </STEP> + <STEP> + <PARA> + <COMPUTEROUTPUT> + <PROMPT>mysql></PROMPT> + <COMMAND>FLUSH PRIVILEGES;</COMMAND> + </COMPUTEROUTPUT> + </PARA> + </STEP> + <STEP> + <PARA> + <COMPUTEROUTPUT> + <PROMPT>mysql></PROMPT> + <COMMAND>create database bugs;</COMMAND> + </COMPUTEROUTPUT> + </PARA> + </STEP> + <STEP> + <PARA> + <COMPUTEROUTPUT> + <PROMPT>mysql></PROMPT> + <COMMAND>exit</COMMAND> + </COMPUTEROUTPUT> + </PARA> + </STEP> + <STEP> + <PARA> + <COMPUTEROUTPUT> + <PROMPT>C:></PROMPT> + <COMMAND>C:\mysql\bin\mysqladmin -u root -p reload</COMMAND> + </COMPUTEROUTPUT> + </PARA> + </STEP> + </SUBSTEPS> + </STEP> + + <STEP> + <PARA> + Configure Bugzilla. For Win32, this involves editing "defparams.pl" + and "localconfig" to taste. Running "checksetup.pl" should create + localconfig for you. Note that getgrnam() doesn't work, and should be + deleted. Change this line: + "my $webservergid = getgrnam($my_webservergroup); " + to + "my $webservergid = $my_webservergroup; " + </PARA> + </STEP> + + <STEP> + <NOTE> + <PARA> + There are several alternatives to Sendmail that will work on Win32. + The one mentioned here is a <EMPHASIS>suggestion</EMPHASIS>, not + a requirement. Some other mail packages that can work include + <ULINK URL="http://www.blat.net/">BLAT</ULINK>, + <ULINK URL="http://www.geocel.com/windmail/">Windmail</ULINK>, + <ULINK URL="http://www.dynamicstate.com/">Mercury Sendmail</ULINK>, + and the CPAN Net::SMTP Perl module (available in .ppm). + Every option requires some hacking of the Perl scripts for Bugzilla + to make it work. The option here simply requires the least. + </PARA> + </NOTE> + <PARA> + Download NTsendmail, available from<ULINK URL="http://www.ntsendmail.com/"> + www.ntsendmail.com</ULINK>. In order for it to work, you must set up some + new environment variables (detailed on the ntsendmail home page). Figuring + out where to put those variables is left as an exercise for the reader. + You must have a "real" mail server which allows you to relay off it + in your $ENV{"NTsendmail"} (which you should probably place in globals.pl) + </PARA> + <PARA> + Once downloaded and installed, modify all open(SENDMAIL) calls to open + "| c:\ntsendmail\ntsendmail -t" instead of "|/usr/lib/sendmail -t". + </PARA> + <NOTE> + <PARA> + We need someone to test this and make sure this works as advertised. + </PARA> + </NOTE> + </STEP> + <STEP> + <PARA> + Modify globals.pl and CGI.pl to remove the word "encrypt". + </PARA> + <NOTE> + <PARA> + I'm not sure this is all that is involved to remove crypt. Any + NT Bugzilla hackers want to pipe up? + </PARA> + </NOTE> + </STEP> + <STEP> + <PARA> + Change all references to "processmail" to "processmail.pl" in + all files, and rename "processmail" to "processmail.pl" + </PARA> + <NOTE> + <PARA> + I really think this may be a change we want to make for + main-tree Bugzilla. It's painless for the UNIX folks, + and will make the Win32 people happier. + </PARA> + </NOTE> + </STEP> + <STEP> + <PARA> + Modify the path to perl on the first line (#!) of all files + to point to your Perl installation, and + add "perl" to the beginning of all Perl system calls that + use a perl script as an argument. This may take you a while. + There is a "setperl.pl" utility to speed part of this procedure, + available in the "Patches and Utilities" section of The Bugzilla Guide. + </PARA> + </STEP> + <STEP> + <PARA> + In processmail.pl, add "binmode(HANDLE)" before all read() calls. + This may not be necessary, but in some cases the read() under + Win32 doesn't count the EOL's without using a binary read(). + </PARA> + </STEP> + </PROCEDURE> + + </SECTION> + + <SECTION id="addlwintips"> + <TITLE>Additional Windows Tips</TITLE> + <TIP> + <PARA> + From Andrew Pearson: + <BLOCKQUOTE> + <PARA> + "You can make Bugzilla work with Personal Web Server for + Windows 98 and higher, as well as for IIS 4.0. Microsoft has + information available at + <ULINK URL=" http://support.microsoft.com/support/kb/articles/Q231/9/98.ASP"> + http://support.microsoft.com/support/kb/articles/Q231/9/98.ASP</ULINK> + </PARA> + <PARA> + Basically you need to add two String Keys in the + registry at the following location: + </PARA> + <PARA> + HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\ScriptMap + </PARA> + <PARA> + The keys should be called ".pl" and ".cgi", and both + should have a value something like: + <COMMAND>c:/perl/bin/perl.exe "%s" "%s"</COMMAND> + </PARA> + <PARA> + The KB article only talks about .pl, but it goes into + more detail and provides a perl test script. + </PARA> + </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> - <para>Now, you will need to edit <filename>pg_hba.conf</filename> which is - usually located in <filename>/var/lib/pgsql/data/</filename>. In this file, - you will need to add a new line to it as follows:</para> - <para> - <computeroutput>host all bugs 127.0.0.1 255.255.255.255 md5</computeroutput> - </para> - - <para>This means that for TCP/IP (host) connections, allow connections from - '127.0.0.1' to 'all' databases on this server from the 'bugs' user, and use - password authentication (md5) for that user.</para> - <para>Now, you will need to restart PostgreSQL, but you will need to fully - stop and start the server rather than just restarting due to the possibility - of a change to <filename>postgresql.conf</filename>. After the server has - restarted, you will need to edit <filename>localconfig</filename>, finding - the <literal>$db_driver</literal> variable and setting it to - <literal>Pg</literal> and changing the password in <literal>$db_pass</literal> - to the one you picked previously, while setting up the account.</para> - </section> - </section> - </section> - <section> - <title>checksetup.pl</title> - - <para> - Next, rerun <filename>checksetup.pl</filename>. It reconfirms - that all the modules are present, and notices the altered - localconfig file, which it assumes you have edited to your - satisfaction. It compiles the UI templates, - connects to the database using the 'bugs' - user you created and the password you defined, and creates the - 'bugs' database and the tables therein. - </para> - - <para> - After that, it asks for details of an administrator account. Bugzilla - can have multiple administrators - you can create more later - but - it needs one to start off with. - Enter the email address of an administrator, his or her full name, - and a suitable Bugzilla password. - </para> - - <para> - <filename>checksetup.pl</filename> will then finish. You may rerun - <filename>checksetup.pl</filename> at any time if you wish. - </para> - </section> - - - <section id="http"> - <title>Web server</title> - <para> - Configure your web server according to the instructions in the - appropriate section. (If it makes a difference in your choice, - the Bugzilla Team recommends Apache.) To check whether your web server - is correctly configured, try to access <filename>testagent.cgi</filename> - from your web server. If "OK" is displayed, then your configuration - is successful. Regardless of which web server - you are using, however, ensure that sensitive information is - not remotely available by properly applying the access controls in - <xref linkend="security-webserver-access"/>. You can run - <filename>testserver.pl</filename> to check if your web server serves - Bugzilla files as expected. - </para> - - <section id="http-apache"> - <title>Bugzilla using Apache</title> - <para>You have two options for running Bugzilla under Apache - - <link linkend="http-apache-mod_cgi">mod_cgi</link> (the default) and - <link linkend="http-apache-mod_perl">mod_perl</link> (new in Bugzilla - 2.23) - </para> - <section id="http-apache-mod_cgi"> - <title>Apache <productname>httpd</productname> with mod_cgi</title> - - <para> - To configure your Apache web server to work with Bugzilla while using - mod_cgi, do the following: - </para> - - <procedure> - <step> - <para> - Load <filename>httpd.conf</filename> in your editor. - In Fedora and Red Hat Linux, this file is found in - <filename class="directory">/etc/httpd/conf</filename>. - </para> - </step> - - <step> - <para> - Apache uses <computeroutput><Directory></computeroutput> - directives to permit fine-grained permission setting. Add the - following lines to a directive that applies to the location - of your Bugzilla installation. (If such a section does not - exist, you'll want to add one.) In this example, Bugzilla has - been installed at - <filename class="directory">/var/www/html/bugzilla</filename>. - </para> - - <programlisting> - <Directory /var/www/html/bugzilla> - AddHandler cgi-script .cgi - Options +Indexes +ExecCGI - DirectoryIndex index.cgi - AllowOverride Limit - </Directory> - </programlisting> - - <para> - These instructions: allow apache to run .cgi files found - within the bugzilla directory; instructs the server to look - for a file called <filename>index.cgi</filename> if someone - only types the directory name into the browser; and allows - Bugzilla's <filename>.htaccess</filename> files to override - global permissions. - </para> - - <note> - <para> - It is possible to make these changes globally, or to the - directive controlling Bugzilla's parent directory (e.g. - <computeroutput><Directory /var/www/html/></computeroutput>). - Such changes would also apply to the Bugzilla directory... - but they would also apply to many other places where they - may or may not be appropriate. In most cases, including - this one, it is better to be as restrictive as possible - when granting extra access. - </para> - </note> - </step> - - <step> - <para> - <filename>checksetup.pl</filename> can set tighter permissions - on Bugzilla's files and directories if it knows what group the - web server runs as. Find the <computeroutput>Group</computeroutput> - line in <filename>httpd.conf</filename>, place the value found - there in the <replaceable>$webservergroup</replaceable> variable - in <filename>localconfig</filename>, then rerun - <filename>checksetup.pl</filename>. - </para> - </step> - - <step> - <para> - Optional: If Bugzilla does not actually reside in the webspace - directory, but instead has been symbolically linked there, you - will need to add the following to the - <computeroutput>Options</computeroutput> line of the Bugzilla - <computeroutput><Directory></computeroutput> directive - (the same one as in the step above): - </para> - - <programlisting> - +FollowSymLinks - </programlisting> - - <para> - Without this directive, Apache will not follow symbolic links - to places outside its own directory structure, and you will be - unable to run Bugzilla. - </para> - </step> - </procedure> - </section> - <section id="http-apache-mod_perl"> - <title>Apache <productname>httpd</productname> with mod_perl</title> - - <para>Some configuration is required to make Bugzilla work with Apache - and mod_perl</para> - - <procedure> - <step> - <para> - Load <filename>httpd.conf</filename> in your editor. - In Fedora and Red Hat Linux, this file is found in - <filename class="directory">/etc/httpd/conf</filename>. - </para> - </step> - - <step> - <para>Add the following information to your httpd.conf file, substituting - where appropriate with your own local paths.</para> - - <note> - <para>This should be used instead of the <Directory> block - shown above. This should also be above any other <literal>mod_perl</literal> - directives within the <filename>httpd.conf</filename> and must be specified - in the order as below.</para> - </note> - <warning> - <para>You should also ensure that you have disabled <literal>KeepAlive</literal> - support in your Apache install when utilizing Bugzilla under mod_perl</para> - </warning> - - <programlisting> - PerlSwitches -I/var/www/html/bugzilla -I/var/www/html/bugzilla/lib -w -T - PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl - </programlisting> - </step> - - <step> - <para> - <filename>checksetup.pl</filename> can set tighter permissions - on Bugzilla's files and directories if it knows what group the - web server runs as. Find the <computeroutput>Group</computeroutput> - line in <filename>httpd.conf</filename>, place the value found - there in the <replaceable>$webservergroup</replaceable> variable - in <filename>localconfig</filename>, then rerun - <filename>checksetup.pl</filename>. - </para> - </step> - </procedure> - - <para>On restarting Apache, Bugzilla should now be running within the - mod_perl environment. Please ensure you have run checksetup.pl to set - permissions before you restart Apache.</para> - - <note> - <para>Please bear the following points in mind when looking at using - Bugzilla under mod_perl: - <itemizedlist> - <listitem> - <para> - mod_perl support in Bugzilla can take up a HUGE amount of RAM. You could be - looking at 30MB per httpd child, easily. Basically, you just need a lot of RAM. - The more RAM you can get, the better. mod_perl is basically trading RAM for - speed. At least 2GB total system RAM is recommended for running Bugzilla under - mod_perl. - </para> - </listitem> - <listitem> - <para> - Under mod_perl, you have to restart Apache if you make any manual change to - any Bugzilla file. You can't just reload--you have to actually - <emphasis>restart</emphasis> the server (as in make sure it stops and starts - again). You <emphasis>can</emphasis> change localconfig and the params file - manually, if you want, because those are re-read every time you load a page. - </para> - </listitem> - <listitem> - <para> - You must run in Apache's Prefork MPM (this is the default). The Worker MPM - may not work--we haven't tested Bugzilla's mod_perl support under threads. - (And, in fact, we're fairly sure it <emphasis>won't</emphasis> work.) - </para> - </listitem> - <listitem> - <para> - Bugzilla generally expects to be the only mod_perl application running on - your entire server. It may or may not work if there are other applications also - running under mod_perl. It does try its best to play nice with other mod_perl - applications, but it still may have conflicts. - </para> - </listitem> - <listitem> - <para> - It is recommended that you have one Bugzilla instance running under mod_perl - on your server. Bugzilla has not been tested with more than one instance running. - </para> - </listitem> - </itemizedlist> - </para> - </note> - </section> - </section> - - <section id="http-iis"> - <title>Microsoft <productname>Internet Information Services</productname></title> - - <para> - If you are running Bugzilla on Windows and choose to use - Microsoft's <productname>Internet Information Services</productname> - or <productname>Personal Web Server</productname> you will need - to perform a number of other configuration steps as explained below. - You may also want to refer to the following Microsoft Knowledge - Base articles: - <ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;245225">245225</ulink> - <quote>HOW TO: Configure and Test a PERL Script with IIS 4.0, - 5.0, and 5.1</quote> (for <productname>Internet Information - Services</productname>) and - <ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;231998">231998</ulink> - <quote>HOW TO: FP2000: How to Use Perl with Microsoft Personal Web - Server on Windows 95/98</quote> (for <productname>Personal Web - Server</productname>). - </para> - - <para> - You will need to create a virtual directory for the Bugzilla - install. Put the Bugzilla files in a directory that is named - something <emphasis>other</emphasis> than what you want your - end-users accessing. That is, if you want your users to access - your Bugzilla installation through - <quote>http://<yourdomainname>/Bugzilla</quote>, then do - <emphasis>not</emphasis> put your Bugzilla files in a directory - named <quote>Bugzilla</quote>. Instead, place them in a different - location, and then use the IIS Administration tool to create a - Virtual Directory named "Bugzilla" that acts as an alias for the - actual location of the files. When creating that virtual directory, - make sure you add the <quote>Execute (such as ISAPI applications or - CGI)</quote> access permission. - </para> - - <para> - You will also need to tell IIS how to handle Bugzilla's - .cgi files. Using the IIS Administration tool again, open up - the properties for the new virtual directory and select the - Configuration option to access the Script Mappings. Create an - entry mapping .cgi to: - </para> - - <programlisting> -<full path to perl.exe >\perl.exe -x<full path to Bugzilla> -wT "%s" %s - </programlisting> - - <para> - For example: - </para> - - <programlisting> -c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s - </programlisting> - - <note> - <para> - The ActiveState install may have already created an entry for - .pl files that is limited to <quote>GET,HEAD,POST</quote>. If - so, this mapping should be <emphasis>removed</emphasis> as - Bugzilla's .pl files are not designed to be run via a web server. - </para> - </note> - - <para> - IIS will also need to know that the index.cgi should be treated - as a default document. On the Documents tab page of the virtual - directory properties, you need to add index.cgi as a default - document type. If you wish, you may remove the other default - document types for this particular virtual directory, since Bugzilla - doesn't use any of them. - </para> - - <para> - Also, and this can't be stressed enough, make sure that files - such as <filename>localconfig</filename> and your - <filename class="directory">data</filename> directory are - secured as described in <xref linkend="security-webserver-access"/>. - </para> - - </section> - - </section> - - <section id="install-config-bugzilla"> - <title>Bugzilla</title> - - <para> - Your Bugzilla should now be working. Access - <filename>http://<your-bugzilla-server>/</filename> - - you should see the Bugzilla - front page. If not, consult the Troubleshooting section, - <xref linkend="troubleshooting"/>. - </para> - - <note> - <para> - The URL above may be incorrect if you installed Bugzilla into a - subdirectory or used a symbolic link from your web site root to - the Bugzilla directory. - </para> - </note> - - <para> - Log in with the administrator account you defined in the last - <filename>checksetup.pl</filename> run. You should go through - the parameters on the Edit Parameters page - (see link in the footer) and see if there are any you wish to - change. - They key parameters are documented in <xref linkend="parameters"/>; - you should certainly alter - <command>maintainer</command> and <command>urlbase</command>; - you may also want to alter - <command>cookiepath</command> or <command>requirelogin</command>. - </para> - - <para> - This would also be a good time to revisit the - <filename>localconfig</filename> file and make sure that the - names of the priorities, severities, platforms and operating systems - are those you wish to use when you start creating bugs. Remember - to rerun <filename>checksetup.pl</filename> if you change it. - </para> - - <para> - Bugzilla has several optional features which require extra - configuration. You can read about those in - <xref linkend="extraconfig"/>. - </para> - </section> - </section> - - <section id="extraconfig"> - <title>Optional Additional Configuration</title> - - <para> - Bugzilla has a number of optional features. This section describes how - to configure or enable them. - </para> - - <section> - <title>Bug Graphs</title> - - <para>If you have installed the necessary Perl modules you - can start collecting statistics for the nifty Bugzilla - graphs.</para> - - <screen><prompt>bash#</prompt> <command>crontab -e</command></screen> - - <para> - This should bring up the crontab file in your editor. - Add a cron entry like this to run - <filename>collectstats.pl</filename> - daily at 5 after midnight: - </para> - - <programlisting>5 0 * * * cd <your-bugzilla-directory> ; ./collectstats.pl</programlisting> - - <para> - After two days have passed you'll be able to view bug graphs from - the Reports page. - </para> - - <para> - When upgrading Bugzilla, this format may change. - To create new status data, (re)move old data and run the following - commands: - </para> - - <screen> - <prompt>bash$</prompt> - <command>cd <your-bugzilla-directory></command> - <prompt>bash$</prompt> - <command>./collectstats.pl --regenerate</command> - </screen> - - <note> - <para> - Windows does not have 'cron', but it does have the Task - Scheduler, which performs the same duties. There are also - third-party tools that can be used to implement cron, such as - <ulink url="http://www.nncron.ru/">nncron</ulink>. - </para> - </note> - </section> - - <section id="installation-whining-cron"> - <title>The Whining Cron</title> - - <para>What good are - bugs if they're not annoying? To help make them more so you - can set up Bugzilla's automatic whining system to complain at engineers - which leave their bugs in the NEW or REOPENED state without triaging them. - </para> - <para> - This can be done by adding the following command as a daily - crontab entry, in the same manner as explained above for bug - graphs. This example runs it at 12.55am. - </para> - - <programlisting>55 0 * * * cd <your-bugzilla-directory> ; ./whineatnews.pl</programlisting> - - <note> - <para> - Windows does not have 'cron', but it does have the Task - Scheduler, which performs the same duties. There are also - third-party tools that can be used to implement cron, such as - <ulink url="http://www.nncron.ru/">nncron</ulink>. - </para> - </note> - </section> - - <section id="installation-whining"> - <title>Whining</title> - - <para> - As of Bugzilla 2.20, users can configure Bugzilla to regularly annoy - them at regular intervals, by having Bugzilla execute saved searches - at certain times and emailing the results to the user. This is known - as "Whining". The process of configuring Whining is described - in <xref linkend="whining"/>, but for it to work a Perl script must be - executed at regular intervals. - </para> - - <para> - This can be done by adding the following command as a daily - crontab entry, in the same manner as explained above for bug - graphs. This example runs it every 15 minutes. - </para> - - <programlisting>*/15 * * * * cd <your-bugzilla-directory> ; ./whine.pl</programlisting> - - <note> - <para> - Whines can be executed as often as every 15 minutes, so if you specify - longer intervals between executions of whine.pl, some users may not - be whined at as often as they would expect. Depending on the person, - this can either be a very Good Thing or a very Bad Thing. - </para> - </note> - - <note> - <para> - Windows does not have 'cron', but it does have the Task - Scheduler, which performs the same duties. There are also - third-party tools that can be used to implement cron, such as - <ulink url="http://www.nncron.ru/">nncron</ulink>. - </para> - </note> - </section> - - <section id="apache-addtype"> - <title>Serving Alternate Formats with the right MIME type</title> - - <para> - Some Bugzilla pages have alternate formats, other than just plain - <acronym>HTML</acronym>. In particular, a few Bugzilla pages can - output their contents as either <acronym>XUL</acronym> (a special - Mozilla format, that looks like a program <acronym>GUI</acronym>) - or <acronym>RDF</acronym> (a type of structured <acronym>XML</acronym> - that can be read by various programs). - </para> - <para> - In order for your users to see these pages correctly, Apache must - send them with the right <acronym>MIME</acronym> type. To do this, - add the following lines to your Apache configuration, either in the - <computeroutput><VirtualHost></computeroutput> section for your - Bugzilla, or in the <computeroutput><Directory></computeroutput> - section for your Bugzilla: - </para> - <para> - <screen>AddType application/vnd.mozilla.xul+xml .xul -AddType application/rdf+xml .rdf</screen> - </para> - </section> - </section> - - <section id="multiple-bz-dbs"> - <title>Multiple Bugzilla databases with a single installation</title> - - <para>The previous instructions referred to a standard installation, with - one unique Bugzilla database. However, you may want to host several - distinct installations, without having several copies of the code. This is - possible by using the PROJECT environment variable. When accessed, - Bugzilla checks for the existence of this variable, and if present, uses - its value to check for an alternative configuration file named - <filename>localconfig.<PROJECT></filename> in the same location as - the default one (<filename>localconfig</filename>). It also checks for - customized templates in a directory named - <filename><PROJECT></filename> in the same location as the - default one (<filename>template/<langcode></filename>). By default - this is <filename>template/en/default</filename> so PROJECT's templates - would be located at <filename>template/en/PROJECT</filename>.</para> - - <para>To set up an alternate installation, just export PROJECT=foo before - running <command>checksetup.pl</command> for the first time. It will - result in a file called <filename>localconfig.foo</filename> instead of - <filename>localconfig</filename>. Edit this file as described above, with - reference to a new database, and re-run <command>checksetup.pl</command> - to populate it. That's all.</para> - - <para>Now you have to configure the web server to pass this environment - variable when accessed via an alternate URL, such as virtual host for - instance. The following is an example of how you could do it in Apache, - other Webservers may differ. -<programlisting> -<VirtualHost 212.85.153.228:80> - ServerName foo.bar.baz - SetEnv PROJECT foo - Alias /bugzilla /var/www/bugzilla -</VirtualHost> -</programlisting> - </para> - - <para>Don't forget to also export this variable before accessing Bugzilla - by other means, such as cron tasks for instance.</para> - </section> - - <section id="os-specific"> - <title>OS-Specific Installation Notes</title> - - <para>Many aspects of the Bugzilla installation can be affected by the - operating system you choose to install it on. Sometimes it can be made - easier and others more difficult. This section will attempt to help you - understand both the difficulties of running on specific operating systems - and the utilities available to make it easier. - </para> - - <para>If you have anything to add or notes for an operating system not - covered, please file a bug in &bzg-bugs;. - </para> - - <section id="os-win32"> - <title>Microsoft Windows</title> - <para> - Making Bugzilla work on Windows is more difficult than making it - work on Unix. For that reason, we still recommend doing so on a Unix - based system such as GNU/Linux. That said, if you do want to get - Bugzilla running on Windows, you will need to make the following - adjustments. A detailed step-by-step - <ulink url="http://www.bugzilla.org/docs/win32install.html"> - installation guide for Windows</ulink> is also available - if you need more help with your installation. - </para> - - <section id="win32-perl"> - <title>Win32 Perl</title> - <para> - Perl for Windows can be obtained from - <ulink url="http://www.activestate.com/">ActiveState</ulink>. - You should be able to find a compiled binary at <ulink - url="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/" />. - The following instructions assume that you are using version - 5.8.1 of ActiveState. - </para> - - <note> - <para> - These instructions are for 32-bit versions of Windows. If you are - using a 64-bit version of Windows, you will need to install 32-bit - Perl in order to install the 32-bit modules as described below. - </para> - </note> - - </section> - - <section id="win32-perl-modules"> - <title>Perl Modules on Win32</title> - - <para> - Bugzilla on Windows requires the same perl modules found in - <xref linkend="install-perlmodules"/>. The main difference is that - windows uses <glossterm linkend="gloss-ppm">PPM</glossterm> instead - of CPAN. ActiveState provides a GUI to manage Perl modules. We highly - recommend that you use it. If you prefer to use ppm from the - command-line, type: - </para> - - <programlisting> -C:\perl> <command>ppm install <module name></command> - </programlisting> - - <para> - The best source for the Windows PPM modules needed for Bugzilla - is probably the theory58S website, which you can add to your list - of repositories as follows (for Perl 5.8.x): - </para> - - <programlisting> -<command>ppm repo add theory58S http://theoryx5.uwinnipeg.ca/ppms/</command> - </programlisting> - - <para> - If you are using Perl 5.10.x, you cannot use the same PPM modules as Perl - 5.8.x as they are incompatible. In this case, you should add the following - repository: - </para> - <programlisting> -<command>ppm repo add theory58S http://cpan.uwinnipeg.ca/PPMPackages/10xx/</command> - </programlisting> - - <note> - <para> - In versions prior to 5.8.8 build 819 of PPM the command is - <programlisting> -<command>ppm repository add theory58S http://theoryx5.uwinnipeg.ca/ppms/</command> - </programlisting> - </para> - </note> - <note> - <para> - The PPM repository stores modules in 'packages' that may have - a slightly different name than the module. If retrieving these - modules from there, you will need to pay attention to the information - provided when you run <command>checksetup.pl</command> as it will - tell you what package you'll need to install. - </para> - </note> - - <tip> - <para> - If you are behind a corporate firewall, you will need to let the - ActiveState PPM utility know how to get through it to access - the repositories by setting the HTTP_proxy system environmental - variable. For more information on setting that variable, see - the ActiveState documentation. - </para> - </tip> - </section> - - <section id="win32-code-changes"> - <title>Code changes required to run on Win32</title> - - <para> - Bugzilla on Win32 is supported out of the box from version 2.20; this - means that no code changes are required to get Bugzilla running. - </para> - - </section> - - <section id="win32-http"> - <title>Serving the web pages</title> - - <para> - As is the case on Unix based systems, any web server should - be able to handle Bugzilla; however, the Bugzilla Team still - recommends Apache whenever asked. No matter what web server - you choose, be sure to pay attention to the security notes - in <xref linkend="security-webserver-access"/>. More - information on configuring specific web servers can be found - in <xref linkend="http"/>. - </para> - - <note> - <para> - If using Apache on windows, you can set the <ulink - url="http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource">ScriptInterpreterSource</ulink> - directive in your Apache config to avoid having to modify - the first line of every script to contain your path to Perl - instead of <filename>/usr/bin/perl</filename>. When setting - <filename>ScriptInterpreterSource</filename>, do not forget - to specify the <command>-T</command> flag to enable the taint - mode. For example: <command>C:\Perl\bin\perl.exe -T</command>. - </para> - </note> - - </section> - - <section id="win32-email"> - <title>Sending Email</title> - - <para> - To enable Bugzilla to send email on Windows, the server running the - Bugzilla code must be able to connect to, or act as, an SMTP server. - </para> - - </section> - </section> - - <section id="os-macosx"> - <title><productname>Mac OS X</productname></title> - - <para>Making Bugzilla work on Mac OS X requires the following - adjustments.</para> - - <section id="macosx-sendmail"> - <title>Sendmail</title> - - <para>In Mac OS X 10.3 and later, - <ulink url="http://www.postfix.org/">Postfix</ulink> - is used as the built-in email server. Postfix provides an executable - that mimics sendmail enough to fool Bugzilla, as long as Bugzilla can - find it.</para> - - <para>As of version 2.20, Bugzilla will be able to find the fake - sendmail executable without any assistance. However, you will have - to turn on the sendmailnow parameter before you do anything that would - result in email being sent. For more information, see the description - of the sendmailnow parameter in <xref linkend="parameters"/>.</para> - - </section> - - <section id="macosx-libraries"> - <title>Libraries & Perl Modules on Mac OS X</title> - - <para>Apple does not include the GD library with Mac OS X. Bugzilla - needs this for bug graphs.</para> - - <para>You can use DarwinPorts (<ulink url="http://darwinports.com/"/>) - or Fink (<ulink url="http://sourceforge.net/projects/fink/"/>), both - of which are similar in nature to the CPAN installer, but install - common unix programs.</para> - - <para>Follow the instructions for setting up DarwinPorts or Fink. - Once you have one installed, you'll want to use it to install the - <filename>gd2</filename> package. - </para> - - <para>Fink will prompt you for a number of dependencies, type 'y' and hit - enter to install all of the dependencies and then watch it work. You will - then be able to use <glossterm linkend="gloss-cpan">CPAN</glossterm> to - install the GD Perl module. - </para> - - <note> - <para>To prevent creating conflicts with the software that Apple - installs by default, Fink creates its own directory tree at - <filename class="directory">/sw</filename> where it installs most of - the software that it installs. This means your libraries and headers - will be at <filename class="directory">/sw/lib</filename> and - <filename class="directory">/sw/include</filename> instead of - <filename class="directory">/usr/lib</filename> and - <filename class="directory">/usr/include</filename>. When the - Perl module config script asks where your <filename>libgd</filename> - is, be sure to tell it - <filename class="directory">/sw/lib</filename>. - </para> - </note> - - <para>Also available via DarwinPorts and Fink is - <filename>expat</filename>. After installing the expat package, you - will be able to install XML::Parser using CPAN. If you use fink, there - is one caveat. Unlike recent versions of - the GD module, XML::Parser doesn't prompt for the location of the - required libraries. When using CPAN, you will need to use the following - command sequence: - </para> - - <screen> -# perl -MCPAN -e'look XML::Parser' <co id="macosx-look"/> -# perl Makefile.PL EXPATLIBPATH=/sw/lib EXPATINCPATH=/sw/include -# make; make test; make install <co id="macosx-make"/> -# exit <co id="macosx-exit"/> - </screen> - <calloutlist> - <callout arearefs="macosx-look macosx-exit"> - <para>The look command will download the module and spawn a - new shell with the extracted files as the current working directory. - The exit command will return you to your original shell. - </para> - </callout> - <callout arearefs="macosx-make"> - <para>You should watch the output from these make commands, - especially <quote>make test</quote> as errors may prevent - XML::Parser from functioning correctly with Bugzilla. - </para> - </callout> - </calloutlist> - </section> - </section> - - <section id="os-linux"> - <title>Linux Distributions</title> - <para>Many Linux distributions include Bugzilla and its - dependencies in their native package management systems. - Installing Bugzilla with root access on any Linux system - should be as simple as finding the Bugzilla package in the - package management application and installing it using the - normal command syntax. Several distributions also perform - the proper web server configuration automatically on installation. - </para> - <para>Please consult the documentation of your Linux - distribution for instructions on how to install packages, - or for specific instructions on installing Bugzilla with - native package management tools. There is also a - <ulink url="http://wiki.mozilla.org/Bugzilla:Linux_Distro_Installation"> - Bugzilla Wiki Page</ulink> for distro-specific installation - notes. - </para> - </section> - </section> - - - <section id="nonroot"> - <title>UNIX (non-root) Installation Notes</title> - - <section> - <title>Introduction</title> - - <para>If you are running a *NIX OS as non-root, either due - to lack of access (web hosts, for example) or for security - reasons, this will detail how to install Bugzilla on such - a setup. It is recommended that you read through the - <xref linkend="installation" /> - first to get an idea on the installation steps required. - (These notes will reference to steps in that guide.)</para> - - </section> - - <section> - <title>MySQL</title> - - <para>You may have MySQL installed as root. If you're - setting up an account with a web host, a MySQL account - needs to be set up for you. From there, you can create - the bugs account, or use the account given to you.</para> - - <warning> - <para>You may have problems trying to set up - <command>GRANT</command> permissions to the database. - If you're using a web host, chances are that you have a - separate database which is already locked down (or one big - database with limited/no access to the other areas), but you - may want to ask your system administrator what the security - settings are set to, and/or run the <command>GRANT</command> - command for you.</para> - - <para>Also, you will probably not be able to change the MySQL - root user password (for obvious reasons), so skip that - step.</para> - </warning> - - <section> - <title>Running MySQL as Non-Root</title> - <section> - <title>The Custom Configuration Method</title> - <para>Create a file .my.cnf in your - home directory (using /home/foo in this example) - as follows....</para> - <programlisting> -[mysqld] -datadir=/home/foo/mymysql -socket=/home/foo/mymysql/thesock -port=8081 - -[mysql] -socket=/home/foo/mymysql/thesock -port=8081 - -[mysql.server] -user=mysql -basedir=/var/lib - -[safe_mysqld] -err-log=/home/foo/mymysql/the.log -pid-file=/home/foo/mymysql/the.pid - </programlisting> - </section> - <section> - <title>The Custom Built Method</title> - - <para>You can install MySQL as a not-root, if you really need to. - Build it with PREFIX set to <filename class="directory">/home/foo/mysql</filename>, - or use pre-installed executables, specifying that you want - to put all of the data files in <filename class="directory">/home/foo/mysql/data</filename>. - If there is another MySQL server running on the system that you - do not own, use the -P option to specify a TCP port that is not - in use.</para> - </section> - - <section> - <title>Starting the Server</title> - <para>After your mysqld program is built and any .my.cnf file is - in place, you must initialize the databases (ONCE).</para> - <screen> - <prompt>bash$</prompt> - <command>mysql_install_db</command> - </screen> - <para>Then start the daemon with</para> - <screen> - <prompt>bash$</prompt> - <command>safe_mysql &</command> - </screen> - <para>After you start mysqld the first time, you then connect to - it as "root" and <command>GRANT</command> permissions to other - users. (Again, the MySQL root account has nothing to do with - the *NIX root account.)</para> - - <note> - <para>You will need to start the daemons yourself. You can either - ask your system administrator to add them to system startup files, or - add a crontab entry that runs a script to check on these daemons - and restart them if needed.</para> - </note> - - <warning> - <para>Do NOT run daemons or other services on a server without first - consulting your system administrator! Daemons use up system resources - and running one may be in violation of your terms of service for any - machine on which you are a user!</para> - </warning> - </section> - </section> - - </section> - - <section> - <title>Perl</title> - - <para> - On the extremely rare chance that you don't have Perl on - the machine, you will have to build the sources - yourself. The following commands should get your system - installed with your own personal version of Perl: - </para> - - <screen> - <prompt>bash$</prompt> - <command>wget http://perl.com/CPAN/src/stable.tar.gz</command> - <prompt>bash$</prompt> - <command>tar zvxf stable.tar.gz</command> - <prompt>bash$</prompt> - <command>cd perl-5.8.1</command> (or whatever the version of Perl is called) - <prompt>bash$</prompt> - <command>sh Configure -de -Dprefix=/home/foo/perl</command> - <prompt>bash$</prompt> - <command>make && make test && make install</command> - </screen> - - <para> - Once you have Perl installed into a directory (probably - in <filename class="directory">~/perl/bin</filename>), you will need to - install the Perl Modules, described below. - </para> - </section> - - <section id="install-perlmodules-nonroot"> - <title>Perl Modules</title> - - <para> - Installing the Perl modules as a non-root user is accomplished by - running the <filename>install-module.pl</filename> - script. For more details on this script, see - <ulink url="api/install-module.html"><filename>install-module.pl</filename> - documentation</ulink> - </para> - </section> - - <section> - <title>HTTP Server</title> - - <para>Ideally, this also needs to be installed as root and - run under a special web server account. As long as - the web server will allow the running of *.cgi files outside of a - cgi-bin, and a way of denying web access to certain files (such as a - .htaccess file), you should be good in this department.</para> - - <section> - <title>Running Apache as Non-Root</title> - - <para>You can run Apache as a non-root user, but the port will need - to be set to one above 1024. If you type <command>httpd -V</command>, - you will get a list of the variables that your system copy of httpd - uses. One of those, namely HTTPD_ROOT, tells you where that - installation looks for its config information.</para> - - <para>From there, you can copy the config files to your own home - directory to start editing. When you edit those and then use the -d - option to override the HTTPD_ROOT compiled into the web server, you - get control of your own customized web server.</para> - - <note> - <para>You will need to start the daemons yourself. You can either - ask your system administrator to add them to system startup files, or - add a crontab entry that runs a script to check on these daemons - and restart them if needed.</para> - </note> - - <warning> - <para>Do NOT run daemons or other services on a server without first - consulting your system administrator! Daemons use up system resources - and running one may be in violation of your terms of service for any - machine on which you are a user!</para> - </warning> - </section> - </section> - - <section> - <title>Bugzilla</title> - - <para> - When you run <command>./checksetup.pl</command> to create - the <filename>localconfig</filename> file, it will list the Perl - modules it finds. If one is missing, go back and double-check the - module installation from <xref linkend="install-perlmodules-nonroot"/>, - then delete the <filename>localconfig</filename> file and try again. - </para> - - <warning> - <para>One option in <filename>localconfig</filename> you - might have problems with is the web server group. If you can't - successfully browse to the <filename>index.cgi</filename> (like - a Forbidden error), you may have to relax your permissions, - and blank out the web server group. Of course, this may pose - as a security risk. Having a properly jailed shell and/or - limited access to shell accounts may lessen the security risk, - but use at your own risk.</para> - </warning> - - <section id="suexec"> - <title>suexec or shared hosting</title> - - <para>If you are running on a system that uses suexec (most shared - hosting environments do this), you will need to set the - <emphasis>webservergroup</emphasis> value in <filename>localconfig</filename> - to match <emphasis>your</emphasis> primary group, rather than the one - the web server runs under. You will need to run the following - shell commands after running <command>./checksetup.pl</command>, - every time you run it (or modify <filename>checksetup.pl</filename> - to do them for you via the system() command). - <programlisting> for i in docs graphs images js skins; do find $i -type d -exec chmod o+rx {} \; ; done - for i in jpg gif css js png html rdf xul; do find . -name \*.$i -exec chmod o+r {} \; ; done - find . -name .htaccess -exec chmod o+r {} \; - chmod o+x . data data/webdot</programlisting> - Pay particular attention to the number of semicolons and dots. - They are all important. A future version of Bugzilla will - hopefully be able to do this for you out of the box.</para> - </section> - </section> - </section> - -</chapter> <!-- Keep this comment at the end of the file Local variables: mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-namecase-general:t +sgml-general-insert-case:upper +sgml-minimize-attributes:nil sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t sgml-indent-step:2 +sgml-indent-data:t +sgml-parent-document:nil +sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t End: --> |