-
-
.. _about:
================
About This Guide
================
-.. _introduction:
-
-Introduction
-############
-
-This is the documentation for version |version| of Bugzilla, a
-bug-tracking system from mozilla.org.
-Bugzilla is an enterprise-class piece of software
-that tracks millions of bugs and issues for hundreds of
-organizations around the world.
-
-The most current version of this document can always be found on the
-`Bugzilla
-Documentation Page <http://www.bugzilla.org/docs/>`_.
-
-.. _copyright:
-
-Copyright Information
-#####################
-
-This document is copyright (c) 2000-2014 by the various
-Bugzilla contributors who wrote it.
-
- Permission is granted to copy, distribute and/or modify this
- document under the terms of the GNU Free Documentation
- License, Version 1.1 or any later version published by the
- Free Software Foundation; with no Invariant Sections, no
- Front-Cover Texts, and with no Back-Cover Texts. A copy of
- the license is included in :ref:`gfdl`.
-
-If you have any questions regarding this document, its
-copyright, or publishing this document in non-electronic form,
-please contact the Bugzilla Team.
-
-.. _disclaimer:
-
-Disclaimer
-##########
-
-No liability for the contents of this document can be accepted.
-Follow the instructions herein at your own risk.
-This document may contain errors
-and inaccuracies that may damage your system, cause your partner
-to leave you, your boss to fire you, your cats to
-pee on your furniture and clothing, and global thermonuclear
-war. Proceed with caution.
-
-Naming of particular products or brands should not be seen as
-endorsements, with the exception of the term "GNU/Linux". We
-wholeheartedly endorse the use of GNU/Linux; it is an extremely
-versatile, stable,
-and robust operating system that offers an ideal operating
-environment for Bugzilla.
-
-Although the Bugzilla development team has taken great care to
-ensure that all exploitable bugs have been fixed, security holes surely
-exist in any piece of code. Great care should be taken both in
-the installation and usage of this software. The Bugzilla development
-team members assume no liability for your use of Bugzilla. You have
-the source code, and are responsible for auditing it yourself to ensure
-your security needs are met.
-
-.. COMMENT: Section 2: New Versions
-
-.. _newversions:
-
-New Versions
-############
-
-This is version |version| of The Bugzilla Guide. It is so named
-to match the current version of Bugzilla.
-
-.. todo:: BZ-DEVEL This version of the guide, like its associated Bugzilla version, is a
- development version.
-
-The latest version of this guide can always be found at `<http://www.bugzilla.org/docs/>`_. However, you should read
-the version which came with the Bugzilla release you are using.
-
-In addition, there are Bugzilla template localization projects in
-`several languages <http://www.bugzilla.org/download/#localizations>`_.
-They may have translated documentation available. If you would like to
-volunteer to translate the Guide into additional languages, please visit the
-`Bugzilla L10n team <https://wiki.mozilla.org/Bugzilla:L10n>`_
-page.
-
-.. _credits:
-
-Credits
-#######
-
-The people listed below have made enormous contributions to the
-creation of this Guide, through their writing, dedicated hacking efforts,
-numerous e-mail and IRC support sessions, and overall excellent
-contribution to the Bugzilla community:
-
-.. COMMENT: TODO: This is evil... there has to be a valid way to get this look
-
-Matthew P. Barnson mbarnson@sisna.com
- for the Herculean task of pulling together the Bugzilla Guide
- and shepherding it to 2.14.
-
-Terry Weissman terry@mozilla.org
- for initially writing Bugzilla and creating the README upon
- which the UNIX installation documentation is largely based.
-
-Tara Hernandez tara@tequilarists.org
- for keeping Bugzilla development going strong after Terry left
- mozilla.org and for running landfill.
-
-Dave Lawrence dkl@redhat.com
- for providing insight into the key differences between Red
- Hat's customized Bugzilla.
-
-Dawn Endico endico@mozilla.org
- for being a hacker extraordinaire and putting up with Matthew's
- incessant questions and arguments on irc.mozilla.org in #mozwebtools
-
-Jacob Steenhagen jake@bugzilla.org
- for taking over documentation during the 2.17 development
- period.
-
-Dave Miller justdave@bugzilla.org
- for taking over as project lead when Tara stepped down and
- continually pushing for the documentation to be the best it can be.
-
-Thanks also go to the following people for significant contributions
-to this documentation:
-Kevin Brannen, Vlad Dascalu, Ben FrantzDale, Eric Hanson, Zach Lipton, Gervase Markham, Andrew Pearson, Joe Robins, Spencer Smith, Ron Teitelbaum, Shane Travis, Martin Wulffeld.
-
-Also, thanks are due to the members of the
-`mozilla.support.bugzilla <news://news.mozilla.org/mozilla.support.bugzilla>`_
-newsgroup (and its predecessor, netscape.public.mozilla.webtools).
-Without your discussions, insight, suggestions, and patches,
-this could never have happened.
-
-.. _conventions:
-
-Document Conventions
-####################
-
-This document uses the following conventions:
-
-.. warning:: This is a warning - something you should be aware of.
-
-.. note:: This is just a note, for your information.
-
-A filename or a path to a filename is displayed like this:
-:file:`/path/to/filename.ext`
-
-A command to type in the shell is displayed like this:
-:command:`command --arguments`
-
-bash$ represents a normal user's prompt under bash shell
-
-bash# represents a root user's prompt under bash shell
-
-A sample of code is illustrated like this:
-
-::
-
- First Line of Code
- Second Line of Code
- ...
-
-This documentation is maintained in reStructured Text format.
-Changes are best submitted as diffs, attached
-to a bug filed in the `Bugzilla Documentation <https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla;component=Documentation>`_
-component.
+.. toctree::
+ :maxdepth: 2
+ about/introduction
+ about/evaluating
+ about/getting-help
+ about/document-conventions
+ about/license
+ about/credits
+.. _conventions:
+
+Document Conventions
+####################
+
+This document uses the following conventions:
+
+.. warning:: This is a warning - something you should be aware of.
+
+.. note:: This is just a note, for your information.
+
+A filename or a path to a filename is displayed like this:
+:file:`/path/to/filename.ext`
+
+A command to type in the shell is displayed like this:
+:command:`command --arguments`
+
+bash$ represents a normal user's prompt under bash shell
+
+bash# represents a root user's prompt under bash shell
+
+A sample of code is illustrated like this:
+
+::
+
+ First Line of Code
+ Second Line of Code
+ ...
+
+This documentation is maintained in reStructured Text format.
+Changes are best submitted as diffs, attached
+to a bug filed in the `Bugzilla Documentation <https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla;component=Documentation>`_
+component.
+
+.. _evaluating:
+
+Evaluating Bugzilla
+###################
+
+If you want to evaluate Bugzilla, you can try it out on "`Landfill <https://landfill.bugzilla.org/bugzilla-4.4-branch/>`_", our test
+server. The `Bugzilla FAQ <https://wiki.mozilla.org/Bugzilla:FAQ>`_ may also
+be helpful, as it answers a number of questions people sometimes have about
+whether Bugzilla can do what they need.
+
+.. _help:
+
+Getting More Help
+#################
+
+If this document does not answer your questions, we run a
+`Mozilla forum <https://www.mozilla.org/about/forums/#support-bugzilla>`_
+which can be accessed as a newsgroup, mailing list, or over the web as a
+Google Group. Please
+`search it <https://groups.google.com/forum/#!forum/mozilla.support.bugzilla>`_
+first, and then ask your question there.
+
+If you need a guaranteed response, commercial support is
+`available <http://www.bugzilla.org/support/consulting.html>`_ for Bugzilla
+from a number of people and organizations.
+
+.. _introduction:
+
+Introduction
+############
+
+This is the documentation for version |version| of Bugzilla, a
+bug-tracking system from mozilla.org.
+Bugzilla is an enterprise-class piece of software
+that tracks millions of bugs and issues for hundreds of
+organizations around the world.
+
+The most current version of this document can always be found on the
+`Bugzilla Documentation Page <http://www.bugzilla.org/docs/>`_.
-
-
-.. _gfdl:
-
-==============================
-GNU Free Documentation License
-==============================
-
-.. COMMENT: - GNU Project - Free Software Foundation (FSF)
-
-.. COMMENT: LINK REV="made" HREF="mailto:webmasters@gnu.org"
-
-.. COMMENT: section>
- <title>GNU Free Documentation License</title
-
-Version 1.1, March 2000
-
- Copyright (C) 2000 Free Software Foundation, Inc. 51 Franklin Street,
- Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and
- distribute verbatim copies of this license document, but changing it is
- not allowed.
-
-.. _gfdl-0:
-
-Preamble
-########
-
-The purpose of this License is to make a manual, textbook, or other
-written document "free" in the sense of freedom: to assure everyone the
-effective freedom to copy and redistribute it, with or without modifying
-it, either commercially or noncommercially. Secondarily, this License
-preserves for the author and publisher a way to get credit for their
-work, while not being considered responsible for modifications made by
-others.
-
-This License is a kind of "copyleft", which means that derivative
-works of the document must themselves be free in the same sense. It
-complements the GNU General Public License, which is a copyleft license
-designed for free software.
-
-We have designed this License in order to use it for manuals for
-free software, because free software needs free documentation: a free
-program should come with manuals providing the same freedoms that the
-software does. But this License is not limited to software manuals; it
-can be used for any textual work, regardless of subject matter or whether
-it is published as a printed book. We recommend this License principally
-for works whose purpose is instruction or reference.
-
-.. _gfdl-1:
-
-Applicability and Definition
-############################
-
-This License applies to any manual or other work that contains a
-notice placed by the copyright holder saying it can be distributed under
-the terms of this License. The "Document", below, refers to any such
-manual or work. Any member of the public is a licensee, and is addressed
-as "you".
-
-A "Modified Version" of the Document means any work containing the
-Document or a portion of it, either copied verbatim, or with
-modifications and/or translated into another language.
-
-A "Secondary Section" is a named appendix or a front-matter section
-of the Document that deals exclusively with the relationship of the
-publishers or authors of the Document to the Document's overall subject
-(or to related matters) and contains nothing that could fall directly
-within that overall subject. (For example, if the Document is in part a
-textbook of mathematics, a Secondary Section may not explain any
-mathematics.) The relationship could be a matter of historical connection
-with the subject or with related matters, or of legal, commercial,
-philosophical, ethical or political position regarding them.
-
-The "Invariant Sections" are certain Secondary Sections whose
-titles are designated, as being those of Invariant Sections, in the
-notice that says that the Document is released under this License.
-
-The "Cover Texts" are certain short passages of text that are
-listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says
-that the Document is released under this License.
-
-A "Transparent" copy of the Document means a machine-readable copy,
-represented in a format whose specification is available to the general
-public, whose contents can be viewed and edited directly and
-straightforwardly with generic text editors or (for images composed of
-pixels) generic paint programs or (for drawings) some widely available
-drawing editor, and that is suitable for input to text formatters or for
-automatic translation to a variety of formats suitable for input to text
-formatters. A copy made in an otherwise Transparent file format whose
-markup has been designed to thwart or discourage subsequent modification
-by readers is not Transparent. A copy that is not "Transparent" is called
-"Opaque".
-
-Examples of suitable formats for Transparent copies include plain
-ASCII without markup, Texinfo input format, LaTeX input format, SGML or
-XML using a publicly available DTD, and standard-conforming simple HTML
-designed for human modification. Opaque formats include PostScript, PDF,
-proprietary formats that can be read and edited only by proprietary word
-processors, SGML or XML for which the DTD and/or processing tools are not
-generally available, and the machine-generated HTML produced by some word
-processors for output purposes only.
-
-The "Title Page" means, for a printed book, the title page itself,
-plus such following pages as are needed to hold, legibly, the material
-this License requires to appear in the title page. For works in formats
-which do not have any title page as such, "Title Page" means the text
-near the most prominent appearance of the work's title, preceding the
-beginning of the body of the text.
-
-.. _gfdl-2:
-
-Verbatim Copying
-################
-
-You may copy and distribute the Document in any medium, either
-commercially or noncommercially, provided that this License, the
-copyright notices, and the license notice saying this License applies to
-the Document are reproduced in all copies, and that you add no other
-conditions whatsoever to those of this License. You may not use technical
-measures to obstruct or control the reading or further copying of the
-copies you make or distribute. However, you may accept compensation in
-exchange for copies. If you distribute a large enough number of copies
-you must also follow the conditions in section 3.
-
-You may also lend copies, under the same conditions stated above,
-and you may publicly display copies.
-
-.. _gfdl-3:
-
-Copying in Quantity
-###################
-
-If you publish printed copies of the Document numbering more than
-100, and the Document's license notice requires Cover Texts, you must
-enclose the copies in covers that carry, clearly and legibly, all these
-Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts
-on the back cover. Both covers must also clearly and legibly identify you
-as the publisher of these copies. The front cover must present the full
-title with all words of the title equally prominent and visible. You may
-add other material on the covers in addition. Copying with changes
-limited to the covers, as long as they preserve the title of the Document
-and satisfy these conditions, can be treated as verbatim copying in other
-respects.
-
-If the required texts for either cover are too voluminous to fit
-legibly, you should put the first ones listed (as many as fit reasonably)
-on the actual cover, and continue the rest onto adjacent pages.
-
-If you publish or distribute Opaque copies of the Document
-numbering more than 100, you must either include a machine-readable
-Transparent copy along with each Opaque copy, or state in or with each
-Opaque copy a publicly-accessible computer-network location containing a
-complete Transparent copy of the Document, free of added material, which
-the general network-using public has access to download anonymously at no
-charge using public-standard network protocols. If you use the latter
-option, you must take reasonably prudent steps, when you begin
-distribution of Opaque copies in quantity, to ensure that this
-Transparent copy will remain thus accessible at the stated location until
-at least one year after the last time you distribute an Opaque copy
-(directly or through your agents or retailers) of that edition to the
-public.
-
-It is requested, but not required, that you contact the authors of
-the Document well before redistributing any large number of copies, to
-give them a chance to provide you with an updated version of the
-Document.
-
-.. _gfdl-4:
-
-Modifications
-#############
-
-You may copy and distribute a Modified Version of the Document
-under the conditions of sections 2 and 3 above, provided that you release
-the Modified Version under precisely this License, with the Modified
-Version filling the role of the Document, thus licensing distribution and
-modification of the Modified Version to whoever possesses a copy of it.
-In addition, you must do these things in the Modified Version:
-
-#. Use in the Title Page (and on the covers, if any) a title
- distinct from that of the Document, and from those of previous
- versions (which should, if there were any, be listed in the History
- section of the Document). You may use the same title as a previous
- version if the original publisher of that version gives
- permission.
-
-#. List on the Title Page, as authors, one or more persons or
- entities responsible for authorship of the modifications in the
- Modified Version, together with at least five of the principal
- authors of the Document (all of its principal authors, if it has less
- than five).
-
-#. State on the Title page the name of the publisher of the
- Modified Version, as the publisher.
-
-#. Preserve all the copyright notices of the Document.
-
-#. Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
-
-#. Include, immediately after the copyright notices, a license
- notice giving the public permission to use the Modified Version under
- the terms of this License, in the form shown in the Addendum
- below.
-
-#. Preserve in that license notice the full lists of Invariant
- Sections and required Cover Texts given in the Document's license
- notice.
-
-#. Include an unaltered copy of this License.
-
-#. Preserve the section entitled "History", and its title, and add
- to it an item stating at least the title, year, new authors, and
- publisher of the Modified Version as given on the Title Page. If
- there is no section entitled "History" in the Document, create one
- stating the title, year, authors, and publisher of the Document as
- given on its Title Page, then add an item describing the Modified
- Version as stated in the previous sentence.
-
-#. Preserve the network location, if any, given in the Document
- for public access to a Transparent copy of the Document, and likewise
- the network locations given in the Document for previous versions it
- was based on. These may be placed in the "History" section. You may
- omit a network location for a work that was published at least four
- years before the Document itself, or if the original publisher of the
- version it refers to gives permission.
-
-#. In any section entitled "Acknowledgements" or "Dedications",
- preserve the section's title, and preserve in the section all the
- substance and tone of each of the contributor acknowledgements and/or
- dedications given therein.
-
-#. Preserve all the Invariant Sections of the Document, unaltered
- in their text and in their titles. Section numbers or the equivalent
- are not considered part of the section titles.
-
-#. Delete any section entitled "Endorsements". Such a section may
- not be included in the Modified Version.
-
-#. Do not retitle any existing section as "Endorsements" or to
- conflict in title with any Invariant Section.
-
-If the Modified Version includes new front-matter sections or
-appendices that qualify as Secondary Sections and contain no material
-copied from the Document, you may at your option designate some or all of
-these sections as invariant. To do this, add their titles to the list of
-Invariant Sections in the Modified Version's license notice. These titles
-must be distinct from any other section titles.
-
-You may add a section entitled "Endorsements", provided it contains
-nothing but endorsements of your Modified Version by various parties--for
-example, statements of peer review or that the text has been approved by
-an organization as the authoritative definition of a standard.
-
-You may add a passage of up to five words as a Front-Cover Text,
-and a passage of up to 25 words as a Back-Cover Text, to the end of the
-list of Cover Texts in the Modified Version. Only one passage of
-Front-Cover Text and one of Back-Cover Text may be added by (or through
-arrangements made by) any one entity. If the Document already includes a
-cover text for the same cover, previously added by you or by arrangement
-made by the same entity you are acting on behalf of, you may not add
-another; but you may replace the old one, on explicit permission from the
-previous publisher that added the old one.
-
-The author(s) and publisher(s) of the Document do not by this
-License give permission to use their names for publicity for or to assert
-or imply endorsement of any Modified Version.
-
-.. _gfdl-5:
-
-Combining Documents
-###################
-
-You may combine the Document with other documents released under
-this License, under the terms defined in section 4 above for modified
-versions, provided that you include in the combination all of the
-Invariant Sections of all of the original documents, unmodified, and list
-them all as Invariant Sections of your combined work in its license
-notice.
-
-The combined work need only contain one copy of this License, and
-multiple identical Invariant Sections may be replaced with a single copy.
-If there are multiple Invariant Sections with the same name but different
-contents, make the title of each such section unique by adding at the end
-of it, in parentheses, the name of the original author or publisher of
-that section if known, or else a unique number. Make the same adjustment
-to the section titles in the list of Invariant Sections in the license
-notice of the combined work.
-
-In the combination, you must combine any sections entitled
-"History" in the various original documents, forming one section entitled
-"History"; likewise combine any sections entitled "Acknowledgements", and
-any sections entitled "Dedications". You must delete all sections
-entitled "Endorsements."
-
-.. _gfdl-6:
-
-Collections of Documents
-########################
-
-You may make a collection consisting of the Document and other
-documents released under this License, and replace the individual copies
-of this License in the various documents with a single copy that is
-included in the collection, provided that you follow the rules of this
-License for verbatim copying of each of the documents in all other
-respects.
-
-You may extract a single document from such a collection, and
-distribute it individually under this License, provided you insert a copy
-of this License into the extracted document, and follow this License in
-all other respects regarding verbatim copying of that document.
-
-.. _gfdl-7:
-
-Aggregation with Independent Works
-##################################
-
-A compilation of the Document or its derivatives with other
-separate and independent documents or works, in or on a volume of a
-storage or distribution medium, does not as a whole count as a Modified
-Version of the Document, provided no compilation copyright is claimed for
-the compilation. Such a compilation is called an "aggregate", and this
-License does not apply to the other self-contained works thus compiled
-with the Document, on account of their being thus compiled, if they are
-not themselves derivative works of the Document.
-
-If the Cover Text requirement of section 3 is applicable to these
-copies of the Document, then if the Document is less than one quarter of
-the entire aggregate, the Document's Cover Texts may be placed on covers
-that surround only the Document within the aggregate. Otherwise they must
-appear on covers around the whole aggregate.
-
-.. _gfdl-8:
-
-Translation
-###########
-
-Translation is considered a kind of modification, so you may
-distribute translations of the Document under the terms of section 4.
-Replacing Invariant Sections with translations requires special
-permission from their copyright holders, but you may include translations
-of some or all Invariant Sections in addition to the original versions of
-these Invariant Sections. You may include a translation of this License
-provided that you also include the original English version of this
-License. In case of a disagreement between the translation and the
-original English version of this License, the original English version
-will prevail.
-
-.. _gfdl-9:
-
-Termination
-###########
-
-You may not copy, modify, sublicense, or distribute the Document
-except as expressly provided for under this License. Any other attempt to
-copy, modify, sublicense or distribute the Document is void, and will
-automatically terminate your rights under this License. However, parties
-who have received copies, or rights, from you under this License will not
-have their licenses terminated so long as such parties remain in full
-compliance.
-
-.. _gfdl-10:
-
-Future Revisions of this License
-################################
-
-The Free Software Foundation may publish new, revised versions of
-the GNU Free Documentation License from time to time. Such new versions
-will be similar in spirit to the present version, but may differ in
-detail to address new problems or concerns. See
-`<http://www.gnu.org/copyleft/>`_.
-
-Each version of the License is given a distinguishing version
-number. If the Document specifies that a particular numbered version of
-this License "or any later version" applies to it, you have the option of
-following the terms and conditions either of that specified version or of
-any later version that has been published (not as a draft) by the Free
-Software Foundation. If the Document does not specify a version number of
-this License, you may choose any version ever published (not as a draft)
-by the Free Software Foundation.
-
-.. _gfdl-howto:
-
-How to use this License for your documents
-##########################################
-
-To use this License in a document you have written, include a copy
-of the License in the document and put the following copyright and
-license notices just after the title page:
-
- Copyright (c) YEAR YOUR NAME. Permission is granted to copy,
- distribute and/or modify this document under the terms of the GNU Free
- Documentation License, Version 1.1 or any later version published by
- the Free Software Foundation; with the Invariant Sections being LIST
- THEIR TITLES, with the Front-Cover Texts being LIST, and with the
- Back-Cover Texts being LIST. A copy of the license is included in the
- section entitled "GNU Free Documentation License".
-
-If you have no Invariant Sections, write "with no Invariant
-Sections" instead of saying which ones are invariant. If you have no
-Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover
-Texts being LIST"; likewise for Back-Cover Texts.
-
-If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of free
-software license, such as the GNU General Public License, to permit their
-use in free software.
+.. _license:
+
+License
+######
+
+Bugzilla is `free <http://www.gnu.org/philosophy/free-sw.html>`_ and
+`open source <http://opensource.org/osd>`_ software, which means (among other
+things) that you can download it, install it and run it for any purpose
+whatsoever without the need for license or payment. Isn't that refreshing?
+
+Bugzilla's code is made available under the
+`Mozilla Public License 2.0 <http://www.mozilla.org/MPL/2.0/>`_ (MPL),
+specifically the variant which is Incompatible with Secondary Licenses.
+However, again, if you only want to install and run Bugzilla, you don't need
+to worry about that; it's only relevant if you redistribute the code or any
+changes you make.
+
+Bugzilla's documentation is made available under the
+`Creative Commons CC-BY-SA International License 4.0 <https://creativecommons.org/licenses/by-sa/4.0/>`_,
+or any later version.
-
-
-.. _administration:
+.. _administering:
======================
Administering Bugzilla
======================
+.. toctree::
+ :maxdepth: 2
+
+ administering/parameters
+ administering/preferences
+ administering/users
+ administering/products
+ administering/versions-and-milestones
+ administering/flags
+ administering/fields
+ administering/workflow
+ administering/groups
+ administering/keywords
+ administering/whining
+ administering/extensions
+
.. _parameters:
Bugzilla Configuration
.. highlight:: perl
-.. _customization:
+.. _customizing:
====================
Customizing Bugzilla
====================
-.. _extensions:
-
-Bugzilla Extensions
-###################
-
-One of the best ways to customize Bugzilla is by writing a Bugzilla
-Extension. Bugzilla Extensions let you modify both the code and
-UI of Bugzilla in a way that can be distributed to other Bugzilla
-users and ported forward to future versions of Bugzilla with minimal
-effort.
-
-See the `Bugzilla Extension
-documentation <../html/api/Bugzilla/Extension.html>`_ for information on how to write an Extension.
-
-.. _cust-skins:
-
-Custom Skins
-############
-
-Bugzilla allows you to have multiple skins. These are custom CSS and possibly
-also custom images for Bugzilla. To create a new custom skin, you have two
-choices:
-
-- Make a single CSS file, and put it in the
- :file:`skins/contrib` directory.
-
-- Make a directory that contains all the same CSS file
- names as :file:`skins/standard/`, and put
- your directory in :file:`skins/contrib/`.
-
-After you put the file or the directory there, make sure to run checksetup.pl
-so that it can reset the file permissions correctly.
-
-After you have installed the new skin, it will show up as an option in the
-user's General Preferences. If you would like to force a particular skin on all
-users, just select it in the Default Preferences and then uncheck "Enabled" on
-the preference.
-
-.. _cust-templates:
-
-Template Customization
-######################
-
-Administrators can configure the look and feel of Bugzilla without
-having to edit Perl files or face the nightmare of massive merge
-conflicts when they upgrade to a newer version in the future.
-
-Templatization also makes localized versions of Bugzilla possible,
-for the first time. It's possible to have Bugzilla's UI language
-determined by the user's browser. More information is available in
-:ref:`template-http-accept`.
-
-.. _template-directory:
-
-Template Directory Structure
-============================
-
-The template directory structure starts with top level directory
-named :file:`template`, which contains a directory
-for each installed localization. The next level defines the
-language used in the templates. Bugzilla comes with English
-templates, so the directory name is :file:`en`,
-and we will discuss :file:`template/en` throughout
-the documentation. Below :file:`template/en` is the
-:file:`default` directory, which contains all the
-standard templates shipped with Bugzilla.
-
-.. warning:: A directory :file:`data/templates` also exists;
- this is where Template Toolkit puts the compiled versions of
- the templates from either the default or custom directories.
- *Do not* directly edit the files in this
- directory, or all your changes will be lost the next time
- Template Toolkit recompiles the templates.
-
-.. _template-method:
-
-Choosing a Customization Method
-===============================
-
-If you want to edit Bugzilla's templates, the first decision
-you must make is how you want to go about doing so. There are two
-choices, and which you use depends mainly on the scope of your
-modifications, and the method you plan to use to upgrade Bugzilla.
-
-The first method of making customizations is to directly edit the
-templates found in :file:`template/en/default`.
-This is probably the best way to go about it if you are going to
-be upgrading Bugzilla through Bzr, because if you then execute
-a :command:`bzr update`, any changes you have made will
-be merged automagically with the updated versions.
-
-.. note:: If you use this method, and Bzr conflicts occur during an
- update, the conflicted templates (and possibly other parts
- of your installation) will not work until they are resolved.
-
-The second method is to copy the templates to be modified
-into a mirrored directory structure under
-:file:`template/en/custom`. Templates in this
-directory structure automatically override any identically-named
-and identically-located templates in the
-:file:`default` directory.
-
-.. note:: The :file:`custom` directory does not exist
- at first and must be created if you want to use it.
-
-The second method of customization should be used if you
-use the overwriting method of upgrade, because otherwise
-your changes will be lost. This method may also be better if
-you are using the Bzr method of upgrading and are going to make major
-changes, because it is guaranteed that the contents of this directory
-will not be touched during an upgrade, and you can then decide whether
-to continue using your own templates, or make the effort to merge your
-changes into the new versions by hand.
-
-Using this method, your installation may break if incompatible
-changes are made to the template interface. Such changes should
-be documented in the release notes, provided you are using a
-stable release of Bugzilla. If you use using unstable code, you will
-need to deal with this one yourself, although if possible the changes
-will be mentioned before they occur in the deprecations section of the
-previous stable release's release notes.
-
-.. note:: Regardless of which method you choose, it is recommended that
- you run :command:`./checksetup.pl` after
- editing any templates in the :file:`template/en/default`
- directory, and after creating or editing any templates in
- the :file:`custom` directory.
-
-.. warning:: It is *required* that you run :command:`./checksetup.pl` after
- creating a new
- template in the :file:`custom` directory. Failure
- to do so will raise an incomprehensible error message.
-
-.. _template-edit:
-
-How To Edit Templates
-=====================
-
-.. note:: If you are making template changes that you intend on submitting back
- for inclusion in standard Bugzilla, you should read the relevant
- sections of the
- `Developers'
- Guide <http://www.bugzilla.org/docs/developer.html>`_.
-
-The syntax of the Template Toolkit language is beyond the scope of
-this guide. It's reasonably easy to pick up by looking at the current
-templates; or, you can read the manual, available on the
-`Template Toolkit home
-page <http://www.template-toolkit.org>`_.
-
-One thing you should take particular care about is the need
-to properly HTML filter data that has been passed into the template.
-This means that if the data can possibly contain special HTML characters
-such as <, and the data was not intended to be HTML, they need to be
-converted to entity form, i.e. <. You use the 'html' filter in the
-Template Toolkit to do this (or the 'uri' filter to encode special
-characters in URLs). If you forget, you may open up your installation
-to cross-site scripting attacks.
-
-Editing templates is a good way of doing a ``poor man's custom
-fields``.
-For example, if you don't use the Status Whiteboard, but want to have
-a free-form text entry box for ``Build Identifier``,
-then you can just
-edit the templates to change the field labels. It's still be called
-status_whiteboard internally, but your users don't need to know that.
-
-.. _template-formats:
-
-Template Formats and Types
-==========================
-
-Some CGI's have the ability to use more than one template. For example,
-:file:`buglist.cgi` can output itself as RDF, or as two
-formats of HTML (complex and simple). The mechanism that provides this
-feature is extensible.
-
-Bugzilla can support different types of output, which again can have
-multiple formats. In order to request a certain type, you can append
-the &ctype=<contenttype> (such as rdf or html) to the
-:file:`<cginame>.cgi` URL. If you would like to
-retrieve a certain format, you can use the &format=<format>
-(such as simple or complex) in the URL.
-
-To see if a CGI supports multiple output formats and types, grep the
-CGI for ``get_format``. If it's not present, adding
-multiple format/type support isn't too hard - see how it's done in
-other CGIs, e.g. config.cgi.
-
-To make a new format template for a CGI which supports this,
-open a current template for
-that CGI and take note of the INTERFACE comment (if present.) This
-comment defines what variables are passed into this template. If
-there isn't one, I'm afraid you'll have to read the template and
-the code to find out what information you get.
-
-Write your template in whatever markup or text style is appropriate.
-
-You now need to decide what content type you want your template
-served as. The content types are defined in the
-:file:`Bugzilla/Constants.pm` file in the
-:file:`contenttypes`
-constant. If your content type is not there, add it. Remember
-the three- or four-letter tag assigned to your content type.
-This tag will be part of the template filename.
-
-.. note:: After adding or changing a content type, it's suitable to
- edit :file:`Bugzilla/Constants.pm` in order to reflect
- the changes. Also, the file should be kept up to date after an
- upgrade if content types have been customized in the past.
-
-Save the template as :file:`<stubname>-<formatname>.<contenttypetag>.tmpl`.
-Try out the template by calling the CGI as
-:file:`<cginame>.cgi?format=<formatname>&ctype=<type>` .
-
-.. _template-specific:
-
-Particular Templates
-====================
-
-There are a few templates you may be particularly interested in
-customizing for your installation.
-
-:command:`index.html.tmpl`:
-This is the Bugzilla front page.
-
-:command:`global/header.html.tmpl`:
-This defines the header that goes on all Bugzilla pages.
-The header includes the banner, which is what appears to users
-and is probably what you want to edit instead. However the
-header also includes the HTML HEAD section, so you could for
-example add a stylesheet or META tag by editing the header.
-
-:command:`global/banner.html.tmpl`:
-This contains the ``banner``, the part of the header
-that appears
-at the top of all Bugzilla pages. The default banner is reasonably
-barren, so you'll probably want to customize this to give your
-installation a distinctive look and feel. It is recommended you
-preserve the Bugzilla version number in some form so the version
-you are running can be determined, and users know what docs to read.
-
-:command:`global/footer.html.tmpl`:
-This defines the footer that goes on all Bugzilla pages. Editing
-this is another way to quickly get a distinctive look and feel for
-your Bugzilla installation.
-
-:command:`global/variables.none.tmpl`:
-XXX Need to describe the use of this file
-
-:command:`list/table.html.tmpl`:
-This template controls the appearance of the bug lists created
-by Bugzilla. Editing this template allows per-column control of
-the width and title of a column, the maximum display length of
-each entry, and the wrap behaviour of long entries.
-For long bug lists, Bugzilla inserts a 'break' every 100 bugs by
-default; this behaviour is also controlled by this template, and
-that value can be modified here.
-
-:command:`bug/create/user-message.html.tmpl`:
-This is a message that appears near the top of the bug reporting page.
-By modifying this, you can tell your users how they should report
-bugs.
-
-:command:`bug/process/midair.html.tmpl`:
-This is the page used if two people submit simultaneous changes to the
-same bug. The second person to submit their changes will get this page
-to tell them what the first person did, and ask if they wish to
-overwrite those changes or go back and revisit the bug. The default
-title and header on this page read "Mid-air collision detected!" If
-you work in the aviation industry, or other environment where this
-might be found offensive (yes, we have true stories of this happening)
-you'll want to change this to something more appropriate for your
-environment.
-
-:command:`bug/create/create.html.tmpl` and
-:command:`bug/create/comment.txt.tmpl`:
-You may not wish to go to the effort of creating custom fields in
-Bugzilla, yet you want to make sure that each bug report contains
-a number of pieces of important information for which there is not
-a special field. The bug entry system has been designed in an
-extensible fashion to enable you to add arbitrary HTML widgets,
-such as drop-down lists or textboxes, to the bug entry page
-and have their values appear formatted in the initial comment.
-A hidden field that indicates the format should be added inside
-the form in order to make the template functional. Its value should
-be the suffix of the template filename. For example, if the file
-is called :file:`create-cust.html.tmpl`, then
-
-::
-
- <input type="hidden" name="format" value="cust">
-
-should be used inside the form.
-
-An example of this is the mozilla.org
-`guided
-bug submission form <http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl;format=guided>`_. The code for this comes with the Bugzilla
-distribution as an example for you to copy. It can be found in the
-files
-:file:`create-guided.html.tmpl` and
-:file:`comment-guided.html.tmpl`.
-
-So to use this feature, create a custom template for
-:file:`enter_bug.cgi`. The default template, on which you
-could base it, is
-:file:`custom/bug/create/create.html.tmpl`.
-Call it :file:`create-<formatname>.html.tmpl`, and
-in it, add widgets for each piece of information you'd like
-collected - such as a build number, or set of steps to reproduce.
-
-Then, create a template like
-:file:`custom/bug/create/comment.txt.tmpl`, and call it
-:file:`comment-<formatname>.txt.tmpl`. This
-template should reference the form fields you have created using
-the syntax :file:`[% form.<fieldname> %]`. When a
-bug report is
-submitted, the initial comment attached to the bug report will be
-formatted according to the layout of this template.
-
-For example, if your custom enter_bug template had a field
-
-::
-
- <input type="text" name="buildid" size="30">
-
-and then your comment.txt.tmpl had
-
-::
-
- BuildID: \[% form.buildid %]
-
-then something like
-
-::
-
- BuildID: 20020303
-
-would appear in the initial comment.
-
-.. _template-http-accept:
-
-Configuring Bugzilla to Detect the User's Language
-==================================================
-
-Bugzilla honours the user's Accept: HTTP header. You can install
-templates in other languages, and Bugzilla will pick the most appropriate
-according to a priority order defined by you. Many
-language templates can be obtained from `<http://www.bugzilla.org/download.html#localizations>`_. Instructions
-for submitting new languages are also available from that location.
-
-.. _cust-change-permissions:
-
-Customizing Who Can Change What
-###############################
-
-.. warning:: This feature should be considered experimental; the Bugzilla code you
- will be changing is not stable, and could change or move between
- versions. Be aware that if you make modifications as outlined here,
- you may have
- to re-make them or port them if Bugzilla changes internally between
- versions, and you upgrade.
-
-Companies often have rules about which employees, or classes of employees,
-are allowed to change certain things in the bug system. For example,
-only the bug's designated QA Contact may be allowed to VERIFY the bug.
-Bugzilla has been
-designed to make it easy for you to write your own custom rules to define
-who is allowed to make what sorts of value transition.
-
-By default, assignees, QA owners and users
-with *editbugs* privileges can edit all fields of bugs,
-except group restrictions (unless they are members of the groups they
-are trying to change). Bug reporters also have the ability to edit some
-fields, but in a more restrictive manner. Other users, without
-*editbugs* privileges, cannot edit
-bugs, except to comment and add themselves to the CC list.
-
-For maximum flexibility, customizing this means editing Bugzilla's Perl
-code. This gives the administrator complete control over exactly who is
-allowed to do what. The relevant method is called
-:file:`check_can_change_field()`,
-and is found in :file:`Bug.pm` in your
-Bugzilla/ directory. If you open that file and search for
-``sub check_can_change_field``, you'll find it.
-
-This function has been carefully commented to allow you to see exactly
-how it works, and give you an idea of how to make changes to it.
-Certain marked sections should not be changed - these are
-the ``plumbing`` which makes the rest of the function work.
-In between those sections, you'll find snippets of code like:
-
-::
-
- # Allow the assignee to change anything.
- if ($ownerid eq $whoid) {
- return 1;
- }
-
-It's fairly obvious what this piece of code does.
-
-So, how does one go about changing this function? Well, simple changes
-can be made just by removing pieces - for example, if you wanted to
-prevent any user adding a comment to a bug, just remove the lines marked
-``Allow anyone to change comments.`` If you don't want the
-Reporter to have any special rights on bugs they have filed, just
-remove the entire section that deals with the Reporter.
-
-More complex customizations are not much harder. Basically, you add
-a check in the right place in the function, i.e. after all the variables
-you are using have been set up. So, don't look at $ownerid before
-$ownerid has been obtained from the database. You can either add a
-positive check, which returns 1 (allow) if certain conditions are true,
-or a negative check, which returns 0 (deny.) E.g.:
-
-::
-
- if ($field eq "qacontact") {
- if (Bugzilla->user->in_group("quality_assurance")) {
- return 1;
- }
- else {
- return 0;
- }
- }
-
-This says that only users in the group "quality_assurance" can change
-the QA Contact field of a bug.
-
-Getting more weird:
-
-::
-
- if (($field eq "priority") &&
- (Bugzilla->user->email =~ /.*\\@example\\.com$/))
- {
- if ($oldvalue eq "P1") {
- return 1;
- }
- else {
- return 0;
- }
- }
-
-This says that if the user is trying to change the priority field,
-and their email address is @example.com, they can only do so if the
-old value of the field was "P1". Not very useful, but illustrative.
-
-.. warning:: If you are modifying :file:`process_bug.cgi` in any
- way, do not change the code that is bounded by DO_NOT_CHANGE blocks.
- Doing so could compromise security, or cause your installation to
- stop working entirely.
-
-For a list of possible field names, look at the bugs table in the
-database. If you need help writing custom rules for your organization,
-ask in the newsgroup.
-
-.. _integration:
-
-Integrating Bugzilla with Third-Party Tools
-###########################################
-
-Many utilities and applications can integrate with Bugzilla,
-either on the client- or server-side. None of them are maintained
-by the Bugzilla community, nor are they tested during our
-QA tests, so use them at your own risk. They are listed at
-`<https://wiki.mozilla.org/Bugzilla:Addons>`_.
-
+.. toctree::
+ :maxdepth: 2
+ customizing/existing-parameters
+ customizing/extensions
+ customizing/skins
+ customizing/languages
+ customizing/templates
+ customizing/who-can-change-what
+ customizing/writing-extensions
+Existing Parameters and Options
+===============================
+
+.. _extensions:
+
+Extensions
+==========
+
+One of the best ways to customize Bugzilla is by writing a Bugzilla
+Extension. Bugzilla Extensions let you modify both the code and
+UI of Bugzilla in a way that can be distributed to other Bugzilla
+users and ported forward to future versions of Bugzilla with minimal
+effort.
+
+See the `Bugzilla Extension
+documentation <../html/api/Bugzilla/Extension.html>`_ for information on how to write an Extension.
+
+Languages
+=========
+
+Bugzilla's templates can be localized, although it's a big job. If you have
+a localized set of templates for your version of Bugzilla, Bugzilla can also
+support multiple languages at once, with the user choosing which UI language
+they would prefer.
+.. _skins:
+
+Skins
+=====
+
+Bugzilla supports skins. It ships with two - "Classic" and "Dusk". You can
+find some more listed
+`on the wiki <https://wiki.mozilla.org/Bugzilla:Addons#Skins>`_, and there
+are a couple more which are part of
+`bugzilla.mozilla.org <http://git.mozilla.org/?p=webtools/bmo/bugzilla.git>`_.
+However, in each
+case you may need to check that the skin supports the version of Bugzilla
+you have.
+
+To create a new custom skin, you have two choices:
+
+- Make a single CSS file, and put it in the
+ :file:`skins/contrib` directory.
+
+- Make a directory that contains all the same CSS file
+ names as :file:`skins/standard/`, and put
+ your directory in :file:`skins/contrib/`.
+
+After you put the file or the directory there, make sure to run checksetup.pl
+so that it can reset the file permissions correctly.
+
+After you have installed the new skin, it will show up as an option in the
+user's General Preferences. If you would like to force a particular skin on all
+users, just select it in the Default Preferences and then uncheck "Enabled" on
+the preference.
+.. _templates:
+
+Templates
+#########
+
+Administrators can configure the look and feel of Bugzilla without
+having to edit Perl files or face the nightmare of massive merge
+conflicts when they upgrade to a newer version in the future.
+
+It's possible to have Bugzilla's UI language
+determined by the user's browser. More information is available in
+:ref:`template-http-accept`.
+
+.. _template-directory:
+
+Template Directory Structure
+============================
+
+The template directory structure starts with top level directory
+named :file:`template`, which contains a directory
+for each installed localization. The next level defines the
+language used in the templates. Bugzilla comes with English
+templates, so the directory name is :file:`en`,
+and we will discuss :file:`template/en` throughout
+the documentation. Below :file:`template/en` is the
+:file:`default` directory, which contains all the
+standard templates shipped with Bugzilla.
+
+.. warning:: A directory :file:`data/templates` also exists;
+ this is where Template Toolkit puts the compiled versions of
+ the templates. *Do not* directly edit the files in this
+ directory, or all your changes will be lost the next time
+ Template Toolkit recompiles the templates.
+
+.. _template-method:
+
+Choosing a Customization Method
+===============================
+
+If you want to edit Bugzilla's templates, the first decision
+you must make is how you want to go about doing so. There are two
+choices, and which you use depends mainly on the scope of your
+modifications, and the method you plan to use to upgrade Bugzilla.
+
+The first method of making customizations is to directly edit the
+templates found in :file:`template/en/default`.
+This is probably the best way for minor changes, because when you upgrade
+Bugzilla, either the source code management system or the :file:`patch` tool
+will merge your changes into the new version for you.
+
+On the downside, if the merge fails then Bugzilla will not work properly until
+you have fixed the problem and re-integrated your code.
+
+The second method is to copy the templates to be modified
+into a mirrored directory structure under
+:file:`template/en/custom`. Templates in this
+directory structure automatically override any identically-named
+and identically-located templates in the
+:file:`default` directory.
+
+The :file:`custom` directory does not exist at first and must be created if
+you want to use it.
+
+The second method of customization should be used if you
+use the overwriting method of upgrade, because otherwise
+your changes will be lost. This method may also be better if
+you are using the Bzr method of upgrading and are going to make major
+changes, because it is guaranteed that the contents of this directory
+will not be touched during an upgrade, and you can then decide whether
+to continue using your own templates, or make the effort to merge your
+changes into the new versions by hand.
+
+Using this method, your installation may break if incompatible
+changes are made to the template interface. Such changes should
+be documented in the release notes, provided you are using a
+stable release of Bugzilla. If you use using unstable code, you will
+need to deal with this one yourself, although if possible the changes
+will be mentioned before they occur in the deprecations section of the
+previous stable release's release notes.
+
+.. note:: Regardless of which method you choose, it is recommended that
+ you run :command:`./checksetup.pl` after
+ editing any templates in the :file:`template/en/default`
+ directory, and after creating or editing any templates in
+ the :file:`custom` directory.
+
+.. warning:: It is *required* that you run :command:`./checksetup.pl` after
+ creating a new
+ template in the :file:`custom` directory. Failure
+ to do so will raise an incomprehensible error message.
+
+.. _template-edit:
+
+How To Edit Templates
+=====================
+
+.. note:: If you are making template changes that you intend on submitting back
+ for inclusion in standard Bugzilla, you should read the relevant
+ sections of the
+ `Developers'
+ Guide <http://www.bugzilla.org/docs/developer.html>`_.
+
+The syntax of the Template Toolkit language is beyond the scope of
+this guide. It's reasonably easy to pick up by looking at the current
+templates; or, you can read the manual, available on the
+`Template Toolkit home
+page <http://www.template-toolkit.org>`_.
+
+One thing you should take particular care about is the need
+to properly HTML filter data that has been passed into the template.
+This means that if the data can possibly contain special HTML characters
+such as <, and the data was not intended to be HTML, they need to be
+converted to entity form, i.e. <. You use the 'html' filter in the
+Template Toolkit to do this (or the 'uri' filter to encode special
+characters in URLs). If you forget, you may open up your installation
+to cross-site scripting attacks.
+
+Editing templates is a good way of doing a ``poor man's custom
+fields``.
+For example, if you don't use the Status Whiteboard, but want to have
+a free-form text entry box for ``Build Identifier``,
+then you can just
+edit the templates to change the field labels. It's still be called
+status_whiteboard internally, but your users don't need to know that.
+
+.. _template-formats:
+
+Template Formats and Types
+==========================
+
+Some CGI's have the ability to use more than one template. For example,
+:file:`buglist.cgi` can output itself as RDF, or as two
+formats of HTML (complex and simple). The mechanism that provides this
+feature is extensible.
+
+Bugzilla can support different types of output, which again can have
+multiple formats. In order to request a certain type, you can append
+the &ctype=<contenttype> (such as rdf or html) to the
+:file:`<cginame>.cgi` URL. If you would like to
+retrieve a certain format, you can use the &format=<format>
+(such as simple or complex) in the URL.
+
+To see if a CGI supports multiple output formats and types, grep the
+CGI for ``get_format``. If it's not present, adding
+multiple format/type support isn't too hard - see how it's done in
+other CGIs, e.g. config.cgi.
+
+To make a new format template for a CGI which supports this,
+open a current template for
+that CGI and take note of the INTERFACE comment (if present.) This
+comment defines what variables are passed into this template. If
+there isn't one, I'm afraid you'll have to read the template and
+the code to find out what information you get.
+
+Write your template in whatever markup or text style is appropriate.
+
+You now need to decide what content type you want your template
+served as. The content types are defined in the
+:file:`Bugzilla/Constants.pm` file in the
+:file:`contenttypes`
+constant. If your content type is not there, add it. Remember
+the three- or four-letter tag assigned to your content type.
+This tag will be part of the template filename.
+
+.. note:: After adding or changing a content type, it's suitable to
+ edit :file:`Bugzilla/Constants.pm` in order to reflect
+ the changes. Also, the file should be kept up to date after an
+ upgrade if content types have been customized in the past.
+
+Save the template as :file:`<stubname>-<formatname>.<contenttypetag>.tmpl`.
+Try out the template by calling the CGI as
+:file:`<cginame>.cgi?format=<formatname>&ctype=<type>` .
+
+.. _template-specific:
+
+Particular Templates
+====================
+
+There are a few templates you may be particularly interested in
+customizing for your installation.
+
+:command:`index.html.tmpl`:
+This is the Bugzilla front page.
+
+:command:`global/header.html.tmpl`:
+This defines the header that goes on all Bugzilla pages.
+The header includes the banner, which is what appears to users
+and is probably what you want to edit instead. However the
+header also includes the HTML HEAD section, so you could for
+example add a stylesheet or META tag by editing the header.
+
+:command:`global/banner.html.tmpl`:
+This contains the ``banner``, the part of the header
+that appears
+at the top of all Bugzilla pages. The default banner is reasonably
+barren, so you'll probably want to customize this to give your
+installation a distinctive look and feel. It is recommended you
+preserve the Bugzilla version number in some form so the version
+you are running can be determined, and users know what docs to read.
+
+:command:`global/footer.html.tmpl`:
+This defines the footer that goes on all Bugzilla pages. Editing
+this is another way to quickly get a distinctive look and feel for
+your Bugzilla installation.
+
+:command:`global/variables.none.tmpl`:
+XXX Need to describe the use of this file
+
+:command:`list/table.html.tmpl`:
+This template controls the appearance of the bug lists created
+by Bugzilla. Editing this template allows per-column control of
+the width and title of a column, the maximum display length of
+each entry, and the wrap behaviour of long entries.
+For long bug lists, Bugzilla inserts a 'break' every 100 bugs by
+default; this behaviour is also controlled by this template, and
+that value can be modified here.
+
+:command:`bug/create/user-message.html.tmpl`:
+This is a message that appears near the top of the bug reporting page.
+By modifying this, you can tell your users how they should report
+bugs.
+
+:command:`bug/process/midair.html.tmpl`:
+This is the page used if two people submit simultaneous changes to the
+same bug. The second person to submit their changes will get this page
+to tell them what the first person did, and ask if they wish to
+overwrite those changes or go back and revisit the bug. The default
+title and header on this page read "Mid-air collision detected!" If
+you work in the aviation industry, or other environment where this
+might be found offensive (yes, we have true stories of this happening)
+you'll want to change this to something more appropriate for your
+environment.
+
+:command:`bug/create/create.html.tmpl` and
+:command:`bug/create/comment.txt.tmpl`:
+You may not wish to go to the effort of creating custom fields in
+Bugzilla, yet you want to make sure that each bug report contains
+a number of pieces of important information for which there is not
+a special field. The bug entry system has been designed in an
+extensible fashion to enable you to add arbitrary HTML widgets,
+such as drop-down lists or textboxes, to the bug entry page
+and have their values appear formatted in the initial comment.
+A hidden field that indicates the format should be added inside
+the form in order to make the template functional. Its value should
+be the suffix of the template filename. For example, if the file
+is called :file:`create-cust.html.tmpl`, then
+
+::
+
+ <input type="hidden" name="format" value="cust">
+
+should be used inside the form.
+
+An example of this is the mozilla.org
+`guided
+bug submission form <http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl;format=guided>`_. The code for this comes with the Bugzilla
+distribution as an example for you to copy. It can be found in the
+files
+:file:`create-guided.html.tmpl` and
+:file:`comment-guided.html.tmpl`.
+
+So to use this feature, create a custom template for
+:file:`enter_bug.cgi`. The default template, on which you
+could base it, is
+:file:`custom/bug/create/create.html.tmpl`.
+Call it :file:`create-<formatname>.html.tmpl`, and
+in it, add widgets for each piece of information you'd like
+collected - such as a build number, or set of steps to reproduce.
+
+Then, create a template like
+:file:`custom/bug/create/comment.txt.tmpl`, and call it
+:file:`comment-<formatname>.txt.tmpl`. This
+template should reference the form fields you have created using
+the syntax :file:`[% form.<fieldname> %]`. When a
+bug report is
+submitted, the initial comment attached to the bug report will be
+formatted according to the layout of this template.
+
+For example, if your custom enter_bug template had a field
+
+::
+
+ <input type="text" name="buildid" size="30">
+
+and then your comment.txt.tmpl had
+
+::
+
+ BuildID: \[% form.buildid %]
+
+then something like
+
+::
+
+ BuildID: 20020303
+
+would appear in the initial comment.
+
+.. _template-http-accept:
+
+Configuring Bugzilla to Detect the User's Language
+==================================================
+
+Bugzilla honours the user's Accept: HTTP header. You can install
+templates in other languages, and Bugzilla will pick the most appropriate
+according to a priority order defined by you. Many
+language templates can be obtained from `<http://www.bugzilla.org/download.html#localizations>`_. Instructions
+for submitting new languages are also available from that location.
+.. _cust-change-permissions:
+
+Who Can Change What
+###################
+
+.. warning:: This feature should be considered experimental; the Bugzilla code you
+ will be changing is not stable, and could change or move between
+ versions. Be aware that if you make modifications as outlined here,
+ you may have
+ to re-make them or port them if Bugzilla changes internally between
+ versions, and you upgrade.
+
+Companies often have rules about which employees, or classes of employees,
+are allowed to change certain things in the bug system. For example,
+only the bug's designated QA Contact may be allowed to VERIFY the bug.
+Bugzilla has been
+designed to make it easy for you to write your own custom rules to define
+who is allowed to make what sorts of value transition.
+
+By default, assignees, QA owners and users
+with *editbugs* privileges can edit all fields of bugs,
+except group restrictions (unless they are members of the groups they
+are trying to change). Bug reporters also have the ability to edit some
+fields, but in a more restrictive manner. Other users, without
+*editbugs* privileges, cannot edit
+bugs, except to comment and add themselves to the CC list.
+
+For maximum flexibility, customizing this means editing Bugzilla's Perl
+code. This gives the administrator complete control over exactly who is
+allowed to do what. The relevant method is called
+:file:`check_can_change_field()`,
+and is found in :file:`Bug.pm` in your
+Bugzilla/ directory. If you open that file and search for
+``sub check_can_change_field``, you'll find it.
+
+This function has been carefully commented to allow you to see exactly
+how it works, and give you an idea of how to make changes to it.
+Certain marked sections should not be changed - these are
+the ``plumbing`` which makes the rest of the function work.
+In between those sections, you'll find snippets of code like:
+
+::
+
+ # Allow the assignee to change anything.
+ if ($ownerid eq $whoid) {
+ return 1;
+ }
+
+It's fairly obvious what this piece of code does.
+
+So, how does one go about changing this function? Well, simple changes
+can be made just by removing pieces - for example, if you wanted to
+prevent any user adding a comment to a bug, just remove the lines marked
+``Allow anyone to change comments.`` If you don't want the
+Reporter to have any special rights on bugs they have filed, just
+remove the entire section that deals with the Reporter.
+
+More complex customizations are not much harder. Basically, you add
+a check in the right place in the function, i.e. after all the variables
+you are using have been set up. So, don't look at $ownerid before
+$ownerid has been obtained from the database. You can either add a
+positive check, which returns 1 (allow) if certain conditions are true,
+or a negative check, which returns 0 (deny.) E.g.:
+
+::
+
+ if ($field eq "qacontact") {
+ if (Bugzilla->user->in_group("quality_assurance")) {
+ return 1;
+ }
+ else {
+ return 0;
+ }
+ }
+
+This says that only users in the group "quality_assurance" can change
+the QA Contact field of a bug.
+
+Getting more weird:
+
+::
+
+ if (($field eq "priority") &&
+ (Bugzilla->user->email =~ /.*\\@example\\.com$/))
+ {
+ if ($oldvalue eq "P1") {
+ return 1;
+ }
+ else {
+ return 0;
+ }
+ }
+
+This says that if the user is trying to change the priority field,
+and their email address is @example.com, they can only do so if the
+old value of the field was "P1". Not very useful, but illustrative.
+
+.. warning:: If you are modifying :file:`process_bug.cgi` in any
+ way, do not change the code that is bounded by DO_NOT_CHANGE blocks.
+ Doing so could compromise security, or cause your installation to
+ stop working entirely.
+
+For a list of possible field names, look at the bugs table in the
+database. If you need help writing custom rules for your organization,
+ask in the newsgroup.
+======================
Bugzilla Documentation
======================
.. highlight:: console
-.. _installing-bugzilla:
+.. _installing:
===================
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
-------
-
-XXX Need to replace instructions for Oracle
-
-.. _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.
-
-.. _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.
-
-
+Bugzilla can be installed under Linux, Windows, Mac OS X, and perhaps other
+operating systems. However, if you are setting it up on a dedicated machine
+and you have control of the operating system to use, the Bugzilla team
+wholeheartedly recommends Linux as an extremely versatile, stable, and robust
+operating system that provides an ideal environment for Bugzilla.
+
+.. toctree::
+ :maxdepth: 1
+
+ installing/quick-start
+ installing/linux
+ installing/windows
+ installing/mac-os-x
+ installing/email
+ installing/optional-features
+ installing/migrating
+ installing/moving
--- /dev/null
+.. _http-apache:
+
+Apache
+######
+
+You have two options for running Bugzilla under Apache - mod_cgi (the
+default) and mod_perl. mod_perl is faster but takes more resources.
+
+.. _http-apache-mod_cgi:
+
+Apache 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 +FollowSymLinks
+ 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:: On Windows, you may have to also add the
+ ``ScriptInterpreterSource Registry-Strict``
+ line, see :ref:`Windows specific notes <win32-http>`.
+
+.. _http-apache-mod_perl:
+
+Apache with mod_perl
+====================
+
+Bugzilla requires version 1.999022 (AKA 2.0.0-RC5) of 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
+
+On restarting Apache, Bugzilla should now be running within the
+mod_perl environment.
+
+Please bear the following points in mind when considering using Bugzilla
+under mod_perl:
+
+- mod_perl support in Bugzilla can take up a HUGE amount of RAM - easily
+ 30MB per httpd child. 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.
+.. _email:
+
+Email
+#####
+
+Bugzilla requires the ability to set up email. You have a number of choices
+here. The simplest is to get Gmail or some other email provider to do the
+work for you, but you can also hand the mail off to a local email server,
+or run one yourself on the Bugzilla machine.
+
+.. _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.
--- /dev/null
+.. _http-iis:
+
+Microsoft IIS
+#############
+
+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`.
+.. _linux:
+
+Linux
+#####
+
+Many Linux distributions include Bugzilla and its dependencies in their
+package management systems. If you have root access, installing Bugzilla on
+any Linux system could be as simple as finding the Bugzilla package in the
+package management application and installing it. There may be a small bit
+of additional configuration required. If you are installing the machine from
+scratch, :ref:`quick-start` may be the best instructions for you.
+
+XXX What's our current position on Debian/Ubuntu packages of Bugzilla?
+
+Install Packages
+================
+
+Use your distribution's package manager to install Perl, your preferred
+database engine (MySQL if in doubt), and a webserver (Apache if in doubt).
+
+XXX Package lists for specific distros
+
+.. _install-perl:
+
+Perl
+====
+
+Test which version of Perl you have installed with:
+::
+
+ $ perl -v
+
+Bugzilla requires at least Perl |min-perl-ver|.
+
+.. _install-bzfiles:
+
+Bugzilla
+========
+
+The best way to get Bugzilla is to check it out from git:
+
+:command:`git clone https://git.mozilla.org/bugzilla/bugzilla`
+
+If that's not possible, you can
+`download a tarball of Bugzilla <http://www.bugzilla.org/download/>`_.
+
+Place Bugzilla in a suitable directory, accessible by the default web server
+user (probably ``apache`` or ``www-data``).
+Good locations are either directly in the web server's document directory
+(often :file:`/var/www/html`) or in :file:`/usr/local`, either with a
+symbolic link to the web server's document directory 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 requires a number of Perl modules. You can install these globally
+using your system's package manager, or install Bugzilla-only copies. At
+times, Bugzilla may require a version of a Perl module newer than the one
+your distribution packages, in which case you will need to install a
+Bugzilla-only copy of the newer version.
+
+At this point, you need to :file:`su` to root. You should remain as root
+until the end of the install.
+
+XXX Is this true, if they are installing modules locally?
+
+Install all missing modules locally like this:
+
+:command:`./install-module.pl --all`
+
+Or, you can pass an individual module name:
+
+:command:`./install-module.pl <modulename>`
+
+To check you indeed have new enough versions of all the required modules, run:
+
+:command:`./checksetup.pl --check-modules`
+
+You can run this command as many times as necessary.
+
+.. note:: If you are using a package-based distribution, and attempting to
+ install the Perl modules from CPAN (e.g. by using
+ :file:`install-module.pl`), 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`.
+
+.. _config-database:
+
+Web Server
+==========
+
+We have instructions for configuring Apache and IIS, although we strongly
+recommend using Apache. However, pretty much any web server that is capable of
+running CGI scripts will work.
+
+.. toctree::
+ :maxdepth: 1
+
+ apache
+ iis
+
+XXX Don't need IIS in the Linux docs.
+
+You can run :command:`testserver.pl http://bugzilla-url/` from the command
+line to check if your web server is correctly configured.
+
+XXX Does this work before doing any localconfig stuff?
+
+Database Engine
+===============
+
+Bugzilla supports MySQL, PostgreSQL, Oracle and SQLite as database servers.
+You only require one of these systems to make use of Bugzilla. MySQL is
+most commonly used. SQLite is good for trial installations as it requires no
+setup. Configure your server according to the instructions below.
+
+.. toctree::
+ :maxdepth: 1
+
+ mysql
+ postgresql
+ oracle
+ sqlite
+
+.. _config-webserver:
+
+.. _localconfig:
+
+localconfig
+===========
+
+You should now run :file:`checksetup.pl` again, this time
+without the ``--check-modules`` switch.
+
+:command:`./checksetup.pl`
+
+:file:`checksetup.pl` will write out a file called :file:`localconfig`.
+This file contains the default settings for a number of
+Bugzilla parameters, the most important of which are the group your web
+server runs as, and information on how to connect to your database.
+
+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`` (case-sensitive).
+
+.. note:: In Oracle, ``$db_name`` should actually be
+ the SID name of your database (e.g. "XE" if you are using Oracle XE).
+
+Set the value of ``$webservergroup`` to the group your web server runs as.
+The default is ``apache`` (correct for Red Hat/Fedora). On Debian and Ubuntu,
+Apache uses the ``www-data`` group.
+
+The other options in the :file:`localconfig` file are documented by their
+accompanying comments. If you have a non-standard database setup, you may
+need to change one or more of the other ``$db_*`` parameters.
+
+checksetup.pl
+=============
+
+Next, run :file:`checksetup.pl` an additional. 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.
+
+.. _install-config-bugzilla:
+
+Bugzilla
+========
+
+Your Bugzilla should now be working. Access
+:file:`http://<your-bugzilla-server>/` -
+you should see the Bugzilla front page.
+
+.. 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`.
+
+== Gentoo ==
+Gentoo pulls in all dependencies and, if you don't have the vhosts USE flag enabled, installs Bugzilla to /var/www/localhost/bugzilla when you issue:
+
+<code># emerge -av bugzilla</code>
+
+You will then have to configure and install your database according to your needs:
+
+For a first time MySQL install:
+
+<code># mysql_install_db</code>
+
+Else:
+
+<code># mysql -u root -p<br />
+mysql>CREATE DATABASE databasename;<br />
+mysql>GRANT <privs> ON databasename.* to 'bugzillauser'@'hostname' identified by 'pa$$w0rd';</code>
+
+== Fedora ==
+
+'''Please be aware of this:''' https://bugzilla.mozilla.org/show_bug.cgi?id=415605
+(Please remove this link once determined the RPM has been repaired)
+
+Bugzilla and its dependencies are in the Fedora yum repository. To install Bugzilla and all its Perl dependencies, simply do (as root)
+
+<code>$ yum install bugzilla</code>
+
+You also need to install the database engine and web server, for example MySQL and httpd:
+
+<code>$ yum install httpd mysql-server</code>
+
+The Fedora packages automatically do the httpd configuration, so there is no need to worry about that.
+
+To configure MySQL, you need to add the bugs user and bugs database to MySQL. You can do this with the normal MySQL tools - either use the command line, the mysqladmin tool, or the mysql-administrator GUI tool. You can also use a web-based control panel like PHPMyADMIN. Make sure the "bugs" user has write permissions ot the "bugs" database.
+
+The next step is to configure <code>/etc/bugzilla/localconfig</code> with the right database information:
+
+<pre>
+# The name of the database
+$db_name = 'bugs';
+
+# Who we connect to the database as.
+$db_user = 'bugs';
+
+# Enter your database password here. It's normally advisable to specify
+# a password for your bugzilla database user.
+# If you use apostrophe (') or a backslash (\) in your password, you'll
+# need to escape it by preceding it with a '\' character. (\') or (\)
+# (Far simpler just not to use those characters.)
+$db_pass = 'PASSWORD';
+</pre>
+
+Fedora stores the Bugzilla files in <code>/usr/share/bugzilla</code>. Change into that directory and run the <code>checksetup.pl</code> script. If any problems are encountered here, you can refer to the Bugzilla user guide.
+
+Finally, start mysqld and httpd and browse to http://localhost/bugzilla
+.. _mac-os-x:
+
+Mac OS X
+########
+
+`https://wiki.mozilla.org/Bugzilla:Mac_OS_X_installation`_ is what we have
+right now...
+
+*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.
+.. _migrating:
+
+Migrating From Other Bug-Tracking Systems
+#########################################
+
+Bugzilla has a framework you can use for migrating from other bug-tracking
+systems -
+`Bugzilla::Migrate <http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/Migrate.html>_.
+It provides the infrastructure you will need,
+but requires a module to be written to define the specifics of the system you
+are coming from. One exists for
+`Gnats <https://www.gnu.org/software/gnats/>`_. If you write one for a
+popular system, please share your code with us.
+
+Alternatively, Bugzilla comes with a script, :file:`importxml.pl`, which
+imports bugs in Bugzilla's XML format. You can see examples of this format
+by clicking the :guilabel:`XML` link at the bottom of a bug in a running
+Bugzilla. You would need to read the script to see how it handles errors,
+default values, creating non-existing values and so on.
+
+Bugzilla::Migrate is preferred if possible.
+
+
+.. _moving:
+
+Moving Bugzilla Between Machines
+################################
+
+Sometimes it's necessary to take a working installation of Bugzilla and move
+it to new hardware. This page explains how to do that, assuming that you
+have Bugzilla's webserver and database on the same machine, and you are moving
+both of them.
+
+You are advised to install the same version of Bugzilla on the new
+machine as the old machine - any :ref:`upgrade <upgrading>` you also need to
+do can then be done as a separate step. But if you do install a newer version,
+things should still work.
+
+1. Shut down your Bugzilla by loading the front page, going to
+ :guilabel:`Administration` | :guilabel:`Parameters` | :guilabel:`General`
+ and putting some text into the :guilabel:`shutdownhtml` parameter.
+
+2. Make a backup of the bugs database. For a typical Bugzilla setup using
+ MySQL, such a command might look like this:
+
+ :command:`mysqldump -u<username> -p bugs > bugzilla-backup.sql`
+
+ See the
+ `mysqldump documentation <http://dev.mysql.com/doc/mysql/en/mysqldump.html>`_
+ for more information on :file:`mysqldump`.
+
+3. On your new machine, install Bugzilla using the instructions at
+ :ref:`installing`. Look at the old machine if you need to know what values
+ you used for configuring e.g. MySQL.
+
+ XXX Need to say how far to go on the install
+
+4. Copy the :file:`data` directory and the :file:`localconfig` file from the
+ old Bugzilla installation to the new one.
+
+5. If anything about your database configuration changed (location of the
+ server, username, password, etc.) as part of the move, update the
+ appropriate variables in :file:`localconfig`.
+
+6. If the new URL to your new Bugzilla installation is different from the old
+ one, update the :guilabel:`urlbase` parameter in :file:`data/params` using
+ a text editor.
+
+7. Copy the database backup file :file:`bugzilla-backup.sql` file from your
+ old server to the new one.
+
+8. Create an empty "bugs" database on the new server:
+
+ :command:`mysql -u root -p -e "CREATE DATABASE bugs DEFAULT CHARACTER SET utf8;"`
+
+9. Import your :file:`bugzilla-backup.sql` file into your new "bugs" database:
+
+ :command:`mysql -u root -p bugs < bugzilla-backup.sql`
+
+ If you get an error about "packet too large" or "mysql server has gone
+ away", you need to adjust the :guilabel:`max_allowed_packet` setting in
+ your :file:`my.cnf` file (usually :file:`/etc/my.cnf`) file to be larger
+ than the largest attachment ever added to your Bugzilla.
+
+ If there are *any* errors during this step, you have to drop the
+ database, create it again using the step above, and do the import again.
+
+10. Run :file:`checksetup.pl` to make sure all is OK.
+ (Unless you are using a newer version of Bugzilla on your new server, this
+ should not make any changes.)
+
+ :command:`./checksetup.pl`
+
+11. Activate your new Bugzilla by loading the front page, going to
+ :guilabel:`Administration` | :guilabel:`Parameters` | :guilabel:`General`
+ and removing the text from the :guilabel:`shutdownhtml` parameter.
--- /dev/null
+.. _install-mysql:
+
+MySQL
+#####
+
+Test which version of MySQL you have installed with:
+
+:command:`mysql -V`
+
+You need MySQL version 5.0.15 or higher.
+
+If you install MySQL manually rather than from a package, make sure the
+server is started when the machine boots.
+
+.. _secure-mysql:
+
+Secure MySQL
+============
+
+On non-Windows platforms, run
+
+:command:`mysql_secure_installation`
+
+and follow its advice.
+
+Add a user
+==========
+
+You need to add a new MySQL user for Bugzilla to use. Run the :file:`mysql`
+command-line client and enter:
+
+::
+
+ 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;
+
+The above permits an account called ``bugs``
+to connect from the local machine, ``localhost``. Modify the command to
+reflect your setup if you will be connecting from another
+machine or as a different user.
+
+Make a note of the password you set.
+
+.. _mysql-max-allowed-packet:
+
+Allow large attachments and many comments
+=========================================
+
+To change MySQL's configuration, you need to edit your MySQL
+configuration file, which is usually :file:`/etc/my.cnf`
+on Linux.
+
+By default, MySQL will only allow you to insert things
+into the database that are smaller than 1MB. Bugzilla 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.
+
+We recommend that you allow at least 16MB packets by
+adding the ``max_allowed_packet`` parameter to your MySQL
+configuration in the ``[mysqld]`` section, like this:
+
+::
+
+ [mysqld]
+ # Allow packets up to 16MB
+ max_allowed_packet=16M
+
+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.
+
+::
+
+ [mysqld]
+ # Allow small words in full-text indexes
+ ft_min_word_len=2
+
+.. _install-setupdatabase-adduser:
+
+Permit attachments table to grow beyond 4GB
+===========================================
+
+This is optional configuration for Bugzillas which are expected to become
+very large, and needs to be done after Bugzilla is fully installed.
+
+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, run the :file:`mysql`
+command-line client and enter the following, replacing ``$bugs_db``
+with your Bugzilla database name (which is ``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, so ideally
+you should do this when your attachments table is still small.
+
+.. note:: If you have set the setting in Bugzilla which allows large
+ attachments to be stored on disk, the above change does not affect that.
+.. _optional-features:
+
+Optional Features
+#################
+
+XXXHACKME
+
+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.
+
--- /dev/null
+.. _install-oracle:
+
+Oracle
+######
+
+.. warning:: Bugzilla supports Oracle, but none of the current developers run
+ it. Your mileage may vary.
+
+You need Oracle version 10.02.0 or later.
+
+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
+: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.
+
+::
+
+ 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.
--- /dev/null
+.. _install-pg:
+
+PostgreSQL
+##########
+
+Test which version of PostgreSQL you have installed with:
+
+:command:`psql -V`
+
+You need PostgreSQL version 8.03.0000 or higher.
+
+If you install PostgreSQL manually rather than from a package, make sure the
+server is started when the machine boots.
+
+Add a User
+==========
+
+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.
+
+On most systems, to create a user in PostgreSQL, login as the root user, and
+then switch to being the postgres (Unix) user:
+
+:command:`su - postgres`
+
+As the postgres user, you then need to create a new user:
+
+:command:`createuser -U postgres -dRSP bugs`
+
+When asked for a password, provide one and write it down for later reference.
+
+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).
+
+Permit Access
+=============
+
+Edit the file :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 stop and start PostgreSQL fully. (Do not use any
+'restart' command, due to the possibility of a change to
+:file:`postgresql.conf`.)
+.. _quick-start:
+
+Quick Start (Ubuntu 14.04 LTS)
+##############################
+
+This quick start guide makes installing Bugzilla as simple as possible for
+those who are able to choose their environment. It creates a system using
+Ubuntu 14.04 LTS, Apache and MySQL, and installs Bugzilla as the default
+home page. It requires a little familiarity with Linux and the command line.
+
+0. Obtain Your Hardware
+
+ Ubuntu 14.04 LTS Server requires a 64-bit processor.
+ Bugzilla itself has no prerequisites beyond that, although you should pick
+ reliable hardware. You can also probably use any 64-bit virtual machine
+ or cloud instance that you have root access on.
+
+1. Install the OS
+
+ Get `Ubuntu Server 14.04 LTS <http://www.ubuntu.com/download/server>`_
+ and follow the `installation instructions <http://www.ubuntu.com/download/server/install-ubuntu-server>`_.
+ Here are some tips:
+
+ * Choose any server name you like.
+ * When creating the initial user, call it "bugzilla", give it a strong
+ password, and write it down.
+ * You do not need an encrypted home directory.
+ * Choose all the defaults for the "partitioning" part (excepting of course
+ where the default is "No" and you need to press "Yes" to continue).
+ * Choose "install security updates automatically" unless you want to do
+ them manually.
+ * From the install options, choose "OpenSSH Server" and "LAMP Server".
+ * Set the password for the MySQL root user to a strong password, and write
+ it down.
+ * Install the Grub boot loader to the Master Boot Record.
+
+ Reboot when the installer finishes.
+
+2. Become root
+
+ ssh to the machine as the 'bugzilla' user, or start a console. Then:
+
+ :command:`sudo su`
+
+3. Install Prerequisites
+
+ :command:`apt-get install git nano`
+
+ :command:`apt-get install apache2 mysql-server libappconfig-perl libdate-calc-perl libtemplate-perl libmime-perl build-essential libdatetime-timezone-perl libdatetime-perl libemail-send-perl libemail-mime-perl libemail-mime-modifier-perl libdbi-perl libdbd-mysql-perl libcgi-pm-perl libmath-random-isaac-perl libmath-random-isaac-xs-perl apache2-mpm-prefork libapache2-mod-perl2 libapache2-mod-perl2-dev libchart-perl libxml-perl libxml-twig-perl perlmagick libgd-graph-perl libtemplate-plugin-gd-perl libsoap-lite-perl libhtml-scrubber-perl libjson-rpc-perl libdaemon-generic-perl libtheschwartz-perl libtest-taint-perl libauthen-radius-perl libfile-slurp-perl libencode-detect-perl libmodule-build-perl libnet-ldap-perl libauthen-sasl-perl libtemplate-perl-doc libfile-mimeinfo-perl libhtml-formattext-withlinks-perl libgd-dev lynx-cur`
+
+ This will take a little while. It's split into two commands so you can do
+ the next steps (up to step 7) in another terminal while you wait for the
+ second command to finish. If you start another terminal, you will need to
+ :command:`sudo su` again.
+
+4. Download Bugzilla
+
+ Get it from our Git repository:
+
+ :command:`cd /var/www`
+
+ :command:`rm -rf html`
+
+ :command:`git clone https://git.mozilla.org/bugzilla/bugzilla html`
+
+ :command:`cd html`
+
+ :command:`git checkout bugzilla-stable`
+
+ You will get a notification about having a detached HEAD. Don't worry,
+ your head is still firmly on your shoulders.
+
+ XXX is this the right way to get the current bugzilla-stable code? Or
+ should we pull directly from a branch?
+
+5. Configure MySQL
+
+ The following instructions use the simple :file:`nano` editor, but feel
+ free to use any text editor you are comfortable with.
+
+ :command:`nano /etc/mysql/my.cnf`
+
+ Set the following values, which increase the maximum attachment size and
+ make it possible to search for short words and terms:
+
+ * Alter on Line 52: ``max_allowed_packet=100M``
+ * Add as new line 31, in [mysqld] section: ``ft_min_word_len=2``
+
+ Save and exit.
+
+ XXX default value of maxattachmentsize is 1MB. Default value of max_allowed_packet
+ is 16MB. Should we just omit this step entirely, for simplicity? Do we need
+ ft_min_word_len changed?
+
+ XXX docs for maxattachmentsize should mention max_allowed_packet. File bug.
+
+ Restart MySQL:
+
+ :command:`service mysql restart`
+
+6. Configure Apache
+
+ :command:`nano /etc/apache2/sites-available/bugzilla.conf`
+
+ Paste in the following and save:
+
+ .. code-block:: none
+
+ ServerName localhost
+
+ <Directory /var/www/html>
+ AddHandler cgi-script .cgi
+ Options +ExecCGI
+ DirectoryIndex index.cgi index.html
+ AllowOverride Limit FileInfo Indexes Options
+ </Directory>
+
+ :command:`a2ensite bugzilla`
+
+ :command:`a2enmod cgi headers expires`
+
+ :command:`service apache2 restart`
+
+8. Check Setup
+
+ Bugzilla comes with a :file:`checksetup.pl` script which helps with the
+ installation process. It needs to be run twice. The first time, it
+ generates a config file (called :file:`localconfig`) for the database
+ access information, and the second time
+ it uses the info you put in the config file to set up the database.
+
+ :command:`cd /var/www/html`
+
+ :command:`./checksetup.pl`
+
+9. Edit :file:`localconfig`
+
+ :command:`nano localconfig`
+
+ You will need to set the following values:
+
+ * Line 29: set $webservergroup to ``www-data``
+ * Line 60: set $db_user to ``root``
+ * Line 67: set $db_pass to the MySQL root user password you created when
+ installing Ubuntu
+
+ XXX Given this is a quick setup on a dedicated box, is it OK to use the
+ MySQL root user?
+
+ XXX Why can't checksetup determine webservergroup automatically,
+ and prompt for db_user and db_pass, and just keep going? Perhaps with a
+ --simple switch?
+
+10. Check Setup (again)
+
+ Run the :file:`checksetup.pl` script again to set up the database.
+
+ :command:`./checksetup.pl`
+
+ It will ask you to give an email address, real name and password for the
+ first Bugzilla account to be created, which will be an administrator.
+ Write down the email address and password you set.
+
+11. Test Server
+
+ :command:`./testserver.pl http://localhost/`
+
+ All the tests should pass. (Note: currently, the first one will give a
+ warning instead. You can ignore that. Bug 1040728.)
+
+ XXX Also, Chart::Base gives deprecation warnings :-|
+
+12. Access Via Web Browser
+
+ Access the front page:
+
+ :command:`lynx http://localhost/`
+
+ Using Bugzilla through Lynx doesn't work for real, but viewing the front
+ page can validate visually that it's up and running.
+
+ You might well need to configure your DNS such that the server has, and
+ is reachable by, a name rather than IP address. Doing so is out of scope
+ of this document. In the mean time, it is available on your local network
+ at ``http://<ip address>/``, where ``<ip address>`` is probably the "inet addr"
+ value displayed when you run :command:`ifconfig eth0`.
+
+13. Configure Bugzilla
+
+ Once you have worked out how to access your Bugzilla in a graphical
+ web browser, bring up the front page, click "Log In" in the header, and
+ log in as the admin user you defined in step 10.
+
+ Click the "Parameters" link on the page it gives you, and set the
+ following parameters in the 'Required Settings' section:
+
+ * urlbase: ``http://<servername>/`` or ``http://<ip address>/``
+
+ Click "Save Changes" at the bottom of the page.
+
+ There are several ways to get Bugzilla to send email. The easiest is to
+ use Gmail, so we do that here so you have it working. Create a new Gmail
+ account for your Bugzilla to use at https://gmail.com. Then, open the "Email"
+ section of the Parameters using the link in the left column, and set the
+ following parameter values:
+
+ * mail_delivery_method: SMTP
+ * mailfrom: ``bugzilla_email_address@gmail.com``
+ * smtpserver: ``smtp.gmail.com:465``
+ * smtp_username: ``bugzilla_email_address@gmail.com``
+ * smtp_password: ``the_gmail_password``
+ * smtp_ssl: On
+
+ Click "Save Changes" at the bottom of the page.
+
+ XXX There should be a "send test email" button on that page
+
+ Now proceed to Chapter XXX, "Initial Configuration".
--- /dev/null
+.. _install-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.
+
+Once you have SQLite installed, no additional configuration is required to
+run Bugzilla. Simply set $db_driver to "Sqlite" (case-sensitive) in
+:file:`localconfig`, when you get to that point in the installation.
+
+XXX This doesn't work - gives a timezone-related error on my box.
+
+The database will be stored in :file:`data/db/$db_name`, where ``$db_name``
+is the database name defined in :file:`localconfig`.
+.. _windows:
+
+Windows
+#######
+
+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.
+
+
+: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:
+Add a User to Oracle
+
+
+
+.. _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.
+.. _integrating:
+
+=========================
+Integrating with Bugzilla
+=========================
+
+.. toctree::
+ :maxdepth: 2
+
+ integrating/apis
+ integrating/tips
+
+.. _integration:
+
+Integrating Bugzilla with Third-Party Tools
+###########################################
+
+Many utilities and applications can integrate with Bugzilla,
+either on the client- or server-side. None of them are maintained
+by the Bugzilla community, nor are they tested during our
+QA tests, so use them at your own risk. They are listed at
+`<https://wiki.mozilla.org/Bugzilla:Addons>`_.
+
+
+.. _maintaining:
+
+====================
Maintaining Bugzilla
====================
.. toctree::
:maxdepth: 2
+
+ maintaining/upgrades
+ maintaining/backups
+ maintaining/sanity-check
+ maintaining/merging-accounts
.. _backups:
-Making Backups
-##############
-
- 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
+Backups
+#######
+
+Database
+========
+
+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. Replace the $VARIABLEs with appropriate values for your
+setup.
+
+MySQL
+-----
+
+:command:`mysqldump --opt -u $USERNAME -p $DATABASENAME > backup.sql`
+
+PostgreSQL
+----------
+
+:command:`pg_dump --no-privileges --no-owner -h localhost -U $USERNAME > bugs.sql`
+
+Bugzilla
+========
+
+It's also a good idea to back up the Bugzilla directory itself, as there are
+some data files and configuration files stored there which you would want to
+retain. A simple recursive copy will do the job here.
+
+:command:`cp -rp $BUGZILLA_HOME /var/backups/bugzilla`
+Merging Accounts
+################
+
+Sometimes, users accidentally create a second account and do things with it,
+perhaps because they don't realise they can change the email address
+associated with their account. And then they don't want to abandon the
+history associated with either.
+
+XXX BMO's merge accounts script?
+.. _sanity-check:
+
+Sanity Check
+============
+
+Bugzilla has an option in the Administration panel called "Sanity Check",
+which makes sure the database is consistent in various ways. You should
+run it every few months or so.
--- /dev/null
+.. _upgrades:
+
+Upgrades
+########
+
+For details on how to upgrade Bugzilla, see the :ref:`upgrading` chapter.
+
+Bugzilla can automatically notify administrators when new releases are
+available if the :guilabel:`upgrade_notification` parameter is set. Administrators
+will see these notifications when they access the Bugzilla home page. Bugzilla
+will check once per day for new releases. If you are behind a proxy, you may
+have to set the :guilabel:`proxy_url` parameter accordingly. If the proxy
+requires authentication, use the ``http://user:pass@proxy_url/`` syntax.
-
-
.. _security:
=================
can't have a substitution inside a link, or bold inside italics.
A filename or a path to a filename is displayed like this:
-:file:`/path/to/filename.ext`
+:file:`/path/to/{variable-bit-of-path}/filename.ext`
A command to type in the shell is displayed like this:
:command:`command --arguments`
-We place static values for substitution (using |subst-name|) in the file
-:file:`$BUGZILLA_HOME/docs/definitions.rst.tmpl`.
-This gets built into definitions.rst, with the script adding some definitions
-for minimum module versions etc. generated from the source itself. Lines in
-that file look like this:
-
-.. |subst-name| replace:: Some Text Here
+A parameter name is displayed like this:
+:guilabel:`shutdownhtml`
+.. _upgrading:
+
+==================
+Upgrading Bugzilla
+==================
+
+.. toctree::
+ :maxdepth: 2
+
+ upgrading/overview
+ upgrading/upgrading-with-git
+ upgrading/upgrading-from-bazaar
+ upgrading/upgrading-from-cvs
+ upgrading/upgrading-from-a-tarball
+.. _upgrading-overview:
+
Overview
########
+.. _upgrading-with-a-tarball:
+
+Upgrading with a 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.
+.. _upgrading-from-bazaar:
+
+Upgrading from Bazaar
+#####################
+
+The procedure to switch to Git is as follows:
+
+Update Your Bugzilla To The Latest Point Release
+================================================
+
+The idea is to switch version control systems without changing the exact
+version of Bugzilla you are using, to minimise the risk of conflict or
+problems. Any major upgrade can then happen
+as a separate step. It is recommended that you switch while using the latest
+point release for your version. You can update to the latest point release
+using bzr.
+
+First, you need to find what version of Bugzilla you are using. It should be
+in the top right corner of the front page but, if not, open the file
+:file:`Bugzilla/Constants.pm` in your Bugzilla directory and search for
+:code:`BUGZILLA_VERSION`.
+
+Then, you need to find out what the latest point release for that major
+version of Bugzilla is. The
+`Bugzilla download page <http://www.bugzilla.org/download/>`_
+should tell you that for supported versions. For versions out of support, here
+is a list of the final point releases:
+
+* 3.6.13
+* 3.4.14
+* 3.2.10
+* 3.0.11
+
+XXX Do we need below here? Are these versions in bzr? Will anyone be running
+them from a bzr install?
+
+* 2.22.7
+* 2.20.7
+* 2.18.6
+* 2.16.11
+* 2.14.5
+
+If you are not currently running the latest point release, you should use the
+following update command:
+
+:command:`bzr up -r tag:bugzilla-$VERSION`
+
+Where you replace $VERSION by the version number of the latest point release.
+Then run checksetup to upgrade your database:
+
+:command:`./checksetup.pl`
+
+You should then test your Bugzilla carefully, or just use it for a day or two,
+to make sure it's all still working fine.
+
+Save Any Local Customizations
+=============================
+
+Go into your Bugzilla directory and run this command:
+
+:command:`bzr diff > patch.diff`
+
+If you have made customizations to your Bugzilla, and you made them by
+changing the Bugzilla code itself (rather than using the Extension system),
+then :file:`patch.diff` will have non-zero size. You will want to keep a copy
+of those changes by keeping a copy of this file. If the file has zero size,
+you haven't made any local customizations.
+
+Download Code from Git
+======================
+
+Download a copy of your current version of Bugzilla from the git repository
+into a separate directory alongside your existing Bugzilla installation
+(which we will assume is in a directory called :file:`bugzilla`).
+
+You will need a copy of the git program. All Linux installations have it;
+search your package manager for "git". On Windows or Mac OS X, you can
+`download the official build <http://www.git-scm.com/downloads>`_. XXXmake_common
+
+Once git is installed, run these commands to pull a copy of Bugzilla:
+
+:command:`git clone https://git.mozilla.org/bugzilla/bugzilla bugzilla-git`
+
+:command:`cd bugzilla-git`
+
+:command:`git checkout $VERSION`
+
+Replace $VERSION with the two-digit version number of your current Bugzilla, e.g.
+4.2. These command will automatically change your version to the latest
+point release of version X.Y. :file:`bugzilla-git` is the name of the local
+directory into which the source code will be downloaded.
+
+Shut Down Bugzilla
+==================
+
+At this point, you should shut down Bugzilla to make sure nothing changes
+while you make the switch. Go into the administrative interface and put an
+appropriate message into the :guilabel:`shutdownhtml` parameter, which is in the
+"General" section of the administration parameters. As the name implies, HTML
+is allowed.
+
+This would be a good time to make :ref:`backups`. We shouldn't be affecting
+the database, but you can't be too careful.
+
+Copy Across Data and Modules
+============================
+
+Copy the contents of the following directories from your current installation
+of Bugzilla into the corresponding directory in :file:`bugzilla-git/`:
+
+.. code-block:: none
+
+ lib/
+ data/
+
+You also need to copy an extensions you have written or installed, which are
+in the :file:`extensions/` directory. In the Bugzilla directory, run this
+command:
+
+:command:`bzr status extensions/`
+
+If any directories are listed as "unknown", copy those across.
+
+Then, copy the following file from your current installation of Bugzilla
+into the corresponding place in :file:`bugzilla-git/`:
+
+.. code-block:: none
+
+ localconfig
+
+This file contains your database password and access details. Because your
+two versions of Bugzilla are the same, this should all work fine.
+
+Reapply Local Customizations
+============================
+
+If your :file:`patch.diff` file was zero sized, you can
+jump to the next step. Otherwise, you have to apply the patch to your new
+installation. If you are on Windows and you don’t have the :command:`patch`
+program, you can download it from
+`GNUWin <http://gnuwin32.sourceforge.net/packages/patch.htm>`_. Once
+downloaded, you must copy patch.exe into the Windows directory.
+
+Copy :file:`patch.diff` into the :file:`bugzilla-git` directory and then do:
+
+:command:`patch -p0 --dry-run < patch.diff`
+
+The patch should apply cleanly because you have exactly the same version of
+Bugzilla in both directories. If it does, remove the :command:`--dry-run` and
+rerun the command to apply it for real. If it does not apply cleanly, it is
+likely that you have managed to get a Bugzilla version mismatch between the
+two directories.
+
+Swap The New Version In
+=======================
+
+Now we swap the directories over, and run checksetup.pl to confirm that all
+is well. From the directory containing the :file:`bugzilla` and
+:file:`bugzilla-git` directories, run:
+
+:command:`mv bugzilla bugzilla-bzr`
+
+:command:`mv bugzilla-git bugzilla`
+
+:command:`cd bugzilla`
+
+:command:`./checksetup.pl`
+
+Running :file:`checksetup.pl` should not result in any changes to your database at
+the end of the run. If it does, then it's most likely that the two versions
+of Bugzilla you have are not, in fact, the same.
+
+Re-enable Bugzilla
+==================
+
+Go into the administrative interface and clear the contents of the
+:guilabel:`shutdownhtml` parameter.
+
+Test Bugzilla
+=============
+
+Use your Bugzilla for several days to check that the switch has had no
+detrimental effects. Then, follow the instructions in
+:ref:`upgrading-with-git` to upgrade to the latest version of Bugzilla.
+
+Rolling Back
+============
+
+If something goes wrong at any stage of the switching process (e.g. your
+patch doesn't apply, or checksetup doesn't complete), you can always just
+switch the directories back (if you've got that far) and re-enable Bugzilla
+(if you disabled it) and then seek help. Even if you have re-enabled Bugzilla,
+and find a problem a little while down the road, you are still using the same
+version so there would be few side effects to switching the directories back
+a day or three later.
+.. _upgrading-from-cvs:
+
+Upgrading from CVS
+##################
+
+XXX https://wiki.mozilla.org/Bugzilla:Moving_From_CVS_To_Bazaar
+
+This will be a clone of the Bzr instructions but using CVS commands.
+We might share some text using the include directive
+if there is a long enough section to be worth splitting it out. But I'm
+not going to fill it in until the Bzr instructions have had a review,
+to save having to maintain two copies of the same stuff.
Upgrading with a Tarball
########################
-If you are unable (or unwilling) to use Bzr, another option that's
+If you are unable (or unwilling) to use Git, 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.
+upgrade your 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.
+The best way to do this is to untar the tarball into a new directory (not
+on top of your existing installation), copy any data and configuration across
+to that directory, and then switch the directories over.
-::
-
- $ 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.
+XXX This now needs much the same info as an SCM switch about having
+parallel directories and copying stuff over.
+.. _upgrading-with-git:
+
+Upgrading with Git
+##################
+
+Upgrading to new Bugzilla releases is very simple, and you can upgrade
+from any version to any later version in one go - there is no need for
+intermediate steps. There is a script named :file:`checksetup.pl` included
+with Bugzilla that will automatically do all of the database migration
+for you.
+
+.. 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 a backup. Those with critical data or large installations may wish
+ to trial the upgrade on a development server first, using a copy of the
+ production data and configuration.
+
+In the commands below, :command:`$BUGZILLA_HOME` represents the directory
+in which Bugzilla is installed.
+
+.. _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 and all intermediate versions, particularly the "Notes for
+ Upgraders" sections, if present.
+
+#. Run the :ref:`sanity-check` on your installation. Attempt to fix all
+ warnings that the page produces before you go any further, or it's
+ possible that you may experience problems during your upgrade.
+
+#. Shut down your Bugzilla installation by putting some explanatory text
+ in the :guilabel:`shutdownhtml` parameter.
+
+#. Make all necessary :ref:`backups`.
+ *THIS IS VERY IMPORTANT*. If anything goes wrong during the upgrade,
+ having a backup allows you to roll back to a known good state.
+
+.. _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 than the simple process
+below. 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.
+
+XXX Need more here
+
+.. _upgrade-files:
+
+Getting The New Bugzilla
+========================
+
+:command:`cd $BUGZILLA_HOME`
+
+:command:`git checkout`
+
+:command:`git pull`
+
+XXX How to pull latest stable?
+
+.. _upgrade-database:
+
+Upgrading the Database
+======================
+
+Run :file:`checksetup.pl`. This will do everything required to convert
+your existing database and settings to the new version.
+
+:command:`cd $BUGZILLA_HOME`
+
+:command:`./checksetup.pl`
+
+ .. warning:: For some upgrades, running :file:`checksetup.pl` on a large
+ installation (75,000 or more bugs) can take a long time,
+ possibly several hours, if e.g. indexes need to be rebuilt. If this
+ would be a problem for you, you can determine timings by doing a test
+ upgrade on a development server with the production data.
+
+.. _upgrade-finish:
+
+Finishing The Upgrade
+=====================
+
+#. Reactivate Bugzilla by clear the text that you put into the
+ :guilabel:`shutdownhtml` parameter.
+
+#. Run a :ref:`sanity-check` on your
+ upgraded Bugzilla. It is recommended that you fix any problems
+ you see immediately. Failure to do this may mean that Bugzilla
+ will not work entirely correctly.
-
-
.. _using:
==============
Using Bugzilla
==============
+.. toctree::
+ :maxdepth: 2
+
+ using/creating-an-account
+ using/filing
+ using/understanding
+ using/editing
+ using/finding
+ using/tips
+ using/preferences
+
+
.. _using-intro:
Introduction
projects / thirdparty / bugzilla.git / commitdiff
