From 78e29c8900fa96d67163a34a0c02c7cecb31b55f Mon Sep 17 00:00:00 2001
From: "jake%bugzilla.org" <>
Date: Wed, 23 Apr 2003 09:04:01 +0000
Subject: The source files for the Bugzilla Guide have long been using the XML
version of DocBook but still residing in the sgml/ directory with an
extension of .sgml.
In an effort to maintain CVS history, the raw files were copied on the CVS server to the xml/ directory and renamed to have .xml for the extension; any checkins before this one did have the .sgml extension.
---
docs/sgml/Bugzilla-Guide.sgml | 205 -----
docs/sgml/about.sgml | 227 ------
docs/sgml/administration.sgml | 1640 ---------------------------------------
docs/sgml/conventions.sgml | 179 -----
docs/sgml/database.sgml | 394 ----------
docs/sgml/dbschema.mysql | 1 -
docs/sgml/faq.sgml | 1321 -------------------------------
docs/sgml/filetemp.patch | 18 -
docs/sgml/gd-makefile.patch | 22 -
docs/sgml/gfdl.sgml | 448 -----------
docs/sgml/glossary.sgml | 482 ------------
docs/sgml/index.sgml | 21 -
docs/sgml/installation.sgml | 1615 --------------------------------------
docs/sgml/integration.sgml | 101 ---
docs/sgml/introduction.sgml | 149 ----
docs/sgml/patches.sgml | 113 ---
docs/sgml/requiredsoftware.sgml | 88 ---
docs/sgml/using.sgml | 580 --------------
docs/sgml/variants.sgml | 123 ---
19 files changed, 7727 deletions(-)
delete mode 100644 docs/sgml/Bugzilla-Guide.sgml
delete mode 100644 docs/sgml/about.sgml
delete mode 100644 docs/sgml/administration.sgml
delete mode 100644 docs/sgml/conventions.sgml
delete mode 100644 docs/sgml/database.sgml
delete mode 100644 docs/sgml/dbschema.mysql
delete mode 100644 docs/sgml/faq.sgml
delete mode 100644 docs/sgml/filetemp.patch
delete mode 100644 docs/sgml/gd-makefile.patch
delete mode 100644 docs/sgml/gfdl.sgml
delete mode 100644 docs/sgml/glossary.sgml
delete mode 100644 docs/sgml/index.sgml
delete mode 100644 docs/sgml/installation.sgml
delete mode 100644 docs/sgml/integration.sgml
delete mode 100644 docs/sgml/introduction.sgml
delete mode 100644 docs/sgml/patches.sgml
delete mode 100644 docs/sgml/requiredsoftware.sgml
delete mode 100644 docs/sgml/using.sgml
delete mode 100644 docs/sgml/variants.sgml
(limited to 'docs/sgml')
diff --git a/docs/sgml/Bugzilla-Guide.sgml b/docs/sgml/Bugzilla-Guide.sgml
deleted file mode 100644
index a9fcf097a..000000000
--- a/docs/sgml/Bugzilla-Guide.sgml
+++ /dev/null
@@ -1,205 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Bugzilla Documentation">
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-]>
-
-
-
-
-
-
-
-
-
- The Bugzilla Guide - &bz-ver; <![%bz-devel;[Development ]]>Release
-
-
-
- Matthew
- P.
- Barnson
-
-
- Jacob
- Steenhagen
-
- The Bugzilla Team
-
-
- &bz-date;
-
-
-
- This is the documentation for Bugzilla, the mozilla.org
- bug-tracking system.
- Bugzilla is an enterprise-class piece of software
- that powers issue-tracking for hundreds of
- organizations around the world, tracking millions of bugs.
-
-
-
- This documentation is maintained in DocBook 4.1.2 XML format.
- Changes are best submitted as plain text or SGML diffs, attached
- to a bug filed in the &bzg-bugs; compontent.
-
- This is a development version of this guide. Information in it
- is subject to change before the &bz-nextver; release of this guide
- (which will correspond with the &bz-nextver; release of Bugzilla).
-
- ]]>
-
-
-
- Bugzilla
- Guide
- installation
- FAQ
- administration
- integration
- MySQL
- Mozilla
- webtools
-
-
-
-
-&about;
-
-
-&introduction;
-
-
-&using;
-
-
-&installation;
-
-
-&administration;
-
-
-&faq;
-
-
-&database;
-
-
-&patches;
-
-
-&variants;
-
-
-&gfdl;
-
-
-&glossary;
-
-
-&index;
-
-
-
-
-
diff --git a/docs/sgml/about.sgml b/docs/sgml/about.sgml
deleted file mode 100644
index ccfcdd23e..000000000
--- a/docs/sgml/about.sgml
+++ /dev/null
@@ -1,227 +0,0 @@
-
-
-
-About This Guide
-
-
- Copyright Information
-
- Copyright (c) 2000-2003 Matthew P. Barnson and &bzg-auth;
-
- 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 .
-
-
-
- If you have any questions regarding this document, its
- copyright, or publishing this document in non-electronic form,
- please contact &bzg-auth;.
-
-
-
-
- Disclaimer
-
- No liability for the contents of this document can be accepted.
- Use the concepts, examples, and other content 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.
-
-
- All copyrights are held by their respective owners, unless
- specifically noted otherwise. Use of a term in this document
- should not be regarded as affecting the validity of any
- trademark or service mark.
-
-
- 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 in every situation
- where it is appropriate. It is an extremely versatile, stable,
- and robust operating system that offers an ideal operating
- environment for Bugzilla.
-
-
- You are strongly recommended to make a backup of your system
- before installing Bugzilla and at regular intervals thereafter.
- If you implement any suggestion in this Guide, implement this one!
-
-
- Although the Bugzilla development team has taken great care to
- ensure that all easily-exploitable bugs or options are
- documented or fixed in the code, security holes surely exist.
- Great care should be taken both in the installation and usage of
- this software. Carefully consider the implications of installing
- other network services with Bugzilla. The Bugzilla development
- team members, Netscape Communications, America Online Inc., and
- any affiliated developers or sponsors assume no liability for
- your use of this product. You have the source code to this
- product, and are responsible for auditing it yourself to ensure
- your security needs are met.
-
-
-
-
-
-
- New Versions
-
- This is the &bz-ver; version of The Bugzilla Guide. It is so named
- to match the current version of Bugzilla.
-
- If you are
- reading this from any source other than those below, please
- check one of these mirrors to make sure you are reading an
- up-to-date version of the Guide.
-
-
- The newest version of this guide can always be found at bugzilla.org; including
- documentation for past releases and the current development version.
-
-
- The documentation for the most recent stable release of Bugzilla can also
- be found at
- The Linux Documentation Project.
-
-
- The latest version of this document can always be checked out via CVS.
- Please follow the instructions available at
- the Mozilla CVS page,
- and check out the mozilla/webtools/bugzilla/docs/
- subtree.
-
-
- The Bugzilla Guide is currently only available in English.
- If you would like to volunteer to translate it, please contact
- Dave Miller.
-
-
-
-
- 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:
-
-
-
-
-
- Matthew P. Barnson mbarnson@sisna.com
-
- for the Herculaean 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, and being largely responsible for
- .
-
-
-
-
-
- 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.
-
-
-
-
-
-
-
- Last but not least, all the members of the
-
- newsgroup. Without your discussions, insight, suggestions, and patches,
- this could never have happened.
-
-
- Thanks also go to the following people for significant contributions
- to this documentation (in alphabetical order):
-
- Andrew Pearson
- Ben FrantzDale
- Eric Hanson
- Gervase Markham
- Joe Robins
- Kevin Brannen
- Ron Teitelbaum
- Spencer Smith
- Zach Liption
-
- .
-
-
-
-
-&conventions;
-
-
-
diff --git a/docs/sgml/administration.sgml b/docs/sgml/administration.sgml
deleted file mode 100644
index f04e2b5ce..000000000
--- a/docs/sgml/administration.sgml
+++ /dev/null
@@ -1,1640 +0,0 @@
-
-
- Administering Bugzilla
-
-
- Bugzilla Configuration
-
- Bugzilla is configured by changing various parameters, accessed
- from the "Edit parameters" link in the page footer. Here are
- some of the key parameters on that page. You should run down this
- list and set them appropriately after installing Bugzilla.
-
-
- checklist
-
-
-
-
-
- maintainer:
- The maintainer parameter is the email address of the person
- responsible for maintaining this
- Bugzilla installation. The address need not be that of a valid Bugzilla
- account.
-
-
-
-
- urlbase:
- This parameter defines the fully qualified domain name and web
- server path to your Bugzilla installation.
-
- For example, if your Bugzilla query page is
- http://www.foo.com/bugzilla/query.cgi,
- set your urlbase
- to http://www.foo.com/bugzilla/.
-
-
-
-
- makeproductgroups:
- This dictates whether or not to automatically create groups
- when new products are created.
-
-
-
-
-
- useentrygroupdefault:
- Bugzilla products can have a group associated with them, so that
- certain users can only see bugs in certain products. When this
- parameter is set to on, this
- causes the initial group controls on newly created products
- to place all newly-created bugs in the group
- having the same name as the product immediately.
- After a product is initially created, the group controls
- can be further adjusted without interference by
- this mechanism.
-
-
-
-
- shadowdb:
- You run into an interesting problem when Bugzilla reaches a
- high level of continuous activity. MySQL supports only table-level
- write locking. What this means is that if someone needs to make a
- change to a bug, they will lock the entire table until the operation
- is complete. Locking for write also blocks reads until the write is
- complete. Note that more recent versions of mysql support row level
- locking using different table types. These types are slower than the
- standard type, and Bugzilla does not yet take advantage of features
- such as transactions which would justify this speed decrease. The
- Bugzilla team are, however, happy to hear about any experiences with
- row level locking and Bugzilla
-
- The shadowdb
- parameter was designed to get around this limitation. While only a
- single user is allowed to write to a table at a time, reads can
- continue unimpeded on a read-only shadow copy of the database.
- Although your database size will double, a shadow database can cause
- an enormous performance improvement when implemented on extremely
- high-traffic Bugzilla databases.
-
-
- As a guide, mozilla.org began needing
- shadowdb
- when they reached around 40,000 Bugzilla users with several hundred
- Bugzilla bug changes and comments per day.
-
- The value of the parameter defines the name of the
- shadow bug database. You will need to set the host and port settings
- from the params page, and set up replication in your database server
- so that updates reach this readonly mirror. Consult your database
- documentation for more detail.
-
-
-
-
- shutdownhtml:
-
- If you need to shut down Bugzilla to perform administration, enter
- some descriptive HTML here and anyone who tries to use Bugzilla will
- receive a page to that effect. Obviously, editparams.cgi will
- still be accessible so you can remove the HTML and re-enable Bugzilla.
- :-)
-
-
-
-
-
- passwordmail:
-
- Every time a user creates an account, the text of
- this parameter (with substitutions) is sent to the new user along with
- their password message.
-
- Add any text you wish to the "passwordmail" parameter box. For
- instance, many people choose to use this box to give a quick training
- blurb about how to use Bugzilla at your site.
-
-
-
-
-
- movebugs:
-
- This option is an undocumented feature to allow moving bugs
- between separate Bugzilla installations. You will need to understand
- the source code in order to use this feature. Please consult
- movebugs.pl in your Bugzilla source tree for
- further documentation, such as it is.
-
-
-
-
-
- useqacontact:
-
- This allows you to define an email address for each component, in
- addition
- to that of the default owner, who will be sent carbon copies of
- incoming bugs.
-
-
-
- usestatuswhiteboard:
- This defines whether you wish to have a free-form, overwritable field
- associated with each bug. The advantage of the Status Whiteboard is
- that it can be deleted or modified with ease, and provides an
- easily-searchable field for indexing some bugs that have some trait
- in common.
-
-
-
-
-
- whinedays:
- Set this to the number of days you want to let bugs go
- in the NEW or REOPENED state before notifying people they have
- untouched new bugs. If you do not plan to use this feature, simply do
- not set up the whining cron job described in the installation
- instructions, or set this value to "0" (never whine).
-
-
-
-
- commenton*:
- All these
- fields allow you to dictate what changes can pass without comment,
- and which must have a comment from the person who changed them.
- Often, administrators will allow users to add themselves to the CC
- list, accept bugs, or change the Status Whiteboard without adding a
- comment as to their reasons for the change, yet require that most
- other changes come with an explanation.
-
- Set the "commenton" options according to your site policy. It
- is a wise idea to require comments when users resolve, reassign, or
- reopen bugs at the very least.
-
- It is generally far better to require a developer comment
- when resolving bugs than not. Few things are more annoying to bug
- database users than having a developer mark a bug "fixed" without
- any comment as to what the fix was (or even that it was truly
- fixed!)
-
-
-
-
-
-
- supportwatchers:
-
- Turning on this option allows users to ask to receive copies of
- all a particular other user's bug email. This is, of
- course, subject to the groupset restrictions on the bug; if the
- watcher
- would not normally be allowed to view a bug, the watcher cannot get
- around the system by setting herself up to watch the bugs of someone
- with bugs outside her privileges. They would still only receive email
- updates for those bugs she could normally view.
-
-
-
-
-
- User Administration
-
-
- Creating the Default User
-
- When you first run checksetup.pl after installing Bugzilla, it
- will prompt you for the administrative username (email address) and
- password for this "super user". If for some reason you delete
- the "super user" account, re-running checksetup.pl will again prompt
- you for this username and password.
-
-
- If you wish to add more administrative users, add them to
- the "admin" group and, optionally, add edit the tweakparams, editusers,
- creategroups, editcomponents, and editkeywords groups to add the
- entire admin group to those groups.
-
-
-
-
-
- Managing Other Users
-
-
- Creating new users
-
- Your users can create their own user accounts by clicking the
- "New Account" link at the bottom of each page (assuming they
- aren't logged in as someone else already.) However, should you
- desire to create user accounts ahead of time, here is how you do
- it.
-
-
-
- After logging in, click the "Users" link at the footer of
- the query page, and then click "Add a new user".
-
-
-
- Fill out the form presented. This page is self-explanatory.
- When done, click "Submit".
-
-
- Adding a user this way will
- not
-
- send an email informing them of their username and password.
- While useful for creating dummy accounts (watchers which
- shuttle mail to another system, for instance, or email
- addresses which are a mailing list), in general it is
- preferable to log out and use the
- New Account
-
- button to create users, as it will pre-populate all the
- required fields and also notify the user of her account name
- and password.
-
-
-
-
-
-
- Modifying Users
-
- To see a specific user, search for their login name
- in the box provided on the "Edit Users" page. To see all users,
- leave the box blank.
-
- You can search in different ways the listbox to the right
- of the text entry box. You can match by
- case-insensitive substring (the default),
- regular expression, or a
- reverse
- regular expression match, which finds every user name which does NOT
- match the regular expression. (Please see
- the man regexp
- manual page for details on regular expression syntax.)
-
-
- Once you have found your user, you can change the following
- fields:
-
-
-
-
- Login Name:
- This is generally the user's full email address. However, if you
- have are using the emailsuffix Param, this may just be the user's
- login name. Note that users can now change their login names
- themselves (to any valid email address.)
-
-
-
-
-
- Real Name: The user's real name. Note that
- Bugzilla does not require this to create an account.
-
-
-
-
- Password:
- You can change the user's password here. Users can automatically
- request a new password, so you shouldn't need to do this often.
- If you want to disable an account, see Disable Text below.
-
-
-
-
-
- Disable Text:
- If you type anything in this box, including just a space, the
- user is prevented from logging in, or making any changes to
- bugs via the web interface.
- The HTML you type in this box is presented to the user when
- they attempt to perform these actions, and should explain
- why the account was disabled.
-
- Don't disable the administrator account!
-
-
-
- The user can still submit bugs via
- the e-mail gateway, if you set it up, even if the disabled text
- field is filled in. The e-mail gateway should
- not
- be enabled for secure installations of Bugzilla.
-
-
-
-
-
-
- <groupname>:
- If you have created some groups, e.g. "securitysensitive", then
- checkboxes will appear here to allow you to add users to, or
- remove them from, these groups.
-
-
-
-
-
- canconfirm:
- This field is only used if you have enabled the "unconfirmed"
- status. If you enable this for a user,
- that user can then move bugs from "Unconfirmed" to a "Confirmed"
- status (e.g.: "New" status).
-
-
-
-
- creategroups:
- This option will allow a user to create and destroy groups in
- Bugzilla.
-
-
-
-
- editbugs:
- Unless a user has this bit set, they can only edit those bugs
- for which they are the assignee or the reporter. Even if this
- option is unchecked, users can still add comments to bugs.
-
-
-
-
-
- editcomponents:
- This flag allows a user to create new products and components,
- as well as modify and destroy those that have no bugs associated
- with them. If a product or component has bugs associated with it,
- those bugs must be moved to a different product or component
- before Bugzilla will allow them to be destroyed.
-
-
-
-
-
- editkeywords:
- If you use Bugzilla's keyword functionality, enabling this
- feature allows a user to create and destroy keywords. As always,
- the keywords for existing bugs containing the keyword the user
- wishes to destroy must be changed before Bugzilla will allow it
- to die.
-
-
-
-
- editusers:
- This flag allows a user to do what you're doing right now: edit
- other users. This will allow those with the right to do so to
- remove administrator privileges from other users or grant them to
- themselves. Enable with care.
-
-
-
-
-
- tweakparams:
- This flag allows a user to change Bugzilla's Params
- (using editparams.cgi.)
-
-
-
-
- <productname>:
- This allows an administrator to specify the products in which
- a user can see bugs. The user must still have the
- "editbugs" privilege to edit bugs in these products.
-
-
-
-
-
-
-
- Product, Component, Milestone, and Version Administration
-
-
- Products
-
-
-
- Products
-
- are the broadest category in Bugzilla, and tend to represent real-world
- shipping products. E.g. if your company makes computer games,
- you should have one product per game, perhaps a "Common" product for
- units of technology used in multiple games, and maybe a few special
- products (Website, Administration...)
-
- Many of Bugzilla's settings are configurable on a per-product
- basis. The number of "votes" available to users is set per-product,
- as is the number of votes
- required to move a bug automatically from the UNCONFIRMED status to the
- NEW status.
-
- To create a new product:
-
-
-
- Select "products" from the footer
-
-
-
-
- Select the "Add" link in the bottom right
-
-
-
- Enter the name of the product and a description. The
- Description field may contain HTML.
-
-
-
- Don't worry about the "Closed for bug entry", "Maximum Votes
- per person", "Maximum votes a person can put on a single bug",
- "Number of votes a bug in this Product needs to automatically get out
- of the UNCOMFIRMED state", and "Version" options yet. We'll cover
- those in a few moments.
-
-
-
-
- Components
-
- Components are subsections of a Product. E.g. the computer game
- you are designing may have a "UI"
- component, an "API" component, a "Sound System" component, and a
- "Plugins" component, each overseen by a different programmer. It
- often makes sense to divide Components in Bugzilla according to the
- natural divisions of responsibility within your Product or
- company.
-
-
- Each component has a owner and (if you turned it on in the parameters),
- a QA Contact. The owner should be the primary person who fixes bugs in
- that component. The QA Contact should be the person who will ensure
- these bugs are completely fixed. The Owner, QA Contact, and Reporter
- will get email when new bugs are created in this Component and when
- these bugs change. Default Owner and Default QA Contact fields only
- dictate the
- default assignments;
- these can be changed on bug submission, or at any later point in
- a bug's life.
-
- To create a new Component:
-
-
-
- Select the "Edit components" link from the "Edit product"
- page
-
-
-
- Select the "Add" link in the bottom right.
-
-
-
- Fill out the "Component" field, a short "Description",
- the "Initial Owner" and "Initial QA Contact" (if enabled.)
- The Component and Description fields may contain HTML;
- the "Initial Owner" field must be a login name
- already existing in the database.
-
-
-
-
-
-
- Versions
-
- Versions are the revisions of the product, such as "Flinders
- 3.1", "Flinders 95", and "Flinders 2000". Version is not a multi-select
- field; the usual practice is to select the most recent version with
- the bug.
-
-
- To create and edit Versions:
-
-
-
- From the "Edit product" screen, select "Edit Versions"
-
-
-
- You will notice that the product already has the default
- version "undefined". Click the "Add" link in the bottom right.
-
-
-
- Enter the name of the Version. This field takes text only.
- Then click the "Add" button.
-
-
-
-
-
-
- Milestones
-
- Milestones are "targets" that you plan to get a bug fixed by. For
- example, you have a bug that you plan to fix for your 3.0 release, it
- would be assigned the milestone of 3.0.
-
-
- Milestone options will only appear for a Product if you turned
- on the "usetargetmilestone" Param in the "Edit Parameters" screen.
-
-
-
- To create new Milestones, set Default Milestones, and set
- Milestone URL:
-
-
-
- Select "Edit milestones" from the "Edit product" page.
-
-
-
- Select "Add" in the bottom right corner.
- text
-
-
-
- Enter the name of the Milestone in the "Milestone" field. You
- can optionally set the "sortkey", which is a positive or negative
- number (-255 to 255) that defines where in the list this particular
- milestone appears. This is because milestones often do not
- occur in alphanumeric order For example, "Future" might be
- after "Release 1.2". Select "Add".
-
-
-
- From the Edit product screen, you can enter the URL of a
- page which gives information about your milestones and what
- they mean.
-
-
- If you want your milestone document to be restricted so
- that it can only be viewed by people in a particular Bugzilla
- group, the best way is to attach the document to a bug in that
- group, and make the URL the URL of that attachment.
-
-
-
-
-
-
-
- Voting
-
- Voting allows users to be given a pot of votes which they can allocate
- to bugs, to indicate that they'd like them fixed.
- This allows developers to gauge
- user need for a particular enhancement or bugfix. By allowing bugs with
- a certain number of votes to automatically move from "UNCONFIRMED" to
- "NEW", users of the bug system can help high-priority bugs garner
- attention so they don't sit for a long time awaiting triage.
-
- To modify Voting settings:
-
-
-
- Navigate to the "Edit product" screen for the Product you
- wish to modify
-
-
-
- Maximum Votes per person:
- Setting this field to "0" disables voting.
-
-
-
- Maximum Votes a person can put on a single
- bug":
- It should probably be some number lower than the
- "Maximum votes per person". Don't set this field to "0" if
- "Maximum votes per person" is non-zero; that doesn't make
- any sense.
-
-
-
- Number of votes a bug in this product needs to
- automatically get out of the UNCONFIRMED state:
- Setting this field to "0" disables the automatic move of
- bugs from UNCONFIRMED to NEW.
-
-
-
-
- Once you have adjusted the values to your preference, click
- "Update".
-
-
-
-
-
- Groups and Group Security
-
- Groups allow the administrator
- to isolate bugs or products that should only be seen by certain people.
- The association between products and groups is controlled from
- the product edit page under Edit Group Controls.
-
-
-
- If the makeproductgroups param is on, a new group will be automatically
- created for every new product.
-
-
-
- On the product edit page, there is a page to edit the
- Group Controls
- for a product and determine which groups are applicable, default,
- and mandatory for each product as well as controlling entry
- for each product and being able to set bugs in a product to be
- totally read-only unless some group restrictions are met.
-
-
-
- For each group, it is possible to specify if membership in that
- group is...
-
-
-
-
- required for bug entry,
-
-
-
-
- Not applicable to this product(NA),
- a possible restriction for a member of the
- group to place on a bug in this product(Shown),
- a default restriction for a member of the
- group to place on a bug in this product(Default),
- or a mandatory restriction to be placed on bugs
- in this product(Mandatory).
-
-
-
-
- Not applicable by non-members to this product(NA),
- a possible restriction for a non-member of the
- group to place on a bug in this product(Shown),
- a default restriction for a non-member of the
- group to place on a bug in this product(Default),
- or a mandatory restriction to be placed on bugs
- in this product when entered by a non-member(Mandatory).
-
-
-
-
- required in order to make any change
- to bugs in this product including comments.
-
-
-
-
- To create Groups:
-
-
-
- Select the groups
- link in the footer.
-
-
-
- Take a moment to understand the instructions on the Edit
- Groups screen, then select the Add Group link.
-
-
-
- Fill out the Group, Description,
- and User RegExp fields.
- User RegExp allows you to automatically
- place all users who fulfill the Regular Expression into the new group.
- When you have finished, click Add.
-
- The User Regexp is a perl regexp and, if not anchored, will match
- any part of an address. So, if you do not want to grant access
- into 'mycompany.com' to 'badperson@mycompany.com.hacker.net', use
- '@mycompany\.com$' as the regexp.
-
-
-
- After you add your new group, edit the new group. On the
- edit page, you can specify other groups that should be included
- in this group and which groups should be permitted to add and delete
- users from this group.
-
-
-
-
- Note that group permissions are such that you need to be a member
- of all the groups a bug is in, for whatever
- reason, to see that bug. Similarly, you must be a member
- of all of the entry groups for a product
- to add bugs to a product and you must be a member
- of all of the canedit groups for a product
- in order to make any change to bugs in that
- product.
-
-
-
-
-
- Bugzilla Security
-
-
- Poorly-configured MySQL and Bugzilla installations have
- given attackers full access to systems in the past. Please take these
- guidelines seriously, even for Bugzilla machines hidden away behind
- your firewall. 80% of all computer trespassers are insiders, not
- anonymous crackers.
-
-
-
- These instructions must, of necessity, be somewhat vague since
- Bugzilla runs on so many different platforms. If you have refinements
- of these directions, please submit a bug to &bzg-bugs;.
-
-
-
-
- This is not meant to be a comprehensive list of every possible
- security issue regarding the tools mentioned in this section. There is
- no subsitute for reading the information written by the authors of any
- software running on your system.
-
-
-
-
- TCP/IP Ports
-
-
- TCP/IP defines 65,000 some ports for trafic. Of those, Bugzilla
- only needs 1... 2 if you need to use features that require e-mail such
- as bug moving or the e-mail interface from contrib. You should audit
- your server and make sure that you aren't listening on any ports you
- don't need to be. You may also wish to use some kind of firewall
- software to be sure that trafic can only be recieved on ports you
- specify.
-
-
-
-
- MySQL
-
- MySQL ships by default with many settings that should be changed.
- By defaults it allows anybody to connect from localhost without a
- password and have full administrative capabilities. It also defaults to
- not have a root password (this is not the same as
- the system root). Also, many installations default to running
- mysqld as the system root.
-
-
-
-
- Consult the documentation that came with your system for
- information on making mysqld run as an
- unprivleged user.
-
-
-
-
- You should also be sure to disable the anonymous user account
- and set a password for the root user. This is accomplished using the
- following commands:
-
-
-bash$ mysql mysql
-mysql> DELETE FROM user WHERE user = '';
-mysql> UPDATE user SET password = password('new_password') WHERE user = 'root';
-mysql> FLUSH PRIVILEGES;
-
- From this point forward you will need to use
- mysql -u root -p and enter
- new_password when prompted when using the
- mysql client.
-
-
-
-
- If you run MySQL on the same machine as your httpd server, you
- should consider disabling networking from within MySQL by adding
- the following to your /etc/my.conf:
-
-
-[myslqd]
-# Prevent network access to MySQL.
-skip-networking
-
-
-
-
- You may also consider running MySQL, or even all of Bugzilla
- in a chroot jail; however, instructions for doing that are beyond
- the scope of this document.
-
-
-
-
-
-
-
-
- Daemon Accounts
-
- Many daemons, such as Apache's httpd and MySQL's mysqld default to
- running as either root or nobody. Running
- as root introduces obvious security problems, but the
- problems introduced by running everything as nobody may
- not be so obvious. Basically, if you're running every daemon as
- nobody and one of them gets comprimised, they all get
- comprimised. For this reason it is recommended that you create a user
- account for each daemon.
-
-
-
- You will need to set the webservergroup to
- the group you created for your webserver to run as in
- localconfig. This will allow
- ./checksetup.pl to better adjust the file
- permissions on your Bugzilla install so as to not require making
- anything world-writable.
-
-
-
-
-
-
- Web Server Access Controls
-
- There are many files that are placed in the Bugzilla directory
- area that should not be accessable from the web. Because of the way
- Bugzilla is currently layed out, the list of what should and should
- not be accessible is rather complicated. A new installation method
- is currently in the works which should solve this by allowing files
- that shouldn't be accessible from the web to be placed in directory
- outside the webroot. See
- bug
- 44659 for more information.
-
-
-
-
- In the main Bugzilla directory, you should:
-
-
- Block:
-
- *.pl
- *localconfig*
- runtests.sh
-
-
-
-
- But allow:
-
- localconfig.js
- localconfig.rdf
-
-
-
-
-
-
-
- In data:
-
-
- Block everything
-
-
- But allow:
-
- duplicates.rdf
-
-
-
-
-
-
-
- In data/webdot:
-
-
- If you use a remote webdot server:
-
-
- Block everything
-
-
- But allow
-
- *.dot
-
- only for the remote webdot server
-
-
-
-
- Otherwise, if you use a local GraphViz:
-
-
- Block everything
-
-
- But allow:
-
- *.png
- *.gif
- *.jpg
- *.map
-
-
-
-
-
-
- And if you don't use any dot:
-
-
- Block everything
-
-
-
-
-
-
-
- In Bugzilla:
-
-
- Block everything
-
-
-
-
-
- In template:
-
-
- Block everything
-
-
-
-
-
-
- Bugzilla ships with the ability to generate
- .htaccess files instructing
- Apache which files
- should and should not be accessible. For more information, see
- .
-
-
-
- You should test to make sure that the files mentioned above are
- not accessible from the Internet, especially your
- localconfig file which contains your database
- password. To test, simply point your web browser at the file; for
- example, to test mozilla.org's installation, we'd try to access
- . You should
- get a 403Forbidden
- error.
-
-
-
- Not following the instructions in this section, including
- testing, may result in sensitive information being globally
- accessible.
-
-
-
-
- You should check to see if instructions
- have been included for your web server. You should also compare those
- instructions with this list to make sure everything is properly
- accounted for.
-
-
-
-
-
-
-
-
- Template Customization
-
-
- One of the large changes for 2.16 was the templatization of the
- entire user-facing UI, using the
- Template Toolkit.
- Administrators can now 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. In the future, a Bugzilla installation may
- have templates installed for multiple localizations, and select
- which ones to use based on the user's browser language setting.
-
-
-
- What to Edit
-
- There are two different ways of editing of Bugzilla's templates,
- and which you use depends mainly on how you upgrade Bugzilla. The
- template directory structure is that there's a top level directory,
- template, which contains a directory for
- each installed localization. The default English templates are
- therefore in en. Underneath that, there
- is the default directory and optionally the
- custom directory. The default
- directory contains all the templates shipped with Bugzilla, whereas
- the custom directory does not exist at first and
- must be created if you want to use it.
-
-
-
- The first method of making customizations is to directly edit the
- templates in template/en/default. This is
- probably the best method for small changes if you are going to use
- the CVS method of upgrading, because if you then execute a
- cvs update, any template fixes will get
- automagically merged into your modified versions.
-
-
-
- If you use this method, your installation will break if CVS conflicts
- occur.
-
-
-
- The other method is to copy the templates into a mirrored directory
- structure under template/en/custom. The templates
- in this directory automatically override those in default.
- This is the technique you
- need to use if you use the overwriting method of upgrade, because
- otherwise your changes will be lost. This method is also better if
- you are using the CVS 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.
-
-
-
- If you use this method, your installation may break if incompatible
- changes are made to the template interface. If such changes are made
- they will 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.
-
-
-
-
- Don't directly edit the compiled templates in
- data/template/* - your
- changes will be lost when Template Toolkit recompiles them.
-
-
-
-
-
- How To Edit Templates
-
-
- 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. However, you should particularly remember (for security
- reasons) to always HTML filter things which come from the database or
- user input, to prevent cross-site scripting attacks.
-
-
-
- However, 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, ie <. You use the 'html' filter in the
- Template Toolkit to do this. If you fail to do this, you may open up
- your installation to cross-site scripting attacks.
-
-
-
- Also note that Bugzilla adds a few filters of its own, that are not
- in standard Template Toolkit. In particular, the 'url_quote' filter
- can convert characters that are illegal or have special meaning in URLs,
- such as &, to the encoded form, ie %26. This actually encodes most
- characters (but not the common ones such as letters and numbers and so
- on), including the HTML-special characters, so there's never a need to
- HTML filter afterwards.
-
-
-
- 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.
-
-
-
-
- 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.
-
-
-
-
-
-
- Template Formats
-
-
- Some CGIs have the ability to use more than one template. For
- example, buglist.cgi can output bug lists as RDF or two
- different forms of HTML (complex and simple). (Try this out
- by appending &format=simple to a buglist.cgi
- URL on your Bugzilla installation.) This
- mechanism, called template 'formats', is extensible.
-
-
-
- To see if a CGI supports multiple output formats, grep the
- CGI for "ValidateOutputFormat". If it's not present, adding
- multiple format support isn't too hard - see how it's done in
- other CGIs.
-
-
-
- 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. Open up the localconfig file and find the
- $contenttypes
- variable. If your content type is not there, add it. Remember
- the three- or four-letter tag assigned to you content type.
- This tag will be part of the template filename.
-
-
-
- Save the template as <stubname>-<formatname>.<contenttypetag>.tmpl.
- Try out the template by calling the CGI as
- <cginame>.cgi?format=<formatname> .
-
-
-
-
-
- Particular Templates
-
-
- There are a few templates you may be particularly interested in
- customizing for your installation.
-
-
-
- index.html.tmpl:
- This is the Bugzilla front page.
-
-
-
- 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.
-
-
-
- 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.
-
-
-
- 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.
-
-
-
- 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.
-
-
-
- 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.
-
-
-
- bug/create/create.html.tmpl and
- bug/create/comment.txt.tmpl:
- You may wish to get bug submitters to give certain bits of structured
- information, each in a separate input widget, for which there is not a
- field in the database. The bug entry system has been designed in an
- extensible fashion to enable you to define arbitrary fields and widgets,
- and have their values appear formatted in the initial
- Description, rather than in database fields. An example of this
- is the mozilla.org
- guided
- bug submission form.
-
-
-
- To make this work, create a custom template for
- enter_bug.cgi (the default template, on which you
- could base it, is create.html.tmpl),
- and either call it create.html.tmpl or use a format and
- call it create-<formatname>.html.tmpl.
- Put it in the custom/bug/create
- directory. 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
- custom/bug/create/comment.txt.tmpl, also named
- after your format if you are using one, which
- references the form fields you have created. 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 enter_bug template had a field
- <input type="text" name="buildid" size="30">
- and then your comment.txt.tmpl had
- BuildID: [% form.buildid %]
- then
- BuildID: 20020303
- would appear in the initial checkin comment.
-
-
-
-
-
-
- Change Permission Customization
-
-
-
- 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 to it, you may have
- to re-make them or port them if Bugzilla changes internally between
- versions.
-
-
-
-
- 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.
-
-
-
- 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 function is called
- CheckCanChangeField(),
- and is found in process_bug.cgi in your
- Bugzilla directory. If you open that file and grep for
- "sub CheckCanChangeField", 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 owner 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 be 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." And if you want the reporter to have
- no special rights on bugs they have filed, just remove the entire section
- which refers to him.
-
-
-
- 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 (UserInGroup("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") &&
- ($vars->{'user'}{'login'} =~ /.*\@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.
-
-
-
- For a list of possible field names, look in
- data/versioncache for the list called
- @::log_columns. If you need help writing custom
- rules for your organization, ask in the newsgroup.
-
-
-
-
- Upgrading to New Releases
-
- Upgrading Bugzilla is something we all want to do from time to time,
- be it to get new features or pick up the latest security fix. How easy
- it is to update depends on a few factors.
-
-
-
-
- If the new version is a revision or a new point release
-
-
- How many, if any, local changes have been made
-
-
-
- There are also three different methods to upgrade your installation.
-
-
-
-
- Using CVS ()
-
-
- Downloading a new tarball ()
-
-
- Applying the relevant patches ()
-
-
-
- Which options are available to you may depend on how large a jump
- you are making and/or your network configuration.
-
-
- Revisions are normally released to fix security vulnerabilities
- and are distinguished by an increase in the third number. For example,
- when 2.16.2 was released, it was a revision to 2.16.1.
-
-
- Point releases are normally released when the Bugzilla team feels
- that there has been a significant amount of progress made between the
- last point release and the current time. These are often proceeded by a
- stabilization period and release candidates, however the use of
- development versions or release candidates is beyond the scope of this
- document. Point releases can be distinguished by an increase in the
- second number, or minor version. For example, 2.16.2 is a newer point
- release than 2.14.5.
-
-
- The examples in this section are written as if you were updating
- to version 2.16.2. The procedures are the same regardless if you are
- updating to a new point release or a new revision. However, the chance
- of running into trouble increases when upgrading to a new point release,
- escpecially if you've made local changes.
-
-
- These examples also assume that your Bugzilla installation is at
- /var/www/html/bugzilla. If that is not the case,
- simply substitute the proper paths where appropriate.
-
-
-
- Upgrading using CVS
-
- Every release of Bugzilla, whether it is a revision or a point
- release, is tagged in CVS. Also, every tarball we have distributed
- since version 2.12 has been primed for using CVS. This does, however,
- require that you are able to access cvs-mirror.mozilla.org on port
- 2401.
-
-
- If you can do this, updating using CVS is probably the most
- painless method, especially if you have a lot of local changes.
-
-
-
-
-
-bash$ cd /var/www/html/bugzilla
-bash$ cvs login
-Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401/cvsroot
-CVS password: anonymous
-bash$ cvs -q update -r BUGZILLA-2_16_2 -dP
-P checksetup.pl
-P collectstats.pl
-P globals.pl
-P docs/rel_notes.txt
-P template/en/default/list/quips.html.tmpl
-
-
-
-
- If a line in the output from cvs update
- begins with a C that represents a
- file with local changes that CVS 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.
-
-
-
-
- You also need to run ./checksetup.pl
- before your Bugzilla upgrade will be complete.
-
-
-
-
-
-
- Upgrading using the tarball
-
- If you are unable or unwilling to use CVS, another option that's
- always available is to download the latest tarball. This is the most
- difficult option to use, especially if you have local changes.
-
-
-
-bash$ cd /var/www/html
-bash$ wget ftp://ftp.mozilla.org/pub/webtools/bugzilla-2.16.2.tar.gz
-Output omitted
-bash$ tar xzvf bugzilla-2.16.2.tar.gz
-bugzilla-2.16.2/
-bugzilla-2.16.2/.cvsignore
-bugzilla-2.16.2/1x1.gif
-Output truncated
-bash$ cd bugzilla-2.16.2
-bash$ cp ../bugzilla/localconfig* .
-bash$ cp -r ../bugzilla/data .
-bash$ cd ..
-bash$ mv bugzilla bugzilla.old
-bash$ mv bugzilla-2.16.2 bugzilla
-bash$ cd bugzilla
-bash$ ./checksetup.pl
-Output omitted
-
-
-
-
- The cp commands both end with periods which
- is a very important detail, it tells the shell that the destination
- directory is the current working directory. Also, the period at the
- beginning of the ./checksetup.pl is important and
- can not be omitted.
-
-
-
-
- You will now have to reapply any changes you have made to your
- local installation manually.
-
-
-
-
-
-
- Upgrading using patches
-
- The Bugzilla team will normally make a patch file available for
- revisions to go from the most recent revision to the new one. You could
- also read the release notes and grab the patches attached to the
- mentioned bug, but it is safer to use the released patch file as
- sometimes patches get changed before they get checked in (for minor
- spelling fixes and the like). It is also theorectically possible to
- scour the fixed bug list and pick and choose which patches to apply
- from a point release, but this is not recommended either as what you'll
- end up with is a hodge podge Bugzilla that isn't really any version.
- This would also make it more difficult to upgrade in the future.
-
-
-
-bash$ cd /var/www/html/bugzilla
-bash$ wget ftp://ftp.mozilla.org/pub/webtools/bugzilla-2.16.1-to-2.16.2.diff.gz
-Output omitted
-bash$ gunzip bugzilla-2.16.1-to-2.16.2.diff.gz
-bash$ patch -p1 < bugzilla-2.16.1-to-2.16.2.diff
-patching file checksetup.pl
-patching file collectstats.pl
-patching file globals.pl
-
-
-
-
- If you do this, beware that this doesn't change the entires in
- your CVS directory so it may make
- updates using CVS () more difficult in the
- future.
-
-
-
-
-
-
-
-
- &integration;
-
-
-
-
-
diff --git a/docs/sgml/conventions.sgml b/docs/sgml/conventions.sgml
deleted file mode 100644
index 5e761d9f4..000000000
--- a/docs/sgml/conventions.sgml
+++ /dev/null
@@ -1,179 +0,0 @@
-
-
- Document Conventions
-
-
- conventions
-
-
- This document uses the following conventions:
-
-
-
-
-
- Descriptions
-
- Appearance
-
-
-
-
-
- Warnings
-
-
-
- Don't run with scissors!
-
-
-
-
-
- Hint
-
-
-
- Would you like a breath mint?
-
-
-
-
-
- Notes
-
-
-
- Dear John...
-
-
-
-
-
- Information requiring special attention
-
-
-
- Read this or the cat gets it.
-
-
-
-
-
- File Names
-
-
- filename
-
-
-
-
- Directory Names
-
-
- directory
-
-
-
-
- Commands to be typed
-
-
- command
-
-
-
-
- Applications Names
-
-
- application
-
-
-
-
-
- Prompt
-
- of users command under bash shell
-
- bash$
-
-
-
-
- Prompt
-
- of root users command under bash shell
-
- bash#
-
-
-
-
- Prompt
-
- of user command under tcsh shell
-
- tcsh$
-
-
-
- Environment Variables
-
-
- VARIABLE
-
-
-
-
- Emphasized word
-
-
- word
-
-
-
-
- Term found in the glossary
-
-
- Bugzilla
-
-
-
-
- Code Example
-
-
- para
-Beginning and end of paragraph
-para
-
-
-
-
-
-
-
-
-
diff --git a/docs/sgml/database.sgml b/docs/sgml/database.sgml
deleted file mode 100644
index d32bb57cc..000000000
--- a/docs/sgml/database.sgml
+++ /dev/null
@@ -1,394 +0,0 @@
-
-
- The Bugzilla Database
-
-
- This document really needs to be updated with more fleshed out
- information about primary keys, interrelationships, and maybe some nifty
- tables to document dependencies. Any takers?
-
-
-
- Modifying Your Running System
-
- Bugzilla optimizes database lookups by storing all relatively
- static information in the
- versioncache file, located in the
- data/
- subdirectory under your installation directory.
-
- If you make a change to the structural data in your database (the
- versions table for example), or to the
- constants
-
- encoded in defparams.pl, you will need to remove
- the cached content from the data directory (by doing a
- rm data/versioncache
-
- ), or your changes won't show up.
-
- versioncache
- gets automatically regenerated whenever it's more than
- an hour old, so Bugzilla will eventually notice your changes by itself,
- but generally you want it to notice right away, so that you can test
- things.
-
-
-
- MySQL Bugzilla Database Introduction
-
- This information comes straight from my life. I was forced to learn
- how Bugzilla organizes database because of nitpicky requests from users
- for tiny changes in wording, rather than having people re-educate
- themselves or figure out how to work our procedures around the tool. It
- sucks, but it can and will happen to you, so learn how the schema works
- and deal with it when it comes.
-
- So, here you are with your brand-new installation of Bugzilla.
- You've got MySQL set up, Apache working right, Perl DBI and DBD talking
- to the database flawlessly. Maybe you've even entered a few test bugs to
- make sure email's working; people seem to be notified of new bugs and
- changes, and you can enter and edit bugs to your heart's content. Perhaps
- you've gone through the trouble of setting up a gateway for people to
- submit bugs to your database via email, have had a few people test it,
- and received rave reviews from your beta testers.
-
- What's the next thing you do? Outline a training strategy for your
- development team, of course, and bring them up to speed on the new tool
- you've labored over for hours.
-
- Your first training session starts off very well! You have a
- captive audience which seems enraptured by the efficiency embodied in
- this thing called "Bugzilla". You are caught up describing the nifty
- features, how people can save favorite queries in the database, set them
- up as headers and footers on their pages, customize their layouts,
- generate reports, track status with greater efficiency than ever before,
- leap tall buildings with a single bound and rescue Jane from the clutches
- of Certain Death!
-
- But Certain Death speaks up -- a tiny voice, from the dark corners
- of the conference room. "I have a concern," the voice hisses from the
- darkness, "about the use of the word 'verified'.
-
- The room, previously filled with happy chatter, lapses into
- reverential silence as Certain Death (better known as the Vice President
- of Software Engineering) continues. "You see, for two years we've used
- the word 'verified' to indicate that a developer or quality assurance
- engineer has confirmed that, in fact, a bug is valid. I don't want to
- lose two years of training to a new software product. You need to change
- the bug status of 'verified' to 'approved' as soon as possible. To avoid
- confusion, of course."
-
- Oh no! Terror strikes your heart, as you find yourself mumbling
- "yes, yes, I don't think that would be a problem," You review the changes
- with Certain Death, and continue to jabber on, "no, it's not too big a
- change. I mean, we have the source code, right? You know, 'Use the
- Source, Luke' and all that... no problem," All the while you quiver
- inside like a beached jellyfish bubbling, burbling, and boiling on a hot
- Jamaican sand dune...
-
- Thus begins your adventure into the heart of Bugzilla. You've been
- forced to learn about non-portable enum() fields, varchar columns, and
- tinyint definitions. The Adventure Awaits You!
-
-
- Bugzilla Database Basics
-
- If you were like me, at this point you're totally clueless about
- the internals of MySQL, and if it weren't for this executive order from
- the Vice President you couldn't care less about the difference between
- a
- bigint
-
- and a
- tinyint
-
- entry in MySQL. I recommend you refer to the MySQL documentation,
- available at
- MySQL.com
-
- . Below are the basics you need to know about the Bugzilla database.
- Check the chart above for more details.
-
-
-
-
- To connect to your database:
-
-
- bash#
-
- mysql
-
- -u root
-
-
- If this works without asking you for a password,
- shame on you
-
- ! You should have locked your security down like the installation
- instructions told you to. You can find details on locking down
- your database in the Bugzilla FAQ in this directory (under
- "Security"), or more robust security generalities in the
- MySQL
- searchable documentation.
-
-
-
-
- You should now be at a prompt that looks like this:
-
-
- mysql>
-
-
- At the prompt, if
- bugs
-
- is the name you chose in the
- localconfig
-
- file for your Bugzilla database, type:
-
-
- mysql
-
- use bugs;
-
-
-
-
-
-
-
- Bugzilla Database Tables
-
- Imagine your MySQL database as a series of spreadsheets, and
- you won't be too far off. If you use this command:
-
-
- mysql>
- show tables from bugs;
-
-
- you'll be able to see the names of all the
- spreadsheets
- (tables) in your database.
-
- From the command issued above, ou should have some
- output that looks like this:
-
-+-------------------+
-| Tables in bugs |
-+-------------------+
-| attachments |
-| bugs |
-| bugs_activity |
-| cc |
-| components |
-| dependencies |
-| fielddefs |
-| groups |
-| keyworddefs |
-| keywords |
-| logincookies |
-| longdescs |
-| milestones |
-| namedqueries |
-| products |
-| profiles |
-| profiles_activity |
-| tokens |
-| versions |
-| votes |
-| watch |
-+-------------------+
-
-
-
-
- Here's an overview of what each table does. Most columns in each table have
-descriptive names that make it fairly trivial to figure out their jobs.
-
-attachments: This table stores all attachments to bugs. It tends to be your
-largest table, yet also generally has the fewest entries because file
-attachments are so (relatively) large.
-
-bugs: This is the core of your system. The bugs table stores most of the
-current information about a bug, with the exception of the info stored in the
-other tables.
-
-bugs_activity: This stores information regarding what changes are made to bugs
-when -- a history file.
-
-cc: This tiny table simply stores all the CC information for any bug which has
-any entries in the CC field of the bug. Note that, like most other tables in
-Bugzilla, it does not refer to users by their user names, but by their unique
-userid, stored as a primary key in the profiles table.
-
-components: This stores the programs and components (or products and
-components, in newer Bugzilla parlance) for Bugzilla. Curiously, the "program"
-(product) field is the full name of the product, rather than some other unique
-identifier, like bug_id and user_id are elsewhere in the database.
-
-dependencies: Stores data about those cool dependency trees.
-
-fielddefs: A nifty table that defines other tables. For instance, when you
-submit a form that changes the value of "AssignedTo" this table allows
-translation to the actual field name "assigned_to" for entry into MySQL.
-
-groups: defines bitmasks for groups. A bitmask is a number that can uniquely
-identify group memberships. For instance, say the group that is allowed to
-tweak parameters is assigned a value of "1", the group that is allowed to edit
-users is assigned a "2", and the group that is allowed to create new groups is
-assigned the bitmask of "4". By uniquely combining the group bitmasks (much
-like the chmod command in UNIX,) you can identify a user is allowed to tweak
-parameters and create groups, but not edit users, by giving him a bitmask of
-"5", or a user allowed to edit users and create groups, but not tweak
-parameters, by giving him a bitmask of "6" Simple, huh?
- If this makes no sense to you, try this at the mysql prompt:
-mysql> select * from groups;
- You'll see the list, it makes much more sense that way.
-
-keyworddefs: Definitions of keywords to be used
-
-keywords: Unlike what you'd think, this table holds which keywords are
-associated with which bug id's.
-
-logincookies: This stores every login cookie ever assigned to you for every
-machine you've ever logged into Bugzilla from. Curiously, it never does any
-housecleaning -- I see cookies in this file I've not used for months. However,
-since Bugzilla never expires your cookie (for convenience' sake), it makes
-sense.
-
-longdescs: The meat of bugzilla -- here is where all user comments are stored!
-You've only got 2^24 bytes per comment (it's a mediumtext field), so speak
-sparingly -- that's only the amount of space the Old Testament from the Bible
-would take (uncompressed, 16 megabytes). Each comment is keyed to the
-bug_id to which it's attached, so the order is necessarily chronological, for
-comments are played back in the order in which they are received.
-
-milestones: Interesting that milestones are associated with a specific product
-in this table, but Bugzilla does not yet support differing milestones by
-product through the standard configuration interfaces.
-
-namedqueries: This is where everybody stores their "custom queries". Very
-cool feature; it beats the tar out of having to bookmark each cool query you
-construct.
-
-products: What products you have, whether new bug entries are allowed for the
-product, what milestone you're working toward on that product, votes, etc. It
-will be nice when the components table supports these same features, so you
-could close a particular component for bug entry without having to close an
-entire product...
-
-profiles: Ahh, so you were wondering where your precious user information was
-stored? Here it is! With the passwords in plain text for all to see! (but
-sshh... don't tell your users!)
-
-profiles_activity: Need to know who did what when to who's profile? This'll
-tell you, it's a pretty complete history.
-
-versions: Version information for every product
-
-votes: Who voted for what when
-
-watch: Who (according to userid) is watching who's bugs (according to their
-userid).
-
-
-===
-THE DETAILS
-===
-
- Ahh, so you're wondering just what to do with the information above? At the
-mysql prompt, you can view any information about the columns in a table with
-this command (where "table" is the name of the table you wish to view):
-
-mysql> show columns from table;
-
- You can also view all the data in a table with this command:
-
-mysql> select * from table;
-
- -- note: this is a very bad idea to do on, for instance, the "bugs" table if
-you have 50,000 bugs. You'll be sitting there a while until you ctrl-c or
-50,000 bugs play across your screen.
-
- You can limit the display from above a little with the command, where
-"column" is the name of the column for which you wish to restrict information:
-
-mysql> select * from table where (column = "some info");
-
- -- or the reverse of this
-
-mysql> select * from table where (column != "some info");
-
- Let's take our example from the introduction, and assume you need to change
-the word "verified" to "approved" in the resolution field. We know from the
-above information that the resolution is likely to be stored in the "bugs"
-table. Note we'll need to change a little perl code as well as this database
-change, but I won't plunge into that in this document. Let's verify the
-information is stored in the "bugs" table:
-
-mysql> show columns from bugs
-
- (exceedingly long output truncated here)
-| bug_status| enum('UNCONFIRMED','NEW','ASSIGNED','REOPENED','RESOLVED','VERIFIED','CLOSED')||MUL | UNCONFIRMED||
-
- Sorry about that long line. We see from this that the "bug status" column is
-an "enum field", which is a MySQL peculiarity where a string type field can
-only have certain types of entries. While I think this is very cool, it's not
-standard SQL. Anyway, we need to add the possible enum field entry
-'APPROVED' by altering the "bugs" table.
-
-mysql> ALTER table bugs CHANGE bug_status bug_status
- -> enum("UNCONFIRMED", "NEW", "ASSIGNED", "REOPENED", "RESOLVED",
- -> "VERIFIED", "APPROVED", "CLOSED") not null;
-
- (note we can take three lines or more -- whatever you put in before the
-semicolon is evaluated as a single expression)
-
-Now if you do this:
-
-mysql> show columns from bugs;
-
- you'll see that the bug_status field has an extra "APPROVED" enum that's
-available! Cool thing, too, is that this is reflected on your query page as
-well -- you can query by the new status. But how's it fit into the existing
-scheme of things?
- Looks like you need to go back and look for instances of the word "verified"
-in the perl code for Bugzilla -- wherever you find "verified", change it to
-"approved" and you're in business (make sure that's a case-insensitive search).
-Although you can query by the enum field, you can't give something a status
-of "APPROVED" until you make the perl changes. Note that this change I
-mentioned can also be done by editing checksetup.pl, which automates a lot of
-this. But you need to know this stuff anyway, right?
-
-
-
-
-
-
-
-
-
diff --git a/docs/sgml/dbschema.mysql b/docs/sgml/dbschema.mysql
deleted file mode 100644
index 8b1378917..000000000
--- a/docs/sgml/dbschema.mysql
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/docs/sgml/faq.sgml b/docs/sgml/faq.sgml
deleted file mode 100644
index ef5f23123..000000000
--- a/docs/sgml/faq.sgml
+++ /dev/null
@@ -1,1321 +0,0 @@
-
-
-
- The Bugzilla FAQ
-
-
- This FAQ includes questions not covered elsewhere in the Guide.
-
-
-
-
-
-
- General Questions
-
-
-
-
- Where can I find information about Bugzilla?
-
-
-
- You can stay up-to-date with the latest Bugzilla
- information at
- http://www.bugzilla.org/
-
-
-
-
-
-
-
- What license is Bugzilla distributed under?
-
-
-
-
- Bugzilla is covered by the Mozilla Public License.
- See details at
- http://www.mozilla.org/MPL/
-
-
-
-
-
-
-
- How do I get commercial support for Bugzilla?
-
-
-
-
- http://bugzilla.org/consulting.html
- is a list of people and companies who have asked us to list them
- as consultants for Bugzilla.
-
-
- www.collab.net offers
- Bugzilla as part of their standard offering to large projects.
- They do have some minimum fees that are pretty hefty, and generally
- aren't interested in small projects.
-
-
- There are several experienced
- Bugzilla hackers on the mailing list/newsgroup who are willing
- to make themselves available for generous compensation.
- Try sending a message to the mailing list asking for a volunteer.
-
-
-
-
-
-
-
- What major companies or projects are currently using Bugzilla
- for bug-tracking?
-
-
-
-
- There are dozens of major companies with public
- Bugzilla sites to track bugs in their products. A few include:
-
- Netscape/AOL
- Mozilla.org
- NASA
- Red Hat Software
- SuSe Corp
- The Horde Project
- AbiSource
- Real Time Enterprises, Inc
- Eggheads.org
- Strata Software
- RockLinux
- Creative Labs (makers of SoundBlaster)
- The Apache Foundation
- The Gnome Foundation
- Ximian
- Linux-Mandrake
-
-
-
- Suffice to say, there are more than enough huge projects using Bugzilla
- that we can safely say it's extremely popular.
-
-
-
-
-
-
-
- Who maintains Bugzilla?
-
-
-
-
- A
- core team,
- led by Dave Miller (justdave@netscape.com).
-
-
-
-
-
-
-
- How does Bugzilla stack up against other bug-tracking databases?
-
-
-
-
- We can't find any head-to-head comparisons of Bugzilla against
- other defect-tracking software. If you know of one, please
- get in touch. However, from the author's personal
- experience with other bug-trackers, Bugzilla offers
- superior performance on commodity hardware, better price
- (free!), more developer- friendly features (such as stored
- queries, email integration, and platform independence),
- improved scalability, open source code, greater
- flexibility, and superior ease-of-use.
-
-
- If you happen to be a commercial bug-tracker vendor, please
- step forward with a list of advantages your product has over
- Bugzilla. We'd be happy to include it in the "Competitors"
- section.
-
-
-
-
-
-
-
- Why doesn't Bugzilla offer this or that feature or compatibility
- with this other tracking software?
-
-
-
-
- It may be that the support has not been built yet, or that you
- have not yet found it. Bugzilla is making tremendous strides in
- usability, customizability, scalability, and user interface. It
- is widely considered the most complete and popular open-source
- bug-tracking software in existence.
-
-
- That doesn't mean it can't use improvement!
- You can help the project along by either hacking a patch yourself
- that supports the functionality you require, or else submitting a
- "Request for Enhancement" (RFE) using the bug submission interface
- at bugzilla.mozilla.org.
-
-
-
-
-
-
-
- Why MySQL? I'm interested in seeing Bugzilla run on
- Oracle/Sybase/Msql/PostgreSQL/MSSQL.
-
-
-
-
- MySQL was originally chosen because it is free, easy to install,
- and was available for the hardware Netscape intended to run it on.
-
-
- There is currently work in progress to make Bugzilla work on
- PostgreSQL and Sybase in the default distribution. You can track
- the progress of these initiatives in bugs 98304
- and 173130
- respectively.
-
-
- Once both of these are done, adding support for additional
- database servers should be trivial.
-
-
-
-
-
-
-
- What is /usr/bonsaitools/bin/perl?
-
-
-
-
- Bugzilla used to have the path to perl on the shebang line set to
- /usr/bonsaitools/bin/perl because when
- Terry first started writing the code for mozilla.org he needed a
- version of Perl and other tools that were completely under his
- control. This location was abandoned for the 2.18 release in favor
- of the more sensible /usr/bin/perl. If you
- installed an older verion of Bugzilla and created the symlink we
- suggested, you can remove it now (provided that you don't have
- anything else, such as Bonsai, using it and you don't intend to
- reinstall an older version of Bugzilla).
-
-
-
-
-
-
-
- My perl is not located at /usr/bin/perl, is
- there an easy way to change it everywhere it needs to be changed?
-
-
-
-
- Yes, the following bit of perl magic will change all the shebang
- lines. Be sure to change /usr/local/bin/perl
- to your path to the perl binary.
-
-
-perl -pi -e 's@#\!/usr/bin/perl@#\!/usr/local/bin/perl@' *cgi *pl
-
-
-
-
-
-
-
- Is there an easy way to change the Bugzilla cookie name?
-
-
-
-
- At present, no.
-
-
-
-
-
-
-
- Managerial Questions
-
-
-
- Questions likely to be asked by managers. :-)
-
-
-
-
-
-
-
- Is Bugzilla web-based, or do you have to have specific software or
- a specific operating system on your machine?
-
-
-
-
- It is web and e-mail based. You can edit bugs by sending specially
- formatted email to a properly configured Bugzilla, or control via the web.
-
-
-
-
-
-
-
- Can Bugzilla integrate with
- Perforce (SCM software)?
-
-
-
-
- Yes! You can find more information elsewhere in "The Bugzilla
- Guide" in the "Integration with Third-Party Products" section.
-
-
-
-
-
-
-
- Does Bugzilla allow the user to track multiple projects?
-
-
-
-
- Absolutely! You can track any number of Products that can each be
- composed of any number of Components.
-
-
-
-
-
-
-
- If I am on many projects, and search for all bugs assigned to me, will
- Bugzilla list them for me and allow me to sort by project, severity etc?
-
-
-
-
- Yes.
-
-
-
-
-
-
-
- Does Bugzilla allow attachments (text, screenshots, URLs etc)? If yes,
- are there any that are NOT allowed?
-
-
-
-
- Yes - any sort of attachment is allowed, although administrators can
- configure a maximum size.
- Bugzilla gives the user the option of either using the MIME-type
- supplied by the browser, choosing from a pre-defined list or
- manually typing any arbitrary MIME-type.
-
-
-
-
-
-
-
- Does Bugzilla allow us to define our own priorities and levels? Do we
- have complete freedom to change the labels of fields and format of them, and
- the choice of acceptable values?
-
-
-
-
- Yes. However, modifying some fields, notably those related to bug
- progression states, also require adjusting the program logic to
- compensate for the change.
-
-
- There is no GUI for adding fields to Bugzilla at this
- time. You can follow development of this feature at
- http://bugzilla.mozilla.org/show_bug.cgi?id=91037
-
-
-
-
-
-
-
- Does Bugzilla provide any reporting features, metrics, graphs, etc? You
- know, the type of stuff that management likes to see. :)
-
-
-
-
- Yes. Look at
- http://bugzilla.mozilla.org/report.cgi for samples of what
- Bugzilla can do in reporting and graphing.
-
-
- If you can not get the reports you want from the included reporting
- scripts, it is possible to hook up a professional reporting package
- such as Crystal Reports using ODBC. If you choose to do this,
- beware that giving direct access to the database does contain some
- security implications. Even if you give read-only access to the
- bugs database it will bypass the secure bugs features of Bugzilla.
-
-
-
-
-
-
-
- Is there email notification and if so, what do you see when you get an
- email?
-
-
-
-
- Email notification is user-configurable. By default, the bug id and
- Summary of the bug report accompany each email notification, along with
- a list of the changes made.
-
-
-
-
-
-
-
- Can email notification be set up to send to multiple
- people, some on the To List, CC List, BCC List etc?
-
-
-
-
- Yes.
-
-
-
-
-
-
-
- Do users have to have any particular
- type of email application?
-
-
-
-
- Bugzilla email is sent in plain text, the most compatible mail format
- on the planet.
-
-
- If you decide to use the bugzilla_email integration features
- to allow Bugzilla to record responses to mail with the associated bug,
- you may need to caution your users to set their mailer to "respond
- to messages in the format in which they were sent". For security reasons
- Bugzilla ignores HTML tags in comments, and if a user sends HTML-based
- email into Bugzilla the resulting comment looks downright awful.
-
-
-
-
-
-
-
-
-
- Does Bugzilla allow data to be imported and exported? If I had outsiders
- write up a bug report using a MS Word bug template, could that template be
- imported into "matching" fields? If I wanted to take the results of a query
- and export that data to MS Excel, could I do that?
-
-
-
-
- Bugzilla can output buglists as HTML (the default), CSV or RDF.
- The link for CSV can be found at the bottom of the buglist in HTML
- format. This CSV format can easily be imported into MS Excel or
- other spread-sheet applications.
-
-
- To use the RDF format of the buglist it is necessary to append a
- &ctype=rdf to the URL. RDF
- is meant to be machine readable and thus it is assumed that the
- URL would be generated progmatically so there is no user visible
- link to this format.
-
-
- Currently the only script included with Bugzilla that can import
- data is importxml.pl which is intended to be
- used for importing the data generated by the XML ctype of
- show_bug.cgi in association with bug moving.
- Any other use is left as an exercise for the user.
-
-
- There are also scripts included in the contrib/
- directory for using e-mail to import information into Bugzilla,
- but these scripts are not currently supported and included for
- educational purposes.
-
-
-
-
-
-
-
- Has anyone converted Bugzilla to another language to be used in other
- countries? Is it localizable?
-
-
-
-
- Yes. For more information including available translated templates,
- see .
- The admin interfaces are still not included in these translated
- templates and is therefore still English only. Also, there may be
- issues with the charset not being declared. See bug 126226
- for more information.
-
-
-
-
-
-
-
- Can a user create and save reports? Can they do this in Word format?
- Excel format?
-
-
-
-
- Yes. No. Yes (using the CSV format).
-
-
-
-
-
-
-
- Does Bugzilla have the ability to search by word, phrase, compound
- search?
-
-
-
-
- You have no idea. Bugzilla's query interface, particularly with the
- advanced Boolean operators, is incredibly versatile.
-
-
-
-
-
-
-
- Does Bugzilla provide record locking when there is simultaneous access
- to the same bug? Does the second person get a notice that the bug is in use
- or how are they notified?
-
-
-
-
- Bugzilla does not lock records. It provides mid-air collision detection,
- and offers the offending user a choice of options to deal with the conflict.
-
-
-
-
-
-
-
- Are there any backup features provided?
-
-
-
-
- MySQL, the database back-end for Bugzilla, allows hot-backup of data.
- You can find strategies for dealing with backup considerations
- at
- http://www.mysql.com/doc/B/a/Backup.html
-
-
-
-
-
-
-
- Can users be on the system while a backup is in progress?
-
-
-
-
- Yes. However, commits to the database must wait
- until the tables are unlocked. Bugzilla databases are typically
- very small, and backups routinely take less than a minute.
-
-
-
-
-
-
-
- What type of human resources are needed to be on staff to install and
- maintain Bugzilla? Specifically, what type of skills does the person need to
- have? I need to find out if we were to go with Bugzilla, what types of
- individuals would we need to hire and how much would that cost vs buying an
- "Out-of-the-Box" solution.
-
-
-
-
- If Bugzilla is set up correctly from the start, continuing maintenance
- needs are minimal and can be done easily using the web interface.
-
-
- Commercial Bug-tracking software typically costs somewhere upwards
- of $20,000 or more for 5-10 floating licenses. Bugzilla consultation
- is available from skilled members of the newsgroup. Simple questions
- are answered there and then.
-
-
-
-
-
-
-
- What time frame are we looking at if we decide to hire people to install
- and maintain the Bugzilla? Is this something that takes hours or weeks to
- install and a couple of hours per week to maintain and customize or is this
- a multi-week install process, plus a full time job for 1 person, 2 people,
- etc?
-
-
-
-
- It all depends on your level of commitment. Someone with much Bugzilla
- experience can get you up and running in less than a day, and
- your Bugzilla install can run untended for years. If your
- Bugzilla strategy is critical to your business workflow, hire somebody
- with reasonable UNIX or Perl skills to handle your process management and
- bug-tracking maintenance & customization.
-
-
-
-
-
-
-
- Is there any licensing fee or other fees for using Bugzilla? Any
- out-of-pocket cost other than the bodies needed as identified above?
-
-
-
-
- No. MySQL asks, if you find their product valuable, that you purchase
- a support contract from them that suits your needs.
-
-
-
-
-
-
- Bugzilla Security
-
-
-
-
- How do I completely disable MySQL security if it's giving me problems
- (I've followed the instructions in the installation section of this guide)?
-
-
-
-
- Run MySQL like this: "mysqld --skip-grant-tables". Please remember this
- makes MySQL as secure as taping a $100 to the floor of a football stadium
- bathroom for safekeeping.
-
-
-
-
-
-
-
- Are there any security problems with Bugzilla?
-
-
-
-
- The Bugzilla code has undergone a reasonably complete security audit,
- and user-facing CGIs run under Perl's taint mode. However,
- it is recommended that you closely examine permissions on your Bugzilla
- installation, and follow the recommended security guidelines found
- in The Bugzilla Guide.
-
-
-
-
-
-
-
-
- I've implemented the security fixes mentioned in Chris Yeh's security
- advisory of 5/10/2000 advising not to run MySQL as root, and am running into
- problems with MySQL no longer working correctly.
-
-
-
-
- This is a common problem, related to running out of file descriptors.
- Simply add "ulimit -n unlimited" to the script which starts
- mysqld.
-
-
-
-
-
-
- Bugzilla Email
-
-
-
-
- I have a user who doesn't want to receive any more email from Bugzilla.
- How do I stop it entirely for this user?
-
-
-
-
- The user should be able to set
- this in user email preferences (uncheck all boxes) or you can add
- their email address to the data/nomail file.
-
-
-
-
-
-
-
- I'm evaluating/testing Bugzilla, and don't want it to send email to
- anyone but me. How do I do it?
-
-
-
-
- Edit the "newchangedmail" Param. Replace "To:" with "X-Real-To:",
- replace "Cc:" with "X-Real-CC:", and add a "To: <youremailaddress>".
-
-
-
-
-
-
-
- I want whineatnews.pl to whine at something more, or other than, only new
- bugs. How do I do it?
-
-
-
-
- Try Klaas Freitag's excellent patch for "whineatassigned" functionality.
- You can find it at . This
- patch is against an older version of Bugzilla, so you must apply
- the diffs manually.
-
-
-
-
-
-
-
-
- I don't like/want to use Procmail to hand mail off to bug_email.pl.
- What alternatives do I have?
-
-
-
-
- You can call bug_email.pl directly from your aliases file, with
- an entry like this:
-
- However, this is fairly nasty and subject to problems; you also
- need to set up your smrsh (sendmail restricted shell) to allow
- it. In a pinch, though, it can work.
-
-
-
-
-
-
-
- How do I set up the email interface to submit/change bugs via email?
-
-
-
-
- You can find an updated README.mailif file in the contrib/ directory
- of your Bugzilla distribution that walks you through the setup.
-
-
-
-
-
-
-
- Email takes FOREVER to reach me from Bugzilla -- it's extremely slow.
- What gives?
-
-
-
-
- If you are using an alternate MTA,
- make sure the options given in Bugzilla/BugMail.pm
- and any other place where sendmail is called from
- are correct for your MTA. You should also ensure that the
- param is set to on.
-
-
- If you are using sendmail, try enabling
- in editparams.cgi.
-
-
-
-
-
-
-
-
- How come email from Bugzilla changes never reaches me?
-
-
-
-
- Double-check that you have not turned off email in your user preferences.
- Confirm that Bugzilla is able to send email by visiting the "Log In"
- link of your Bugzilla installation and clicking the "Email me a password"
- button after entering your email address.
-
-
- If you never receive mail from Bugzilla, chances you do not have
- sendmail in "/usr/lib/sendmail". Ensure sendmail lives in, or is symlinked
- to, "/usr/lib/sendmail".
-
-
-
-
-
-
- Bugzilla Database
-
-
-
-
- I've heard Bugzilla can be used with Oracle?
-
-
-
-
- Red Hat's old version of Bugzilla (based on 2.8) worked on Oracle.
- Red Hat's newer version (based on 2.17.1 and soon to be merged into
- the main distribution) runs on PostgreSQL. At this time we know of
- no recent ports of Bugzilla to Oracle but do intend to support it
- in the future (possibly the 2.20 time-frame).
-
-
-
-
-
-
-
- I think my database might be corrupted, or contain invalid entries. What
- do I do?
-
-
-
-
- Run the sanity check utility
- (./sanitycheck.cgi in the
- Bugzilla_home directory) from your web browser to see! If
- it finishes without errors, you're
- probably OK. If it doesn't come back
- OK (i.e. any red letters), there are certain things
- Bugzilla can recover from and certain things it can't. If
- it can't auto-recover, I hope you're familiar with
- mysqladmin commands or have installed another way to
- manage your database. Sanity Check, although it is a good
- basic check on your database integrity, by no means is a
- substitute for competent database administration and
- avoiding deletion of data. It is not exhaustive, and was
- created to do a basic check for the most common problems
- in Bugzilla databases.
-
-
-
-
-
-
-
- I want to manually edit some entries in my database. How?
-
-
-
-
- There is no facility in Bugzilla itself to do this. It's also generally
- not a smart thing to do if you don't know exactly what you're doing.
- However, if you understand SQL you can use the mysql
- command line utility to manually insert, delete and modify table
- information. There are also more intuitive GUI clients available.
- Personal favorites of the Bugzilla team are phpMyAdmin and MySQL Control
- Center.
-
-
-
-
-
-
-
- I think I've set up MySQL permissions correctly, but Bugzilla still can't
- connect.
-
-
-
-
- Try running MySQL from its binary: "mysqld --skip-grant-tables". This
- will allow you to completely rule out grant tables as the cause of your
- frustration. If this Bugzilla is able to connect at this point then
- you need to check that you have granted proper permission to the user
- password combo defined in localconfig.
-
-
-
- Running MySQL with this command line option is very insecure and
- should only be done when not connected to the external network
- as a troubleshooting step.
-
-
-
-
-
-
-
-
- How do I synchronize bug information among multiple different Bugzilla
- databases?
-
-
-
-
- Well, you can synchronize or you can move bugs. Synchronization will
- only work one way -- you can create a read-only copy of the database
- at one site, and have it regularly updated at intervals from the main
- database.
-
-
- MySQL has some synchronization features builtin to the latest releases.
- It would be great if someone looked into the possibilities there
- and provided a report to the newsgroup on how to effectively
- synchronize two Bugzilla installations.
-
-
- If you simply need to transfer bugs from one Bugzilla to another,
- checkout the "move.pl" script in the Bugzilla distribution.
-
-
-
-
-
-
- Bugzilla and Win32
-
-
-
-
- What is the easiest way to run Bugzilla on Win32 (Win98+/NT/2K)?
-
-
-
-
- Remove Windows. Install Linux. Install Bugzilla.
- The boss will never know the difference.
-
-
-
-
-
-
-
- Is there a "Bundle::Bugzilla" equivalent for Win32?
-
-
-
-
- Not currently. Bundle::Bugzilla enormously simplifies Bugzilla
- installation on UNIX systems. If someone can volunteer to
- create a suitable PPM bundle for Win32, it would be appreciated.
-
-
-
-
-
-
-
- CGI's are failing with a "something.cgi is not a valid Windows NT
- application" error. Why?
-
-
-
-
- Depending on what Web server you are using, you will have to configure
- the Web server to treat *.cgi files as CGI scripts. In IIS, you do this by
- adding *.cgi to the App Mappings with the <path>\perl.exe %s %s as the
- executable.
-
-
- Microsoft has some advice on this matter, as well:
-
-
- "Set application mappings. In the ISM, map the extension for the script
- file(s) to the executable for the script interpreter. For example, you might
- map the extension .py to Python.exe, the executable for the Python script
- interpreter. Note For the ActiveState Perl script interpreter, the extension
- .pl is associated with PerlIS.dll by default. If you want to change the
- association of .pl to perl.exe, you need to change the application mapping.
- In the mapping, you must add two percent (%) characters to the end of the
- pathname for perl.exe, as shown in this example: c:\perl\bin\perl.exe %s %s"
-
-
-
-
-
-
-
-
-
- I'm having trouble with the perl modules for NT not being able to talk to
- to the database.
-
-
-
-
- Your modules may be outdated or inaccurate. Try:
-
-
-
- Hitting http://www.activestate.com/ActivePerl
-
-
-
-
- Download ActivePerl
-
-
-
-
- Go to your prompt
-
-
-
-
- Type 'ppm'
-
-
-
-
- PPM>install DBI DBD-mysql GD
-
-
-
- I reckon TimeDate and Data::Dumper come with the activeperl. You can check
- the ActiveState site for packages for installation through PPM.
-
- http://www.activestate.com/Packages/
-
-
-
-
-
-
-
- Bugzilla Usage
-
-
-
-
- How do I change my user name (email address) in Bugzilla?
-
-
-
-
- New in 2.16 - go to the Account section of the Preferences. You will
- be emailed at both addresses for confirmation.
-
-
-
-
-
-
-
- The query page is very confusing. Isn't there a simpler way to query?
-
-
-
-
- The interface was simplified by a UI designer for 2.16. Further
- suggestions for improvement are welcome, but we won't sacrifice power for
- simplicity.
-
-
-
-
-
-
-
- I'm confused by the behavior of the "accept" button in the Show Bug form.
- Why doesn't it assign the bug to me when I accept it?
-
-
-
-
- The current behavior is acceptable to bugzilla.mozilla.org and most
- users. You have your choice of patches
- to change this behavior, however.
-
-
- Add a "and accept bug" radio button
-
- "Accept" button automatically assigns to you
-
- Note that these patches are somewhat dated. You will need to apply
- them manually.
-
-
-
-
-
-
-
- I can't upload anything into the database via the "Create Attachment"
- link. What am I doing wrong?
-
-
-
-
- The most likely cause is a very old browser or a browser that is
- incompatible with file upload via POST. Download the latest Netscape,
- Microsoft, or Mozilla browser to handle uploads correctly.
-
-
-
-
-
-
-
- How do I change a keyword in Bugzilla, once some bugs are using it?
-
-
-
-
- In the Bugzilla administrator UI, edit the keyword and it will let you
- replace the old keyword name with a new one. This will cause a problem
- with the keyword cache. Run sanitycheck.cgi to fix it.
-
-
-
-
-
-
-
- Bugzilla Hacking
-
-
-
-
- What kind of style should I use for templatization?
-
-
-
-
- Gerv and Myk suggest a 2-space indent, with embedded code sections on
- their own line, in line with outer tags. Like this:
-
-[% IF foo %]
-
- [% FOREACH x = barney %]
-
-
- [% x %]
-
-
- [% END %]
-[% END %]
-
-]]>
-
- Myk also recommends you turn on PRE_CHOMP in the template
- initialization to prevent bloating of HTML with unnecessary whitespace.
-
-
- Please note that many have differing opinions on this subject,
- and the existing templates in Bugzilla espouse both this and a 4-space
- style. Either is acceptable; the above is preferred.
-
-
-
-
-
-
- What bugs are in Bugzilla right now?
-
-
-
-
- Try
- this link to view current bugs or requests for
- enhancement for Bugzilla.
-
-
- You can view bugs marked for &bz-nextver; release
- here.
- This list includes bugs for the &bz-nextver; release that have already
- been fixed and checked into CVS. Please consult the
-
- Bugzilla Project Page for details on how to
- check current sources out of CVS so you can have these
- bug fixes early!
-
-
-
-
-
-
-
- How can I change the default priority to a null value? For instance, have the default
- priority be "---" instead of "P2"?
-
-
-
-
- This is well-documented here:
- http://bugzilla.mozilla.org/show_bug.cgi?id=49862. Ultimately, it's as easy
- as adding the "---" priority field to your localconfig file in the appropriate area,
- re-running checksetup.pl, and then changing the default priority in your browser using
- "editparams.cgi".
-
-
-
-
-
-
-
- What's the best way to submit patches? What guidelines should I follow?
-
-
-
-
-
-
-
- Enter a bug into bugzilla.mozilla.org for the Bugzilla
- product.
-
-
-
-
- Upload your patch as a unified diff (having used "diff -u" against
- the current sources checked out of CVS),
- or new source file by clicking
- "Create a new attachment" link on the bug page you've just created, and
- include any descriptions of database changes you may make, into the bug
- ID you submitted in step #1. Be sure and click the "Patch" checkbox
- to indicate the text you are sending is a patch!
-
-
-
-
- Announce your patch and the associated URL
- (http://bugzilla.mozilla.org/show_bug.cgi?id=XXXXXX) for discussion in
- the newsgroup (netscape.public.mozilla.webtools). You'll get a really
- good, fairly immediate reaction to the implications of your patch,
- which will also give us an idea how well-received the change would
- be.
-
-
-
-
- If it passes muster with minimal modification, the person to whom
- the bug is assigned in Bugzilla is responsible for seeing the patch
- is checked into CVS.
-
-
-
-
- Bask in the glory of the fact that you helped write the most successful
- open-source bug-tracking software on the planet :)
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/sgml/filetemp.patch b/docs/sgml/filetemp.patch
deleted file mode 100644
index 9fb70adce..000000000
--- a/docs/sgml/filetemp.patch
+++ /dev/null
@@ -1,18 +0,0 @@
---- File/Temp.pm.orig Thu Feb 6 16:26:00 2003
-+++ File/Temp.pm Thu Feb 6 16:26:23 2003
-@@ -205,6 +205,7 @@
- # eg CGI::Carp
- local $SIG{__DIE__} = sub {};
- local $SIG{__WARN__} = sub {};
-+ local *CORE::GLOBAL::die = sub {};
- $bit = &$func();
- 1;
- };
-@@ -226,6 +227,7 @@
- # eg CGI::Carp
- local $SIG{__DIE__} = sub {};
- local $SIG{__WARN__} = sub {};
-+ local *CORE::GLOBAL::die = sub {};
- $bit = &$func();
- 1;
- };
diff --git a/docs/sgml/gd-makefile.patch b/docs/sgml/gd-makefile.patch
deleted file mode 100644
index 8ec35a23a..000000000
--- a/docs/sgml/gd-makefile.patch
+++ /dev/null
@@ -1,22 +0,0 @@
---- GD-1.33/Makefile.PL Fri Aug 4 16:59:22 2000
-+++ GD-1.33-darwin/Makefile.PL Tue Jun 26 01:29:32 2001
-@@ -3,8 +3,8 @@
- warn "NOTICE: This module requires libgd 1.8.3 or higher (shared library version 4.X).\n";
-
- # =====> PATHS: CHECK AND ADJUST <=====
--my @INC = qw(-I/usr/local/include -I/usr/local/include/gd);
--my @LIBPATH = qw(-L/usr/lib/X11 -L/usr/X11R6/lib -L/usr/X11/lib -L/usr/local/lib );
-+my @INC = qw(-I/sw/include -I/sw/include/gd -I/usr/local/include -I/usr/local/include/gd);
-+my @LIBPATH = qw(-L/usr/lib/X11 -L/usr/X11R6/lib -L/usr/X11/lib -L/sw/lib -L/usr/local/lib);
- my @LIBS = qw(-lgd -lpng -lz);
-
- # FEATURE FLAGS
-@@ -23,7 +23,7 @@
-
- push @LIBS,'-lttf' if $TTF;
- push @LIBS,'-ljpeg' if $JPEG;
--push @LIBS, '-lm' unless $^O eq 'MSWin32';
-+push @LIBS, '-lm' unless ($^O =~ /^MSWin32|darwin$/);
-
- # FreeBSD 3.3 with libgd built from ports croaks if -lXpm is specified
- if ($^O ne 'freebsd' && $^O ne 'MSWin32') {
diff --git a/docs/sgml/gfdl.sgml b/docs/sgml/gfdl.sgml
deleted file mode 100644
index fdfdb4bc5..000000000
--- a/docs/sgml/gfdl.sgml
+++ /dev/null
@@ -1,448 +0,0 @@
-
-
- GNU Free Documentation License
-
-
-
-
- Version 1.1, March 2000
-
-
- Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place,
- Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and
- distribute verbatim copies of this license document, but changing it is
- not allowed.
-
-
-
- PREAMBLE
-
- The purpose of this License is to make a manual, textbook, or other
- written document "free" in the sense of freedom: to assure everyone the
- effective freedom to copy and redistribute it, with or without modifying
- it, either commercially or noncommercially. Secondarily, this License
- preserves for the author and publisher a way to get credit for their
- work, while not being considered responsible for modifications made by
- others.
-
- This License is a kind of "copyleft", which means that derivative
- works of the document must themselves be free in the same sense. It
- complements the GNU General Public License, which is a copyleft license
- designed for free software.
-
- We have designed this License in order to use it for manuals for
- free software, because free software needs free documentation: a free
- program should come with manuals providing the same freedoms that the
- software does. But this License is not limited to software manuals; it
- can be used for any textual work, regardless of subject matter or whether
- it is published as a printed book. We recommend this License principally
- for works whose purpose is instruction or reference.
-
-
-
- APPLICABILITY AND DEFINITIONS
-
- This License applies to any manual or other work that contains a
- notice placed by the copyright holder saying it can be distributed under
- the terms of this License. The "Document", below, refers to any such
- manual or work. Any member of the public is a licensee, and is addressed
- as "you".
-
- A "Modified Version" of the Document means any work containing the
- Document or a portion of it, either copied verbatim, or with
- modifications and/or translated into another language.
-
- A "Secondary Section" is a named appendix or a front-matter section
- of the Document that deals exclusively with the relationship of the
- publishers or authors of the Document to the Document's overall subject
- (or to related matters) and contains nothing that could fall directly
- within that overall subject. (For example, if the Document is in part a
- textbook of mathematics, a Secondary Section may not explain any
- mathematics.) The relationship could be a matter of historical connection
- with the subject or with related matters, or of legal, commercial,
- philosophical, ethical or political position regarding them.
-
- The "Invariant Sections" are certain Secondary Sections whose
- titles are designated, as being those of Invariant Sections, in the
- notice that says that the Document is released under this License.
-
- The "Cover Texts" are certain short passages of text that are
- listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says
- that the Document is released under this License.
-
- A "Transparent" copy of the Document means a machine-readable copy,
- represented in a format whose specification is available to the general
- public, whose contents can be viewed and edited directly and
- straightforwardly with generic text editors or (for images composed of
- pixels) generic paint programs or (for drawings) some widely available
- drawing editor, and that is suitable for input to text formatters or for
- automatic translation to a variety of formats suitable for input to text
- formatters. A copy made in an otherwise Transparent file format whose
- markup has been designed to thwart or discourage subsequent modification
- by readers is not Transparent. A copy that is not "Transparent" is called
- "Opaque".
-
- Examples of suitable formats for Transparent copies include plain
- ASCII without markup, Texinfo input format, LaTeX input format, SGML or
- XML using a publicly available DTD, and standard-conforming simple HTML
- designed for human modification. Opaque formats include PostScript, PDF,
- proprietary formats that can be read and edited only by proprietary word
- processors, SGML or XML for which the DTD and/or processing tools are not
- generally available, and the machine-generated HTML produced by some word
- processors for output purposes only.
-
- The "Title Page" means, for a printed book, the title page itself,
- plus such following pages as are needed to hold, legibly, the material
- this License requires to appear in the title page. For works in formats
- which do not have any title page as such, "Title Page" means the text
- near the most prominent appearance of the work's title, preceding the
- beginning of the body of the text.
-
-
-
- VERBATIM COPYING
-
- You may copy and distribute the Document in any medium, either
- commercially or noncommercially, provided that this License, the
- copyright notices, and the license notice saying this License applies to
- the Document are reproduced in all copies, and that you add no other
- conditions whatsoever to those of this License. You may not use technical
- measures to obstruct or control the reading or further copying of the
- copies you make or distribute. However, you may accept compensation in
- exchange for copies. If you distribute a large enough number of copies
- you must also follow the conditions in section 3.
-
- You may also lend copies, under the same conditions stated above,
- and you may publicly display copies.
-
-
-
- COPYING IN QUANTITY
-
- If you publish printed copies of the Document numbering more than
- 100, and the Document's license notice requires Cover Texts, you must
- enclose the copies in covers that carry, clearly and legibly, all these
- Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts
- on the back cover. Both covers must also clearly and legibly identify you
- as the publisher of these copies. The front cover must present the full
- title with all words of the title equally prominent and visible. You may
- add other material on the covers in addition. Copying with changes
- limited to the covers, as long as they preserve the title of the Document
- and satisfy these conditions, can be treated as verbatim copying in other
- respects.
-
- If the required texts for either cover are too voluminous to fit
- legibly, you should put the first ones listed (as many as fit reasonably)
- on the actual cover, and continue the rest onto adjacent pages.
-
- If you publish or distribute Opaque copies of the Document
- numbering more than 100, you must either include a machine-readable
- Transparent copy along with each Opaque copy, or state in or with each
- Opaque copy a publicly-accessible computer-network location containing a
- complete Transparent copy of the Document, free of added material, which
- the general network-using public has access to download anonymously at no
- charge using public-standard network protocols. If you use the latter
- option, you must take reasonably prudent steps, when you begin
- distribution of Opaque copies in quantity, to ensure that this
- Transparent copy will remain thus accessible at the stated location until
- at least one year after the last time you distribute an Opaque copy
- (directly or through your agents or retailers) of that edition to the
- public.
-
- It is requested, but not required, that you contact the authors of
- the Document well before redistributing any large number of copies, to
- give them a chance to provide you with an updated version of the
- Document.
-
-
-
- MODIFICATIONS
-
- You may copy and distribute a Modified Version of the Document
- under the conditions of sections 2 and 3 above, provided that you release
- the Modified Version under precisely this License, with the Modified
- Version filling the role of the Document, thus licensing distribution and
- modification of the Modified Version to whoever possesses a copy of it.
- In addition, you must do these things in the Modified Version:
-
-
-
- Use in the Title Page (and on the covers, if any) a title
- distinct from that of the Document, and from those of previous
- versions (which should, if there were any, be listed in the History
- section of the Document). You may use the same title as a previous
- version if the original publisher of that version gives
- permission.
-
-
-
- List on the Title Page, as authors, one or more persons or
- entities responsible for authorship of the modifications in the
- Modified Version, together with at least five of the principal
- authors of the Document (all of its principal authors, if it has less
- than five).
-
-
-
- State on the Title page the name of the publisher of the
- Modified Version, as the publisher.
-
-
-
- Preserve all the copyright notices of the Document.
-
-
-
- Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
-
-
-
- Include, immediately after the copyright notices, a license
- notice giving the public permission to use the Modified Version under
- the terms of this License, in the form shown in the Addendum
- below.
-
-
-
- Preserve in that license notice the full lists of Invariant
- Sections and required Cover Texts given in the Document's license
- notice.
-
-
-
- Include an unaltered copy of this License.
-
-
-
- Preserve the section entitled "History", and its title, and add
- to it an item stating at least the title, year, new authors, and
- publisher of the Modified Version as given on the Title Page. If
- there is no section entitled "History" in the Document, create one
- stating the title, year, authors, and publisher of the Document as
- given on its Title Page, then add an item describing the Modified
- Version as stated in the previous sentence.
-
-
-
- Preserve the network location, if any, given in the Document
- for public access to a Transparent copy of the Document, and likewise
- the network locations given in the Document for previous versions it
- was based on. These may be placed in the "History" section. You may
- omit a network location for a work that was published at least four
- years before the Document itself, or if the original publisher of the
- version it refers to gives permission.
-
-
-
- In any section entitled "Acknowledgements" or "Dedications",
- preserve the section's title, and preserve in the section all the
- substance and tone of each of the contributor acknowledgements and/or
- dedications given therein.
-
-
-
- Preserve all the Invariant Sections of the Document, unaltered
- in their text and in their titles. Section numbers or the equivalent
- are not considered part of the section titles.
-
-
-
- Delete any section entitled "Endorsements". Such a section may
- not be included in the Modified Version.
-
-
-
- Do not retitle any existing section as "Endorsements" or to
- conflict in title with any Invariant Section.
-
-
-
- If the Modified Version includes new front-matter sections or
- appendices that qualify as Secondary Sections and contain no material
- copied from the Document, you may at your option designate some or all of
- these sections as invariant. To do this, add their titles to the list of
- Invariant Sections in the Modified Version's license notice. These titles
- must be distinct from any other section titles.
-
- You may add a section entitled "Endorsements", provided it contains
- nothing but endorsements of your Modified Version by various parties--for
- example, statements of peer review or that the text has been approved by
- an organization as the authoritative definition of a standard.
-
- You may add a passage of up to five words as a Front-Cover Text,
- and a passage of up to 25 words as a Back-Cover Text, to the end of the
- list of Cover Texts in the Modified Version. Only one passage of
- Front-Cover Text and one of Back-Cover Text may be added by (or through
- arrangements made by) any one entity. If the Document already includes a
- cover text for the same cover, previously added by you or by arrangement
- made by the same entity you are acting on behalf of, you may not add
- another; but you may replace the old one, on explicit permission from the
- previous publisher that added the old one.
-
- The author(s) and publisher(s) of the Document do not by this
- License give permission to use their names for publicity for or to assert
- or imply endorsement of any Modified Version.
-
-
-
- COMBINING DOCUMENTS
-
- You may combine the Document with other documents released under
- this License, under the terms defined in section 4 above for modified
- versions, provided that you include in the combination all of the
- Invariant Sections of all of the original documents, unmodified, and list
- them all as Invariant Sections of your combined work in its license
- notice.
-
- The combined work need only contain one copy of this License, and
- multiple identical Invariant Sections may be replaced with a single copy.
- If there are multiple Invariant Sections with the same name but different
- contents, make the title of each such section unique by adding at the end
- of it, in parentheses, the name of the original author or publisher of
- that section if known, or else a unique number. Make the same adjustment
- to the section titles in the list of Invariant Sections in the license
- notice of the combined work.
-
- In the combination, you must combine any sections entitled
- "History" in the various original documents, forming one section entitled
- "History"; likewise combine any sections entitled "Acknowledgements", and
- any sections entitled "Dedications". You must delete all sections
- entitled "Endorsements."
-
-
-
- COLLECTIONS OF DOCUMENTS
-
- You may make a collection consisting of the Document and other
- documents released under this License, and replace the individual copies
- of this License in the various documents with a single copy that is
- included in the collection, provided that you follow the rules of this
- License for verbatim copying of each of the documents in all other
- respects.
-
- You may extract a single document from such a collection, and
- distribute it individually under this License, provided you insert a copy
- of this License into the extracted document, and follow this License in
- all other respects regarding verbatim copying of that document.
-
-
-
- AGGREGATION WITH INDEPENDENT WORKS
-
- A compilation of the Document or its derivatives with other
- separate and independent documents or works, in or on a volume of a
- storage or distribution medium, does not as a whole count as a Modified
- Version of the Document, provided no compilation copyright is claimed for
- the compilation. Such a compilation is called an "aggregate", and this
- License does not apply to the other self-contained works thus compiled
- with the Document, on account of their being thus compiled, if they are
- not themselves derivative works of the Document.
-
- If the Cover Text requirement of section 3 is applicable to these
- copies of the Document, then if the Document is less than one quarter of
- the entire aggregate, the Document's Cover Texts may be placed on covers
- that surround only the Document within the aggregate. Otherwise they must
- appear on covers around the whole aggregate.
-
-
-
- TRANSLATION
-
- Translation is considered a kind of modification, so you may
- distribute translations of the Document under the terms of section 4.
- Replacing Invariant Sections with translations requires special
- permission from their copyright holders, but you may include translations
- of some or all Invariant Sections in addition to the original versions of
- these Invariant Sections. You may include a translation of this License
- provided that you also include the original English version of this
- License. In case of a disagreement between the translation and the
- original English version of this License, the original English version
- will prevail.
-
-
-
- TERMINATION
-
- You may not copy, modify, sublicense, or distribute the Document
- except as expressly provided for under this License. Any other attempt to
- copy, modify, sublicense or distribute the Document is void, and will
- automatically terminate your rights under this License. However, parties
- who have received copies, or rights, from you under this License will not
- have their licenses terminated so long as such parties remain in full
- compliance.
-
-
-
- FUTURE REVISIONS OF THIS LICENSE
-
- The Free Software Foundation may publish new, revised versions of
- the GNU Free Documentation License from time to time. Such new versions
- will be similar in spirit to the present version, but may differ in
- detail to address new problems or concerns. See
-
- http://www.gnu.org/copyleft/
-
- .
-
- Each version of the License is given a distinguishing version
- number. If the Document specifies that a particular numbered version of
- this License "or any later version" applies to it, you have the option of
- following the terms and conditions either of that specified version or of
- any later version that has been published (not as a draft) by the Free
- Software Foundation. If the Document does not specify a version number of
- this License, you may choose any version ever published (not as a draft)
- by the Free Software Foundation.
-
-
-
- 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.
-
-
-
-
-
diff --git a/docs/sgml/glossary.sgml b/docs/sgml/glossary.sgml
deleted file mode 100644
index d979505ca..000000000
--- a/docs/sgml/glossary.sgml
+++ /dev/null
@@ -1,482 +0,0 @@
-
-
-
- 0-9, high ascii
-
-
- .htaccess
-
-
- Apache web server, and other NCSA-compliant web servers,
- observe the convention of using files in directories called
- .htaccess
-
- to restrict access to certain files. In Bugzilla, they are used
- to keep secret files which would otherwise
- compromise your installation - e.g. the
- localconfig
- file contains the password to your database.
- curious.
-
-
-
-
-
- A
-
-
- Apache
-
-
- In this context, Apache is the web server most commonly used
- for serving up Bugzilla
- pages. Contrary to popular belief, the apache web server has nothing
- to do with the ancient and noble Native American tribe, but instead
- derived its name from the fact that it was
- a patchy
- version of the original
- NCSA
- world-wide-web server.
-
-
- Useful Directives when configuring Bugzilla
-
-
- AddHandler
-
- Tell Apache that it's OK to run CGI scripts.
-
-
-
- AllowOverride
- Options
-
- These directives are used to tell Apache many things about
- the directory they apply to. For Bugzilla's purposes, we need
- them to allow script execution and .htaccess
- overrides.
-
-
-
-
- DirectoryIndex
-
- Used to tell Apache what files are indexes. If you can
- not add index.cgi to the list of valid files,
- you'll need to set $index_html to
- 1 in localconfig so
- ./checksetup.pl will create an
- index.html that redirects to
- index.cgi.
-
-
-
-
- ScriptInterpreterSource
-
- Used when running Apache on windows so the shebang line
- doesn't have to be changed in every Bugzilla script.
-
-
-
-
-
- For more information about how to configure Apache for Bugzilla,
- see .
-
-
-
-
-
-
- B
-
-
- Bug
-
-
- A
- bug
-
- in Bugzilla refers to an issue entered into the database which has an
- associated number, assignments, comments, etc. Some also refer to a
- tickets
- or
- issues;
- in the context of Bugzilla, they are synonymous.
-
-
-
-
- Bug Number
-
-
- Each Bugzilla bug is assigned a number that uniquely identifies
- that bug. The bug associated with a bug number can be pulled up via a
- query, or easily from the very front page by typing the number in the
- "Find" box.
-
-
-
-
- Bugzilla
-
-
- Bugzilla is the world-leading free software bug tracking system.
-
-
-
-
-
-
- C
-
-
- Common Gateway Interface
- CGI
-
- CGI is an acronym for Common Gateway Interface. This is
- a standard for interfacing an external application with a web server. Bugzilla
- is an example of a CGI application.
-
-
-
-
-
- Component
-
-
- A Component is a subsection of a Product. It should be a narrow
- category, tailored to your organization. All Products must contain at
- least one Component (and, as a matter of fact, creating a Product
- with no Components will create an error in Bugzilla).
-
-
-
-
-
- CPAN
-
-
-
-
- CPAN
-
- stands for the
- Comprehensive Perl Archive Network.
- CPAN maintains a large number of extremely useful
- Perl
- modules - encapsulated chunks of code for performing a
- particular task.
-
-
-
-
-
- D
-
-
- daemon
-
-
- A daemon is a computer program which runs in the background. In
- general, most daemons are started at boot time via System V init
- scripts, or through RC scripts on BSD-based systems.
- mysqld,
- the MySQL server, and
- apache,
- a web server, are generally run as daemons.
-
-
-
-
-
- G
-
-
- Groups
-
-
- The word
- Groups
-
- has a very special meaning to Bugzilla. Bugzilla's main security
- mechanism comes by placing users in groups, and assigning those
- groups certain privileges to view bugs in particular
- Products
- in the
- Bugzilla
- database.
-
-
-
-
-
- J
-
-
- JavaScript
-
- JavaScript is cool, we should talk about it.
-
-
-
-
-
-
- M
-
-
- Message Transport Agent
- MTA
-
-
- A Message Transport Agent is used to control the flow of email
- on a system. Many unix based systems use
- sendmail which is what
- Bugzilla expects to find by default at /usr/sbin/sendmail.
- Many other MTA's will work, but they all require that the
- param be set to on.
-
-
-
-
-
- MySQL
-
-
- MySQL is currently the required
- RDBMS for Bugzilla. MySQL
- can be downloaded from . While you
- should familiarize yourself with all of the documentation, some high
- points are:
-
-
-
- Backup
-
- Methods for backing up your Bugzilla database.
-
-
-
-
- Option Files
-
- Information about how to configure MySQL using
- my.cnf.
-
-
-
-
- Privilege System
-
- Much more detailed information about the suggestions in
- .
-
-
-
-
-
-
-
-
-
- P
-
-
- Product
-
-
- A Product is a broad category of types of bugs, normally
- representing a single piece of software or entity. In general,
- there are several Components to a Product. A Product may define a
- group (used for security) for all bugs entered into
- its Components.
-
-
-
-
- Perl
-
-
- First written by Larry Wall, Perl is a remarkable program
- language. It has the benefits of the flexibility of an interpreted
- scripting language (such as shell script), combined with the speed
- and power of a compiled language, such as C.
- Bugzilla
-
- is maintained in Perl.
-
-
-
-
-
- Q
-
-
- QA
-
-
-
- QA,
- Q/A, and
- Q.A.
- are short for
- Quality Assurance.
- In most large software development organizations, there is a team
- devoted to ensuring the product meets minimum standards before
- shipping. This team will also generally want to track the progress of
- bugs over their life cycle, thus the need for the
- QA Contact
-
- field in a bug.
-
-
-
-
-
- R
-
-
- Relational DataBase Managment System
- RDBMS
-
-
- A relational database management system is a database system
- that stores information in tables that are related to each other.
-
-
-
-
-
-
- S
-
-
-
- SGML
-
-
-
-
- SGML
-
- stands for
- Standard Generalized Markup Language.
- Created in the 1980's to provide an extensible means to maintain
- documentation based upon content instead of presentation,
- SGML
-
- has withstood the test of time as a robust, powerful language.
-
- XML
-
-
- is the
- baby brother
-
- of SGML; any valid
- XML
-
- document it, by definition, a valid
- SGML
-
- document. The document you are reading is written and maintained in
- SGML,
- and is also valid
- XML
-
- if you modify the Document Type Definition.
-
-
-
-
-
- T
-
-
- Target Milestone
-
-
- Target Milestones are Product goals. They are configurable on a
- per-Product basis. Most software development houses have a concept of
-
- milestones
-
- where the people funding a project expect certain functionality on
- certain dates. Bugzilla facilitates meeting these milestones by
- giving you the ability to declare by which milestone a bug will be
- fixed, or an enhancement will be implemented.
-
-
-
-
- Tool Command Language
- TCL
-
- TCL is an open source scripting language available for Windows,
- Macintosh, and Unix based systems. Bugzilla 1.0 was written in TCL but
- never released. The first release of Bugzilla was 2.0, which was when
- it was ported to perl.
-
-
-
-
-
-
- Z
-
-
- Zarro Boogs Found
-
-
- This is just a goofy way of saying that there were no bugs
- found matching your query. When asked to explain this message,
- Terry had the following to say:
-
-
-
- Terry Weissman
- I've been asked to explain this ... way back when, when
- Netscape released version 4.0 of its browser, we had a release
- party. Naturally, there had been a big push to try and fix every
- known bug before the release. Naturally, that hadn't actually
- happened. (This is not unique to Netscape or to 4.0; the same thing
- has happened with every software project I've ever seen.) Anyway,
- at the release party, T-shirts were handed out that said something
- like "Netscape 4.0: Zarro Boogs". Just like the software, the
- T-shirt had no known bugs. Uh-huh.
-
-
- So, when you query for a list of bugs, and it gets no results,
- you can think of this as a friendly reminder. Of *course* there are
- bugs matching your query, they just aren't in the bugsystem yet...
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/sgml/index.sgml b/docs/sgml/index.sgml
deleted file mode 100644
index 3b3516e14..000000000
--- a/docs/sgml/index.sgml
+++ /dev/null
@@ -1,21 +0,0 @@
-
-
diff --git a/docs/sgml/installation.sgml b/docs/sgml/installation.sgml
deleted file mode 100644
index b9fee2cc8..000000000
--- a/docs/sgml/installation.sgml
+++ /dev/null
@@ -1,1615 +0,0 @@
-
-
- Installation
-
-
- Step-by-step Install
-
-
- Introduction
-
- Bugzilla has been successfully installed under Solaris, Linux,
- and Win32. Win32 is not yet officially supported, but many people
- have got it working fine.
- Please see
-
- for further advice on getting Bugzilla to work on Microsoft
- Windows.
-
-
-
-
- Package List
-
-
- If you are running the very most recent
- version of Perl and MySQL (both the executables and development
- libraries) on your system, you can skip these manual installation
- steps for the Perl modules by using Bundle::Bugzilla; see
- .
-
-
-
- The software packages necessary for the proper running of
- Bugzilla (with download links) are:
-
-
-
-
-
- MySQL database server
- (&min-mysql-ver; or greater)
-
-
-
-
-
- Perl
- (&min-perl-ver;, 5.6.1 is recommended if you wish to
- use Bundle::Bugzilla)
-
-
-
-
- Perl Modules (minimum version):
-
-
-
-
- Template
- (v&min-template-ver;)
-
-
-
-
-
-
- File::Temp
- (&min-file-temp-ver;) (Prerequisite for Template)
-
-
-
-
-
- AppConfig
-
- (&min-appconfig-ver;)
-
-
-
-
-
- Text::Wrap
- (&min-text-wrap-ver;)
-
-
-
-
-
- File::Spec
-
- (&min-file-spec-ver;)
-
-
-
-
-
- Data::Dumper
-
- (&min-data-dumper-ver;)
-
-
-
-
-
- DBD::mysql
-
- (&min-dbd-mysql-ver;)
-
-
-
-
-
- DBI
- (&min-dbi-ver;)
-
-
-
-
-
- Date::Parse
-
- (&min-date-format-ver;)
-
-
-
-
-
- CGI
-
- (&min-cgi-ver;)
-
-
-
-
- and, optionally:
-
-
-
- GD
- (&min-gd-ver;) for bug charting
-
-
-
-
-
- GD::Graph
- (&min-gd-graph-ver;) for bug charting
-
-
-
-
-
- GD::Text::Align
- (&min-gd-text-align-ver;) for bug charting
-
-
-
-
-
- Chart::Base
-
- (&min-chart-base-ver;) for bug charting
-
-
-
-
-
- XML::Parser
- (&min-xml-parser-ver;) for the XML interface
-
-
-
-
-
- MIME::Parser
- (&min-mime-parser-ver;) for the email interface
-
-
-
-
-
-
-
-
-
- The web server of your choice.
- Apache
- is highly recommended.
-
-
-
-
-
-
-
- It is a good idea, while installing Bugzilla, to ensure that there
- is some kind of firewall between you and the rest of the Internet,
- because your machine may be insecure for periods during the install.
- Many
- installation steps require an active Internet connection to complete,
- but you must take care to ensure that at no point is your machine
- vulnerable to an attack.
-
-
-
-
-
-
- MySQL
-
- Visit the MySQL homepage at
- www.mysql.com
- to grab and install the latest stable release of the server.
-
-
-
- Many of the binary
- versions of MySQL store their data files in
- /var.
- On some Unix systems, this is part of a smaller root partition,
- and may not have room for your bug database. You can set the data
- directory as an option to configure
- if you build MySQL from source yourself.
-
-
- If you install from something other than an RPM or Debian
- package, you will need to add mysqld
- to your init scripts so the server daemon will come back up whenever
- your machine reboots. Further discussion of UNIX init sequences are
- beyond the scope of this guide.
-
-
- Change your init script to start
- mysqld
- with the ability to accept large packets. By default,
- mysqld
- only accepts packets up to 64K long. This limits the size of
- attachments you may put on bugs. If you add
-
- to the command that starts
- mysqld
- (or safe_mysqld),
- then you will be able to have attachments up to about 1 megabyte.
- There is a Bugzilla parameter for maximum attachment size;
- you should configure it to match the value you choose here.
-
- If you plan on running Bugzilla and MySQL on the same machine,
- consider using the
-
- option in the init script. This enhances security by preventing
- network access to MySQL.
-
-
-
-
- Perl
-
- Any machine that doesn't have Perl on it is a sad machine indeed.
- Perl can be got in source form from
- perl.com for the rare
- *nix systems which don't have it.
- Although Bugzilla runs with perl &min-perl-ver;,
- it's a good idea to be up to the very latest version
- if you can when running Bugzilla. As of this writing, that is Perl
- version &newest-perl-ver;.
-
-
-
- You can skip the following Perl module installation steps by
- installing
- Bundle::Bugzilla
-
- from
- CPAN,
- which installs all required modules for you.
-
-
-
- bash#
-
- perl -MCPAN -e 'install "Bundle::Bugzilla"'
-
-
-
- Bundle::Bugzilla doesn't include GD, Chart::Base, or
- MIME::Parser, which are not essential to a basic Bugzilla install. If
- installing this bundle fails, you should install each module
- individually to isolate the problem.
-
-
-
-
- Perl Modules
-
-
- All Perl modules can be found on the
- Comprehensive Perl
- Archive Network (CPAN). The
- CPAN servers have a real tendency to bog down, so please use mirrors.
-
-
- Quality, general Perl module installation instructions can be
- found on the CPAN website, but the easy thing to do is to just use the
- CPAN shell which does all the hard work for you.
- To use the CPAN shell to install a module:
-
-
-
-
- bash#
- perl -MCPAN -e 'install "<modulename>"'
-
-
-
-
- To do it the hard way:
-
-
- Untar the module tarball -- it should create its own
- directory
-
- CD to the directory just created, and enter the following
- commands:
-
-
-
-
- bash#
-
- perl Makefile.PL
-
-
-
-
-
-
-
- bash#
-
- make
-
-
-
-
-
-
-
- bash#
-
- make test
-
-
-
-
-
-
-
- bash#
-
- make install
-
-
-
-
-
-
-
- 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.
-
-
-
-
- DBI
-
- The DBI module is a generic Perl module used the
- MySQL-related modules. As long as your Perl installation was done
- correctly the DBI module should be a breeze. It's a mixed Perl/C
- module, but Perl's MakeMaker system simplifies the C compilation
- greatly.
-
-
-
- Data::Dumper
-
- The Data::Dumper module provides data structure persistence for
- Perl (similar to Java's serialization). It comes with later
- sub-releases of Perl 5.004, but a re-installation just to be sure it's
- available won't hurt anything.
-
-
-
- MySQL-related modules
-
- The Perl/MySQL interface requires a few mutually-dependent Perl
- modules. These modules are grouped together into the the
- Msql-Mysql-modules package.
-
- The MakeMaker process will ask you a few questions about the
- desired compilation target and your MySQL installation. For most of the
- questions the provided default will be adequate, but when asked if your
- desired target is the MySQL or mSQL packages, you should
- select the MySQL related ones. Later you will be asked if you wish to
- provide backwards compatibility with the older MySQL packages; you
- should answer YES to this question. The default is NO.
-
- A host of 'localhost' should be fine and a testing user of 'test'
- with a null password should find itself with sufficient access to run
- tests on the 'test' database which MySQL created upon installation.
-
-
-
-
- TimeDate modules
-
- Many of the more common date/time/calendar related Perl modules
- have been grouped into a bundle similar to the MySQL modules bundle.
- This bundle is stored on the CPAN under the name TimeDate.
- The component module we're most interested in is the Date::Format
- module, but installing all of them is probably a good idea anyway.
-
-
-
-
- GD (optional)
-
- The GD library was written by Thomas Boutell a long while ago to
- programatically generate images in C. Since then it's become the
- defacto standard for programmatic image construction. The Perl bindings
- to it found in the GD library are used on millions of web pages to
- generate graphs on the fly. That's what Bugzilla will be using it for
- so you must install it if you want any of the graphing to work.
-
-
- The Perl GD library requires some other libraries that may or
- may not be installed on your system, including
- libpng
- and
- libgd.
- The full requirements are listed in the Perl GD library README.
- If compiling GD fails, it's probably because you're
- missing a required library.
-
-
-
-
- Chart::Base (optional)
-
- The Chart module provides Bugzilla with on-the-fly charting
- abilities. It can be installed in the usual fashion after it has been
- fetched from CPAN.
- Note that earlier versions that 0.99c used GIFs, which are no longer
- supported by the latest versions of GD.
-
-
-
- Template Toolkit
-
- When you install Template Toolkit, you'll get asked various
- questions about features to enable. The defaults are fine, except
- that it is recommended you use the high speed XS Stash of the Template
- Toolkit, in order to achieve best performance.
-
-
-
-
-
-
-
- HTTP Server
-
- You have freedom of choice here, pretty much any web server that
- is capable of running CGI
- scripts will work. has more information about
- configuring web servers to work with Bugzilla.
-
-
-
- We strongly recommend Apache as the web server to use. The
- Bugzilla Guide installation instructions, in general, assume you are
- using Apache. If you have got Bugzilla working using another webserver,
- please share your experiences with us.
-
-
-
-
-
- Bugzilla
-
- You should untar the Bugzilla files into a directory that you're
- willing to make writable by the default web server user (probably
- nobody).
- You may decide to put the files in the main web space for your
- web server or perhaps in
- /usr/local
- with a symbolic link in the web space that points to the Bugzilla
- directory.
-
-
- If you symlink the bugzilla directory into your Apache's HTML
- hierarchy, you may receive
- Forbidden
- errors unless you add the
- FollowSymLinks
- directive to the <Directory> entry for the HTML root
- in httpd.conf.
-
-
- Once all the files are in a web accessible directory, make that
- directory writable by your webserver's user. This is a temporary step
- until you run the post-install
- checksetup.pl
- script, which locks down your installation.
-
-
-
- Setting Up the MySQL Database
-
- After you've gotten all the software installed and working you're
- ready to start preparing the database for its life as the back end to
- a high quality bug tracker.
-
- First, you'll want to fix MySQL permissions to allow access from
- Bugzilla. For the purpose of this Installation section, the Bugzilla
- username will be
- bugs, and will have minimal permissions.
-
-
- Begin by giving the MySQL root user a password. MySQL passwords are limited
- to 16 characters.
-
-
-
- bash#
-
- mysql -u root mysql
-
-
-
-
-
- mysql>
-
- UPDATE user SET Password=PASSWORD('<new_password'>)
- WHERE user='root';
-
-
-
-
-
- mysql>
-
- FLUSH PRIVILEGES;
-
-
-
-
- From this point on, if you need to access MySQL as the MySQL root user,
- you will need to use
- mysql -u root -p
-
- and enter <new_password>. Remember that MySQL user names have
- nothing to do with Unix user names (login names).
-
- Next, we use an SQL GRANT command to create a
- bugs
-
- user, and grant sufficient permissions for checksetup.pl, which we'll
- use later, to work its magic. 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.
-
- Remember to set <bugs_password> to some unique password.
-
-
-
- mysql>
-
- GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,
- ALTER,CREATE,DROP,REFERENCES ON bugs.* TO bugs@localhost
- IDENTIFIED BY '<bugs_password>';
-
-
-
-
-
- mysql>
-
- FLUSH PRIVILEGES;
-
-
-
-
-
-
- If you are using MySQL 4, the bugs user also needs to be granted
- the LOCK TABLES and CREATE TEMPORARY TABLES permissions.
-
-
-
-
-
-
- <filename>checksetup.pl</filename>
-
-
- Next, run the magic checksetup.pl script. (Many thanks to
- Holger Schurig
- for writing this script!)
- This script is designed to make sure your MySQL database and other
- configuration options are consistent with the Bugzilla CGI files.
- It will make sure Bugzilla files and directories have reasonable
- permissions, set up the
- data
- directory, and create all the MySQL tables.
-
-
-
- bash#
-
- ./checksetup.pl
-
-
-
-
- The first time you run it, it will create a file called
- localconfig.
-
- This file contains a variety of settings you may need to tweak
- including how Bugzilla should connect to the MySQL database.
-
- The connection settings include:
-
-
- server's host: just use
- localhost
- if the MySQL server is local
-
-
-
- database name:
- bugs
- if you're following these directions
-
-
-
- MySQL username:
- bugs
- if you're following these directions
-
-
-
- Password for the
- bugs
- MySQL account; (<bugs_password>) above
-
-
-
-
- Once you are happy with the settings,
- su to the user
- your web server runs as, and re-run
- checksetup.pl. (Note: on some security-conscious
- systems, you may need to change the login shell for the webserver
- account before you can do this.)
- On this second run, it will create the database and an administrator
- account for which you will be prompted to provide information.
-
-
- The checksetup.pl script is designed so that you can run it at
- any time without causing harm. You should run it after any upgrade to
- Bugzilla.
-
-
-
-
- Configuring Bugzilla
-
- You should run through the parameters on the Edit Parameters page
- (link in the footer) and set them all to appropriate values.
- They key parameters are documented in .
-
-
-
-
-
- Optional Additional Configuration
-
-
- Dependency Charts
-
- As well as the text-based dependency graphs, Bugzilla also
- supports dependency graphing, using a package called 'dot'.
- Exactly how this works is controlled by the 'webdotbase' parameter,
- which can have one of three values:
-
-
-
-
-
-
- A complete file path to the command 'dot' (part of
- GraphViz)
- will generate the graphs locally
-
-
-
-
- A URL prefix pointing to an installation of the webdot package will
- generate the graphs remotely
-
-
-
-
- A blank value will disable dependency graphing.
-
-
-
-
-
- So, to get this working, install
- GraphViz. If you
- do that, you need to
- enable
- server-side image maps in Apache.
- Alternatively, you could set up a webdot server, or use the AT&T
- public webdot server (the
- default for the webdotbase param). Note that AT&T's server won't work
- if Bugzilla is only accessible using HARTS.
-
-
-
-
- Bug Graphs
-
- As long as you installed the GD and Graph::Base Perl modules you
- might as well turn on the nifty Bugzilla bug reporting graphs.
-
- Add a cron entry like this to run
- collectstats.pl
- daily at 5 after midnight:
-
-
-
- bash#
-
- crontab -e
-
-
-
-
- 5 0 * * * cd <your-bugzilla-directory> ;
- ./collectstats.pl
-
-
-
-
- After two days have passed you'll be able to view bug graphs from
- the Bug Reports page.
-
-
-
- The Whining Cron
-
- By now you have a fully functional Bugzilla, but what good are
- bugs if they're not annoying? To help make those bugs more annoying you
- can set up Bugzilla's automatic whining system to complain at engineers
- which leave their bugs in the NEW state without triaging them.
-
-
- This can be done by
- adding the following command as a daily crontab entry (for help on that
- see that crontab man page):
-
-
-
- cd <your-bugzilla-directory> ;
- ./whineatnews.pl
-
-
-
-
-
-
- Depending on your system, crontab may have several manpages.
- The following command should lead you to the most useful page for
- this purpose:
-
-man 5 crontab
-
-
-
-
-
-
- LDAP Authentication
-
-
- This information on using the LDAP
- authentication options with Bugzilla is old, and the authors do
- not know of anyone who has tested it. Approach with caution.
-
-
-
-
-
- The existing authentication
- scheme for Bugzilla uses email addresses as the primary user ID, and a
- password to authenticate that user. All places within Bugzilla where
- you need to deal with user ID (e.g assigning a bug) use the email
- address. The LDAP authentication builds on top of this scheme, rather
- than replacing it. The initial log in is done with a username and
- password for the LDAP directory. This then fetches the email address
- from LDAP and authenticates seamlessly in the standard Bugzilla
- authentication scheme using this email address. If an account for this
- address already exists in your Bugzilla system, it will log in to that
- account. If no account for that email address exists, one is created at
- the time of login. (In this case, Bugzilla will attempt to use the
- "displayName" or "cn" attribute to determine the user's full name.)
- After authentication, all other user-related tasks are still handled by
- email address, not LDAP username. You still assign bugs by email
- address, query on users by email address, etc.
-
-
- Using LDAP for Bugzilla authentication requires the
- Mozilla::LDAP (aka PerLDAP) Perl module. The
- Mozilla::LDAP module in turn requires Netscape's Directory SDK for C.
- After you have installed the SDK, then install the PerLDAP module.
- Mozilla::LDAP and the Directory SDK for C are both
- available for
- download from mozilla.org.
-
-
-
- Set the Param 'useLDAP' to "On" **only** if you will be using an LDAP
- directory for
- authentication. Be very careful when setting up this parameter; if you
- set LDAP authentication, but do not have a valid LDAP directory set up,
- you will not be able to log back in to Bugzilla once you log out. (If
- this happens, you can get back in by manually editing the data/params
- file, and setting useLDAP back to 0.)
-
-
- If using LDAP, you must set the
- three additional parameters: Set LDAPserver to the name (and optionally
- port) of your LDAP server. If no port is specified, it defaults to the
- default port of 389. (e.g "ldap.mycompany.com" or
- "ldap.mycompany.com:1234") Set LDAPBaseDN to the base DN for searching
- for users in your LDAP directory. (e.g. "ou=People,o=MyCompany") uids
- must be unique under the DN specified here. Set LDAPmailattribute to
- the name of the attribute in your LDAP directory which contains the
- primary email address. On most directory servers available, this is
- "mail", but you may need to change this.
-
-
- You can also try using
- OpenLDAP with Bugzilla, using any of a number of administration
- tools. You should apply the patch attached this bug:
-
- http://bugzilla.mozilla.org/show_bug.cgi?id=158630, then set
- the following object classes for your users:
-
-
- objectClass: person
- objectClass: organizationalPerson
- objectClass: inetOrgPerson
- objectClass: top
- objectClass: posixAccount
- objectClass: shadowAccount
-
-
- Please note that this patch has not yet been
- accepted by the Bugzilla team, and so you may need to do some
- manual tweaking. That said, it looks like Net::LDAP is probably
- the way to go in the future.
-
-
-
-
-
- Preventing untrusted Bugzilla content from executing malicious
- Javascript code
-
- It is possible for a Bugzilla to execute malicious Javascript
- code. Due to internationalization concerns, we are unable to
- incorporate the code changes necessary to fulfill the CERT advisory
- requirements mentioned in
-
- http://www.cet.org/tech_tips/malicious_code_mitigation.html/#3.
- Executing the following code snippet from a UNIX command shell will
- rectify the problem if your Bugzilla installation is intended for an
- English-speaking audience. As always, be sure your Bugzilla
- installation has a good backup before making changes, and I recommend
- you understand what the script is doing before executing it.
-
-
-
-bash# perl -pi -e "s/Content-Type\: text\/html/Content-Type\: text\/html\; charset=ISO-8859-1/i" *.cgi *.pl
-
-
-
- All this one-liner command does is search for all instances of
- Content-type: text/html
-
- and replaces it with
- Content-Type: text/html; charset=ISO-8859-1
-
- . This specification prevents possible Javascript attacks on the
- browser, and is suggested for all English-speaking sites. For
- non-English-speaking Bugzilla sites, I suggest changing
- ISO-8859-1, above, to
- UTF-8.
-
-
- Using <meta> tags to set the charset is not
- recommended, as there's a bug in Netscape 4.x which causes pages
- marked up in this way to load twice. See
- bug
- 126266 for more information including progress toward making
- bugzilla charset aware by default.
-
-
-
-
-
-
- <filename>directoryindex</filename> for the Bugzilla default page.
-
-
- You should modify the <DirectoryIndex> parameter for
- the Apache virtual host running your Bugzilla installation to
- allow index.cgi as the index page for a
- directory, as well as the usual index.html,
- index.htm, and so forth.
-
-
-
-
- Bugzilla and <filename>mod_perl</filename>
-
- Bugzilla is unsupported under mod_perl. Effort is underway
- to make it work cleanly in a mod_perl environment, but it is
- slow going.
-
-
-
-
-
- <filename>mod_throttle</filename>
-
- and Security
-
- It is possible for a user, by mistake or on purpose, to access
- the database many times in a row which can result in very slow access
- speeds for other users. If your Bugzilla installation is experiencing
- this problem , you may install the Apache module
- mod_throttle
-
- which can limit connections by ip-address. You may download this module
- at
-
- http://www.snert.com/Software/Throttle/.
- Follow the instructions to install into your Apache install.
- This module only functions with the Apache web
- server!
- You may use the
- ThrottleClientIP
-
- command provided by this module to accomplish this goal. See the
- Module
- Instructions
- for more information.
-
-
-
-
- OS Specific Installation Notes
-
- Many aspects of the Bugzilla installation can be affected by the
- 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 &bzg-bugs;.
-
-
-
- Microsoft Windows
-
- Making Bugzilla work on windows is still a very painful processes.
- The Bugzilla Team is working to make it easier, but that goal is not
- considered a top priority. If you wish to run Bugzilla, we still
- recommend doing so on a Unix based system such as GNU/Linux. As of this
- writing, all members of the Bugzilla team and all known large installations
- run on Unix based systems.
-
-
- If after hearing all that, you have enough pain tolerance to attempt
- installing Bugzilla on Win32, here are some pointers.
-
-
-
-
- Win32 Perl
-
- Perl for Windows can be obtained from ActiveState. You should be
- able to find a compiled binary at http://aspn.activestate.com/ASPN/Downloads/ActivePerl/.
-
-
-
-
- Perl Modules on Win32
-
- Bugzilla on Windows requires the same perl modules found in
- . The main difference is that
- windows uses ppm instead of CPAN.
-
-
-
-C:\perl> ppm <module name>
-
-
-
- The above syntax should work for all modules with the exception
- of Template Toolkit. The Template Toolkit website
- suggests using the instructions on OpenInteract's website.
-
-
-
-
- A complete list of modules that can be installed using ppm can
- be found at http://www.activestate.com/PPMPackages/5.6plus.
-
-
-
-
-
- Code changes required to run on win32
-
- Unfortunately, Bugzilla still doesn't run "out of the box" on
- Windows. There is work in progress to make this easier, but until that
- happens code will have to be modified. This section is an attempt to
- list the required changes. It is an attempt to be all inclusive, but
- there may be other changes required. If you find something is missing,
- please file a bug in &bzg-bugs;.
-
-
-
- Changes to <filename>checksetup.pl</filename>
-
- In checksetup.pl, the line reading:
-
-
-my $mysql_binaries = `which mysql`;
-
- to
-
-my $mysql_binaries = "D:\\mysql\\bin\\mysql";
-
-
- And you'll also need to change:
-
-
-my $webservergid = getgrnam($my_webservergroup)
-
- to
-
-my $webservergid = '8'
-
-
-
-
-
-
- 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 .
- More information on configuring specific web servers can be found in
- .
-
-
-
- If using Apache on windows, you can set the ScriptInterpreterSource
- directive in your Apache config, if you don't do this, you'll have
- to modify the first line of every script to contain your path to
- perl instead of /usr/bin/perl.
-
-
-
-
-
-
-
-
- <productname>Mac OS X</productname>
-
-
- There are a lot of common libraries and utilities out there that
- Apple did not include with Mac OS X, but which run perfectly well on it.
- The GD library, which Bugzilla needs to do bug graphs, is one of
- these.
-
- The easiest way to get a lot of these is with a program called
- Fink, which is similar in nature to the CPAN installer, but installs
- common GNU utilities. Fink is available from
- .
-
- Follow the instructions for setting up Fink. Once it's installed,
- you'll want to run the following as root:
- fink install gd
-
-
- It will prompt you for a number of dependencies, type 'y' and hit
- enter to install all of the dependencies. Then watch it work.
-
- To prevent creating conflicts with the software that Apple installs
- by default, Fink creates its own directory tree at /sw where it installs
- most of the software that it installs. This means your libraries and
- headers for libgd will be at /sw/lib and /sw/include instead of /usr/lib
- and /usr/local/include. Because of these changed locations for the
- libraries, the Perl GD module will not install directly via CPAN, because it
- looks for the specific paths instead of getting them from your
- environment. But there's a way around that :-)
-
- Instead of typing
- install GD
- at the
- cpan>
- prompt, type
- look GD.
- This should go through the motions of downloading the latest version of
- the GD module, then it will open a shell and drop you into the build
- directory. Apply this patch
- to the Makefile.PL file (save the
- patch into a file and use the command
- patch < patchfile.)
-
-
- Then, run these commands to finish the installation of the GD
- module:
-
-
- perl Makefile.PL
-
-
-
- make
-
-
-
- make test
-
-
-
- make install
-
-
- And don't forget to run
- exit
-
- to get back to CPAN.
-
-
-
-
-
-
- Linux-Mandrake 8.0
-
- Linux-Mandrake 8.0 includes every required and optional library
- for Bugzilla. The easiest way to install them is by using the
- urpmi utility. If you follow these commands, you
- should have everything you need for Bugzilla, and
- ./checksetup.pl should not complain about any
- missing libraries. You may already have some of these installed.
-
-
-
-bash#urpmi perl-mysql
-bash#urpmi perl-chart
-bash#urpmi perl-gd
-bash#urpmi perl-MailTools
-bash#urpmi apache-modules
-
-
-
- for Bugzilla e-mail integration
-
-
-
-
-
-
-
-
- HTTP Server Configuration
-
- The Bugzilla Team recommends Apache when using Bugzilla, however, any web server
- that can be configured to run CGI scripts
- should be able to handle Bugzilla. No matter what web server you choose, but
- especially if you choose something other than Apache, you should be sure to read
- .
-
-
- The plan for this section is to eventually document the specifics of how to lock
- down permissions on individual web servers.
-
-
-
- Apache <productname>httpd</productname>
-
- As mentioned above, the Bugzilla Team recommends Apache for use
- with Bugzilla. You will have to make sure that Apache is properly
- configured to run the Bugzilla CGI scripts. You also need to make sure
- that the .htaccess files created by
- ./checksetup.pl (shown in
- for the curious) are allowed to override Apache's normal access
- permissions or else important password information may be exposed to the
- Internet.
-
-
- Many Apache installations are not configured to run scripts
- anywhere but in the cgi-bin
- directory; however, we recommend that Bugzilla not be installed in the
- cgi-bin, otherwise the static
- files such as images and
- will not work correctly. To allow scripts to run in the normal
- web space, the following changes should be made to your
- httpd.conf file.
-
-
- To allow files with a .cgi extension to be run, make sure the
- following line exists and is uncommented:
-
-AddHandler cgi-script .cgi
-
-
- To allow .htaccess files to override
- permissions and .cgi files to run in the Bugzilla directory, make sure
- the following two lines are in a Directory
- directive that applies to the Bugzilla directory on your system
- (either the Bugzilla directory or one of its parents).
-
-
-Options +ExecCGI
-AllowOverride Limit
-
-
-
- For more information on Apache and its directives, see the
- glossary entry on .
-
-
-
-
- <filename>.htaccess</filename> files for Apache
-
- $BUGZILLA_HOME/.htaccess
-
- deny from all
-
-
- allow from all
-
- ]]>
-
-
- $BUGZILLA_HOME/data/.htaccess
-
- allow from all
-
- ]]>
-
-
- $BUGZILLA_HOME/data/webdot
-
- Allow from 192.20.225.10
- Deny from all
-
-
-# Allow access by a local copy of 'dot' to .png, .gif, .jpg, and
-# .map files
-
- Allow from all
-
-
-# And no directory listings, either.
-Deny from all
- ]]>
-
-
- $BUGZILLA_HOME/Bugzilla/.htaccess
-
-# nothing in this directory is retrievable unless overriden by an .htaccess
-# in a subdirectory
-deny from all
-
-
-
- $BUGZILLA_HOME/template/.htaccess
-
-# nothing in this directory is retrievable unless overriden by an .htaccess
-# in a subdirectory
-deny from all
-
-
-
-
-
-
-
-
- Microsoft <productname>Internet Information Services</productname>
-
- If you need, or for some reason even want, to use Microsoft's
- Internet Information Services or
- Personal Web Server you should be able
- to. You will need to configure them to know how to run CGI scripts,
- however. This is described in Microsoft Knowledge Base article
- Q245225
- for Internet Information Services and
- Q231998
- for Personal Web Server.
-
-
- Also, and this can't be stressed enough, make sure that files such as
- localconfig and your data
- directory are secured as described in .
-
-
-
-
-
- AOL Server
-
- Ben FrantzDale reported success using AOL Server with Bugzilla. He
- reported his experience and what appears below is based on that.
-
-
- AOL Server will have to be configured to run
- CGI scripts, please consult
- the documentation that came with your server for more information on
- how to do this.
-
-
- Because AOL Server doesn't support .htaccess
- files, you'll have to create a TCL
- script. You should create an aolserver/modules/tcl/filter.tcl
- file (the filename shouldn't matter) with the following contents (change
- /bugzilla/ to the web-based path to
- your Bugzilla installation):
-
-
-
-ns_register_filter preauth GET /bugzilla/localconfig filter_deny
-ns_register_filter preauth GET /bugzilla/localconfig~ filter_deny
-ns_register_filter preauth GET /bugzilla/\#localconfig\# filter_deny
-ns_register_filter preauth GET /bugzilla/*.pl filter_deny
-ns_register_filter preauth GET /bugzilla/syncshadowdb filter_deny
-ns_register_filter preauth GET /bugzilla/runtests.sh filter_deny
-ns_register_filter preauth GET /bugzilla/data/* filter_deny
-ns_register_filter preauth GET /bugzilla/template/* filter_deny
-
-proc filter_deny { why } {
- ns_log Notice "filter_deny"
- return "filter_return"
-}
-
-
-
- This probably doesn't account for all possible editor backup
- files so you may wish to add some additional variations of
- localconfig. For more information, see
- bug
- 186383 or Bugtraq ID 6501.
-
-
-
-
- If you are using webdot from research.att.com (the default
- configuration for the paramater), you
- will need to allow access to data/webdot/*.dot
- for the reasearch.att.com machine.
-
- If you are using a local installation of GraphViz, you will need to allow
- everybody to access *.png,
- *.gif, *.jpg, and
- *.map in the
- data/webdot directory.
-
-
-
-
-
-
- Troubleshooting
-
- This section gives solutions to common Bugzilla installation
- problems.
-
-
-
- Bundle::Bugzilla makes me upgrade to Perl 5.6.1
-
-
- Try executing perl -MCPAN -e 'install CPAN'
- and then continuing.
-
-
-
- Certain older versions of the CPAN toolset were somewhat naive about how
- to upgrade Perl modules. When a couple of modules got rolled into the core
- Perl distribution for 5.6.1, CPAN thought that the best way to get those
- modules up to date was to haul down the Perl distribution itself and
- build it. Needless to say, this has caused headaches for just about
- everybody. Upgrading to a newer version of CPAN with the
- commandline above should fix things.
-
-
-
-
-
- DBD::Sponge::db prepare failed
-
-
- The following error message may appear due to a bug in DBD::mysql
- (over which the Bugzilla team have no control):
-
-
-
-
-
- To fix this, go to
- <path-to-perl>/lib/DBD/sponge.pm
- in your Perl installation and replace
-
-
-{'NUM_OF_FIELDS'}) {
- $numFields = $attribs->{'NUM_OF_FIELDS'};
- } elsif ($attribs->{'NAME'}) {
- $numFields = @{$attribs->{NAME}};
-]]>
-
-
- by
-
-
-{'NUM_OF_FIELDS'}) {
- $numFields = $attribs->{'NUM_OF_FIELDS'};
- } elsif ($attribs->{'NAMES'}) {
- $numFields = @{$attribs->{NAMES}};
-]]>
-
-
- (note the S added to NAME.)
-
-
-
-
- cannot chdir(/var/spool/mqueue)
-
- If you are installing Bugzilla on SuSE Linux, or some other
- distributions with
- paranoid
- security options, it is possible that the checksetup.pl script may fail
- with the error:
-
-
-
-
- This is because your
- /var/spool/mqueue
- directory has a mode of
- drwx------. Type
- chmod 755
- /var/spool/mqueue
-
- as root to fix this problem.
-
-
-
-
- Your vendor has not defined Fcntl macro O_NOINHERIT
-
- This is caused by a bug in the version of
- File::Temp that is distributed with perl
- 5.6.0. Many minor variations of this error have been reported. Examples
- can be found in .
-
-
-
- Other File::Temp error messages
-
-
-Your vendor has not defined Fcntl macro O_NOINHERIT, used
-at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 208.
-
-Your vendor has not defined Fcntl macro O_EXLOCK, used
-at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 210.
-
-Your vendor has not defined Fcntl macro O_TEMPORARY, used
-at /usr/lib/perl5/site_perl/5.6.0/File/Temp.pm line 233.
-
-
-
- Numerous people have reported that upgrading to version 5.6.1
- or higher solved the problem for them. A less involved fix is to apply
- the patch in . The patch is also
- available as a patch file.
-
-
-
- Patch for File::Temp in Perl 5.6.0
-
-
-
-
-
-
-
-
-
diff --git a/docs/sgml/integration.sgml b/docs/sgml/integration.sgml
deleted file mode 100644
index 1b0489fd9..000000000
--- a/docs/sgml/integration.sgml
+++ /dev/null
@@ -1,101 +0,0 @@
-
-
-
- Integrating Bugzilla with Third-Party Tools
-
-
- Bonsai
-
- Bonsai is a web-based tool for managing
-
-
- . Using Bonsai, administrators can control open/closed status of trees,
- query a fast relational database back-end for change, branch, and comment
- information, and view changes made since the last time the tree was
- closed. Bonsai
- also integrates with
- .
-
-
-
-
- CVS
-
- CVS integration is best accomplished, at this point, using the
- Bugzilla Email Gateway.
-
- Follow the instructions in this Guide for enabling Bugzilla e-mail
- integration. Ensure that your check-in script sends an email to your
- Bugzilla e-mail gateway with the subject of
- [Bug XXXX],
- and you can have CVS check-in comments append to your Bugzilla bug. If
- you want to have the bug be closed automatically, you'll have to modify
- the contrib/bugzilla_email_append.pl script.
-
-
- There is also a CVSZilla project, based upon somewhat dated
- Bugzilla code, to integrate CVS and Bugzilla through CVS' ability to
- email. Check it out at:
-
- http://homepages.kcbbs.gen.nz/~tonyg/.
-
-
-
-
-
- Perforce SCM
-
- You can find the project page for Bugzilla and Teamtrack Perforce
- integration (p4dti) at:
-
- http://www.ravenbrook.com/project/p4dti
-
- .
- p4dti
-
- is now an officially supported product from Perforce, and you can find
- the "Perforce Public Depot" p4dti page at
-
- http://public.perforce.com/public/perforce/p4dti/index.html
-
- .
-
- Integration of Perforce with Bugzilla, once patches are applied, is
- seamless. Perforce replication information will appear below the comments
- of each bug. Be certain you have a matching set of patches for the
- Bugzilla version you are installing. p4dti is designed to support
- multiple defect trackers, and maintains its own documentation for it.
- Please consult the pages linked above for further information.
-
-
-
- Tinderbox/Tinderbox2
-
- We need Tinderbox integration information.
-
-
-
-
-
diff --git a/docs/sgml/introduction.sgml b/docs/sgml/introduction.sgml
deleted file mode 100644
index 33907552b..000000000
--- a/docs/sgml/introduction.sgml
+++ /dev/null
@@ -1,149 +0,0 @@
-
- Introduction
-
-
- What is Bugzilla?
-
-
- Bugzilla is a bug- or issue-tracking system. Bug-tracking
- systems allow individual or groups of developers effectively to keep track
- of outstanding problems with their product.
- Bugzilla was originally
- written by Terry Weissman in a programming language called TCL, to
- replace a rudimentary bug-tracking database used internally by Netscape
- Communications. Terry later ported Bugzilla to Perl from TCL, and in Perl
- it remains to this day. Most commercial defect-tracking software vendors
- at the time charged enormous licensing fees, and Bugzilla quickly became
- a favorite of the open-source crowd (with its genesis in the open-source
- browser project, Mozilla). It is now the de-facto standard
- defect-tracking system against which all others are measured.
-
-
- Bugzilla boasts many advanced features. These include:
-
-
- Powerful searching
-
-
-
- User-configurable email notifications of bug changes
-
-
-
- Full change history
-
-
-
- Inter-bug dependency tracking and graphing
-
-
-
- Excellent attachment management
-
-
-
- Integrated, product-based, granular security schema
-
-
-
- Fully security-audited, and runs under Perl's taint mode
-
-
-
- A robust, stable RDBMS back-end
-
-
-
- Web, XML, email and console interfaces
-
-
-
- Completely customisable and/or localisable web user
- interface
-
-
-
- Extensive configurability
-
-
-
- Smooth upgrade pathway between versions
-
-
-
-
-
-
- Why Should We Use Bugzilla?
-
- For many years, defect-tracking software has remained principally
- the domain of large software development houses. Even then, most shops
- never bothered with bug-tracking software, and instead simply relied on
- shared lists and email to monitor the status of defects. This procedure
- is error-prone and tends to cause those bugs judged least significant by
- developers to be dropped or ignored.
-
- These days, many companies are finding that integrated
- defect-tracking systems reduce downtime, increase productivity, and raise
- customer satisfaction with their systems. Along with full disclosure, an
- open bug-tracker allows manufacturers to keep in touch with their clients
- and resellers, to communicate about problems effectively throughout the
- data management chain. Many corporations have also discovered that
- defect-tracking helps reduce costs by providing IT support
- accountability, telephone support knowledge bases, and a common,
- well-understood system for accounting for unusual system or software
- issues.
-
- But why should
- you
-
- use Bugzilla?
-
- Bugzilla is very adaptable to various situations. Known uses
- currently include IT support queues, Systems Administration deployment
- management, chip design and development problem tracking (both
- pre-and-post fabrication), and software and hardware bug tracking for
- luminaries such as Redhat, NASA, Linux-Mandrake, and VA Systems.
- Combined with systems such as
- CVS,
- Bonsai, or
- Perforce SCM, Bugzilla
- provides a powerful, easy-to-use solution to configuration management and
- replication problems.
-
- Bugzilla can dramatically increase the productivity and
- accountability of individual employees by providing a documented workflow
- and positive feedback for good performance. How many times do you wake up
- in the morning, remembering that you were supposed to do
- something
- today, but you just can't quite remember? Put it in Bugzilla, and you
- have a record of it from which you can extrapolate milestones, predict
- product versions for integration, and follow the discussion trail
- that led to critical decisions.
-
- Ultimately, Bugzilla puts the power in your hands to improve your
- value to your employer or business while providing a usable framework for
- your natural attention to detail and knowledge store to flourish.
-
-
-
-
diff --git a/docs/sgml/patches.sgml b/docs/sgml/patches.sgml
deleted file mode 100644
index 43f816758..000000000
--- a/docs/sgml/patches.sgml
+++ /dev/null
@@ -1,113 +0,0 @@
-
-
- Useful Patches and Utilities for Bugzilla
-
- Are you looking for a way to put your Bugzilla into overdrive? Catch
- some of the niftiest tricks here in this section.
-
-
- Apache
- <filename>mod_rewrite</filename>
-
- magic
-
- Apache's
- mod_rewrite
-
- module lets you do some truly amazing things with URL rewriting. Here are
- a couple of examples of what you can do.
-
-
-
- Make it so if someone types
- http://www.foo.com/12345
-
- , Bugzilla spits back http://www.foo.com/show_bug.cgi?id=12345. Try
- setting up your VirtualHost section for Bugzilla with a rule like
- this:
-
-
-RewriteEngine On
-RewriteRule ^/([0-9]+)$ http://foo.bar.com/show_bug.cgi?id=$1 [L,R]
-
-]]>
-
-
-
- There are many, many more things you can do with mod_rewrite.
- Please refer to the mod_rewrite documentation at
- http://www.apache.org.
-
-
-
-
-
-
- Command-line Bugzilla Queries
-
- There are a suite of Unix utilities for querying Bugzilla from the
- command line. They live in the
- contrib/cmdline
- directory. However, they
- have not yet been updated to work with 2.16 (post-templatisation.).
- There are three files - query.conf,
- buglist and bugs.
-
- query.conf
- contains the mapping from options to field
- names and comparison types. Quoted option names are "grepped" for, so it
- should be easy to edit this file. Comments (#) have no effect; you must
- make sure these lines do not contain any quoted "option".
-
- buglist
- is a shell script which submits a Bugzilla query and writes
- the resulting HTML page to stdout. It supports both short options, (such
- as "-Afoo" or "-Rbar") and long options (such as "--assignedto=foo" or
- "--reporter=bar"). If the first character of an option is not "-", it is
- treated as if it were prefixed with "--default=".
-
- The column list is taken from the COLUMNLIST environment variable.
- This is equivalent to the "Change Columns" option when you list bugs in
- buglist.cgi. If you have already used Bugzilla, grep for COLUMNLIST
- in your cookies file to see your current COLUMNLIST setting.
-
- bugs is a simple shell script which calls
- buglist and extracts the
- bug numbers from the output. Adding the prefix
- "http://bugzilla.mozilla.org/buglist.cgi?bug_id=" turns the bug list into
- a working link if any bugs are found. Counting bugs is easy. Pipe the
- results through
- sed -e 's/,/ /g' | wc | awk '{printf $2 "\n"}'
-
-
- Akkana Peck says she has good results piping
- buglist output through
- w3m -T text/html -dump
-
-
-
-
-
-
-
-
diff --git a/docs/sgml/requiredsoftware.sgml b/docs/sgml/requiredsoftware.sgml
deleted file mode 100644
index f32f0dc2f..000000000
--- a/docs/sgml/requiredsoftware.sgml
+++ /dev/null
@@ -1,88 +0,0 @@
-
-
- Software Download Links
-
- All of these sites are current as of April, 2001. Hopefully they'll
- stay current for a while.
-
- Apache Web Server:
- http://www.apache.org
-
- Optional web server for Bugzilla, but recommended because of broad user
- base and support.
-
- Bugzilla:
-
- http://www.bugzilla.org/
-
-
- MySQL:
- http://www.mysql.com/
-
-
- Perl:
- http://www.perl.org/
-
-
- CPAN:
- http://www.cpan.org/
-
-
- DBI Perl module:
-
- http://www.cpan.org/modules/by-module/DBI/
-
-
- Data::Dumper module:
-
- http://www.cpan.org/modules/by-module/Data/
-
-
- MySQL related Perl modules:
-
- http://www.cpan.org/modules/by-module/Mysql/
-
-
- TimeDate Perl module collection:
-
- http://www.cpan.org/modules/by-module/Date/
-
-
- GD Perl module:
-
- http://www.cpan.org/modules/by-module/GD/
-
- Alternately, you should be able to find the latest version of GD at
- http://www.boutell.com/gd/
-
-
- Chart::Base module:
-
- http://www.cpan.org/modules/by-module/Chart/
-
-
- (But remember, Bundle::Bugzilla will install all the modules for you.)
-
-
-
-
-
diff --git a/docs/sgml/using.sgml b/docs/sgml/using.sgml
deleted file mode 100644
index a3986c27d..000000000
--- a/docs/sgml/using.sgml
+++ /dev/null
@@ -1,580 +0,0 @@
-
-
-
- Using Bugzilla
-
-
- How do I use Bugzilla?
-
- This section contains information for end-users of Bugzilla.
- There is a Bugzilla test installation, called
- Landfill,
- which you are welcome to play with (if it's up.)
- However, it does not necessarily
- have all Bugzilla features enabled, and often runs cutting-edge versions
- of Bugzilla for testing, so some things may work slightly differently
- than mentioned here.
-
-
- Create a Bugzilla Account
-
- If you want to use Bugzilla, first you need to create an account.
- Consult with the administrator responsible for your installation of
- Bugzilla for the URL you should use to access it. If you're
- test-driving Bugzilla, use this URL:
-
- http://landfill.bugzilla.org/bugzilla-tip/
-
-
-
-
- Click the
- Open a new Bugzilla account
-
- link, enter your email address and, optionally, your name in the
- spaces provided, then click
- Create Account
-
- .
-
-
-
- Within moments, you should receive an email to the address
- you provided above, which contains your login name (generally the
- same as the email address), and a password you can use to access
- your account. This password is randomly generated, and can be
- changed to something more memorable.
-
-
-
- Click the
- Log In
- link in the yellow area at the bottom of the page in your browser,
- enter your email address and password into the spaces provided, and
- click
- Login.
-
-
-
-
-
- You are now logged in. Bugzilla uses cookies for authentication
- so, unless your IP address changes, you should not have to log in
- again.
-
-
-
- Anatomy of a Bug
-
- The core of Bugzilla is the screen which displays a particular
- bug. It's a good place to explain some Bugzilla concepts.
-
- Bug 1 on Landfill
-
- is a good example. Note that the labels for most fields are hyperlinks;
- clicking them will take you to context-sensitive help on that
- particular field. Fields marked * may not be present on every
- installation of Bugzilla.
-
-
-
-
- Product and Component:
- Bugs are divided up by Product and Component, with a Product
- having one or more Components in it. For example,
- bugzilla.mozilla.org's "Bugzilla" Product is composed of several
- Components:
-
-
- Administration:
- Administration of a Bugzilla installation.
-
-
- Bugzilla-General:
- Anything that doesn't fit in the other components, or spans
- multiple components.
-
-
- Creating/Changing Bugs:
- Creating, changing, and viewing bugs.
-
-
- Documentation:
- The Bugzilla documentation, including The Bugzilla Guide.
-
-
- Email:
- Anything to do with email sent by Bugzilla.
-
-
- Installation:
- The installation process of Bugzilla.
-
-
- Query/Buglist:
- Anything to do with searching for bugs and viewing the
- buglists.
-
-
- Reporting/Charting:
- Getting reports from Bugzilla.
-
-
- User Accounts:
- Anything about managing a user account from the user's perspective.
- Saved queries, creating accounts, changing passwords, logging in,
- etc.
-
-
- User Interface:
- General issues having to do with the user interface cosmetics (not
- functionality) including cosmetic issues, HTML templates,
- etc.
-
-
-
-
-
-
- Status and Resolution:
-
- These define exactly what state the bug is in - from not even
- being confirmed as a bug, through to being fixed and the fix
- confirmed by Quality Assurance. The different possible values for
- Status and Resolution on your installation should be documented in the
- context-sensitive help for those items.
-
-
-
-
- Assigned To:
- The person responsible for fixing the bug.
-
-
-
-
- *URL:
- A URL associated with the bug, if any.
-
-
-
-
- Summary:
- A one-sentence summary of the problem.
-
-
-
-
- *Status Whiteboard:
- (a.k.a. Whiteboard) A free-form text area for adding short notes
- and tags to a bug.
-
-
-
-
- *Keywords:
- The administrator can define keywords which you can use to tag and
- categorise bugs - e.g. The Mozilla Project has keywords like crash
- and regression.
-
-
-
-
- Platform and OS:
- These indicate the computing environment where the bug was
- found.
-
-
-
-
- Version:
- The "Version" field is usually used for versions of a product which
- have been released, and is set to indicate which versions of a
- Component have the particular problem the bug report is
- about.
-
-
-
-
- Priority:
- The bug assignee uses this field to prioritise his or her bugs.
- It's a good idea not to change this on other people's bugs.
-
-
-
-
- Severity:
- This indicates how severe the problem is - from blocker
- ("application unusable") to trivial ("minor cosmetic issue"). You
- can also use this field to indicate whether a bug is an enhancement
- request.
-
-
-
-
- *Target:
- (a.k.a. Target Milestone) A future version by which the bug is to
- be fixed. e.g. The Bugzilla Project's milestones for future
- Bugzilla versions are 2.18, 2.20, 3.0, etc. Milestones are not
- restricted to numbers, thought - you can use any text strings, such
- as dates.
-
-
-
-
- Reporter:
- The person who filed the bug.
-
-
-
-
- CC list:
- A list of people who get mail when the bug changes.
-
-
-
-
- Attachments:
- You can attach files (e.g. testcases or patches) to bugs. If there
- are any attachments, they are listed in this section.
-
-
-
-
- *Dependencies:
- If this bug cannot be fixed unless other bugs are fixed (depends
- on), or this bug stops other bugs being fixed (blocks), their
- numbers are recorded here.
-
-
-
-
- *Votes:
- Whether this bug has any votes.
-
-
-
-
- Additional Comments:
- You can add your two cents to the bug discussion here, if you have
- something worthwhile to say.
-
-
-
-
-
- Searching for Bugs
-
- The Bugzilla Search page is is the interface where you can find
- any bug report, comment, or patch currently in the Bugzilla system. You
- can play with it here:
-
- landfill.bugzilla.org/bugzilla-tip/query.cgi
-
- .
-
- The Search page has controls for selecting different possible
- values for all of the fields in a bug, as described above. Once you've
- defined a search, you can either run it, or save it as a Remembered
- Query, which can optionally appear in the footer of your pages.
-
- Highly advanced querying is done using Boolean Charts, which have
- their own
-
- context-sensitive help
-
- .
-
-
-
- Bug Lists
-
- If you run a search, a list of matching bugs will be returned.
- The default search is to return all open bugs on the system - don't try
- running this search on a Bugzilla installation with a lot of
- bugs!
-
- The format of the list is configurable. For example, it can be
- sorted by clicking the column headings. Other useful features can be
- accessed using the links at the bottom of the list:
-
-
- Long Format:
-
- this gives you a large page with a non-editable summary of the fields
- of each bug.
-
-
- Change Columns:
-
- change the bug attributes which appear in the list.
-
-
- Change several bugs at once:
-
- If your account is sufficiently empowered, you can make the same
- change to all the bugs in the list - for example, changing their
- owner.
-
-
- Send mail to bug owners:
-
- Sends mail to the owners of all bugs on the list.
-
-
- Edit this query:
-
- If you didn't get exactly the results you were looking for, you can
- return to the Query page through this link and make small revisions
- to the query you just made so you get more accurate results.
-
-
-
-
-
- Filing Bugs
-
- Years of bug writing experience has been distilled for your
- reading pleasure into the
-
- Bug Writing Guidelines.
- While some of the advice is Mozilla-specific, the basic principles of
- reporting Reproducible, Specific bugs, isolating the Product you are
- using, the Version of the Product, the Component which failed, the
- Hardware Platform, and Operating System you were using at the time of
- the failure go a long way toward ensuring accurate, responsible fixes
- for the bug that bit you.
-
- The procedure for filing a test bug is as follows:
-
-
-
- Go to
-
- Landfill
- in your browser and click
-
- Enter a new bug report.
-
-
-
-
- Select a product - any one will do.
-
-
-
- Fill in the fields. Bugzilla should have made reasonable
- guesses, based upon your browser, for the "Platform" and "OS"
- drop-down boxes. If they are wrong, change them.
-
-
-
- Select "Commit" and send in your bug report.
-
-
-
-
-
-
- Hints and Tips
-
- This section distills some Bugzilla tips and best practices
- that have been developed.
-
-
- Autolinkification
- Bugzilla comments are plain text - so posting HTML will result
- in literal HTML tags rather than being interpreted by a browser.
- However, Bugzilla will automatically make hyperlinks out of certain
- sorts of text in comments. For example, the text
- http://www.bugzilla.org will be turned into
- http://www.bugzilla.org.
- Other strings which get linkified in the obvious manner are:
-
- bug 12345
- bug 23456, comment 53
- attachment 4321
- mailto:george@example.com
- george@example.com
- ftp://ftp.mozilla.org
- Most other sorts of URL
-
-
-
- A corollary here is that if you type a bug number in a comment,
- you should put the word "bug" before it, so it gets autolinkified
- for the convenience of others.
-
-
-
-
- Quicksearch
-
- Quicksearch is a single-text-box query tool which uses
- metacharacters to indicate what is to be searched. For example, typing
- "foo|bar"
- into Quicksearch would search for "foo" or "bar" in the
- summary and status whiteboard of a bug; adding
- ":BazProduct" would
- search only in that product.
-
-
- You'll find the Quicksearch box on Bugzilla's
- front page, along with a
- Help
- link which details how to use it.
-
-
-
- Comments
-
- If you are changing the fields on a bug, only comment if
- either you have something pertinent to say, or Bugzilla requires it.
- Otherwise, you may spam people unnecessarily with bug mail.
- To take an example: a user can set up their account to filter out messages
- where someone just adds themselves to the CC field of a bug
- (which happens a lot.) If you come along, add yourself to the CC field,
- and add a comment saying "Adding self to CC", then that person
- gets a pointless piece of mail they would otherwise have avoided.
-
-
-
- Don't use sigs in comments. Signing your name ("Bill") is acceptable,
- particularly if you do it out of habit, but full mail/news-style
- four line ASCII art creations are not.
-
-
-
-
- Attachments
-
-
- Use attachments, rather than comments, for large chunks of ASCII data,
- such as trace, debugging output files, or log files. That way, it doesn't
- bloat the bug for everyone who wants to read it, and cause people to
- receive fat, useless mails.
-
-
- Trim screenshots. There's no need to show the whole screen if
- you are pointing out a single-pixel problem.
-
-
- Don't attach simple test cases (e.g. one HTML file, one
- CSS file and an image) as a ZIP file. Instead, upload them in
- reverse order and edit the referring file so that they point to the
- attached files. This way, the test case works immediately
- out of the bug.
-
-
-
-
- Filing Bugs
-
- Try to make sure that everything said in the summary is also
- said in the first comment. Summaries are often updated and this will
- ensure your original information is easily accessible.
-
-
-
- You do not need to put "any" or similar strings in the URL field.
- If there is no specific URL associated with the bug, leave this
- field blank.
-
-
- If you feel a bug you filed was incorrectly marked as a
- DUPLICATE of another, please question it in your bug, not
- the bug it was duped to. Feel free to CC the person who duped it
- if they are not already CCed.
-
-
-
-
-
- User Preferences
-
- Once you have logged in, you can customise various aspects of
- Bugzilla via the "Edit prefs" link in the page footer.
- The preferences are split into four tabs:
-
-
- Account Settings
-
- On this tab, you can change your basic account information,
- including your password, email address and real name. For security
- reasons, in order to change anything on this page you must type your
- current
- password into the
- Password
- field at the top of the page.
- If you attempt to change your email address, a confirmation
- email is sent to both the old and new addresses, with a link to use to
- confirm the change. This helps to prevent account hijacking.
-
-
-
- Email Settings
-
- On this tab you can reduce or increase the amount of email sent
- you from Bugzilla, opting in our out depending on your relationship to
- the bug and the change that was made to it. (Note that you can also do
- client-side filtering using the X-Bugzilla-Reason header which Bugzilla
- adds to all bugmail.)
-
- By entering user email names, delineated by commas, into the
- "Users to watch" text entry box you can receive a copy of all the
- bugmail of other users (security settings permitting.) This powerful
- functionality enables seamless transitions as developers change
- projects or users go on holiday.
-
-
- The ability to watch other users may not be available in all
- Bugzilla installations. If you can't see it, ask your
- administrator.
-
-
-
-
- Page Footer
-
- On the Search page, you can store queries in Bugzilla, so if you
- regularly run a particular query it is just a drop-down menu away.
- Once you have a stored query, you can come
- here to request that it also be displayed in your page footer.
-
-
-
- Permissions
-
- This is a purely informative page which outlines your current
- permissions on this installation of Bugzilla - what product groups you
- are in, and whether you can edit bugs or perform various administration
- functions.
-
-
-
-
-
-
diff --git a/docs/sgml/variants.sgml b/docs/sgml/variants.sgml
deleted file mode 100644
index 3a7fd6743..000000000
--- a/docs/sgml/variants.sgml
+++ /dev/null
@@ -1,123 +0,0 @@
-
-
- Bugzilla Variants and Competitors
-
- I created this section to answer questions about Bugzilla competitors
- and variants, then found a wonderful site which covers an awful lot of what
- I wanted to discuss. Rather than quote it in its entirety, I'll simply
- refer you here:
-
- http://linas.org/linux/pm.html
-
-
-
- Red Hat Bugzilla
-
- Red Hat's old fork of Bugzilla which was based on version 2.8 is now
- obsolete. The newest version in use is based on version 2.17.1 and is in
- the process of being integrated into the main Bugzilla source tree. The
- back-end is modified to work with PostgreSQL instead of MySQL and they have
- custom templates to get their desired look and feel, but other than that it
- is Bugzilla 2.17.1. Dave Lawrence of Red Hat put forth a great deal of
- effort to make sure that the changes he made could be integrated back into
- the main tree.
- Bug
- 98304 exists to track this integration.
-
-
- URL:
-
- http://bugzilla.redhat.com/bugzilla/
-
-
- This section last updated 24 Dec 2002
-
-
-
- Loki Bugzilla (Fenris)
-
- Fenris was a fork from Bugzilla made by Loki Games; when
- Loki went into receivership, it died. While Loki's other code lives on,
- its custodians recommend Bugzilla for future bug-tracker deployments.
-
-
- This section last updated 27 Jul 2002
-
-
-
- Issuezilla
-
- Issuezilla was another fork from Bugzilla, made by collab.net and
- hosted at tigris.org. It is also dead; the primary focus of bug-tracking
- at tigris.org is their Java-based bug-tracker,
- .
-
- This section last updated 27 Jul 2002
-
-
-
- Scarab
-
- Scarab is a new open source bug-tracking system built using Java
- Servlet technology. It is currently at version 1.0 beta 13.
-
- URL:
- http://scarab.tigris.org
-
-
- This section last updated 18 Jan 2003
-
-
-
- Perforce SCM
-
- Although Perforce isn't really a bug tracker, it can be used as
- such through the jobs
- functionality.
-
- URL:
-
- http://www.perforce.com/perforce/technotes/note052.html
-
-
-
- This section last updated 27 Jul 2002
-
-
-
- SourceForge
-
- SourceForge is a way of coordinating geographically
- distributed free software and open source projects over the Internet.
- It has a built-in bug tracker, but it's not highly thought of.
-
- URL:
-
- http://www.sourceforge.net
-
-
- This section last updated 27 Jul 2002
-
-
-
-
-
--
cgit v1.2.3-24-g4f1b