diff options
Diffstat (limited to 'docs/en/rst/installation.rst')
| -rw-r--r-- | docs/en/rst/installation.rst | 1813 |
1 files changed, 0 insertions, 1813 deletions
diff --git a/docs/en/rst/installation.rst b/docs/en/rst/installation.rst deleted file mode 100644 index 5c0aa2de5..000000000 --- a/docs/en/rst/installation.rst +++ /dev/null @@ -1,1813 +0,0 @@ -.. highlight:: console - -.. _installing-bugzilla: - -=================== -Installing Bugzilla -=================== - -.. _installation: - -Installation -############ - -.. note:: If you just want to *use* 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. - -The Bugzilla server software is usually installed on Linux or -Solaris. -If you are installing on another OS, check :ref:`os-specific` -before you start your installation to see if there are any special -instructions. - -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. - -.. warning:: The installation process may make your machine insecure for - short periods of time. Make sure there is a firewall between you - and the Internet. - -You are strongly recommended to make a backup of your system -before installing Bugzilla (and at regular intervals thereafter :-). - -In outline, the installation proceeds as follows: - -#. :ref:`Install Perl <install-perl>` - (|min-perl-ver| or above) - -#. :ref:`Install a Database Engine <install-database>` - -#. :ref:`Install a Webserver <install-webserver>` - -#. :ref:`Install Bugzilla <install-bzfiles>` - -#. :ref:`Install Perl modules <install-perlmodules>` - -#. :ref:`Install a Mail Transfer Agent <install-MTA>` - (Sendmail 8.7 or above, or an MTA that is Sendmail-compatible with at least this version) - -#. Configure all of the above. - -.. _install-perl: - -Perl -==== - -Installed Version Test: -:: - - $ perl -v - -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 `<http://www.perl.org>`_. -Although Bugzilla runs with Perl |min-perl-ver|, -it's a good idea to be using the latest stable version. - -.. _install-database: - -Database Engine -=============== - -Bugzilla supports MySQL, PostgreSQL and Oracle as database servers. -You only require one of these systems to make use of Bugzilla. - -.. _install-mysql: - -MySQL ------ - -Installed Version Test: -:: - - $ mysql -V - -If you don't have it and your OS doesn't provide official packages, -visit `<http://www.mysql.com>`_. You need MySQL version -5.0.15 or higher. - -.. note:: Many of the binary - versions of MySQL store their data files in :file:`/var`. - 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 :file:`configure`. - -If you install from something other than a packaging/installation -system, such as .rpm (RPM Package Manager), .deb (Debian Package), .exe -(Windows Executable), or .msi (Windows Installer), make sure the MySQL -server is started when the machine boots. - -.. _install-pg: - -PostgreSQL ----------- - -Installed Version Test: -:: - - $ psql -V - -If you don't have it and your OS doesn't provide official packages, -visit `<http://www.postgresql.org/>`_. You need PostgreSQL -version 8.03.0000 or higher. - -If you install from something other than a packaging/installation -system, such as .rpm (RPM Package Manager), .deb (Debian Package), .exe -(Windows Executable), or .msi (Windows Installer), make sure the -PostgreSQL server is started when the machine boots. - -.. _install-oracle: - -Oracle ------- - -Installed Version Test: - -.. code-block:: sql - - SELECT * FROM v$version - -(you first have to log in into your DB) - -If you don't have it and your OS doesn't provide official packages, -visit `<http://www.oracle.com/>`_. You need Oracle -version 10.02.0 or higher. - -If you install from something other than a packaging/installation -system, such as .rpm (RPM Package Manager), .deb (Debian Package), .exe -(Windows Executable), or .msi (Windows Installer), make sure the -Oracle server is started when the machine boots. - -.. _install-webserver: - -Web Server -========== - -Installed Version Test: view the default welcome page at -`http://<your-machine>/` . - -You have freedom of choice here, pretty much any web server that -is capable of running CGI -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 -`Bugzilla Documentation <http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla;component=Documentation>`_. - -If you don't have Apache and your OS doesn't provide official packages, -visit `<http://httpd.apache.org/>`_. - -.. _install-bzfiles: - -Bugzilla -======== - -`Download a Bugzilla tarball <http://www.bugzilla.org/download/>`_ -(or `check it out from Bzr <https://wiki.mozilla.org/Bugzilla:Bzr>`_) -and place it in a suitable directory, accessible by the default web server user -(probably ``apache`` or ``www``). -Good locations are either directly in the web server's document directories or -in :file:`/usr/local` with a symbolic link to the web server's -document directories or an alias in the web server's configuration. - -.. warning:: The default Bugzilla distribution is NOT designed to be placed - in a :file:`cgi-bin` directory. This - includes any directory which is configured using the - ``ScriptAlias`` directive of Apache. - -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 -:file:`checksetup.pl` -script, which locks down your installation. - -.. _install-perlmodules: - -Perl Modules -============ - -Bugzilla's installation process is based -on a script called :file:`checksetup.pl`. -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 :ref:`configuration`. - -At this point, you need to :file:`su` to root. You should -remain as root until the end of the install. To check you have the -required modules, run: - -:: - - # ./checksetup.pl --check-modules - -:file:`checksetup.pl` 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. - -The preferred way to install missing Perl modules is to use the package -manager provided by your operating system (e.g ``rpm``, ``apt-get`` or -``yum`` on Linux distros, or ``ppm`` on Windows -if using ActivePerl, see :ref:`win32-perl-modules`). -If some Perl modules are still missing or are too old, then we recommend -using the :file:`install-module.pl` script (doesn't work -with ActivePerl on Windows). For instance, on Unix, -you invoke :file:`install-module.pl` as follows: - -:: - - # perl install-module.pl <modulename> - -.. note:: Many people complain that Perl modules will not install for - them. Most times, the error messages complain that they are missing a - file in - ``@INC``. - 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 - *are* - the local UNIX sysadmin, please consult the newsgroup/mailing list - for further assistance or hire someone to help you out. - -.. note:: 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 :file:`<packagename>-devel`. - -If for some reason you really need to install the Perl modules manually, see -:ref:`install-perlmodules-manual`. - -.. _install-MTA: - -Mail Transfer Agent (MTA) -========================= - -Bugzilla is dependent on the availability of an e-mail system for its -user authentication and for other tasks. - -.. note:: 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). - For more information, see the ``mail_delivery_method`` parameter - in :ref:`parameters`. - -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. - -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. - -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. - -If a simple mail sent with the command-line 'mail' program -succeeds, then Bugzilla should also be fine. - -.. _using-mod_perl-with-bugzilla: - -Installing Bugzilla on mod_perl -=============================== - -It is now possible to run the Bugzilla software under ``mod_perl`` on -Apache. ``mod_perl`` has some additional requirements to that of running -Bugzilla under ``mod_cgi`` (the standard and previous way). - -Bugzilla requires ``mod_perl`` to be installed, which can be -obtained from `<http://perl.apache.org>`_ - Bugzilla requires -version 1.999022 (AKA 2.0.0-RC5) to be installed. - -.. _configuration: - -Configuration -############# - -.. warning:: 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 :ref:`security` for some important security tips. - -.. _localconfig: - -localconfig -=========== - -You should now run :file:`checksetup.pl` again, this time -without the ``--check-modules`` switch. - -:: - - # ./checksetup.pl - -This time, :file:`checksetup.pl` should tell you that all -the correct modules are installed and will display a message about, and -write out a file called, :file:`localconfig`. This file -contains the default settings for a number of Bugzilla parameters. - -Load this file in your editor. The only two values you -*need* to change are $db_driver and $db_pass, -respectively the type of the database and 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. $db_driver can be either 'mysql', -'Pg', 'Oracle' or 'Sqlite'. - -.. note:: In Oracle, ``$db_name`` should actually be - the SID name of your database (e.g. "XE" if you are using Oracle XE). - -You may need to change the value of -*webservergroup* 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 -*webservergroup* empty, ignoring the warnings -that :file:`checksetup.pl` will subsequently display -every time it is run. - -.. warning:: If you are using suexec, you should use your own primary group - for *webservergroup* rather than leaving it - empty, and see the additional directions in the suexec section :ref:`suexec`. - -The other options in the :file:`localconfig` file -are documented by their accompanying comments. If you have a slightly -non-standard database setup, you may wish to change one or more of -the other "$db_*" parameters. - -.. _database-engine: - -Database Server -=============== - -This section deals with configuring your database server for use -with Bugzilla. Currently, MySQL (:ref:`mysql`), -PostgreSQL (:ref:`postgresql`), Oracle (:ref:`oracle`) -and SQLite (:ref:`sqlite`) are available. - -.. _database-schema: - -Bugzilla Database Schema ------------------------- - -The Bugzilla database schema is available at -`Ravenbrook <http://www.ravenbrook.com/project/p4dti/tool/cgi/bugzilla-schema/>`_. -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. - -.. _mysql: - -MySQL ------ - -.. warning:: MySQL's default configuration is insecure. - We highly recommend to run :file:`mysql_secure_installation` - on Linux or the MySQL installer on Windows, and follow the instructions. - Important points to note are: - -#. Be sure that the root account has a secure password set. -#. Do not create an anonymous account, and if it exists, say "yes" - to remove it. -#. If your web server and MySQL server are on the same machine, - you should disable the network access. - -.. _mysql-max-allowed-packet: - -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 :file:`/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 - -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 :file:`/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>`_. - -.. _install-setupdatabase-adduser: - -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 -:file:`localconfig`; if you changed those, -you need to modify the SQL command appropriately. You will -need the $db_pass password you -set in :file:`localconfig` in -:ref:`localconfig`. - -We use an SQL :command:`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 :file:`mysql` command-line client and enter: - -.. code-block:: sql - - GRANT SELECT, INSERT, - UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES, - CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.* - TO bugs@localhost IDENTIFIED BY '$db_pass'; - - FLUSH PRIVILEGES; - -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 :file:`MySQL` -command-line client and enter the following, replacing ``$bugs_db`` -with your Bugzilla database name (*bugs* by default): - -.. code-block:: sql - - USE $bugs_db; - - 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. - -.. note:: This does not affect Big Files, attachments that are stored directly - on disk instead of in the database. - -.. _postgresql: - -PostgreSQL ----------- - -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 :file:`localconfig`; if you -changed those, you need to modify the commands appropriately. You will -need the $db_pass password you -set in :file:`localconfig` in -:ref:`localconfig`. - -On most systems, to create the user in PostgreSQL, you will need to -login as the root user, and then - -:: - - # su - postgres - -As the postgres user, you then need to create a new user: - -:: - - $ createuser -U postgres -dRSP bugs - -When asked for a password, provide the password which will be set as -$db_pass in :file:`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). - -Configure PostgreSQL -~~~~~~~~~~~~~~~~~~~~ - -Now, you will need to edit :file:`pg_hba.conf` which is -usually located in :file:`/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 :file:`postgresql.conf`. After the server has -restarted, you will need to edit :file:`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. - -.. _oracle: - -Oracle ------- - -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: - -.. code-block:: sql - - 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 -:file:`/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. - -Add a User to Oracle -~~~~~~~~~~~~~~~~~~~~ - -The user name and password must match what you set in -:file:`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. - -.. code-block:: sql - - 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; - -Configure the Web Server -~~~~~~~~~~~~~~~~~~~~~~~~ - -If you use Apache, append these lines to :file:`httpd.conf` -to set ORACLE_HOME and LD_LIBRARY_PATH. For instance: - -.. code-block:: apache - - 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. - -.. _sqlite: - -SQLite ------- - -.. warning:: Due to SQLite's `concurrency - limitations <http://sqlite.org/faq.html#q5>`_ we recommend SQLite only for small and development - Bugzilla installations. - -No special configuration is required to run Bugzilla on SQLite. -The database will be stored in :file:`data/db/$db_name`, -where ``$db_name`` is the database name defined -in :file:`localconfig`. - -checksetup.pl -============= - -Next, rerun :file:`checksetup.pl`. 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. - -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. - -:file:`checksetup.pl` will then finish. You may rerun -:file:`checksetup.pl` at any time if you wish. - -.. _http: - -Web server -========== - -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 :file:`testagent.cgi` -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 -:ref:`security-webserver-access`. You can run -:file:`testserver.pl` to check if your web server serves -Bugzilla files as expected. - -.. _http-apache: - -Bugzilla using Apache ---------------------- - -You have two options for running Bugzilla under Apache - -:ref:`mod_cgi <http-apache-mod_cgi>` (the default) and -:ref:`mod_perl <http-apache-mod_perl>` (new in Bugzilla -2.23) - -.. _http-apache-mod_cgi: - -Apache *httpd* with mod_cgi -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To configure your Apache web server to work with Bugzilla while using -mod_cgi, do the following: - -#. Load :file:`httpd.conf` in your editor. - In Fedora and Red Hat Linux, this file is found in - :file:`/etc/httpd/conf`. - -#. Apache uses ``<Directory>`` - 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 :file:`/var/www/html/bugzilla`. - -.. code-block:: apache - - <Directory /var/www/html/bugzilla> - AddHandler cgi-script .cgi - Options +ExecCGI - DirectoryIndex index.cgi index.html - AllowOverride Limit FileInfo Indexes Options - </Directory> - -These instructions: allow apache to run .cgi files found -within the bugzilla directory; instructs the server to look -for a file called :file:`index.cgi` or, if not -found, :file:`index.html` if someone -only types the directory name into the browser; and allows -Bugzilla's :file:`.htaccess` files to override -some global permissions. - -.. note:: It is possible to make these changes globally, or to the - directive controlling Bugzilla's parent directory (e.g. - ``<Directory /var/www/html/>``). - 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. - -.. note:: On Windows, you may have to also add the - ``ScriptInterpreterSource Registry-Strict`` - line, see :ref:`Windows specific notes <win32-http>`. - -#. :file:`checksetup.pl` can set tighter permissions - on Bugzilla's files and directories if it knows what group the - web server runs as. Find the ``Group`` - line in :file:`httpd.conf`, place the value found - there in the *$webservergroup* variable - in :file:`localconfig`, then rerun :file:`checksetup.pl`. - -#. 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 - ``Options`` line of the Bugzilla - ``<Directory>`` directive - (the same one as in the step above): - -.. code-block:: apache - - +FollowSymLinks - -Without this directive, Apache will not follow symbolic links -to places outside its own directory structure, and you will be -unable to run Bugzilla. - -Apache *httpd* log files with bugzilla -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For security reasons it is recommended to prevent Apache from logging -query strings. - -For example: -When external systems interact with Bugzilla via webservices (REST/XMLRPC/JSONRPC) -they include the user's credentials as part of the URL (query-string). For security -reasons we recommend configuring Apache to not include the query-string in its log -files to avoid storing passwords in clear text on the server. - -#. Load :file:`httpd.conf` or :file:`apache2.conf` in your editor. - In most of the Linux distributions this file is found in :folder:`/etc/httpd/conf/httpd.conf` - or in :folder:`/etc/apache2/apache2.conf`. - -#. Find the following line in the above mentioned file. - LogFormat "%v:%p %h %l %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-Agent}i\"" vhost_combined. - -#. Replace \"%r\" with \"%m %U\". - -#. Now restart Apache. - -.. _http-apache-mod_perl: - -Apache *httpd* with mod_perl -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some configuration is required to make Bugzilla work with Apache -and mod_perl - -#. Load :file:`httpd.conf` in your editor. - In Fedora and Red Hat Linux, this file is found in :file:`/etc/httpd/conf`. - -#. Add the following information to your httpd.conf file, substituting - where appropriate with your own local paths. - - .. note:: This should be used instead of the <Directory> block - shown above. This should also be above any other ``mod_perl`` - directives within the :file:`httpd.conf` and must be specified - in the order as below. - - .. warning:: You should also ensure that you have disabled ``KeepAlive`` - support in your Apache install when utilizing Bugzilla under mod_perl - -.. code-block:: apache - - PerlSwitches -w -T - PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl - -#. :file:`checksetup.pl` can set tighter permissions - on Bugzilla's files and directories if it knows what group the - web server runs as. Find the ``Group`` - line in :file:`httpd.conf`, place the value found - there in the *$webservergroup* variable - in :file:`localconfig`, then rerun :file:`checksetup.pl`. - -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. - -.. note:: 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. - -.. _http-iis: - -Microsoft *Internet Information Services* ------------------------------------------ - -If you are running Bugzilla on Windows and choose to use -Microsoft's *Internet Information Services* -or *Personal Web Server* 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: -`245225 - HOW TO: Configure and Test a PERL Script with IIS 4.0, -5.0, and 5.1 <http://support.microsoft.com/default.aspx?scid=kb;en-us;245225>`_ -(for *Internet Information Services*) and -`231998 - HOW TO: FP2000: How to Use Perl with Microsoft Personal Web -Server on Windows 95/98 <http://support.microsoft.com/default.aspx?scid=kb;en-us;231998>`_ -(for *Personal Web Server*). - -You will need to create a virtual directory for the Bugzilla -install. Put the Bugzilla files in a directory that is named -something *other* than what you want your -end-users accessing. That is, if you want your users to access -your Bugzilla installation through -``http://<yourdomainname>/Bugzilla``, then do -*not* put your Bugzilla files in a directory -named ``Bugzilla``. 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 ``Execute (such as ISAPI applications or -CGI)`` access permission. - -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: - -:: - - <full path to perl.exe >\perl.exe -x<full path to Bugzilla> -wT "%s" %s - -For example: - -:: - - c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s - -.. note:: The ActiveState install may have already created an entry for - .pl files that is limited to ``GET,HEAD,POST``. If - so, this mapping should be *removed* as - Bugzilla's .pl files are not designed to be run via a web server. - -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. - -Also, and this can't be stressed enough, make sure that files -such as :file:`localconfig` and your -:file:`data` directory are -secured as described in :ref:`security-webserver-access`. - -.. _install-config-bugzilla: - -Bugzilla -======== - -Your Bugzilla should now be working. Access -:file:`http://<your-bugzilla-server>/` - -you should see the Bugzilla -front page. If not, consult the Troubleshooting section, -:ref:`troubleshooting`. - -.. note:: 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. - -Log in with the administrator account you defined in the last -:file:`checksetup.pl` run. You should go through -the Parameters page and see if there are any you wish to change. -They key parameters are documented in :ref:`parameters`; -you should certainly alter -:command:`maintainer` and :command:`urlbase`; -you may also want to alter -:command:`cookiepath` or :command:`requirelogin`. - -Bugzilla has several optional features which require extra -configuration. You can read about those in -:ref:`extraconfig`. - -.. _extraconfig: - -Optional Additional Configuration -################################# - -Bugzilla has a number of optional features. This section describes how -to configure or enable them. - -Bug Graphs -========== - -If you have installed the necessary Perl modules you -can start collecting statistics for the nifty Bugzilla -graphs. - -:: - - # crontab -e - -This should bring up the crontab file in your editor. -Add a cron entry like this to run -:file:`collectstats.pl` -daily at 5 after midnight: - -.. code-block:: none - - 5 0 * * * cd <your-bugzilla-directory> && ./collectstats.pl - -After two days have passed you'll be able to view bug graphs from -the Reports page. - -.. note:: 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 - `nncron <http://www.nncron.ru/>`_. - -.. _installation-whining-cron: - -The Whining Cron -================ - -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 CONFIRMED state without triaging them. - -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. - -.. code-block:: none - - 55 0 * * * cd <your-bugzilla-directory> && ./whineatnews.pl - -.. note:: 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 - `nncron <http://www.nncron.ru/>`_. - -.. _installation-whining: - -Whining -======= - -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 :ref:`whining`, but for it to work a Perl script must be -executed at regular intervals. - -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. - -.. code-block:: none - - */15 * * * * cd <your-bugzilla-directory> && ./whine.pl - -.. note:: 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. - -.. note:: 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 - `nncron <http://www.nncron.ru/>`_. - -.. _apache-addtype: - -Serving Alternate Formats with the right MIME type -================================================== - -Some Bugzilla pages have alternate formats, other than just plain -HTML. In particular, a few Bugzilla pages can -output their contents as either XUL (a special -Mozilla format, that looks like a program GUI) -or RDF (a type of structured XML -that can be read by various programs). - -In order for your users to see these pages correctly, Apache must -send them with the right MIME type. To do this, -add the following lines to your Apache configuration, either in the -``<VirtualHost>`` section for your -Bugzilla, or in the ``<Directory>`` -section for your Bugzilla: - -.. code-block:: apache - - AddType application/vnd.mozilla.xul+xml .xul - AddType application/rdf+xml .rdf - -.. _multiple-bz-dbs: - -Multiple Bugzilla databases with a single installation -###################################################### - -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 -:file:`localconfig.<PROJECT>` in the same location as -the default one (:file:`localconfig`). It also checks for -customized templates in a directory named -:file:`<PROJECT>` in the same location as the -default one (:file:`template/<langcode>`). By default -this is :file:`template/en/default` so PROJECT's templates -would be located at :file:`template/en/PROJECT`. - -To set up an alternate installation, just export PROJECT=foo before -running :command:`checksetup.pl` for the first time. It will -result in a file called :file:`localconfig.foo` instead of -:file:`localconfig`. Edit this file as described above, with -reference to a new database, and re-run :command:`checksetup.pl` -to populate it. That's all. - -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. - -.. code-block:: apache - - <VirtualHost 212.85.153.228:80> - ServerName foo.bar.baz - SetEnv PROJECT foo - Alias /bugzilla /var/www/bugzilla - </VirtualHost> - -Don't forget to also export this variable before accessing Bugzilla -by other means, such as cron tasks for instance. - -.. _os-specific: - -OS-Specific Installation Notes -############################## - -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. - -If you have anything to add or notes for an operating system not covered, -please file a bug in `Bugzilla Documentation <http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla;component=Documentation>`_. - -.. _os-win32: - -Microsoft Windows -================= - -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 -`installation guide for Windows <https://wiki.mozilla.org/Bugzilla:Win32Install>`_ is also available -if you need more help with your installation. - -.. _win32-perl: - -Win32 Perl ----------- - -Perl for Windows can be obtained from -`ActiveState <http://www.activestate.com/>`_. -You should be able to find a compiled binary at `<http://aspn.activestate.com/ASPN/Downloads/ActivePerl/>`_. -The following instructions assume that you are using version -|min-perl-ver| of ActiveState. - -.. note:: 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. - -.. _win32-perl-modules: - -Perl Modules on Win32 ---------------------- - -Bugzilla on Windows requires the same perl modules found in -:ref:`install-perlmodules`. The main difference is that -windows uses PPM 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: - -:: - - C:\perl> ppm install <module name> - -If you are using Perl |min-perl-ver|, 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: - -:: - - ppm repo add theory58S http://cpan.uwinnipeg.ca/PPMPackages/10xx/ - -If you are using Perl 5.12 or newer, you no longer need to add -this repository. All modules you need are already available from -the ActiveState repository. - -.. note:: 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` as it will - tell you what package you'll need to install. - -.. note:: 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. - -.. _win32-http: - -Serving the web pages ---------------------- - -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 :ref:`security-webserver-access`. More -information on configuring specific web servers can be found -in :ref:`http`. - -.. note:: The web server looks at :file:`/usr/bin/perl` to - call Perl. If you are using Apache on windows, you can set the - `ScriptInterpreterSource <http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource>`_ - directive in your Apache config file to make it look at the - right place: insert the line - - :: - ScriptInterpreterSource Registry-Strict - - into your :file:`httpd.conf` file, and create the key - - :: - HKEY_CLASSES_ROOT\\.cgi\\Shell\\ExecCGI\\Command - - with ``C:\\Perl\\bin\\perl.exe -T`` as value (adapt to your - path if needed) in the registry. When this is done, restart Apache. - -.. _win32-email: - -Sending Email -------------- - -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. - -.. _os-macosx: - -*Mac OS X* -========== - -Making Bugzilla work on Mac OS X requires the following -adjustments. - -.. _macosx-sendmail: - -Sendmail --------- - -In Mac OS X 10.3 and later, -`Postfix <http://www.postfix.org/>`_ -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. Bugzilla is able to find the fake sendmail executable without -any assistance. - -.. _macosx-libraries: - -Libraries & Perl Modules on Mac OS X ------------------------------------- - -Apple does not include the GD library with Mac OS X. Bugzilla -needs this for bug graphs. - -You can use MacPorts (`<http://www.macports.org/>`_) -or Fink (`<http://sourceforge.net/projects/fink/>`_), both -of which are similar in nature to the CPAN installer, but install -common unix programs. - -Follow the instructions for setting up MacPorts or Fink. -Once you have one installed, you'll want to use it to install the -:file:`gd2` package. - -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 CPAN to -install the GD Perl module. - -.. note:: To prevent creating conflicts with the software that Apple - installs by default, Fink creates its own directory tree at :file:`/sw` - where it installs most of - the software that it installs. This means your libraries and headers - will be at :file:`/sw/lib` and :file:`/sw/include` instead - of :file:`/usr/lib` and :file:`/usr/include`. When the - Perl module config script asks where your :file:`libgd` - is, be sure to tell it :file:`/sw/lib`. - -Also available via MacPorts and Fink is -:file:`expat`. 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: - -:: - - # perl -MCPAN -e'look XML::Parser' - # perl Makefile.PL EXPATLIBPATH=/sw/lib EXPATINCPATH=/sw/include - # make; make test; make install - # exit - -The :command:`look` command will download the module and spawn -a new shell with the extracted files as the current working directory. - -You should watch the output from these :command:`make` commands, -especially ``make test`` as errors may prevent -XML::Parser from functioning correctly with Bugzilla. - -The :command:`exit` command will return you to your original shell. - -.. _os-linux: - -Linux Distributions -=================== - -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. - -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 -`Bugzilla Wiki Page <http://wiki.mozilla.org/Bugzilla:Linux_Distro_Installation>`_ for distro-specific installation -notes. - -.. _nonroot: - -UNIX (non-root) Installation Notes -################################## - -Introduction -============ - -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 -:ref:`installation` -first to get an idea on the installation steps required. -(These notes will reference to steps in that guide.) - -MySQL -===== - -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. - -.. warning:: You may have problems trying to set up :command:`GRANT` - 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 for you. - Also, you will probably not be able to change the MySQL - root user password (for obvious reasons), so skip that - step. - -Running MySQL as Non-Root -------------------------- - -The Custom Configuration Method -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Create a file .my.cnf in your -home directory (using /home/foo in this example) -as follows.... - -:: - - [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 - -The Custom Built Method -~~~~~~~~~~~~~~~~~~~~~~~ - -You can install MySQL as a not-root, if you really need to. -Build it with PREFIX set to :file:`/home/foo/mysql`, -or use pre-installed executables, specifying that you want -to put all of the data files in :file:`/home/foo/mysql/data`. -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. - -Starting the Server -~~~~~~~~~~~~~~~~~~~ - -After your mysqld program is built and any .my.cnf file is -in place, you must initialize the databases (ONCE). - -:: - - $ mysql_install_db - -Then start the daemon with - -:: - - $ safe_mysql & - -After you start mysqld the first time, you then connect to -it as "root" and :command:`GRANT` permissions to other -users. (Again, the MySQL root account has nothing to do with -the \*NIX root account.) - -.. note:: 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. - -.. warning:: 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! - -Perl -==== - -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: - -:: - - $ wget http://perl.org/CPAN/src/stable.tar.gz - $ tar zvxf stable.tar.gz - $ cd perl-|min-perl-ver| - $ sh Configure -de -Dprefix=/home/foo/perl - $ make && make test && make install - -Once you have Perl installed into a directory (probably -in :file:`~/perl/bin`), you will need to -install the Perl Modules, described below. - -.. _install-perlmodules-nonroot: - -Perl Modules -============ - -Installing the Perl modules as a non-root user is accomplished by -running the :file:`install-module.pl` -script. For more details on this script, see the -`install-module.pl documentation <../html/api/install-module.html>`_. - -HTTP Server -=========== - -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. - -Running Apache as Non-Root --------------------------- - -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`, -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. - -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. - -.. note:: 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. - -.. warning:: 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! - -Bugzilla -======== - -When you run :command:`./checksetup.pl` to create -the :file:`localconfig` file, it will list the Perl -modules it finds. If one is missing, go back and double-check the -module installation from :ref:`install-perlmodules-nonroot`, -then delete the :file:`localconfig` file and try again. - -.. warning:: One option in :file:`localconfig` you - might have problems with is the web server group. If you can't - successfully browse to the :file:`index.cgi` (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. - -.. _suexec: - -suexec or shared hosting ------------------------- - -If you are running on a system that uses suexec (most shared -hosting environments do this), you will need to set the -*webservergroup* value in :file:`localconfig` -to match *your* 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`, -every time you run it (or modify :file:`checksetup.pl` -to do them for you via the system() command). - -:: - - 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 - -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. - -.. _upgrade: - -Upgrading to New Releases -######################### - -Upgrading to new Bugzilla releases is very simple. There is -a script named :file:`checksetup.pl` included with -Bugzilla that will automatically do all of the database migration -for you. - -The following sections explain how to upgrade from one -version of Bugzilla to another. Whether you are upgrading -from one bug-fix version to another (such as 4.2 to 4.2.1) -or from one major version to another (such as from 4.0 to 4.2), -the instructions are always the same. - -.. note:: Any examples in the following sections are written as though the - user were updating to version 4.2.1, but the procedures are the - same no matter what version you're updating to. Also, in the - examples, the user's Bugzilla installation is found - at :file:`/var/www/html/bugzilla`. If that is not the - same as the location of your Bugzilla installation, simply - substitute the proper paths where appropriate. - -.. _upgrade-before: - -Before You Upgrade -================== - -Before you start your upgrade, there are a few important -steps to take: - -#. Read the `Release - Notes <http://www.bugzilla.org/releases/>`_ of the version you're upgrading to, - particularly the "Notes for Upgraders" section. - -#. View the Sanity Check (:ref:`sanitycheck`) page - on your installation before upgrading. Attempt to fix all warnings - that the page produces before you go any further, or you may - experience problems during your upgrade. - -#. Shut down your Bugzilla installation by putting some HTML or - text in the shutdownhtml parameter - (see :ref:`parameters`). - -#. Make a backup of the Bugzilla database. - *THIS IS VERY IMPORTANT*. If - anything goes wrong during the upgrade, your installation - can be corrupted beyond recovery. Having a backup keeps you safe. - - .. warning:: Upgrading is a one-way process. You cannot "downgrade" an - upgraded Bugzilla. If you wish to revert to the old Bugzilla - version for any reason, you will have to restore your database - from this backup. - - Here are some sample commands you could use to backup - your database, depending on what database system you're - using. You may have to modify these commands for your - particular setup. - - MySQL: - mysqldump --opt -u bugs -p bugs > bugs.sql - PostgreSQL: - pg_dump --no-privileges --no-owner -h localhost -U bugs - > bugs.sql - -.. _upgrade-files: - -Getting The New Bugzilla -======================== - -There are three ways to get the new version of Bugzilla. -We'll list them here briefly and then explain them -more later. - -Bzr (:ref:`upgrade-bzr`) - If you have :command:`bzr` installed on your machine - and you have Internet access, this is the easiest way to - upgrade, particularly if you have made modifications - to the code or templates of Bugzilla. - -Download the tarball (:ref:`upgrade-tarball`) - This is a very simple way to upgrade, and good if you - haven't made many (or any) modifications to the code or - templates of your Bugzilla. - -Patches (:ref:`upgrade-patches`) - If you have made modifications to your Bugzilla, and - you don't have Internet access or you don't want to use - bzr, then this is the best way to upgrade. - You can only do minor upgrades (such as 4.2 to 4.2.1 or - 4.2.1 to 4.2.2) with patches. - -.. _upgrade-modified: - -If you have modified your Bugzilla ----------------------------------- - -If you have modified the code or templates of your Bugzilla, -then upgrading requires a bit more thought and effort. -A discussion of the various methods of updating compared with -degree and methods of local customization can be found in -:ref:`template-method`. - -The larger the jump you are trying to make, the more difficult it -is going to be to upgrade if you have made local customizations. -Upgrading from 4.2 to 4.2.1 should be fairly painless even if -you are heavily customized, but going from 2.18 to 4.2 is going -to mean a fair bit of work re-writing your local changes to use -the new files, logic, templates, etc. If you have done no local -changes at all, however, then upgrading should be approximately -the same amount of work regardless of how long it has been since -your version was released. - -.. _upgrade-bzr: - -Upgrading using Bzr -------------------- - -This requires that you have bzr installed (most Unix machines do), -and requires that you are able to access -`bzr.mozilla.org <http://bzr.mozilla.org/bugzilla/>`_, -which may not be an option if you don't have Internet access. - -The following shows the sequence of commands needed to update a -Bugzilla installation via Bzr, and a typical series of results. -These commands assume that you already have Bugzilla installed -using Bzr. - -.. warning:: If your installation is still using CVS, you must first convert - it to Bzr. A very detailed step by step documentation can be - found on `wiki.mozilla.org <https://wiki.mozilla.org/Bugzilla:Moving_From_CVS_To_Bazaar>`_. - -:: - - $ cd /var/www/html/bugzilla - $ bzr switch 4.2 - (only run the previous command when not yet running 4.2) - $ bzr up -r tag:bugzilla-4.2.1 - +N extensions/MoreBugUrl/ - +N extensions/MoreBugUrl/Config.pm - +N extensions/MoreBugUrl/Extension.pm - ... - M Bugzilla/Attachment.pm - M Bugzilla/Attachment/PatchReader.pm - M Bugzilla/Bug.pm - ... - All changes applied successfully. - -.. warning:: If a line in the output from :command:`bzr up` mentions - a conflict, then that represents a file with local changes that - Bzr was unable to properly merge. You need to resolve these - conflicts manually before Bugzilla (or at least the portion using - that file) will be usable. - -.. _upgrade-tarball: - -Upgrading using the tarball ---------------------------- - -If you are unable (or unwilling) to use Bzr, another option that's -always available is to obtain the latest tarball from the `Download Page <http://www.bugzilla.org/download/>`_ and -create a new Bugzilla installation from that. - -This sequence of commands shows how to get the tarball from the -command-line; it is also possible to download it from the site -directly in a web browser. If you go that route, save the file -to the :file:`/var/www/html` -directory (or its equivalent, if you use something else) and -omit the first three lines of the example. - -:: - - $ cd /var/www/html - $ wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-4.2.1.tar.gz - ... - $ tar xzvf bugzilla-4.2.1.tar.gz - bugzilla-4.2.1/ - bugzilla-4.2.1/colchange.cgi - ... - $ cd bugzilla-4.2.1 - $ cp ../bugzilla/localconfig* . - $ cp -r ../bugzilla/data . - $ cd .. - $ mv bugzilla bugzilla.old - $ mv bugzilla-4.2.1 bugzilla - -.. warning:: The :command:`cp` commands both end with periods which - is a very important detail--it means that the destination - directory is the current working directory. - -.. warning:: If you have some extensions installed, you will have to copy them - to the new bugzilla directory too. Extensions are located in :file:`bugzilla/extensions/`. - Only copy those you - installed, not those managed by the Bugzilla team. - -This upgrade method will give you a clean install of Bugzilla. -That's fine if you don't have any local customizations that you -want to maintain. If you do have customizations, then you will -need to reapply them by hand to the appropriate files. - -.. _upgrade-patches: - -Upgrading using patches ------------------------ - -A patch is a collection of all the bug fixes that have been made -since the last bug-fix release. - -If you are doing a bug-fix upgrade—that is, one where only the -last number of the revision changes, such as from 4.2 to -4.2.1—then you have the option of obtaining and applying a -patch file from the `Download Page <http://www.bugzilla.org/download/>`_. - -As above, this example starts with obtaining the file via the -command line. If you have already downloaded it, you can omit the -first two commands. - -:: - - $ cd /var/www/html/bugzilla - $ wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-4.2-to-4.2.1.diff.gz - ... - $ gunzip bugzilla-4.2-to-4.2.1.diff.gz - $ patch -p1 < bugzilla-4.2-to-4.2.1.diff - patching file Bugzilla/Constants.pm - patching file enter_bug.cgi - ... - -.. warning:: Be aware that upgrading from a patch file does not change the - entries in your :file:`.bzr` directory. - This could make it more difficult to upgrade using Bzr - (:ref:`upgrade-bzr`) in the future. - -.. _upgrade-completion: - -Completing Your Upgrade -======================= - -Now that you have the new Bugzilla code, there are a few final -steps to complete your upgrade. - -#. If your new Bugzilla installation is in a different - directory or on a different machine than your old Bugzilla - installation, make sure that you have copied the - :file:`data` directory and the - :file:`localconfig` file from your old Bugzilla - installation. (If you followed the tarball instructions - above, this has already happened.) - -#. If this is a major update, check that the configuration - (:ref:`configuration`) for your new Bugzilla is - up-to-date. Sometimes the configuration requirements change - between major versions. - -#. If you didn't do it as part of the above configuration step, - now you need to run :command:`checksetup.pl`, which - will do everything required to convert your existing database - and settings for the new version: - - :: - - $ :command:`cd /var/www/html/bugzilla` - $ :command:`./checksetup.pl` - - .. warning:: The period at the beginning of the - command :command:`./checksetup.pl` is important and cannot - be omitted. - - .. warning:: If this is a major upgrade (say, 3.6 to 4.2 or similar), - running :command:`checksetup.pl` on a large - installation (75,000 or more bugs) can take a long time, - possibly several hours. - -#. Clear any HTML or text that you put into the shutdownhtml - parameter, to re-activate Bugzilla. - -#. View the Sanity Check (:ref:`sanitycheck`) page in your - upgraded Bugzilla. - It is recommended that, if possible, you fix any problems - you see, immediately. Failure to do this may mean that Bugzilla - will not work correctly. Be aware that if the sanity check page - contains more errors after an upgrade, it doesn't necessarily - mean there are more errors in your database than there were - before, as additional tests are added to the sanity check over - time, and it is possible that those errors weren't being - checked for in the old version. - -.. _upgrade-notifications: - -Automatic Notifications of New Releases -======================================= - -Bugzilla 3.0 introduced the ability to automatically notify -administrators when new releases are available, based on the -``upgrade_notification`` parameter, see -:ref:`parameters`. Administrators will see these -notifications when they access the :file:`index.cgi` -page, i.e. generally when logging in. Bugzilla will check once per -day for new releases, unless the parameter is set to -``disabled``. If you are behind a proxy, you may have to set -the ``proxy_url`` parameter accordingly. If the proxy -requires authentication, use the -``http://user:pass@proxy_url/`` syntax. - - |