2.2. Configuration

2.2.2.2.1. Allow large attachments and many comments

By default, MySQL will only allow you to insert things into the database that are smaller than 1MB. Attachments may be larger than this. Also, Bugzilla combines all comments on a single bug into one field for full-text searching, and the combination of all comments on a single bug could in some cases be larger than 1MB.

To change MySQL's default, you need to edit your MySQL configuration file, which is usually /etc/my.cnf on Linux. We recommend that you allow at least 4MB packets by adding the "max_allowed_packet" parameter to your MySQL configuration in the "[mysqld]" section, like this:

[mysqld]
# Allow packets up to 4MB
max_allowed_packet=4M
          

2.2.2.2.2. Allow small words in full-text indexes

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".

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 /etc/my.cnf according to the example below:

  [mysqld]
  # Allow small words in full-text indexes
  ft_min_word_len=2

Rebuilding the indexes can be done based on documentation found at http://www.mysql.com/doc/en/Fulltext_Fine-tuning.html.

2.2.2.2.3. Add a user to MySQL

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 localconfig; if you changed those, you need to modify the SQL command appropriately. You will need the $db_pass password you set in localconfig in Section 2.2.1.

We use an SQL GRANT command to create a "bugs" user. 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.

Run the mysql command-line client and enter:

    mysql> GRANT SELECT, INSERT,
           UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES,
           CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.*
           TO bugs@localhost IDENTIFIED BY '$db_pass';
    mysql> FLUSH PRIVILEGES;
          

2.2.2.2.4. Permit attachments table to grow beyond 4GB

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.

After you have completed the rest of the installation (or at least the database setup parts), you should run the MySQL command-line client and enter the following, replacing $bugs_db with your Bugzilla database name (bugs by default):

    mysql> use $bugs_db
    mysql> ALTER TABLE attachments
           AVG_ROW_LENGTH=1000000, MAX_ROWS=20000;
          

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.

This does not affect Big Files, attachments that are stored directly on disk instead of in the database.

2.2.2.3.1. Add a User to PostgreSQL

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 localconfig; if you changed those, you need to modify the commands appropriately. You will need the $db_pass password you set in localconfig in Section 2.2.1.

On most systems, to create the user in PostgreSQL, you will need to login as the root user, and then

 bash# su - postgres

As the postgres user, you then need to create a new user:

 bash$ createuser -U postgres -dRSP bugs

When asked for a password, provide the password which will be set as $db_pass in localconfig. The created user will not be a superuser (-S) and will not be able to create new users (-R). He will only have the ability to create databases (-d).

2.2.2.3.2. Configure PostgreSQL

Now, you will need to edit pg_hba.conf which is usually located in /var/lib/pgsql/data/. In this file, you will need to add a new line to it as follows:

host all bugs 127.0.0.1 255.255.255.255 md5

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.

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 postgresql.conf. After the server has restarted, you will need to edit localconfig, finding the $db_driver variable and setting it to Pg and changing the password in $db_pass to the one you picked previously, while setting up the account.

2.2.2.4.1. Create a New Tablespace

You can use the existing tablespace or create a new one for Bugzilla. To create a new tablespace, run the following command:

    CREATE TABLESPACE bugs
    DATAFILE '$path_to_datafile' SIZE 500M
    AUTOEXTEND ON NEXT 30M MAXSIZE UNLIMITED
          

Here, the name of the tablespace is 'bugs', but you can choose another name. $path_to_datafile is the path to the file containing your database, for instance /u01/oradata/bugzilla.dbf. The initial size of the database file is set in this example to 500 Mb, with an increment of 30 Mb everytime we reach the size limit of the file.

2.2.2.4.2. Add a User to Oracle

The user name and password must match what you set in localconfig ($db_user and $db_pass, respectively). Here, we assume that the user name is 'bugs' and the tablespace name is the same as above.

    CREATE USER bugs
    IDENTIFIED BY "$db_pass"
    DEFAULT TABLESPACE bugs
    TEMPORARY TABLESPACE TEMP
    PROFILE DEFAULT;
    -- GRANT/REVOKE ROLE PRIVILEGES
    GRANT CONNECT TO bugs;
    GRANT RESOURCE TO bugs;
    -- GRANT/REVOKE SYSTEM PRIVILEGES
    GRANT UNLIMITED TABLESPACE TO bugs;
    GRANT EXECUTE ON CTXSYS.CTX_DDL TO bugs;
          

2.2.2.4.3. Configure the Web Server

If you use Apache, append these lines to httpd.conf to set ORACLE_HOME and LD_LIBRARY_PATH. For instance:

    SetEnv ORACLE_HOME /u01/app/oracle/product/10.2.0/
    SetEnv LD_LIBRARY_PATH /u01/app/oracle/product/10.2.0/lib/
          

When this is done, restart your web server.

2.2.4.1.1. Apache httpd with mod_cgi

To configure your Apache web server to work with Bugzilla while using mod_cgi, do the following:

2.2.4.1.2. Apache httpd with mod_perl

Some configuration is required to make Bugzilla work with Apache and mod_perl

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.

Please bear the following points in mind when looking at using Bugzilla under mod_perl: 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. 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 restart the server (as in make sure it stops and starts again). You can change localconfig and the params file manually, if you want, because those are re-read every time you load a page. 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 won't work.) 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. 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.