From: Gervase Markham Date: Thu, 11 Sep 2014 11:06:45 +0000 (+0100) Subject: Work in progress... X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3fb5117632fd04f336068279871c0559c5dce554;p=thirdparty%2Fbugzilla.git Work in progress... --- diff --git a/docs/en/rst/about.rst b/docs/en/rst/about.rst index 3ebde939da..720c5d4cc1 100644 --- a/docs/en/rst/about.rst +++ b/docs/en/rst/about.rst @@ -1,177 +1,15 @@ - - .. _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 `_. - -.. _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 ``_. 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 `_. -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 `_ -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 `_ -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 `_ -component. +.. toctree:: + :maxdepth: 2 + about/introduction + about/evaluating + about/getting-help + about/document-conventions + about/license + about/credits diff --git a/docs/en/rst/about/document-conventions.rst b/docs/en/rst/about/document-conventions.rst index e69de29bb2..7e446bc691 100644 --- a/docs/en/rst/about/document-conventions.rst +++ b/docs/en/rst/about/document-conventions.rst @@ -0,0 +1,34 @@ +.. _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 `_ +component. + diff --git a/docs/en/rst/about/evaluating.rst b/docs/en/rst/about/evaluating.rst index e69de29bb2..cbbe7ba258 100644 --- a/docs/en/rst/about/evaluating.rst +++ b/docs/en/rst/about/evaluating.rst @@ -0,0 +1,10 @@ +.. _evaluating: + +Evaluating Bugzilla +################### + +If you want to evaluate Bugzilla, you can try it out on "`Landfill `_", our test +server. The `Bugzilla FAQ `_ may also +be helpful, as it answers a number of questions people sometimes have about +whether Bugzilla can do what they need. + diff --git a/docs/en/rst/about/getting-help.rst b/docs/en/rst/about/getting-help.rst index e69de29bb2..4ff0a5d199 100644 --- a/docs/en/rst/about/getting-help.rst +++ b/docs/en/rst/about/getting-help.rst @@ -0,0 +1,16 @@ +.. _help: + +Getting More Help +################# + +If this document does not answer your questions, we run a +`Mozilla forum `_ +which can be accessed as a newsgroup, mailing list, or over the web as a +Google Group. Please +`search it `_ +first, and then ask your question there. + +If you need a guaranteed response, commercial support is +`available `_ for Bugzilla +from a number of people and organizations. + diff --git a/docs/en/rst/about/introduction.rst b/docs/en/rst/about/introduction.rst index e69de29bb2..091472c77d 100644 --- a/docs/en/rst/about/introduction.rst +++ b/docs/en/rst/about/introduction.rst @@ -0,0 +1,13 @@ +.. _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 `_. diff --git a/docs/en/rst/about/license.rst b/docs/en/rst/about/license.rst index 4c831a1d43..6ba8f89ea0 100644 --- a/docs/en/rst/about/license.rst +++ b/docs/en/rst/about/license.rst @@ -1,408 +1,21 @@ - - -.. _gfdl: - -============================== -GNU Free Documentation License -============================== - -.. COMMENT: - GNU Project - Free Software Foundation (FSF) - -.. COMMENT: LINK REV="made" HREF="mailto:webmasters@gnu.org" - -.. COMMENT: section> - GNU Free Documentation License`_. - -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 `_ and +`open source `_ 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 `_ (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 `_, +or any later version. diff --git a/docs/en/rst/administering.rst b/docs/en/rst/administering.rst index 81dc35107c..8c1f225f02 100644 --- a/docs/en/rst/administering.rst +++ b/docs/en/rst/administering.rst @@ -1,11 +1,25 @@ - - -.. _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 diff --git a/docs/en/rst/customizing.rst b/docs/en/rst/customizing.rst index d82ded8d05..9f7887ca27 100644 --- a/docs/en/rst/customizing.rst +++ b/docs/en/rst/customizing.rst @@ -1,477 +1,18 @@ .. 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 `_. - -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 `_. - -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= (such as rdf or html) to the -:file:`.cgi` URL. If you would like to -retrieve a certain format, you can use the &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:`-..tmpl`. -Try out the template by calling the CGI as -:file:`.cgi?format=&ctype=` . - -.. _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 - -:: - - - -should be used inside the form. - -An example of this is the mozilla.org -`guided -bug submission form `_. 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-.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-.txt.tmpl`. This -template should reference the form fields you have created using -the syntax :file:`[% form. %]`. 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 - -:: - - - -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 ``_. 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 -``_. - +.. toctree:: + :maxdepth: 2 + customizing/existing-parameters + customizing/extensions + customizing/skins + customizing/languages + customizing/templates + customizing/who-can-change-what + customizing/writing-extensions diff --git a/docs/en/rst/customizing/existing-parameters.rst b/docs/en/rst/customizing/existing-parameters.rst index e69de29bb2..d6585dfb1e 100644 --- a/docs/en/rst/customizing/existing-parameters.rst +++ b/docs/en/rst/customizing/existing-parameters.rst @@ -0,0 +1,3 @@ +Existing Parameters and Options +=============================== + diff --git a/docs/en/rst/customizing/extensions.rst b/docs/en/rst/customizing/extensions.rst index e69de29bb2..b79d911cb6 100644 --- a/docs/en/rst/customizing/extensions.rst +++ b/docs/en/rst/customizing/extensions.rst @@ -0,0 +1,14 @@ +.. _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. + diff --git a/docs/en/rst/customizing/languages.rst b/docs/en/rst/customizing/languages.rst index e69de29bb2..6dc1e49dd2 100644 --- a/docs/en/rst/customizing/languages.rst +++ b/docs/en/rst/customizing/languages.rst @@ -0,0 +1,7 @@ +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. diff --git a/docs/en/rst/customizing/skins.rst b/docs/en/rst/customizing/skins.rst index e69de29bb2..f400c43e63 100644 --- a/docs/en/rst/customizing/skins.rst +++ b/docs/en/rst/customizing/skins.rst @@ -0,0 +1,30 @@ +.. _skins: + +Skins +===== + +Bugzilla supports skins. It ships with two - "Classic" and "Dusk". You can +find some more listed +`on the wiki `_, and there +are a couple more which are part of +`bugzilla.mozilla.org `_. +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. diff --git a/docs/en/rst/customizing/templates.rst b/docs/en/rst/customizing/templates.rst index e69de29bb2..37a229ccb5 100644 --- a/docs/en/rst/customizing/templates.rst +++ b/docs/en/rst/customizing/templates.rst @@ -0,0 +1,308 @@ +.. _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 `_. + +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 `_. + +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= (such as rdf or html) to the +:file:`.cgi` URL. If you would like to +retrieve a certain format, you can use the &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:`-..tmpl`. +Try out the template by calling the CGI as +:file:`.cgi?format=&ctype=` . + +.. _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 + +:: + + + +should be used inside the form. + +An example of this is the mozilla.org +`guided +bug submission form `_. 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-.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-.txt.tmpl`. This +template should reference the form fields you have created using +the syntax :file:`[% form. %]`. 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 + +:: + + + +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 ``_. Instructions +for submitting new languages are also available from that location. diff --git a/docs/en/rst/customizing/who-can-change-what.rst b/docs/en/rst/customizing/who-can-change-what.rst index e69de29bb2..b7b236b3ee 100644 --- a/docs/en/rst/customizing/who-can-change-what.rst +++ b/docs/en/rst/customizing/who-can-change-what.rst @@ -0,0 +1,105 @@ +.. _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. diff --git a/docs/en/rst/index.rst b/docs/en/rst/index.rst index c7e65d71d0..9d6fcc298b 100644 --- a/docs/en/rst/index.rst +++ b/docs/en/rst/index.rst @@ -1,3 +1,4 @@ +====================== Bugzilla Documentation ====================== diff --git a/docs/en/rst/installing.rst b/docs/en/rst/installing.rst index 4aca12176c..c59f6e7206 100644 --- a/docs/en/rst/installing.rst +++ b/docs/en/rst/installing.rst @@ -1,1775 +1,30 @@ .. 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 ` - (|min-perl-ver| or above) - -#. :ref:`Install a Database Engine ` - -#. :ref:`Install a Webserver ` - -#. :ref:`Install Bugzilla ` - -#. :ref:`Install Perl modules ` - -#. :ref:`Install a Mail Transfer Agent ` - (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 ``_. -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 ``_. 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 ``_. 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:///` . - -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 `_. - -If you don't have Apache and your OS doesn't provide official packages, -visit ``_. - -.. _install-bzfiles: - -Bugzilla -======== - -`Download a Bugzilla tarball `_ -(or `check it out from 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 - -.. 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:`-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 ``_ - 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 `_. -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 -``_. - -.. _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 `_ 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 ` (the default) and -:ref:`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 ```` - 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 - - - AddHandler cgi-script .cgi - Options +ExecCGI - DirectoryIndex index.cgi index.html - AllowOverride Limit FileInfo Indexes Options - - -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. - ````). - 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 `. - -#. :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 - ```` 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 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 `_ -(for *Internet Information Services*) and -`231998 - HOW TO: FP2000: How to Use Perl with Microsoft Personal Web -Server on Windows 95/98 `_ -(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:///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: - -:: - - \perl.exe -x -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:///` - -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 && ./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 `_. - -.. _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 && ./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 `_. - -.. _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 && ./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 `_. - -.. _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 -```` section for your -Bugzilla, or in the ```` -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.` in the same location as -the default one (:file:`localconfig`). It also checks for -customized templates in a directory named -:file:`` in the same location as the -default one (:file:`template/`). 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 - - - ServerName foo.bar.baz - SetEnv PROJECT foo - Alias /bugzilla /var/www/bugzilla - - -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 `_. - -.. _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 `_ is also available -if you need more help with your installation. - -.. _win32-perl: - -Win32 Perl ----------- - -Perl for Windows can be obtained from -`ActiveState `_. -You should be able to find a compiled binary at ``_. -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 - -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 `_ - 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 `_ -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 (``_) -or 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 `_ 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 `_ 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 `_, -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 `_. - -:: - - $ 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 `_ 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 `_. - -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 diff --git a/docs/en/rst/installing/apache.rst b/docs/en/rst/installing/apache.rst new file mode 100644 index 0000000000..bc924f0522 --- /dev/null +++ b/docs/en/rst/installing/apache.rst @@ -0,0 +1,105 @@ +.. _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 ```` + 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 + + + AddHandler cgi-script .cgi + Options +ExecCGI +FollowSymLinks + DirectoryIndex index.cgi index.html + AllowOverride Limit FileInfo Indexes Options + + +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 `. + +.. _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 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. diff --git a/docs/en/rst/installing/email.rst b/docs/en/rst/installing/email.rst index e69de29bb2..ac9cc4e4ce 100644 --- a/docs/en/rst/installing/email.rst +++ b/docs/en/rst/installing/email.rst @@ -0,0 +1,47 @@ +.. _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. diff --git a/docs/en/rst/installing/iis.rst b/docs/en/rst/installing/iis.rst new file mode 100644 index 0000000000..5f3e89fe07 --- /dev/null +++ b/docs/en/rst/installing/iis.rst @@ -0,0 +1,64 @@ +.. _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 `_ +(for *Internet Information Services*) and +`231998 - HOW TO: FP2000: How to Use Perl with Microsoft Personal Web +Server on Windows 95/98 `_ +(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:///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: + +:: + + \perl.exe -x -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`. diff --git a/docs/en/rst/installing/linux.rst b/docs/en/rst/installing/linux.rst index e69de29bb2..d33a62f865 100644 --- a/docs/en/rst/installing/linux.rst +++ b/docs/en/rst/installing/linux.rst @@ -0,0 +1,271 @@ +.. _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 `_. + +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 ` + +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:`-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:///` - +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: + +# emerge -av bugzilla + +You will then have to configure and install your database according to your needs: + +For a first time MySQL install: + +# mysql_install_db + +Else: + +# mysql -u root -p
+mysql>CREATE DATABASE databasename;
+mysql>GRANT ON databasename.* to 'bugzillauser'@'hostname' identified by 'pa$$w0rd'; + +== 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) + +$ yum install bugzilla + +You also need to install the database engine and web server, for example MySQL and httpd: + +$ yum install httpd mysql-server + +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 /etc/bugzilla/localconfig with the right database information: + +
+# 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';
+
+ +Fedora stores the Bugzilla files in /usr/share/bugzilla. Change into that directory and run the checksetup.pl 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 diff --git a/docs/en/rst/installing/mac-os-x.rst b/docs/en/rst/installing/mac-os-x.rst index e69de29bb2..ed5c5b9eaf 100644 --- a/docs/en/rst/installing/mac-os-x.rst +++ b/docs/en/rst/installing/mac-os-x.rst @@ -0,0 +1,80 @@ +.. _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 `_ +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 (``_) +or 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. diff --git a/docs/en/rst/installing/migrating.rst b/docs/en/rst/installing/migrating.rst index e69de29bb2..45d2213e07 100644 --- a/docs/en/rst/installing/migrating.rst +++ b/docs/en/rst/installing/migrating.rst @@ -0,0 +1,23 @@ +.. _migrating: + +Migrating From Other Bug-Tracking Systems +######################################### + +Bugzilla has a framework you can use for migrating from other bug-tracking +systems - +`Bugzilla::Migrate _. +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 `_. 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. + + diff --git a/docs/en/rst/installing/moving.rst b/docs/en/rst/installing/moving.rst index e69de29bb2..7b8cf02f3b 100644 --- a/docs/en/rst/installing/moving.rst +++ b/docs/en/rst/installing/moving.rst @@ -0,0 +1,73 @@ +.. _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 ` 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 -p bugs > bugzilla-backup.sql` + + See the + `mysqldump documentation `_ + 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. diff --git a/docs/en/rst/installing/mysql.rst b/docs/en/rst/installing/mysql.rst new file mode 100644 index 0000000000..20ff67c5f0 --- /dev/null +++ b/docs/en/rst/installing/mysql.rst @@ -0,0 +1,116 @@ +.. _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. diff --git a/docs/en/rst/installing/optional-features.rst b/docs/en/rst/installing/optional-features.rst index e69de29bb2..37d75494bb 100644 --- a/docs/en/rst/installing/optional-features.rst +++ b/docs/en/rst/installing/optional-features.rst @@ -0,0 +1,157 @@ +.. _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 && ./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 `_. + +.. _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 && ./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 `_. + +.. _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 && ./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 `_. + +.. _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 +```` section for your +Bugzilla, or in the ```` +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.` in the same location as +the default one (:file:`localconfig`). It also checks for +customized templates in a directory named +:file:`` in the same location as the +default one (:file:`template/`). 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 + + + ServerName foo.bar.baz + SetEnv PROJECT foo + Alias /bugzilla /var/www/bugzilla + + +Don't forget to also export this variable before accessing Bugzilla +by other means, such as cron tasks for instance. + diff --git a/docs/en/rst/installing/oracle.rst b/docs/en/rst/installing/oracle.rst new file mode 100644 index 0000000000..80489805b0 --- /dev/null +++ b/docs/en/rst/installing/oracle.rst @@ -0,0 +1,63 @@ +.. _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. diff --git a/docs/en/rst/installing/postgresql.rst b/docs/en/rst/installing/postgresql.rst new file mode 100644 index 0000000000..e0f53e60af --- /dev/null +++ b/docs/en/rst/installing/postgresql.rst @@ -0,0 +1,54 @@ +.. _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`.) diff --git a/docs/en/rst/installing/quick-start.rst b/docs/en/rst/installing/quick-start.rst index e69de29bb2..3a87e3516c 100644 --- a/docs/en/rst/installing/quick-start.rst +++ b/docs/en/rst/installing/quick-start.rst @@ -0,0 +1,218 @@ +.. _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 `_ + and follow the `installation instructions `_. + 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 + + + AddHandler cgi-script .cgi + Options +ExecCGI + DirectoryIndex index.cgi index.html + AllowOverride Limit FileInfo Indexes Options + + + :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:///``, where ```` 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:///`` or ``http:///`` + + 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". diff --git a/docs/en/rst/installing/sqlite.rst b/docs/en/rst/installing/sqlite.rst new file mode 100644 index 0000000000..dd7b8d3bab --- /dev/null +++ b/docs/en/rst/installing/sqlite.rst @@ -0,0 +1,17 @@ +.. _install-sqlite: + +SQLite +###### + +.. warning:: Due to SQLite's `concurrency + limitations `_ 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`. diff --git a/docs/en/rst/installing/windows.rst b/docs/en/rst/installing/windows.rst index e69de29bb2..dca6b26d73 100644 --- a/docs/en/rst/installing/windows.rst +++ b/docs/en/rst/installing/windows.rst @@ -0,0 +1,127 @@ +.. _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 `_ 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 `_. +You should be able to find a compiled binary at ``_. +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 + +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 `_ + 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. diff --git a/docs/en/rst/integrating.rst b/docs/en/rst/integrating.rst index e69de29bb2..6c4cb2e72b 100644 --- a/docs/en/rst/integrating.rst +++ b/docs/en/rst/integrating.rst @@ -0,0 +1,12 @@ +.. _integrating: + +========================= +Integrating with Bugzilla +========================= + +.. toctree:: + :maxdepth: 2 + + integrating/apis + integrating/tips + diff --git a/docs/en/rst/integrating/tips.rst b/docs/en/rst/integrating/tips.rst index e69de29bb2..be5006bed3 100644 --- a/docs/en/rst/integrating/tips.rst +++ b/docs/en/rst/integrating/tips.rst @@ -0,0 +1,12 @@ +.. _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 +``_. + + diff --git a/docs/en/rst/maintaining.rst b/docs/en/rst/maintaining.rst index 532bf97943..299f011be8 100644 --- a/docs/en/rst/maintaining.rst +++ b/docs/en/rst/maintaining.rst @@ -1,5 +1,13 @@ +.. _maintaining: + +==================== Maintaining Bugzilla ==================== .. toctree:: :maxdepth: 2 + + maintaining/upgrades + maintaining/backups + maintaining/sanity-check + maintaining/merging-accounts diff --git a/docs/en/rst/maintaining/backups.rst b/docs/en/rst/maintaining/backups.rst index 039dbaf03c..1c59dc26f4 100644 --- a/docs/en/rst/maintaining/backups.rst +++ b/docs/en/rst/maintaining/backups.rst @@ -1,16 +1,33 @@ .. _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` diff --git a/docs/en/rst/maintaining/merging-accounts.rst b/docs/en/rst/maintaining/merging-accounts.rst index e69de29bb2..07309576ad 100644 --- a/docs/en/rst/maintaining/merging-accounts.rst +++ b/docs/en/rst/maintaining/merging-accounts.rst @@ -0,0 +1,9 @@ +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? diff --git a/docs/en/rst/maintaining/sanity-check.rst b/docs/en/rst/maintaining/sanity-check.rst index e69de29bb2..3138b822fa 100644 --- a/docs/en/rst/maintaining/sanity-check.rst +++ b/docs/en/rst/maintaining/sanity-check.rst @@ -0,0 +1,8 @@ +.. _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. diff --git a/docs/en/rst/maintaining/upgrades.rst b/docs/en/rst/maintaining/upgrades.rst new file mode 100644 index 0000000000..e02a536f31 --- /dev/null +++ b/docs/en/rst/maintaining/upgrades.rst @@ -0,0 +1,13 @@ +.. _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. diff --git a/docs/en/rst/security.rst b/docs/en/rst/security.rst index 17dfc73a22..bda308cacb 100644 --- a/docs/en/rst/security.rst +++ b/docs/en/rst/security.rst @@ -1,5 +1,3 @@ - - .. _security: ================= diff --git a/docs/en/rst/style.rst b/docs/en/rst/style.rst index 8fd9dc0373..966f91be76 100644 --- a/docs/en/rst/style.rst +++ b/docs/en/rst/style.rst @@ -87,15 +87,10 @@ Inline Directives 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` diff --git a/docs/en/rst/upgrading.rst b/docs/en/rst/upgrading.rst index e69de29bb2..1eb7505bbb 100644 --- a/docs/en/rst/upgrading.rst +++ b/docs/en/rst/upgrading.rst @@ -0,0 +1,14 @@ +.. _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 diff --git a/docs/en/rst/upgrading/overview.rst b/docs/en/rst/upgrading/overview.rst index 297d63c16a..42f5931428 100644 --- a/docs/en/rst/upgrading/overview.rst +++ b/docs/en/rst/upgrading/overview.rst @@ -1,3 +1,5 @@ +.. _upgrading-overview: + Overview ######## diff --git a/docs/en/rst/upgrading/upgrading-from-a-tarball.rst b/docs/en/rst/upgrading/upgrading-from-a-tarball.rst index e69de29bb2..9a41ba76c1 100644 --- a/docs/en/rst/upgrading/upgrading-from-a-tarball.rst +++ b/docs/en/rst/upgrading/upgrading-from-a-tarball.rst @@ -0,0 +1,45 @@ +.. _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 `_ 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. diff --git a/docs/en/rst/upgrading/upgrading-from-bazaar.rst b/docs/en/rst/upgrading/upgrading-from-bazaar.rst index e69de29bb2..2fb1acfebe 100644 --- a/docs/en/rst/upgrading/upgrading-from-bazaar.rst +++ b/docs/en/rst/upgrading/upgrading-from-bazaar.rst @@ -0,0 +1,195 @@ +.. _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 `_ +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 `_. 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 `_. 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. diff --git a/docs/en/rst/upgrading/upgrading-from-cvs.rst b/docs/en/rst/upgrading/upgrading-from-cvs.rst index e69de29bb2..f642fe4529 100644 --- a/docs/en/rst/upgrading/upgrading-from-cvs.rst +++ b/docs/en/rst/upgrading/upgrading-from-cvs.rst @@ -0,0 +1,12 @@ +.. _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. diff --git a/docs/en/rst/upgrading/upgrading-with-a-tarball.rst b/docs/en/rst/upgrading/upgrading-with-a-tarball.rst index 9a41ba76c1..e9ca577aaf 100644 --- a/docs/en/rst/upgrading/upgrading-with-a-tarball.rst +++ b/docs/en/rst/upgrading/upgrading-with-a-tarball.rst @@ -3,43 +3,13 @@ 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 `_ 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. diff --git a/docs/en/rst/upgrading/upgrading-with-git.rst b/docs/en/rst/upgrading/upgrading-with-git.rst index e69de29bb2..fb7cc7c9b8 100644 --- a/docs/en/rst/upgrading/upgrading-with-git.rst +++ b/docs/en/rst/upgrading/upgrading-with-git.rst @@ -0,0 +1,111 @@ +.. _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 `_ 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. diff --git a/docs/en/rst/using.rst b/docs/en/rst/using.rst index 5be1a2582e..3f74d3936f 100644 --- a/docs/en/rst/using.rst +++ b/docs/en/rst/using.rst @@ -1,11 +1,21 @@ - - .. _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