diff options
Diffstat (limited to 'docs/en/xml/installation.xml')
| -rw-r--r-- | docs/en/xml/installation.xml | 2040 |
1 files changed, 2040 insertions, 0 deletions
diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml new file mode 100644 index 000000000..0373ab72c --- /dev/null +++ b/docs/en/xml/installation.xml @@ -0,0 +1,2040 @@ +<!-- <!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> + + <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> + + <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> + + <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> + + <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> + + <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> + + <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> + + <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> + + <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-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-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: +--> |