diff options
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: --> |