Skip to content

bugzilla
bugzilla
Commit c32ed779 authored by mozilla%colinogilvie.co.uk's avatar mozilla%colinogilvie.co.uk
Browse files
Options

Bug 297475: Add docs about how to install and configure Bugzilla using PostgreSQL

Patch by Colin Ogilvie <colin.ogilvie@gmail.com> (with info from mkanat) r=mkanat
parent 257634d7
Hide whitespace changes
Inline Side-by-side
Showing with 205 additions and 131 deletions
docs/xml/installation.xml
View file @ c32ed779
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> --> <!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
<!-- $Id: installation.xml,v 1.101 2005/07/25 12:50:49 mozilla%colinogilvie.co.uk Exp $ --> <!-- $Id: installation.xml,v 1.102 2005/07/31 23:35:40 mozilla%colinogilvie.co.uk Exp $ -->
<chapter id="installing-bugzilla"> <chapter id="installing-bugzilla">
<title>Installing Bugzilla</title> <title>Installing Bugzilla</title>
...@@ -95,7 +95,7 @@ ...@@ -95,7 +95,7 @@
If you don't have it and your OS doesn't provide official packages, If you don't have it and your OS doesn't provide official packages,
visit <ulink url="http://www.perl.com"/>. visit <ulink url="http://www.perl.com"/>.
Although Bugzilla runs with Perl &min-perl-ver;, Although Bugzilla runs with Perl &min-perl-ver;,
it's a good idea to be using the latest stable version. it's a good idea to be using the latest stable version.
</para> </para>
</section> </section>
...@@ -611,174 +611,248 @@ ...@@ -611,174 +611,248 @@
</para> </para>
</section> </section>
<section id="mysql"> <section id="database-engine">
<title>MySQL</title> <title>Database Server</title>
<para>This section deals with configuring your database server for use
with Bugzilla. Currently <xref linkend="mysql"/> and
<xref linkend="postgresql"/> are available.</para>
<section id="mysql">
<title>MySQL</title>
<caution> <caution>
<para> <para>
MySQL's default configuration is very insecure. MySQL's default configuration is very insecure.
<xref linkend="security-mysql"/> has some good information for <xref linkend="security-mysql"/> has some good information for
improving your installation's security. improving your installation's security.
</para> </para>
</caution> </caution>
<section id="install-setupdatabase">
<title>Allow large attachments</title>
<para> <section id="install-setupdatabase">
By default, MySQL will only accept packets up to 64Kb in size. <title>Allow large attachments</title>
If you want to have attachments larger than this, you will need
to modify your <filename>/etc/my.cnf</filename> as below. <para>
</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>
<para> <para>
If you are using MySQL 4.0 or newer, enter: If you are using MySQL 4.0 or newer, enter:
</para> </para>
<screen> [mysqld] <screen> [mysqld]
# Allow packets up to 1M # Allow packets up to 1M
max_allowed_packet=1M</screen> max_allowed_packet=1M</screen>
<para> <para>
If you are using an older version of MySQL, enter: If you are using an older version of MySQL, enter:
</para> </para>
<screen> [mysqld] <screen> [mysqld]
# Allow packets up to 1M # Allow packets up to 1M
set-variable = max_allowed_packet=1M</screen> set-variable = 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> <para>
This does not affect Big Files, attachments that are stored directly There is also a parameter in Bugzilla called 'maxattachmentsize'
on disk instead of in the database. Their maximum size is (default = 1000 Kb) that controls the maximum allowable attachment
controlled using the 'maxlocalattachment' parameter. size. Attachments larger than <emphasis>either</emphasis> the
'max_allowed_packet' or 'maxattachmentsize' value will not be
accepted by Bugzilla.
</para> </para>
</note>
</section>
<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>
<section> <para>MySQL can be configured to index those words by setting the
<title>Allow small words in full-text indexes</title> 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>
<para>By default, words must be at least four characters in length according to the example below:</para>
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] <screen> [mysqld]
# Allow small words in full-text indexes # Allow small words in full-text indexes
ft_min_word_len=2</screen> ft_min_word_len=2</screen>
<para>Rebuilding the indexes can be done based on documentation found at <para>Rebuilding the indexes can be done based on documentation found at
<ulink url="http://www.mysql.com/doc/en/Fulltext_Fine-tuning.html"/>. <ulink url="http://www.mysql.com/doc/en/Fulltext_Fine-tuning.html"/>.
</para> </para>
<note>
<para>
The ft_min_word_len parameter is only suported in MySQL v4 or higher.
</para>
</note>
</section>
<section>
<title>Permit attachments table to grow beyond 4GB</title>
<note>
<para> <para>
The ft_min_word_len parameter is only suported in MySQL v4 or higher. 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>
</note>
</section>
<section> <para>
<title>Permit attachments table to grow beyond 4GB</title> Run the <filename>MySQL</filename> command-line client and
enter:
</para>
<para> <screen> <prompt>mysql&gt;</prompt> ALTER TABLE attachments
By default, MySQL will limit the size of a table to 4GB. AVG_ROW_LENGTH=1000000, MAX_ROWS=20000;
This limit is present even if the underlying filesystem </screen>
has no such limit. To set a higher limit, follow these
instructions.
</para>
<para> <para>
Run the <filename>MySQL</filename> command-line client and The above command will change the limit to 20GB. Mysql will have
enter: to make a temporary copy of your entire table to do this. Ideally,
</para> you should do this when your attachments table is still small.
</para>
<screen> <prompt>mysql&gt;</prompt> ALTER TABLE attachments <note>
AVG_ROW_LENGTH=1000000, MAX_ROWS=20000; <para>
</screen> This does not affect Big Files, attachments that are stored directly
on disk instead of in the database.
</para>
</note>
</section>
<section id="install-setupdatabase-adduser">
<title>Add a user to MySQL</title>
<para> <para>
The above command will change the limit to 20GB. Mysql will have You need to add a new MySQL user for Bugzilla to use.
to make a temporary copy of your entire table to do this. Ideally, (It's not safe to have Bugzilla use the MySQL root account.)
you should do this when your attachments table is still small. The following instructions assume the defaults in
</para> <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>
<note>
<para> <para>
This does not affect Big Files, attachments that are stored directly We use an SQL <command>GRANT</command> command to create
on disk instead of in the database. 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>
</note>
<para>
Run the <filename>mysql</filename> command-line client.
</para>
<para>
If you are using MySQL 4.0 or newer, enter:
</para>
<screen> <prompt>mysql&gt;</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&gt;</prompt> FLUSH PRIVILEGES;</screen>
<para>
If you are using an older version of MySQL,the
<computeroutput>LOCK TABLES</computeroutput> and
<computeroutput>CREATE TEMPORARY TABLES</computeroutput>
permissions will be unavailable and should be removed from
the permissions list. In this case, the following command
line can be used:
</para>
<screen> <prompt>mysql&gt;</prompt> GRANT SELECT, INSERT,
UPDATE, DELETE, INDEX, ALTER, CREATE, DROP,
REFERENCES ON bugs.* TO bugs@localhost IDENTIFIED BY
'<replaceable>$db_pass</replaceable>';
<prompt>mysql&gt;</prompt> FLUSH PRIVILEGES;</screen>
</section>
</section> </section>
<section id="install-setupdatabase-adduser"> <section id="postgresql">
<title>Add a user to MySQL</title> <title>PostgreSQL</title>
<note>
<para>Note if you are using PostgreSQL 8.0.1 or higher, then you
will require to use a version of DBD::Pg which is equal to or
greater than version 1.41
</para>
</note>
<section>
<title>Add a User to PostgreSQL</title>
<para> <para>You need to add a new user to PostgreSQL for the Bugzilla
You need to add a new MySQL user for Bugzilla to use. application to use when accessing the database. The following instructions
(It's not safe to have Bugzilla use the MySQL root account.) assume the defaults in <filename>localconfig</filename>; if you
The following instructions assume the defaults in changed those, you need to modify the commands appropriately. You will
<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 need the <replaceable>$db_pass</replaceable> password you
set in <filename>localconfig</filename> in set in <filename>localconfig</filename> in
<xref linkend="localconfig"/>. <xref linkend="localconfig"/>.</para>
</para>
<para> <para>On most systems, to create the user in PostgreSQL, you will need to
We use an SQL <command>GRANT</command> command to create login as the root user, and then</para>
a <quote>bugs</quote> user. This also restricts the
<quote>bugs</quote>user to operations within a database <screen> <prompt>bash#</prompt> su - postgres</screen>
called <quote>bugs</quote>, and only allows the account
to connect from <quote>localhost</quote>. Modify it to <para>As the postgres user, you then need to create a new user: </para>
reflect your setup if you will be connecting from another
machine or as a different user. <screen> <prompt>bash$</prompt> createuser -U postgres -dAP bugs</screen>
</para>
<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>
<para> <section>
Run the <filename>mysql</filename> command-line client. <title>Configure PostgreSQL</title>
</para>
<para> <para>Now, you will need to edit <filename>pg_hba.conf</filename> which is
If you are using MySQL 4.0 or newer, enter: usually located in <filename>/var/lib/pgsql/data/</filename>. In this file,
</para> you will need to add a new line to it as follows:</para>
<screen> <prompt>mysql&gt;</prompt> GRANT SELECT, INSERT, <computeroutput>host all bugs 127.0.0.1 255.255.255.255 md5</computeroutput>
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&gt;</prompt> FLUSH PRIVILEGES;</screen>
<para> <para>This means that for TCP/IP (host) connections, allow connections from
If you are using an older version of MySQL,the '127.0.0.1' to 'all' databases on this server from the 'bugs' user, and use
<computeroutput>LOCK TABLES</computeroutput> and password authentication (md5) for that user.</para>
<computeroutput>CREATE TEMPORARY TABLES</computeroutput>
permissions will be unavailable and should be removed from
the permissions list. In this case, the following command
line can be used:
</para>
<screen> <prompt>mysql&gt;</prompt> GRANT SELECT, INSERT, <para>If you are using <emphasis role="bold">versions of PostgreSQL
UPDATE, DELETE, INDEX, ALTER, CREATE, DROP, before version 8</emphasis>, you may also need to edit <filename>postgresql.conf</filename>
REFERENCES ON bugs.* TO bugs@localhost IDENTIFIED BY , also usually found in the <filename>/var/lib/pgsql/data/</filename> folder.
'<replaceable>$db_pass</replaceable>'; You will need to make a single line change, changing</para>
<prompt>mysql&gt;</prompt> FLUSH PRIVILEGES;</screen>
</section> <computeroutput># tcpip_socket = false</computeroutput>
</section>
<para>to</para>
<computeroutput>tcpip_socket = true</computeroutput>
<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> <section>
<title>checksetup.pl</title> <title>checksetup.pl</title>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment