5930 lines
237 KiB
Plaintext
5930 lines
237 KiB
Plaintext
= The Bugzilla4Intranet Guide - (UNRELEASED)
|
|
|
|
[[about]]
|
|
== About This Guide
|
|
|
|
[[copyright]]
|
|
=== Copyright Information
|
|
|
|
This document is copyright (c) 2000-2014 by the various
|
|
Bugzilla and Bugzilla4Intranet contributors who wrote it.
|
|
|
|
[quote]
|
|
____
|
|
|
|
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 <<gfdl,GFDL>>.
|
|
____
|
|
|
|
If you have any questions regarding this document, its
|
|
copyright, or publishing this document in non-electronic form,
|
|
please contact the Bugzilla Team.
|
|
|
|
[[disclaimer]]
|
|
=== Disclaimer
|
|
|
|
No liability for the contents of this document can be accepted.
|
|
Follow the instructions herein at your own risk.
|
|
This document may contain errors
|
|
and inaccuracies that may damage your system, cause your partner
|
|
to leave you, your boss to fire you, your cats to
|
|
pee on your furniture and clothing, and global thermonuclear
|
|
war. Proceed with caution.
|
|
|
|
Naming of particular products or brands should not be seen as
|
|
endorsements, with the exception of the term "GNU/Linux". We
|
|
wholeheartedly endorse the use of GNU/Linux; it is an extremely
|
|
versatile, stable,
|
|
and robust operating system that offers an ideal operating
|
|
environment for Bugzilla.
|
|
|
|
Although the Bugzilla development team has taken great care to
|
|
ensure that all exploitable bugs have been fixed, security holes surely
|
|
exist in any piece of code. Great care should be taken both in
|
|
the installation and usage of this software. The Bugzilla development
|
|
team members assume no liability for your use of Bugzilla. You have
|
|
the source code, and are responsible for auditing it yourself to ensure
|
|
your security needs are met.
|
|
|
|
[[newversions]]
|
|
=== New Versions
|
|
|
|
This is the (UNRELEASED) version of The Bugzilla4Intranet Guide. It is so named
|
|
to match the current version of Bugzilla4Intranet.
|
|
|
|
The latest version of this guide can always be found at
|
|
http://github.com/vitalif/bugzilla4intranet/tree/beta/docs/en/asciidoc/Bugzilla-Guide.asciidoc.
|
|
However, you should read the version which came with the Bugzilla4Intranet release you are using.
|
|
|
|
[[credits]]
|
|
=== Credits
|
|
|
|
The people listed below have made enormous contributions to the
|
|
creation of this Guide, through their writing, dedicated hacking efforts,
|
|
numerous e-mail and IRC support sessions, and overall excellent
|
|
contribution to the Bugzilla community:
|
|
|
|
Matthew P. Barnson pass:[<email>mbarnson@sisna.com</email>]:: for the Herculean task of pulling together the Bugzilla Guide
|
|
and shepherding it to 2.14.
|
|
|
|
Terry Weissman pass:[<email>terry@mozilla.org</email>]:: for initially writing Bugzilla and creating the README upon
|
|
which the UNIX installation documentation is largely based.
|
|
|
|
Tara Hernandez pass:[<email>tara@tequilarists.org</email>]:: for keeping Bugzilla development going strong after Terry left
|
|
mozilla.org and for running landfill.
|
|
|
|
Dave Lawrence pass:[<email>dkl@redhat.com</email>]:: for providing insight into the key differences between Red
|
|
Hat's customized Bugzilla.
|
|
|
|
Dawn Endico pass:[<email>endico@mozilla.org</email>]:: for being a hacker extraordinaire and putting up with Matthew's
|
|
incessant questions and arguments on irc.mozilla.org in #mozwebtools
|
|
|
|
Jacob Steenhagen pass:[<email>jake@bugzilla.org</email>]:: for taking over documentation during the 2.17 development
|
|
period.
|
|
|
|
Dave Miller pass:[<email>justdave@bugzilla.org</email>]:: for taking over as project lead when Tara stepped down and
|
|
continually pushing for the documentation to be the best it can be.
|
|
|
|
Thanks also go to the following people for significant contributions to this documentation:
|
|
|
|
* Kevin Brannen
|
|
* Vlad Dascalu
|
|
* Ben FrantzDale
|
|
* Eric Hanson
|
|
* Zach Lipton
|
|
* Gervase Markham
|
|
* Andrew Pearson
|
|
* Joe Robins
|
|
* Spencer Smith
|
|
* Ron Teitelbaum
|
|
* Shane Travis
|
|
* Martin Wulffeld
|
|
|
|
Also, thanks are due to the members of the
|
|
link:$$news://news.mozilla.org/mozilla.support.bugzilla$$[mozilla.support.bugzilla]
|
|
newsgroup (and its predecessor, netscape.public.mozilla.webtools).
|
|
Without your discussions, insight, suggestions, and patches,
|
|
this could never have happened.
|
|
|
|
[[conventions]]
|
|
=== Document Conventions
|
|
|
|
This document uses the following conventions:
|
|
|
|
File or directory name:: _filename_
|
|
Command to be typed:: _command_
|
|
Application name:: application
|
|
Normal user's prompt under bash shell:: bash$
|
|
Root user's prompt under bash shell:: bash#
|
|
Normal user's prompt under tcsh shell:: tcsh$
|
|
Environment variables:: VARIABLE
|
|
|
|
----
|
|
Code example
|
|
----
|
|
|
|
== About Bugzilla and Bugzilla4Intranet
|
|
|
|
Bugzilla is a free bug-tracking system that is developed by the Mozilla community.
|
|
While it's actively maintained, it contains a lot of legacy and ugly code, and some features
|
|
that are implemented in a very strange and non-intuitive manner.
|
|
|
|
Bugzilla4Intranet is a highly improved fork of Bugzilla version 3.6.4, which was started
|
|
just as a customised Bugzilla version used internally in link:http://custis.ru/[CUSTIS]
|
|
company. CUSTIS is a Russian company that develops custom-built large-scale information systems
|
|
for banking and trade applications.
|
|
|
|
The amount of changes has quickly become so great and so "fundamental" that starting with 3.6.4,
|
|
the idea of merging with the upstream was rejected and that's when Bugzilla4Intranet
|
|
became a separate project.
|
|
|
|
The ideal goal of Bugzilla4Intranet is being Fast and Customisable. Ideally, no behaviour should
|
|
be hardcoded, no modification of code or templates should be required for customisation or localisation.
|
|
|
|
In this guide, both 'Bugzilla' and 'Bugzilla4Intranet' terms usually refer to Bugzilla4Intranet.
|
|
If something only applies to the 'original Bugzilla', it is stated separately.
|
|
|
|
[[installing-bugzilla]]
|
|
== Installing Bugzilla
|
|
|
|
[[installation]]
|
|
=== Installation
|
|
|
|
[NOTE]
|
|
If you just want to _use_ Bugzilla,
|
|
you do not need to install it. None of this chapter is relevant to
|
|
you. Ask your Bugzilla administrator for the URL to access it from
|
|
your web browser.
|
|
|
|
The Bugzilla server software is usually installed on GNU/Linux or *BSD system.
|
|
If you are installing on another OS, check <<os-specific,OS-Specific Installation Notes>>
|
|
before you start your installation to see if there are any special
|
|
instructions.
|
|
|
|
This guide assumes that you have administrative access to the
|
|
Bugzilla machine. It is also possible to install and run Bugzilla
|
|
without administrative access, although it is usually harder.
|
|
|
|
[WARNING]
|
|
The installation process may make your machine insecure for
|
|
short periods of time. Make sure there is a firewall between you
|
|
and the Internet.
|
|
|
|
You are strongly recommended to make a backup of your system
|
|
before installing Bugzilla (and at regular intervals thereafter :-).
|
|
|
|
In outline, the installation proceeds as follows:
|
|
|
|
<<install-perl5,Install Perl 5>>
|
|
(5.8.1 or above)
|
|
|
|
<<install-database,Install a Database Engine>> (and optionally <<install-sphinx,Sphinx Search>>)
|
|
|
|
<<install-webserver,Install a Webserver>>
|
|
|
|
<<install-bzfiles,Install Bugzilla>>
|
|
|
|
<<install-perlmodules,Install Perl modules>>
|
|
|
|
<<install-MTA,Install a Mail Transfer Agent>>
|
|
(Sendmail 8.7 or above, or an MTA that is Sendmail-compatible with at least this version)
|
|
|
|
Configure all of the above.
|
|
|
|
[[install-perl5]]
|
|
==== Perl 5
|
|
|
|
Installed Version Test:
|
|
----
|
|
perl -v
|
|
----
|
|
|
|
Any machine that doesn't have Perl 5 on it is a sad machine indeed.
|
|
If you don't have it and your OS doesn't provide official packages,
|
|
visit http://www.perl.org. Although Bugzilla should run with Perl 5.8.1,
|
|
it's a good idea to be using the latest stable version.
|
|
|
|
NOTE: Although Windows is not a recommended platform itself,
|
|
we recommend to use link:http://strawberryperl.com/[Strawberry Perl] on it.
|
|
Strawberry Perl contains a working GCC compiler toolchain and a package manager
|
|
that allows to install Perl modules containing native code easily.
|
|
|
|
[[install-database]]
|
|
==== Database Engine
|
|
|
|
Bugzilla supports MySQL/MariaDB, PostgreSQL and Oracle as database servers,
|
|
or SQLite as an embedded SQL database for small or development installations.
|
|
|
|
You only require one of these systems to make use of Bugzilla.
|
|
|
|
[[install-mysql]]
|
|
===== MySQL or MariaDB
|
|
|
|
MySQL is a popular free and open-source DBMS; MariaDB is an enhanced
|
|
community fork of MySQL started when MySQL company
|
|
has been acquired by Oracle. It's fully compatible with MySQL.
|
|
|
|
Installed Version Test:
|
|
----
|
|
mysql -V
|
|
----
|
|
|
|
If you don't have it and your OS doesn't provide official packages,
|
|
visit http://mariadb.org/ or http://www.mysql.com/.
|
|
|
|
Bugzilla is compatible with any MySQL/MariaDB version 4.1.2 or higher, but the best
|
|
is to use the latest MariaDB version, because it contains more advanced features out-of-the-box.
|
|
|
|
[NOTE]
|
|
Many of the binary versions of MySQL/MariaDB store their data files in _/var_.
|
|
On some systems, this is part of a smaller root partition,
|
|
and may not have room for your bug database. In this case just move
|
|
existing database files to some other place and change
|
|
data directory in your _my.cnf_ configuration file.
|
|
|
|
If you install from something other than a packaging/installation
|
|
system, such as .rpm (Redhat Package), .deb (Debian Package), .exe
|
|
(Windows Executable), or .msi (Microsoft Installer), make sure the MySQL
|
|
server is started when the machine boots.
|
|
|
|
[[install-pg]]
|
|
===== PostgreSQL
|
|
|
|
Installed Version Test:
|
|
----
|
|
psql -V
|
|
----
|
|
|
|
If you don't have it and your OS doesn't provide official packages,
|
|
visit http://www.postgresql.org/. You need PostgreSQL
|
|
version 8.00.0000 or higher.
|
|
|
|
If you install from something other than a packaging/installation
|
|
system, such as .rpm (Redhat Package), .deb (Debian Package), .exe
|
|
(Windows Executable), or .msi (Microsoft Installer), make sure the
|
|
PostgreSQL server is started when the machine boots.
|
|
|
|
[[install-oracle]]
|
|
===== Oracle
|
|
|
|
WARNING: Oracle is not a recommended database for Bugzilla4Intranet.
|
|
It's a closed-source commercial product, it's harded to administer and it
|
|
doesn't offer any real advantage over MySQL or PostgreSQL for Bugzilla.
|
|
Moreover, there are some MySQL-specific features in Bugzilla and most testing is done on
|
|
MySQL and PostgreSQL installations so while Oracle support should mostly work,
|
|
it may be more buggy than MySQL or PostgreSQL.
|
|
|
|
Installed Version Test:
|
|
----
|
|
select * from v$version
|
|
----
|
|
|
|
(you first have to log in into your DB)
|
|
|
|
If you don't have it and your OS doesn't provide official packages,
|
|
visit http://www.oracle.com/. You need Oracle
|
|
version 10.02.0 or higher.
|
|
|
|
If you install from something other than a packaging/installation
|
|
system, such as .rpm (Redhat Package), .deb (Debian Package), .exe
|
|
(Windows Executable), or .msi (Microsoft Installer), make sure the
|
|
Oracle server is started when the machine boots.
|
|
|
|
===== SQLite
|
|
|
|
SQLite is a small and lightweight embedded SQL database library, so it doesn't
|
|
require separate DBMS server.
|
|
|
|
Due to SQLite's link:$$http://sqlite.org/faq.html#q5$$[concurrency limitations]
|
|
we recommend SQLite only for small and development Bugzilla installations.
|
|
|
|
No special configuration is required to run Bugzilla on SQLite, besides
|
|
installing perl `DBD::SQLite` module. The database will be stored in _data/db/$db_name_,
|
|
where `$db_name` is the database name defined in _localconfig_.
|
|
|
|
[[install-sphinx]]
|
|
==== Sphinx Search
|
|
|
|
link:http://sphinxsearch.com[Sphinx Search] is an easy-to-use high-performance full-text
|
|
search server. It's faster (in some cases *much* faster) and gives better search quality
|
|
than the full-text search built into any of the databases Bugzilla may use (especially
|
|
MySQL).
|
|
|
|
Bugzilla4Intranet may use Sphinx for full-text searching. If you want to use it,
|
|
you must install Sphinx server (any version that supports SphinxQL, that is, at least 2.0.1).
|
|
Use official packages of your distribution or visit http://sphinxsearch.com/downloads/.
|
|
|
|
After installing Sphinx, you must enable SphinxQL protocol by adding 'listen'
|
|
directive to the 'searchd' section of your 'sphinx.conf' (usually located in
|
|
'/etc/sphinxsearch' on GNU/Linux), and configure the index for Bugzilla.
|
|
Example configuration is (also provided in 'data/sphinx.conf'):
|
|
|
|
----
|
|
index bugs
|
|
{
|
|
type = rt
|
|
path = /var/lib/sphinxsearch/data/bugs
|
|
rt_field = short_desc
|
|
rt_field = comments
|
|
rt_field = comments_private
|
|
docinfo = extern
|
|
enable_star = 1
|
|
charset_type = utf-8
|
|
charset_table = 0..9, A..Z->a..z, a..z, U+410..U+42F->U+430..U+44F, U+430..U+44F
|
|
blend_chars = _, -, &, +, @, $
|
|
morphology = stem_enru
|
|
min_word_len = 2
|
|
}
|
|
|
|
searchd
|
|
{
|
|
...
|
|
listen = /var/run/sphinxsearch/searchd.sock:mysql41
|
|
...
|
|
}
|
|
----
|
|
|
|
After configuring Sphinx server set '$sphinx_*' variables in your 'localconfig'.
|
|
For the above case it should look like the following:
|
|
|
|
----
|
|
$sphinx_index = 'bugs';
|
|
$sphinx_host = '127.0.0.1';
|
|
$sphinx_port = 0;
|
|
$sphinx_sock = '/var/run/sphinxsearch/searchd.sock';
|
|
----
|
|
|
|
.Installing Sphinx from source
|
|
|
|
To install Sphinx from source, run the following commands:
|
|
|
|
----
|
|
tar -zxf sphinx-<YOUR_VERSION>.tar.gz
|
|
cd sphinx-<YOUR_VERSION>
|
|
./configure --prefix=/usr --sysconfdir=/etc/sphinxsearch --localstatedir=/var --datarootdir=/var/lib/sphinxsearch --enable-id64 --with-libstemmer
|
|
make clean
|
|
make -j4
|
|
sudo make install
|
|
----
|
|
|
|
[[install-webserver]]
|
|
==== Web Server
|
|
|
|
You have several options here:
|
|
|
|
* *Recommended option:* use the pure-perl standalone HTTP server 'HTTPServerSimple.pl'
|
|
supplied with Bugzilla4Intranet installed behind a fast reverse-proxy like link:http://nginx.org[nginx]
|
|
or link:http://lighttpd.net/[lighttpd].
|
|
|
|
* *The simplest way:* Use just 'HTTPServerSimple.pl' without any reverse proxy. It is capable of serving static files,
|
|
so this setup also works, but it may be less secure to have it point directly to the public network
|
|
(because it's of course less tested than nginx or lighttpd). Also note that the standalone server
|
|
doesn't support keepalive so the client will open much more connections which also affects page load speed.
|
|
|
|
* Run Bugzilla inside link:http://httpd.apache.org/[Apache] with link:http://perl.apache.org/[mod_perl].
|
|
This setup should result in roughly the same performance, but usually consumes more memory than the
|
|
standalone server, especially if you have several virtual hosts / web applications in a single Apache instance.
|
|
Sometimes mod_perl usage also results is very strange bugs that don't show up in the bare Perl.
|
|
|
|
* *The worst:* Run Bugzilla using CGI with any webserver capable of running CGI scripts.
|
|
This is the worst option because CGI means Perl must re-initialise all Bugzilla modules on every request
|
|
which usually leads to poor performance.
|
|
|
|
[[install-bzfiles]]
|
|
==== Bugzilla4Intranet
|
|
|
|
You can check out Bugzilla4Intranet from one of these Git repositories:
|
|
|
|
* https://github.com/vitalif/bugzilla-4intranet
|
|
* http://yourcmc.ru/git/summary/bugzilla-4intranet.git
|
|
|
|
Also you can download a release archive from GitHub 'Releases' page: https://github.com/vitalif/bugzilla-4intranet/releases
|
|
or just from a branch: https://github.com/vitalif/bugzilla-4intranet/archive/beta.zip and extract
|
|
it in a suitable directory, accessible by the default web server user
|
|
(in case of Apache, it's usually "httpd", "apache" or "www-data").
|
|
|
|
[CAUTION]
|
|
The Bugzilla distribution is NOT designed to be placed in a _cgi-bin_ directory.
|
|
This includes any directory which is configured using the ScriptAlias directive of Apache.
|
|
|
|
It's not needed (and even _not recommended_) to make Bugzilla files to be writable by your web-server user.
|
|
Although they _must_ be readable by it and you may even leave them world-readable - that's no problem
|
|
because _checksetup.pl_ will take care of setting correct permissions to sensitive files and to files
|
|
that Bugzilla needs to write (mainly _data/_ directory). But you should run _checksetup.pl_ as
|
|
the user that is a member of the web-server group (or a superuser) so it could change group on these files.
|
|
|
|
[[install-perlmodules]]
|
|
==== Perl Modules
|
|
|
|
Bugzilla's installation process is based on a script called _checksetup.pl_.
|
|
The first thing it checks is whether you have appropriate versions of all the required
|
|
Perl modules. The aim of this section is to pass this check.
|
|
When it passes, proceed to <<configuration,Configuration>>.
|
|
|
|
To check you have the required modules, run:
|
|
|
|
----
|
|
bash# ./checksetup.pl --check-modules
|
|
----
|
|
|
|
_checksetup.pl_ will print out a list of the required and optional Perl modules,
|
|
together with the versions (if any) installed on your machine. The list of required
|
|
modules is reasonably long; however, you may already have several of them installed.
|
|
|
|
The best is to install missing Perl modules system-wise, but this requires root permissions
|
|
(_su_ or _sudo bash_ to root before proceeding).
|
|
|
|
You may install modules using the following methods:
|
|
|
|
. Using the official packages of your operating system or distribution.
|
|
It's *almost certain* that not all modules are available as the official packages,
|
|
at least on GNU/Linux distributions, but you may install the ones that are available
|
|
with the system package manager. Package manager is usually 'yum' or 'zypper' in
|
|
RPM-based GNU/Linux distros, 'apt-get' in Debian GNU/Linux-based systems, and 'ppm'
|
|
(Perl Package Manager) in Windows link:http://www.activestate.com/activeperl[ActivePerl]
|
|
and link:http://strawberryperl.com/[Strawberry Perl] distributions. Package names vary:
|
|
|
|
* For example, in Debian ImageMagick is 'perlmagick' and most other packages
|
|
have names similar to 'libxxx-yyyperl' for 'Xxx::Yyy' perl module.
|
|
* In RPM-based distros, packages are usually named 'perl-Xxx-Yyy'.
|
|
* In PPM, they're usually just 'Xxx-Yyy'.
|
|
|
|
. Using link:http://cpan.org/[CPAN] shell. In fact, you may install all required modules using CPAN.
|
|
To install modules using CPAN shell, run `cpan Module1 Module2...` or `perl -MCPAN -eshell Module1 Module2...`
|
|
command as the root user, where 'Module1', 'Module2' and etc are the required
|
|
modules.
|
|
+
|
|
NOTE: Some of modules (database drivers, GD, ImageMagick and etc) contain native code (C/C++)
|
|
and require a working compiler toolchain, libraries and their development ('-dev' or '-devel') packages to install.
|
|
|
|
. Using the _install-module.pl_ script. In this case just run `perl install-module.pl <modulename>`
|
|
from the Bugzilla installation directory. It basically invokes CPAN, but it's capable
|
|
of installing modules to local Bugzilla directory instead of installing them system-wise.
|
|
|
|
. Manually. In this case see <<install-perlmodules-manual,Manual Installation of Perl Modules>>.
|
|
|
|
[TIP]
|
|
====
|
|
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.
|
|
====
|
|
|
|
Here is a complete list of modules and their minimum versions.
|
|
Some modules have special installation notes, which follow.
|
|
|
|
Required Perl modules:
|
|
|
|
include::../../required-modules.asciidoc[]
|
|
|
|
Optional Perl modules:
|
|
|
|
include::../../optional-modules.asciidoc[]
|
|
|
|
[[install-MTA]]
|
|
==== Mail Transfer Agent (MTA)
|
|
|
|
Bugzilla is dependent on the availability of an e-mail system for its
|
|
user authentication and for other tasks.
|
|
|
|
[NOTE]
|
|
====
|
|
This is not entirely true. It is possible to completely disable
|
|
email sending, or to have Bugzilla store email messages in a
|
|
file instead of sending them. However, this is mainly intended
|
|
for testing, as disabling or diverting email on a production
|
|
machine would mean that users could miss important events (such
|
|
as bug changes or the creation of new accounts).
|
|
|
|
For more information, see the "mail_delivery_method" parameter
|
|
in <<parameters,Parameters>>.
|
|
====
|
|
|
|
On Linux, any Sendmail-compatible MTA (Mail Transfer Agent) will
|
|
suffice. Sendmail, Postfix, qmail and Exim are examples of common
|
|
MTAs. Sendmail is the original Unix MTA, but the others are easier to
|
|
configure, and therefore many people replace Sendmail with Postfix or
|
|
Exim. They are drop-in replacements, so Bugzilla will not
|
|
distinguish between them.
|
|
|
|
If you are using Sendmail, version 8.7 or higher is required.
|
|
If you are using a Sendmail-compatible MTA, it must be congruent with
|
|
at least version 8.7 of Sendmail.
|
|
|
|
Consult the manual for the specific MTA you choose for detailed
|
|
installation instructions. Each of these programs will have their own
|
|
configuration files where you must configure certain parameters to
|
|
ensure that the mail is delivered properly. They are implemented
|
|
as services, and you should ensure that the MTA is in the auto-start
|
|
list of services for the machine.
|
|
|
|
If a simple mail sent with the command-line 'mail' or 'sendmail -t' program
|
|
succeeds, then Bugzilla should also be fine.
|
|
|
|
[[configuration]]
|
|
=== Configuration
|
|
|
|
[WARNING]
|
|
====
|
|
Poorly-configured MySQL and Bugzilla installations have
|
|
given attackers full access to systems in the past. Please take the
|
|
security parts of these guidelines seriously, even for Bugzilla
|
|
machines hidden away behind your firewall. Be certain to read
|
|
<<security,Security>> for some important security tips.
|
|
====
|
|
|
|
[[localconfig]]
|
|
==== localconfig
|
|
|
|
You should now run _checksetup.pl_ again, this time
|
|
without the +--check-modules+ switch.
|
|
|
|
----
|
|
bash ./checksetup.pl
|
|
----
|
|
|
|
This time, _checksetup.pl_ should tell you that all
|
|
the correct modules are installed and will display a message about, and
|
|
write out a file called, _localconfig_. This file
|
|
contains the default settings for a number of Bugzilla parameters.
|
|
|
|
Load this file in your editor. The only values you _need_ to change are
|
|
database connection details:
|
|
|
|
'$db_driver' :: Name of the database driver you want to use. May be 'mysql', 'pg', 'oracle' or 'sqlite'.
|
|
'$db_host' :: Hostname or IP address on which the database server runs, usually 'localhost' (ignored by SQLite).
|
|
'$db_user' and '$db_password' :: Database user and password to connect as (ignored by SQLite).
|
|
Pick a username and a strong password; you will create this user during the next installation step.
|
|
'$db_name' :: Name of the database Bugzilla should use (database filename in case of SQLite).
|
|
In case of MySQL/PostgreSQL you will create this database during the next installation step.
|
|
+
|
|
NOTE: In Oracle, '$db_name' should actually be
|
|
the SID name of your database (e.g. "XE" if you are using Oracle XE).
|
|
|
|
You may need to change the value of '$webservergroup' if your web server does not
|
|
run in the "apache" group. On Debian, for example, Apache runs in the "www-data" group.
|
|
If you are going to run Bugzilla on a machine where you do not have root or web-server
|
|
group access, you will need to leave _webservergroup_ empty, ignoring the warnings that
|
|
_checksetup.pl_ will subsequently display every time it is run.
|
|
|
|
The other options in the _localconfig_ file are documented by their accompanying comments.
|
|
|
|
[[database-engine]]
|
|
==== Database Server
|
|
|
|
This section deals with configuring your database server for use
|
|
with Bugzilla. Currently, <<mysql,MySQL>>, <<postgresql,PostgreSQL>>
|
|
and <<oracle,Oracle>> are available.
|
|
|
|
SQLite does not require additional configuration.
|
|
|
|
[[database-schema]]
|
|
===== Bugzilla Database Schema
|
|
|
|
The Bugzilla database schema is described in 'Bugzilla/DB/Schema.pm' source file.
|
|
|
|
There is the link:$$http://www.ravenbrook.com/project/p4dti/tool/cgi/bugzilla-schema/$$[Ravenbrook]
|
|
utility which can generate a written description of the schema, but it's now limited to
|
|
Bugzilla 3.4.2 and surely it doesn't know anything about Bugzilla4Intranet. Nevertheless,
|
|
its source is available in link:https://github.com/Ravenbrook/bugzilla-schema[this GitHub repository],
|
|
so you may try to use it by hand on a Bugzilla4Intranet installation.
|
|
|
|
[[mysql]]
|
|
===== MySQL
|
|
|
|
[CAUTION]
|
|
====
|
|
MySQL's default configuration may be insecure.
|
|
We highly recommend to run _$$mysql_secure_installation$$_
|
|
on Linux or the MySQL installer on Windows, and follow the instructions.
|
|
Important points to note are:
|
|
|
|
. Be sure that the root account has a secure password set.
|
|
. Do not create an anonymous account, and if it exists, say "yes" to remove it.
|
|
. If your web server and MySQL server are on the same machine, you should disable the network access.
|
|
====
|
|
|
|
[[mysql-max-allowed-packet]]
|
|
.Allow many comments
|
|
|
|
By default, MySQL will only allow you to insert things into the database that are smaller than 1MB.
|
|
But in the case you use MySQL full-text search, Bugzilla combines all comments
|
|
on a single bug into one field, and the combination of all comments on a single
|
|
bug could in some cases be larger than 1MB.
|
|
|
|
Original Bugzilla also used to store attachments in the DB, but Bugzilla4Intranet
|
|
doesn't do it by default, so max_allowed_packet doesn't affect them.
|
|
|
|
To change MySQL's default, you need to edit your MySQL
|
|
configuration file, which is usually _/etc/my.cnf_
|
|
on Linux. We recommend that you allow at least 4MB packets by
|
|
adding the "max_allowed_packet" parameter to your MySQL
|
|
configuration in the "[mysqld]" section, like this:
|
|
|
|
----
|
|
[mysqld]
|
|
# Allow packets up to 4MB
|
|
max_allowed_packet=4M
|
|
----
|
|
|
|
.Allow small words in full-text indexes
|
|
|
|
By default, words must be at least four characters in length
|
|
in order to be indexed by MySQL's full-text indexes. This causes
|
|
a lot of Bugzilla specific words to be missed, including "cc",
|
|
"ftp" and "uri".
|
|
|
|
MySQL can be configured to index those words by setting the
|
|
ft_min_word_len param to the minimum size of the words to index.
|
|
This can be done by modifying the _/etc/my.cnf_
|
|
according to the example below:
|
|
|
|
----
|
|
[mysqld]
|
|
# Allow small words in full-text indexes
|
|
ft_min_word_len=2
|
|
----
|
|
|
|
Rebuilding the indexes can be done based on documentation found at
|
|
link:$$http://www.mysql.com/doc/en/Fulltext_Fine-tuning.html$$[].
|
|
|
|
[[install-setupdatabase-adduser]]
|
|
.Add a user to MySQL
|
|
|
|
You need to add a new MySQL user for Bugzilla to use
|
|
(It's not safe to have Bugzilla use the MySQL root account).
|
|
You will need the '$db_*' values you set in _localconfig_ in <<localconfig,localconfig>>.
|
|
|
|
We use an SQL _GRANT_ command to create the '$db_user' user. This also restricts him
|
|
to operations within a database called '$db_name', and only allows the account
|
|
to connect from '$db_host' (usually 'localhost'). Modify it to reflect your setup if
|
|
you will be connecting from another machine or as a different user.
|
|
|
|
Run the _mysql_ command-line client and enter:
|
|
|
|
----
|
|
mysql> GRANT ALL PRIVILEGES ON $db_name.* TO '$db_user'@'$db_host' IDENTIFIED BY '$db_pass';
|
|
mysql> FLUSH PRIVILEGES;
|
|
----
|
|
|
|
[[postgresql]]
|
|
===== PostgreSQL
|
|
|
|
.Add a User to PostgreSQL
|
|
|
|
You need to add a new user to PostgreSQL for the Bugzilla
|
|
application to use when accessing the database. The following instructions
|
|
assume the defaults in __localconfig__; if you changed those, you need to modify the commands appropriately. You will
|
|
need the '$db_pass' password you set in _localconfig_ in <<localconfig,localconfig>>.
|
|
|
|
On most systems, to create the user in PostgreSQL, you will need to
|
|
login as the root user, and then
|
|
|
|
----
|
|
bash# su - postgres
|
|
----
|
|
|
|
As the postgres user, you then need to create a new user:
|
|
|
|
----
|
|
bash$ createuser -U postgres -dRSP $db_user
|
|
----
|
|
|
|
When asked for a password, provide the password which will be set as
|
|
'$db_pass' in _localconfig_. The created user will not be a superuser (-S)
|
|
and will not be able to create new users (-R). He will only have the
|
|
ability to create databases (-d).
|
|
|
|
[NOTE]
|
|
If your are running PostgreSQL 8.0, you must replace -dRSP by -dAP.
|
|
|
|
.Configure PostgreSQL
|
|
|
|
Now, you will need to edit _$$pg_hba.conf$$_ which is
|
|
usually located in _/var/lib/pgsql/data/_. In this file,
|
|
you will need to add a new line to it as follows:
|
|
|
|
----
|
|
host all $db_user 127.0.0.1 255.255.255.255 md5
|
|
----
|
|
|
|
This means that for TCP/IP (host) connections, allow connections from
|
|
'127.0.0.1' to 'all' databases on this server from the '$db_user' user, and use
|
|
password authentication (md5) for that user.
|
|
|
|
Now, you will need to restart PostgreSQL, but you will need to fully
|
|
stop and start the server rather than just restarting due to the possibility
|
|
of a change to _postgresql.conf_.
|
|
|
|
[[oracle]]
|
|
===== Oracle
|
|
|
|
.Create a New Tablespace
|
|
|
|
You can use the existing tablespace or create a new one for Bugzilla.
|
|
To create a new tablespace, run the following command:
|
|
|
|
----
|
|
CREATE TABLESPACE bugs
|
|
DATAFILE '$path_to_datafile' SIZE 500M
|
|
AUTOEXTEND ON NEXT 30M MAXSIZE UNLIMITED
|
|
----
|
|
|
|
Here, the name of the tablespace is 'bugs', but you can
|
|
choose another name. '$path_to_datafile' is
|
|
the path to the file containing your database, for instance
|
|
_/u01/app/oracle/oradata/XE/bugzilla.dbf_.
|
|
The initial size of the database file is set in this example to 500 Mb,
|
|
with an increment of 30 Mb everytime we reach the size limit of the file.
|
|
|
|
.Add a User to Oracle
|
|
|
|
The user name and password must match what you set in _localconfig_ ('$db_user' and '$db_pass', respectively).
|
|
Here, we assume that the user name is 'bugs' and the tablespace name is the same as above.
|
|
|
|
----
|
|
CREATE USER bugs
|
|
IDENTIFIED BY "$db_pass"
|
|
DEFAULT TABLESPACE bugs
|
|
TEMPORARY TABLESPACE TEMP
|
|
PROFILE DEFAULT;
|
|
-- GRANT/REVOKE ROLE PRIVILEGES
|
|
GRANT CONNECT TO bugs;
|
|
GRANT RESOURCE TO bugs;
|
|
-- GRANT/REVOKE SYSTEM PRIVILEGES
|
|
GRANT UNLIMITED TABLESPACE TO bugs;
|
|
GRANT EXECUTE ON CTXSYS.CTX_DDL TO bugs;
|
|
----
|
|
|
|
.Configure the Web Server
|
|
|
|
For Oracle database driver to work, you must add ORACLE_HOME and
|
|
LD_LIBRARY_PATH to your web-server environment
|
|
variables. For instance, for Apache and Oracle XE installed into
|
|
'/u01/app/oracle/product/11.2.0/xe', add the following into 'httpd.conf':
|
|
|
|
----
|
|
SetEnv ORACLE_HOME /u01/app/oracle/product/11.2.0/xe
|
|
SetEnv LD_LIBRARY_PATH /u01/app/oracle/product/11.2.0/xe/lib/
|
|
----
|
|
|
|
When this is done, restart your web server.
|
|
|
|
==== checksetup.pl
|
|
|
|
Next, rerun _checksetup.pl_. It reconfirms
|
|
that all the modules are present, and notices the altered
|
|
localconfig file, which it assumes you have edited to your
|
|
satisfaction. It compiles the UI templates,
|
|
connects to the database using the 'bugs'
|
|
user you created and the password you defined, and creates the
|
|
'bugs' database and the tables therein.
|
|
|
|
After that, it asks for details of an administrator account. Bugzilla
|
|
can have multiple administrators - you can create more later - but
|
|
it needs one to start off with.
|
|
Enter the email address of an administrator, his or her full name,
|
|
and a suitable Bugzilla password.
|
|
|
|
_checksetup.pl_ will then finish. You may rerun _checksetup.pl_ at any time if you wish.
|
|
|
|
[[http]]
|
|
==== Web server
|
|
|
|
Configure your web server according to the instructions in the appropriate section.
|
|
To check whether your web server is correctly configured, run
|
|
`perl testserver.pl http://<your-bugzilla-url>`
|
|
from the Bugzilla installation directory. It will perform some checks;
|
|
if OK is displayed for all of them, then your configuration is successful.
|
|
|
|
Regardless of which web server you are using, however, ensure that
|
|
sensitive information is not remotely available by properly applying the access controls in
|
|
<<security-webserver-access,Disabling Remote Access to Bugzilla Configuration Files>>.
|
|
|
|
[[http-standalone]]
|
|
===== Standalone server (HTTPServerSimple.pl)
|
|
|
|
NOTE: *HTTPServerSimple.pl is the recommended way to run Bugzilla.*
|
|
It's a simple pure-perl application that doesn't require an external web server to run.
|
|
it's fast, it's free of mod_perl-specific bugs, it doesn't require Apache to be
|
|
installed, and it consumes less memory than mod_perl or CGI-based setups.
|
|
|
|
The fastest and safest way is to use it with a reverse proxy like
|
|
link:http://nginx.org[nginx] or link:http://lighttpd.net/[lighttpd] so it serves
|
|
static files and proxies all script requests to 'HTTPServerSimple.pl'.
|
|
Refer to the official documentation of these servers for information about
|
|
how to configure them.
|
|
|
|
It's also possible to use the standalone server without a reverse proxy if you
|
|
don't want to use one. In this case just configure 'HTTPServerSimple.pl' to listen
|
|
on '0.0.0.0:80'. However this setup does not allow you to use SSL and even HTTP keepalive,
|
|
and to have a single server for multiple sites or webapplications, because port 80
|
|
is occupied by Bugzilla.
|
|
|
|
.How to configure HTTPServerSimple.pl
|
|
|
|
'HTTPServerSimple.pl' is configured either in the config file or via
|
|
command line options:
|
|
|
|
perl HTTPServerSimple.pl --<OPTION> <VALUE> [CONFIG-FILE]
|
|
|
|
It has reasonable defaults for most options, so the simplest way to run
|
|
it undex Linux/BSD system is:
|
|
|
|
perl HTTPServerSimple.pl --port [HOST:]PORT --user USER --group GROUP
|
|
|
|
Where HOST and PORT are the desired host and port which Bugzilla should listen on,
|
|
and USER and GROUP are the system user/group for running the web server process.
|
|
|
|
Configuration file syntax is also very simple:
|
|
|
|
----
|
|
# Comment
|
|
option value
|
|
----
|
|
|
|
[[standalone-options]]
|
|
.Full list of configuration options
|
|
|
|
port :: TCP port or 'host:port' to listen on. Default '127.0.0.1:8157',
|
|
which means to listen on port 8157 of loopback interface.+
|
|
WARNING: You should leave '127.0.0.1' for setups with a reverse proxy.
|
|
|
|
min_servers, max_servers, min_spare_servers, max_spare_servers ::
|
|
Prefork parameters. The first two parameters specify minumum and maximum
|
|
total count of server processes, the second two specify minimum and maximum
|
|
count of idle server processes ready to handle new requests.
|
|
These usually depend on your load; default is 4-20 total processes with 4-8 idle ones.
|
|
|
|
max_requests :: Each server process is restarted after this number of requests.
|
|
Used to fight memory leaks. Default value is 1000 requests.
|
|
|
|
user, group :: System user and group to run as. *Never* set it to root!
|
|
|
|
log_file :: Path to the log file. Default '/var/log/bugzilla.log'. It must
|
|
be writable by user/group specified in the previous options.
|
|
|
|
log_level :: Log level (0-4). Greater numbers mean more log messages. Default 2.
|
|
|
|
pid_file :: Path to the PID file (file to which the server writes its process ID).
|
|
|
|
background :: Whether to detach from the terminal from which the server is started
|
|
(--background on the command line or 'background 1' in the config file).
|
|
|
|
reload :: Whether to reload Bugzilla modules and scripts on each request
|
|
(used for development, specified similar to the 'background' option).
|
|
|
|
path_parent_regexp :: This regexp is stripped from the beginning of server request URI.
|
|
Specify something here if your Bugzilla installation is not in the root server path.
|
|
|
|
deny_regexp :: HTTP 403 Access Denied is returned to all requests with URI matching this regexp.
|
|
This option has a reasonable default value; usually you should not override it.
|
|
|
|
http_env :: This option is a comma-separated list of environment variables that
|
|
should be taken from the 'X-<name>' request header. For example, for a multiple-database
|
|
setup you may set it to 'http_env PROJECT' and pass 'X-Project' from your reverse proxy.+
|
|
WARNING: You should not use this option without a reverse proxy.
|
|
|
|
preload :: '*.cgi' is specified here by default to reduce server memory usage by
|
|
preloading all Bugzilla scripts into memory 'before' startup, so child processes
|
|
can share memory with the parent one and don't need to load scripts by themselves.
|
|
|
|
.nginx configuration example
|
|
|
|
Example nginx virtual host for reverse-proxying requests to HTTPServerSimple.pl:
|
|
|
|
----
|
|
server {
|
|
listen 80;
|
|
server_name <your-bugzilla-site-name>; # for example my-bugzilla.com
|
|
root <your-bugzilla-installation-directory>; # for example /var/www/bugzilla
|
|
location ~ ^(localconfig|data/(?!webdot/)|.*\.(pm|pl|sh)($|\?)|(/|^)(CVS|\.(ht|svn|hg|bzr|git)).*) {
|
|
deny all;
|
|
}
|
|
location ~ ^/*[^/]+.cgi {
|
|
proxy_pass http://127.0.0.1:8157;
|
|
include proxy_params;
|
|
}
|
|
location /buglist.cgi {
|
|
proxy_pass http://127.0.0.1:8157;
|
|
include proxy_params;
|
|
proxy_buffering off;
|
|
}
|
|
}
|
|
----
|
|
|
|
[[http-apache-mod_perl]]
|
|
===== Bugzilla in Apache using mod_perl
|
|
|
|
mod_perl is an Apache module than allows to run Perl applications as Apache handlers.
|
|
|
|
Apache virtual host configuration for Bugzilla with mod_perl should look like the following:
|
|
|
|
----
|
|
<VirtualHost *:80>
|
|
ServerAdmin <your-email>
|
|
ServerName <your-bugzilla-site-name>
|
|
DocumentRoot <your-bugzilla-installation-directory>
|
|
|
|
PerlOptions +Parent
|
|
PerlOptions +GlobalRequest
|
|
PerlSwitches -T -I<your-bugzilla-installation-directory>
|
|
PerlModule Apache::XMLRPC::Lite
|
|
PerlConfigRequire <your-bugzilla-installation-directory>/mod_perl.pl
|
|
</VirtualHost>
|
|
----
|
|
|
|
You should also set '$webservergroup' variable in your 'localconfig' to
|
|
the group Apache runs as and re-run 'checksetup.pl'.
|
|
|
|
After that restart Apache and Bugzilla should now be running within the mod_perl environment.
|
|
|
|
[NOTE]
|
|
====
|
|
Please bear the following points in mind when looking at using Bugzilla under mod_perl:
|
|
|
|
* mod_perl support in Bugzilla can take up a HUGE amount of RAM. You could be
|
|
looking at 30MB per httpd child, easily, and that's just for a single Bugzilla
|
|
instance without any other web applications.
|
|
Basically, you just need a lot of RAM. The more RAM you can get, the better.
|
|
|
|
* You must run in Apache's Prefork MPM (this is the default). The Worker MPM
|
|
may not work--we haven't tested Bugzilla's mod_perl support under threads.
|
|
(And, in fact, we're fairly sure it _won't_ work.)
|
|
|
|
* Bugzilla4Intranet supports module reload in mod_perl without restart.
|
|
It's mainly useful for development purposes; if you upgrade Bugzilla, you should
|
|
fully restart Apache with `apachectl restart`. To use reload support add the
|
|
following just before `PerlConfigRequire <...>/mod_perl.pl`:
|
|
+
|
|
--
|
|
----
|
|
<Perl>
|
|
$Bugzilla::RELOAD_MODULES = 1;
|
|
$^P |= 0x10;
|
|
</Perl>
|
|
----
|
|
--
|
|
====
|
|
|
|
[[http-apache]]
|
|
===== Bugzilla using CGI
|
|
|
|
The last possibility to run Bugzilla is using any web or application server capable
|
|
of running CGI scripts, for example, Apache, uWSGI, IIS...
|
|
|
|
It's the worst option because CGI means Perl must re-initialise all Bugzilla modules
|
|
on every request which usually leads to poor performance.
|
|
|
|
.Apache with mod_cgi
|
|
|
|
For example, when using Apache mod_cgi, the virtual host config should look like:
|
|
----
|
|
<VirtualHost *:80>
|
|
ServerAdmin <your-email>
|
|
ServerName <your-bugzilla-site-name>
|
|
DocumentRoot <your-bugzilla-installation-directory>
|
|
<Directory <your-bugzilla-installation-directory>>
|
|
AddHandler cgi-script .cgi
|
|
Options -Indexes +ExecCGI
|
|
DirectoryIndex index.cgi
|
|
AllowOverride Limit
|
|
</Directory>
|
|
</VirtualHost>
|
|
----
|
|
|
|
NOTE: On Windows, you may have to also add the ScriptInterpreterSource
|
|
Registry-Strict line, see <<win32-http,Windows specific notes>>.
|
|
|
|
NOTE: If Bugzilla does not actually reside in the DocumentRoot
|
|
directory, but instead has been symbolically linked there, you
|
|
will need to add `+FollowSymLinks` to `Options` line of the Bugzilla
|
|
<Directory> directive.
|
|
|
|
[[http-iis]]
|
|
.CGI with Microsoft Internet Information Services
|
|
|
|
NOTE: Both <<http-apache-mod_perl,mod_perl>> and <<http-standalone,HTTPServerSimple.pl>>
|
|
are available under Windows, so IIS CGI is not a recommended option.
|
|
|
|
If you are running Bugzilla on Windows and choose to use Microsoft's Internet Information Services
|
|
or Personal Web Server you will need to perform a number of other configuration steps as explained below.
|
|
You may also want to refer to the following Microsoft Knowledge Base articles:
|
|
link:$$http://support.microsoft.com/default.aspx?scid=kb;en-us;245225$$[245225]
|
|
"HOW TO: Configure and Test a PERL Script with IIS 4.0, 5.0, and 5.1" (for Internet Information Services) and
|
|
link:$$http://support.microsoft.com/default.aspx?scid=kb;en-us;231998$$[231998]
|
|
"HOW TO: FP2000: How to Use Perl with Microsoft Personal Web
|
|
Server on Windows 95/98" (for Personal Web Server).
|
|
|
|
You will need to create a virtual directory for the Bugzilla
|
|
install. Put the Bugzilla files in a directory that is named
|
|
something _other_ than what you want your end-users accessing.
|
|
That is, if you want your users to access your Bugzilla installation through
|
|
"http://<yourdomainname>/Bugzilla", then do
|
|
_not_ put your Bugzilla files in a directory named "Bugzilla".
|
|
Instead, place them in a different location, and then use the IIS
|
|
Administration tool to create a Virtual Directory named "Bugzilla"
|
|
that acts as an alias for the actual location of the files.
|
|
When creating that virtual directory, make sure you add the
|
|
"Execute (such as ISAPI applications or CGI)" access permission.
|
|
|
|
You will also need to tell IIS how to handle Bugzilla's
|
|
.cgi files. Using the IIS Administration tool again, open up
|
|
the properties for the new virtual directory and select the
|
|
Configuration option to access the Script Mappings. Create an
|
|
entry mapping .cgi to:
|
|
|
|
----
|
|
<full path to perl.exe>\perl.exe -x<full path to Bugzilla> -wT "%s" %s
|
|
----
|
|
|
|
For example:
|
|
|
|
----
|
|
c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
|
|
----
|
|
|
|
NOTE: The ActiveState install may have already created an entry for
|
|
.pl files that is limited to "GET,HEAD,POST". If so, this mapping should be _removed_ as
|
|
Bugzilla's .pl files are not designed to be run via a web server.
|
|
|
|
IIS will also need to know that the index.cgi should be treated
|
|
as a default document. On the Documents tab page of the virtual
|
|
directory properties, you need to add index.cgi as a default
|
|
document type. If you wish, you may remove the other default
|
|
document types for this particular virtual directory, since Bugzilla
|
|
doesn't use any of them.
|
|
|
|
Also, and this can't be stressed enough, make sure that files
|
|
such as _localconfig_ and your _data_ directory are secured as described in
|
|
<<security-webserver-access,Disabling Remote Access to Bugzilla Configuration Files>>.
|
|
|
|
[[install-config-bugzilla]]
|
|
==== Bugzilla
|
|
|
|
Your Bugzilla should now be working. Access
|
|
_http://<your-bugzilla-server>/_ - you should see the Bugzilla
|
|
front page. If not, consult the <<troubleshooting,Troubleshooting section>>.
|
|
|
|
Log in with the administrator account you defined in the last
|
|
_checksetup.pl_ run. You should go through the Parameters page and
|
|
see if there are any you wish to change. The key parameters are documented in <<parameters,Parameters>>;
|
|
you should certainly alter _maintainer_ and __urlbase__; you may also want to alter _cookiepath_ or _requirelogin_.
|
|
|
|
Bugzilla has several optional features which require extra
|
|
configuration. You can read about those in <<extraconfig,Optional Additional Configuration>>.
|
|
|
|
[[extraconfig]]
|
|
=== Optional Additional Configuration
|
|
|
|
Bugzilla has a number of optional features. This section describes how
|
|
to configure or enable them.
|
|
|
|
==== Charts
|
|
|
|
If you have installed the necessary Perl modules you
|
|
can start collecting statistics for the nifty Bugzilla statistics graphs.
|
|
|
|
----
|
|
bash# crontab -e
|
|
----
|
|
|
|
This should bring up the crontab file in your editor.
|
|
Add a cron entry like this to run _collectstats.pl_
|
|
daily at 5 after midnight:
|
|
|
|
----
|
|
5 0 * * * cd <your-bugzilla-directory> ; ./collectstats.pl
|
|
----
|
|
|
|
After two days have passed you'll be able to view bug graphs from
|
|
the Reports page.
|
|
|
|
[[installation-whining]]
|
|
==== Whining
|
|
|
|
As of Bugzilla 2.20, users can configure Bugzilla to regularly annoy
|
|
them at regular intervals, by having Bugzilla execute saved searches
|
|
at certain times and emailing the results to the user. This is known
|
|
as "Whining". The process of configuring Whining is described
|
|
in <<whining,Whining>>, but for it to work a Perl script must be
|
|
executed at regular intervals.
|
|
|
|
This can be done by adding the following command as a daily
|
|
crontab entry, in the same manner as explained above for bug
|
|
graphs. This example runs it every 15 minutes.
|
|
|
|
----
|
|
*/15 * * * * cd <your-bugzilla-directory> ; ./whine.pl
|
|
----
|
|
|
|
NOTE: Whines can be executed as often as every 15 minutes, so if you specify
|
|
longer intervals between executions of whine.pl, some users may not
|
|
be whined at as often as they would expect. Depending on the person,
|
|
this can either be a very Good Thing or a very Bad Thing.
|
|
|
|
[[installation-whining-cron]]
|
|
==== Whining at New Bugs
|
|
|
|
What good are bugs if they're not annoying? To help make them more so you
|
|
can set up Bugzilla's automatic whining system to complain at engineers
|
|
which leave their bugs in the NEW or REOPENED state without triaging them.
|
|
|
|
This can be done by adding the following command as a daily crontab entry,
|
|
in the same manner as explained above for bug graphs. This example runs it at 12.55am.
|
|
|
|
----
|
|
55 0 * * * cd <your-bugzilla-directory> ; ./whineatnews.pl
|
|
----
|
|
|
|
[[multiple-bz-dbs]]
|
|
==== Multiple Bugzilla databases with a single installation
|
|
|
|
The previous instructions referred to a standard installation, with
|
|
one unique Bugzilla database. However, you may want to host several
|
|
distinct installations, without having several copies of the code. This is
|
|
possible by using the PROJECT environment variable. When accessed,
|
|
Bugzilla checks for the existence of this variable, and if present, uses
|
|
its value to check for an alternative configuration file named
|
|
_localconfig.<PROJECT>_ in the same location as
|
|
the default one (__localconfig__). It also checks for
|
|
customized templates in a directory named
|
|
__<PROJECT>__ in the same location as the
|
|
default one (__template/<langcode>__). By default
|
|
this is __template/en/default__ so PROJECT's templates
|
|
would be located at __template/en/PROJECT__.
|
|
|
|
To set up an alternate installation, just export PROJECT=foo before
|
|
running _checksetup.pl_ for the first time. It will
|
|
result in a file called _localconfig.foo_ instead of
|
|
_localconfig_. Edit this file as described above, with
|
|
reference to a new database, and re-run _checksetup.pl_
|
|
to populate it. That's all.
|
|
|
|
Now you have to configure the web server to pass this environment
|
|
variable when accessed via an alternate URL, such as virtual host for
|
|
instance. The following is an example of how you could do it in Apache,
|
|
other Webservers may differ.
|
|
|
|
----
|
|
<VirtualHost 212.85.153.228:80>
|
|
ServerName foo.bar.baz
|
|
SetEnv PROJECT foo
|
|
Alias /bugzilla /var/www/bugzilla
|
|
</VirtualHost>
|
|
----
|
|
|
|
Don't forget to also export this variable before accessing Bugzilla
|
|
by other means, such as cron tasks for instance.
|
|
|
|
NOTE: To use multiple databases with 'HTTPServerSimple.pl'-based install,
|
|
use its <<standalone-options,http_env>> configuration variable.
|
|
|
|
[[os-specific,OS-Specific Installation Notes]]
|
|
=== OS-Specific Installation Notes
|
|
|
|
Many aspects of the Bugzilla installation can be affected by the
|
|
operating system you choose to install it on. Sometimes it can be made
|
|
easier and others more difficult. This section will attempt to help you
|
|
understand both the difficulties of running on specific operating systems
|
|
and the utilities available to make it easier.
|
|
|
|
If you have anything to add or notes for an operating system not
|
|
covered, please file a bug in link:$$https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla&component=Documentation$$[Bugzilla Documentation].
|
|
|
|
[[os-win32]]
|
|
==== Microsoft Windows
|
|
|
|
Making Bugzilla work on Windows is more difficult than making it work on Unix.
|
|
For that reason, we still recommend doing so on a Unix based system such as GNU/Linux.
|
|
That said, if you do want to get Bugzilla running on Windows, you will need to make some
|
|
adjustments.
|
|
|
|
[[win32-perl]]
|
|
===== Win32 Perl
|
|
|
|
There are two main Perl distributions for Windows:
|
|
link:http://strawberryperl.com/[Strawberry Perl] and link:http://www.activestate.com/activeperl[ActivePerl].
|
|
|
|
We recommended to use Strawberry Perl. It's fully open-source, it's easier to use,
|
|
and it contains both working GCC compiler toolchain and a package manager
|
|
that allows to install Perl modules containing native code without problem.
|
|
|
|
[[win32-perl-modules]]
|
|
===== Perl Modules on Win32
|
|
|
|
Bugzilla on Windows requires the same perl modules found in <<install-perlmodules,Perl Modules>>.
|
|
The main difference is that PPM is used on Windows instead of CPAN.
|
|
Both ActivePerl and Strawberry Perl have 'PPM' utility; we highly recommend that you use it.
|
|
|
|
----
|
|
C:\perl> ppm install <module name>
|
|
----
|
|
|
|
[NOTE]
|
|
The PPM repository stores modules in 'packages' that may have
|
|
a slightly different name than the module. If retrieving these
|
|
modules from there, you will need to pay attention to the information
|
|
provided when you run _checksetup.pl_ as it will
|
|
tell you what package you'll need to install.
|
|
|
|
[TIP]
|
|
If you are behind a corporate firewall, you will need to let the
|
|
ActiveState PPM utility know how to get through it to access
|
|
the repositories by setting the HTTP_proxy system environmental
|
|
variable. For more information on setting that variable, see
|
|
the ActiveState documentation.
|
|
|
|
[[win32-http]]
|
|
===== Serving the web pages
|
|
|
|
As is the case on Unix based systems, any web server should be able to handle Bugzilla;
|
|
however, recommended options is still <<http-standalone,HTTPServerSimple.pl>>.
|
|
<<http-apache-mod_perl,mod_perl>> is a little tricky to get running under Windows,
|
|
but it's also possible.
|
|
|
|
No matter what web server you choose, be sure to pay attention to the security notes
|
|
in <<security-webserver-access,Disabling Remote Access to Bugzilla Configuration Files>>.
|
|
More information on configuring specific web servers can be found in <<http,Web server>>.
|
|
|
|
[NOTE]
|
|
====
|
|
The web server looks at _/usr/bin/perl_ to
|
|
call Perl. If you are using Apache on windows, you can set the
|
|
link:$$http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource$$[ScriptInterpreterSource]
|
|
directive in your Apache config file to make it look at the
|
|
right place: insert the line
|
|
|
|
----
|
|
ScriptInterpreterSource Registry-Strict
|
|
----
|
|
|
|
into your _httpd.conf_ file, and create the key
|
|
|
|
----
|
|
HKEY_CLASSES_ROOT\.cgi\Shell\ExecCGI\Command
|
|
----
|
|
|
|
with C:\Perl\bin\perl.exe -T as value (adapt to your
|
|
path if needed) in the registry. When this is done, restart Apache.
|
|
====
|
|
|
|
===== Sending Email
|
|
|
|
To enable Bugzilla to send email on Windows, the server running the
|
|
Bugzilla code must be able to connect to, or act as, an SMTP server.
|
|
|
|
===== Scheduled Tasks (cron)
|
|
|
|
Windows does not have 'cron', but it does have the Task Scheduler, which performs the same duties.
|
|
There are also third-party tools that can be used to implement cron, such as link:$$http://www.nncron.ru/$$[nncron].
|
|
|
|
Task Scheduler is available under 'Control Panel -> Scheduled Tasks -> Add Scheduled Task'.
|
|
|
|
[[os-macosx]]
|
|
==== Mac OS X
|
|
|
|
Making Bugzilla work on Mac OS X requires the following adjustments.
|
|
|
|
[[macosx-sendmail]]
|
|
===== Sendmail
|
|
|
|
In Mac OS X 10.3 and later, link:$$http://www.postfix.org/$$[Postfix]
|
|
is used as the built-in email server. Postfix provides an executable
|
|
that mimics sendmail enough to fool Bugzilla, as long as Bugzilla can
|
|
find it.
|
|
|
|
As of version 2.20, Bugzilla will be able to find the fake
|
|
sendmail executable without any assistance. However, you will have
|
|
to turn on the sendmailnow parameter before you do anything that would
|
|
result in email being sent. For more information, see the description
|
|
of the sendmailnow parameter in <<parameters,Parameters>>.
|
|
|
|
[[macosx-libraries]]
|
|
===== Libraries & Perl Modules on Mac OS X
|
|
|
|
Apple does not include the GD library with Mac OS X. Bugzilla needs this for bug graphs.
|
|
|
|
You can use MacPorts (https://macports.org/), Homebrew (http://brew.sh/) or Fink (http://www.finkproject.org/),
|
|
all of which are similar in nature to the CPAN installer, but install common UNIX programs.
|
|
|
|
Once you have one of them installed, you'll want to use it to install the _gd2_ package.
|
|
|
|
Fink will prompt you for a number of dependencies, type 'y' and hit
|
|
enter to install all of the dependencies and then watch it work. You will
|
|
then be able to use CPAN to install the GD Perl module.
|
|
|
|
[NOTE]
|
|
====
|
|
To prevent creating conflicts with the software that Apple
|
|
installs by default, Fink creates its own directory tree at
|
|
_/sw_ where it installs most of the software that it installs. This means your libraries and headers
|
|
will be at _/sw/lib_ and _/sw/include_ instead of _/usr/lib_ and
|
|
_/usr/include_. When the Perl module config script asks where your _libgd_ is,
|
|
be sure to tell it _/sw/lib_.
|
|
====
|
|
|
|
To install XML::Parser from CPAN, the expat package is needed.
|
|
If you use fink, there is one caveat. Unlike recent versions of
|
|
the GD module, XML::Parser doesn't prompt for the location of the
|
|
required libraries. When using CPAN, you will need to use the following
|
|
command sequence:
|
|
|
|
----
|
|
bash# perl -MCPAN -e'look XML::Parser' <1>
|
|
bash# perl Makefile.PL EXPATLIBPATH=/sw/lib EXPATINCPATH=/sw/include
|
|
bash# make; make test; make install <2>
|
|
bash# exit
|
|
----
|
|
|
|
<1> The look command will download the module and spawn a
|
|
new shell with the extracted files as the current working directory.
|
|
The exit command will return you to your original shell.
|
|
|
|
<2> You should watch the output from these make commands,
|
|
especially "make test" as errors may prevent
|
|
XML::Parser from functioning correctly with Bugzilla.
|
|
|
|
[[nonroot]]
|
|
==== Linux/UNIX (non-root)
|
|
|
|
===== Introduction
|
|
|
|
If you are running a *NIX OS as non-root, either due
|
|
to lack of access (web hosts, for example) or for security
|
|
reasons, this will detail how to install Bugzilla on such
|
|
a setup. It is recommended that you read through the
|
|
<<installation,Installation>>
|
|
first to get an idea on the installation steps required.
|
|
(These notes will reference to steps in that guide.)
|
|
|
|
===== MySQL
|
|
|
|
You may have MySQL installed as root. If you're
|
|
setting up an account with a web host, a MySQL account
|
|
needs to be set up for you. From there, you can create
|
|
the bugs account, or use the account given to you.
|
|
|
|
[WARNING]
|
|
====
|
|
You may have problems trying to set up _GRANT_ permissions to the database.
|
|
If you're using a web host, chances are that you have a
|
|
separate database which is already locked down (or one big
|
|
database with limited/no access to the other areas), but you
|
|
may want to ask your system administrator what the security
|
|
settings are set to, and/or run the _GRANT_ command for you.
|
|
|
|
Also, you will probably not be able to change the MySQL
|
|
root user password (for obvious reasons), so skip that step.
|
|
====
|
|
|
|
.The Custom Configuration Method
|
|
|
|
Create a file .my.cnf in your home directory (using /home/foo in this example) as follows...
|
|
|
|
----
|
|
[mysqld]
|
|
datadir=/home/foo/mymysql
|
|
socket=/home/foo/mymysql/thesock
|
|
skip-networking
|
|
|
|
[mysql]
|
|
socket=/home/foo/mymysql/thesock
|
|
|
|
[safe_mysqld]
|
|
err-log=/home/foo/mymysql/mysql.log
|
|
pid-file=/home/foo/mymysql/mysql.pid
|
|
----
|
|
|
|
.The Custom Built Method
|
|
|
|
You can install MySQL as a not-root, if you really need to.
|
|
Build it with PREFIX set to _/home/foo/mysql_,
|
|
or use pre-installed executables, specifying that you want
|
|
to put all of the data files in _/home/foo/mysql/data_.
|
|
If there is another MySQL server running on the system that you
|
|
do not own, use the -P option to specify a TCP port that is not
|
|
in use.
|
|
|
|
.Starting the Server
|
|
|
|
After your mysqld program is built and any .my.cnf file is
|
|
in place, you must initialize the databases (ONCE).
|
|
|
|
----
|
|
bash$ mysql_install_db
|
|
----
|
|
|
|
Then start the daemon with
|
|
|
|
----
|
|
bash$ mysqld_safe &
|
|
----
|
|
|
|
After you start mysqld the first time, you then connect to
|
|
it as "root" and _GRANT_ permissions to other
|
|
users. (Again, the MySQL root account has nothing to do with
|
|
the *NIX root account.)
|
|
|
|
[NOTE]
|
|
You will need to start the daemons yourself. You can either
|
|
ask your system administrator to add them to system startup files, or
|
|
add a crontab entry that runs a script to check on these daemons
|
|
and restart them if needed.
|
|
|
|
[WARNING]
|
|
Do NOT run daemons or other services on a server without first
|
|
consulting your system administrator! Daemons use up system resources
|
|
and running one may be in violation of your terms of service for any
|
|
machine on which you are a user!
|
|
|
|
===== Perl
|
|
|
|
On the extremely rare chance that you don't have Perl on
|
|
the machine, you will have to build the sources
|
|
yourself. The following commands should get your system
|
|
installed with your own personal version of Perl:
|
|
|
|
----
|
|
bash$ wget http://perl.org/CPAN/src/stable.tar.gz
|
|
bash$ tar zvxf stable.tar.gz
|
|
bash$ cd perl-5.8.1 (or whatever the version of Perl is called)
|
|
bash$ sh Configure -de -Dprefix=/home/foo/perl
|
|
bash$ make && make test && make install
|
|
----
|
|
|
|
Once you have Perl installed into a directory (probably
|
|
in __$$~/perl/bin$$__), you will need to
|
|
install the Perl Modules, described below.
|
|
|
|
[[install-perlmodules-nonroot]]
|
|
===== Perl Modules
|
|
|
|
Installing the Perl modules as a non-root user is accomplished by
|
|
running the _install-module.pl_ script. For more details on this script, see
|
|
link:$$api/install-module.html$$[_install-module.pl_ documentation]
|
|
|
|
===== HTTP Server
|
|
|
|
Ideally, this also needs to be installed as root and
|
|
run under a special web server account. As long as
|
|
the web server will allow the running of *.cgi files outside of a
|
|
cgi-bin, and a way of denying web access to certain files (such as a
|
|
.htaccess file), you should be good in this department.
|
|
|
|
===== Running Apache as Non-Root
|
|
|
|
You can run Apache as a non-root user, but the port will need
|
|
to be set to one above 1024. If you type _httpd -V_,
|
|
you will get a list of the variables that your system copy of httpd
|
|
uses. One of those, namely HTTPD_ROOT, tells you where that
|
|
installation looks for its config information.
|
|
|
|
From there, you can copy the config files to your own home
|
|
directory to start editing. When you edit those and then use the -d
|
|
option to override the HTTPD_ROOT compiled into the web server, you
|
|
get control of your own customized web server.
|
|
|
|
[NOTE]
|
|
You will need to start the daemons yourself. You can either
|
|
ask your system administrator to add them to system startup files, or
|
|
add a crontab entry that runs a script to check on these daemons
|
|
and restart them if needed.
|
|
|
|
===== Bugzilla
|
|
|
|
When you run _./checksetup.pl_ to create
|
|
the _localconfig_ file, it will list the Perl
|
|
modules it finds. If one is missing, go back and double-check the
|
|
module installation from <<install-perlmodules-nonroot,non-root Perl module installation>>,
|
|
then delete the _localconfig_ file and try again.
|
|
|
|
[WARNING]
|
|
====
|
|
One option in _localconfig_ you might have problems with is the web server group. If you can't
|
|
successfully browse to the _index.cgi_ (like a Forbidden error), you may have to relax your permissions,
|
|
and blank out the web server group. Of course, this may pose
|
|
as a security risk. Having a properly jailed shell and/or
|
|
limited access to shell accounts may lessen the security risk, but use at your own risk.
|
|
|
|
If you are running on a system that uses 'suexec' (most shared
|
|
hosting environments do this), you will need to set the _webservergroup_ value in _localconfig_
|
|
to match _your_ primary group, rather than the one the web server runs under.
|
|
====
|
|
|
|
[[upgrade]]
|
|
=== Upgrading to New Releases
|
|
|
|
Upgrading to new Bugzilla4Intranet releases from older Bugzilla4Intranet version
|
|
or from any version of original Bugzilla up to Bugzilla 4.4 is very simple.
|
|
'./checksetup.pl' does all of the database migration for you.
|
|
|
|
The overall process looks like the following: shutdown Bugzilla web server ->
|
|
backup database and files -> update code -> run './checksetup.pl' -> start web server again.
|
|
|
|
During minor upgrades that do not affect database you may even not need to run 'checksetup.pl'
|
|
at all, however it is safer to always run it, regardless of how big the update is.
|
|
You may use 'shutdownhtml' parameter instead of shutting down the whole Bugzilla web server;
|
|
however, it will logout all users who visit Bugzilla while it is active.
|
|
|
|
==== Before You Upgrade
|
|
|
|
Before you start your upgrade, there are a few important steps to take:
|
|
|
|
. Read the Release Notes of the version you're upgrading to, particularly the "Notes for Upgraders" section.
|
|
|
|
. (Optional) View the <<sanitycheck,Sanity Check>> page on your installation before upgrading.
|
|
Problems Sanity Check checks for are non-critical and should not usually affect the upgrade.
|
|
|
|
. Shut down your Bugzilla installation by putting some HTML or
|
|
text in the shutdownhtml parameter (see <<parameters,Parameters>>).
|
|
|
|
. Make a backup of the Bugzilla database. _THIS IS VERY IMPORTANT_. If
|
|
anything goes wrong during the upgrade, your installation
|
|
can be corrupted beyond recovery. Having a backup keeps you safe.
|
|
|
|
[WARNING]
|
|
Upgrading is a one-way process. You cannot "downgrade" an
|
|
upgraded Bugzilla. If you wish to revert to the old Bugzilla
|
|
version for any reason, you will have to restore your database
|
|
from this backup.
|
|
|
|
[WARNING]
|
|
Upgrading original Bugzilla to Bugzilla4Intranet is also a one-way process.
|
|
You *can* upgrade original Bugzilla installations (any version up to 4.4)
|
|
to Bugzilla4Intranet, but you *can not* downgrade Bugzilla4Intranet back to the
|
|
original Bugzilla.
|
|
|
|
Here are some sample commands you could use to backup
|
|
your database, depending on what database system you're
|
|
using. You may have to modify these commands for your
|
|
particular setup.
|
|
|
|
MySQL::: `mysqldump --opt -u bugs -p bugs > bugs.sql`
|
|
|
|
PostgreSQL::: `pg_dump --no-privileges --no-owner -h localhost -U bugs > bugs.sql`
|
|
|
|
SQLite::: Just make a copy 'data/db/<your-database.db>'.
|
|
|
|
==== Getting The New Bugzilla4Intranet
|
|
|
|
Just like when your were doing the initial installation, download a release archive
|
|
or pull and checkout a new version Bugzilla4Intranet from Git repository.
|
|
|
|
To update using Git, run these commands in your bugzilla installation directory:
|
|
----
|
|
bash$ git pull
|
|
bash$ git up v<version>
|
|
----
|
|
|
|
To update using an archive, just extract it to your installation directory overwriting
|
|
all Bugzilla files.
|
|
|
|
[NOTE]
|
|
====
|
|
You should never modify the code or templates of Bugzilla, because otherwise some day
|
|
you may find yourself publishing your own fork, just like we did it with Bugzilla4Intranet :)
|
|
|
|
Instead of making adjustments that change the hardcoded behaviour, better make your change
|
|
configurable and submit it a pull request for Bugzilla4Intranet on link:https://github.com/vitalif/bugzilla4intranet[GitHub]!
|
|
====
|
|
|
|
==== Completing Your Upgrade
|
|
|
|
Now that you have the new Bugzilla code, there are a few final
|
|
steps to complete your upgrade.
|
|
|
|
. If you change installation directory, remember to move your 'data' directory and 'localconfig' file there.
|
|
. If this is a major update, 'checksetup.pl' will warn you about the new configuration variables.
|
|
Review this warning and make appropriate changes.
|
|
+
|
|
--
|
|
[CAUTION]
|
|
If this is a major upgrade (say, 2.22 to 3.0 or similar), running _checksetup.pl_ on
|
|
a large installation (75,000 or more bugs) can take a long time, possibly several hours.
|
|
--
|
|
. Clear any HTML or text that you put into the shutdownhtml parameter, to re-activate Bugzilla.
|
|
|
|
[[upgrade-notifications]]
|
|
==== Automatic Notifications of New Releases
|
|
|
|
Bugzilla 3.0 introduced the ability to automatically notify
|
|
administrators when new releases are available, based on the
|
|
'upgrade_notification' parameter, see <<parameters,Parameters>>.
|
|
|
|
Bugzilla4Intranet is also configured for this auto-notification with its own upgrade channel.
|
|
|
|
Administrators will see these notifications when they access the _index.cgi_
|
|
page, i.e. generally when logging in. Bugzilla will check once per
|
|
day for new releases, unless the parameter is set to "disabled".
|
|
If you are behind a proxy, you may have to set the 'proxy_url' parameter accordingly.
|
|
If the proxy requires authentication, use the 'http://user:pass@proxy_url/' syntax.
|
|
|
|
[[administration]]
|
|
== Administering Bugzilla
|
|
|
|
[[parameters]]
|
|
=== Parameters
|
|
|
|
include::../params.asciidoc[]
|
|
|
|
[[useradmin]]
|
|
=== User Administration
|
|
|
|
[[defaultuser]]
|
|
==== 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.
|
|
|
|
[TIP]
|
|
====
|
|
If you wish to add more administrative users, add them to
|
|
the "admin" group and, optionally, edit other system groups to add the
|
|
entire admin group to those groups (which is the case by default).
|
|
====
|
|
|
|
[[manageusers]]
|
|
==== Managing Other Users
|
|
|
|
[[user-account-search]]
|
|
===== Searching for existing users
|
|
|
|
If you have "editusers" privileges or if you are allowed
|
|
to grant privileges for some groups, the "Users" link
|
|
will appear in the Administration page.
|
|
|
|
The first screen is a search form to search for existing user
|
|
accounts. You can run searches based either on the user ID, real
|
|
name or login name (i.e. the email address, or just the first part
|
|
of the email address if the "emailsuffix" parameter is set).
|
|
The search can be conducted
|
|
in different ways using the listbox to the right of the text entry
|
|
box. You can match by case-insensitive substring (the default),
|
|
regular expression, a _reverse_ regular expression
|
|
match (which finds every user name which does NOT match the regular
|
|
expression), or the exact string if you know exactly who you are
|
|
looking for. The search can be restricted to users who are in a
|
|
specific group. By default, the restriction is turned off.
|
|
|
|
The search returns a list of
|
|
users matching your criteria. User properties can be edited by clicking
|
|
the login name. The Account History of a user can be viewed by clicking
|
|
the "View" link in the Account History column. The Account History
|
|
displays changes that have been made to the user account, the time of
|
|
the change and the user who made the change. For example, the Account
|
|
History page will display details of when a user was added or removed
|
|
from a group.
|
|
|
|
[[createnewusers]]
|
|
===== Creating new users
|
|
|
|
[[self-registration]]
|
|
.Self-registration
|
|
|
|
By default, 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). If you want to disable
|
|
this self-registration, or if you want to restrict who can create his
|
|
own user account, you have to edit the "createemailregexp"
|
|
parameter in the "Configuration" page, see
|
|
<<parameters,Parameters>>.
|
|
|
|
[[user-account-creation]]
|
|
.Accounts created by an administrator
|
|
|
|
Users with "editusers" privileges, such as administrators,
|
|
can create user accounts for other users:
|
|
|
|
. 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".
|
|
|
|
[NOTE]
|
|
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.
|
|
|
|
[[modifyusers]]
|
|
===== Modifying Users
|
|
|
|
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" parameter, 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.
|
|
|
|
* __Bugmail Disabled__:
|
|
Mark this checkbox to disable bugmail and whinemail completely
|
|
for this account. This checkbox replaces the data/nomail file
|
|
which existed in older versions of Bugzilla.
|
|
|
|
* __Disable Text__:
|
|
+
|
|
--
|
|
If you type a non-empty string in this box the user is prevented
|
|
from logging in, or making any changes to bugs via the web interface
|
|
or the email gateway.
|
|
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.
|
|
|
|
Users with disabled accounts will continue to receive
|
|
mail from Bugzilla; furthermore, they will not be able
|
|
to log in themselves to change their own preferences and
|
|
stop it. If you want an account (disabled or active) to
|
|
stop receiving mail, simply check the "Bugmail Disabled" checkbox above.
|
|
|
|
WARNING: Don't disable all the administrator accounts!
|
|
--
|
|
|
|
* __<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.
|
|
|
|
NOTE: The first checkbox gives the user the ability to add and remove
|
|
other users as members of this group. The second checkbox adds the user
|
|
himself as a member of the group.
|
|
|
|
NOTE: System groups listed here grant special permissions to users.
|
|
For more information see <<systemgroups,System Groups>>.
|
|
--
|
|
|
|
[[user-account-deletion]]
|
|
===== Deleting Users
|
|
|
|
If the 'allowuserdeletion' parameter is turned on, then you can also delete user accounts.
|
|
Note that this is most of the time not the best thing to do. If only
|
|
a warning in a yellow box is displayed, then the deletion is safe.
|
|
If a warning is also displayed in a red box, then you won't be able
|
|
to delete the user account - referential integrity checks in the database won't allow this.
|
|
|
|
[[impersonatingusers]]
|
|
==== Impersonating Users
|
|
|
|
There may be times when an administrator would like to do something as
|
|
another user. The _sudo_ feature may be used to do this.
|
|
|
|
NOTE: To use the sudo feature, you must be in the 'bz_sudoers' group. By default, all
|
|
administrators are in this group.
|
|
|
|
If you have access to this feature, you may start a session by
|
|
going to the Edit Users page, searching for a user and clicking on
|
|
their login. You should see a link below their login name titled
|
|
"Impersonate this user". Click on the link. This will take you
|
|
to a page where you will see a description of the feature and
|
|
instructions for using it. After reading the text, simply
|
|
enter the login of the user you would like to impersonate, provide
|
|
a short message explaining why you are doing this, and press the
|
|
button.
|
|
|
|
As long as you are using this feature, everything you do will be done
|
|
as if you were logged in as the user you are impersonating.
|
|
|
|
WARNING: The user you are impersonating will be warned about it by a e-mail
|
|
message from Bugzilla, so do not abuse this feature.
|
|
|
|
[[groups]]
|
|
=== Groups and Group Security
|
|
|
|
Bugzilla permission system is based on the concept of 'Groups' which
|
|
are just sets of specific users.
|
|
|
|
There are two kinds of groups: 'System Groups' and 'Bug Groups'. 'System Groups' just grant their members
|
|
some specific system-wide permissions, while 'Bug Groups' are configured by Bugzilla administrators
|
|
to grant you some per-product or per-bug permissions. Note that several bug groups may be configured
|
|
to restrict access to a single bug; in this case you must be a member _of all of them_ to see that bug.
|
|
These group controls are edited from the product page; see <<product-group-controls,Assigning Group Controls to Products>>
|
|
for more detail.
|
|
|
|
Administrators, or more specifically, members of the 'creategroups' system group, may grant specific
|
|
users or even whole groups a permission to edit the members of any group. This is called
|
|
'Can turn these bits on for other users' on the user list page, and 'Groups That Can Grant Membership in This Group'
|
|
on the group edit page. If a user has the grant option for some group, he'll also be able to include
|
|
specific users into this group or exclude them from it.
|
|
|
|
The whole groups may be included in other groups for easier maintenance. Editing inclusions is also
|
|
done by only the administrators.
|
|
|
|
There are also several global configuration parameters that specify groups for specific features;
|
|
for more information on these parameters, see <<param-groupsecurity,Group Security>>.
|
|
|
|
[NOTE]
|
|
All bugs can always be seen by their 'Assignee' and 'QA Contact', regardless of whether
|
|
or not the bug would typically be viewable by them.
|
|
By default, bugs can also be seen by the Reporter, and by everyone on the CC List.
|
|
Visibility to the Reporter and CC List can be overridden on a per-bug basis by bringing
|
|
up the bug, finding the section that starts with "Users in the roles selected below..."
|
|
and un-checking the box next to either 'Reporter' or 'CC List' (or both).
|
|
|
|
[[systemgroups]]
|
|
==== System Groups
|
|
|
|
admin:: Administrator group. Usually allows to access *all* administrative functions.
|
|
admin_index:: Allows to enter Administration area. *Should not be edited by hand*, granted automatically if you can access any of the administrative functions.
|
|
tweakparams:: Allows to change Bugzilla's Parameters.
|
|
editusers:: Allows to edit or disable users and include/exclude them from *all* groups.
|
|
creategroups:: Allows to create, destroy and edit all groups.
|
|
editclassifications:: Allows to create, destroy and edit classifications.
|
|
editcomponents:: Allows to create, destroy and edit all products, components, versions and milestones.
|
|
editkeywords:: Allows to create, destroy and edit keywords.
|
|
editbugs:: Allows to edit all fields of all bugs the user has access to.
|
|
A user will be only able to comment on a bug if he's not a member of this group and
|
|
not an assignee, QA contact or a reporter of that bug. If he's the reporter, but not the 'editbugs'
|
|
member, he will be able to change anything except assignee, QA, target milestone, priority
|
|
(if 'letsubmitterchoosepriority' parameter is disabled) fields, and except moving the bug between
|
|
different open statuses. If he's the assignee or a QA of a bug, he can always change all aspects of it.
|
|
canconfirm:: Allows to confirm bugs (that is, change their status from an unconfirmed to a confirmed one) or mark them as duplicates.
|
|
bz_canusewhineatothers:: Allows to configure whine reports for other users.
|
|
bz_canusewhines:: Allows to configure whine reports for self.
|
|
bz_sudoers:: Allows to impersonate other users and perform actions as them.
|
|
bz_sudo_protect:: Forbids other users to impersonate you.
|
|
bz_editcheckers:: Allows to edit Predicates ("Correctness Checkers").
|
|
editfields:: Allows to create, destroy and edit properties of bug fields.
|
|
editvalues:: Allows to edit allowed values for all bug fields.
|
|
importxls:: Allows to create or update many bugs at once using Excel and CSV files.
|
|
worktimeadmin:: Allows to register working time for other users and for dates in the past (see "Fix Worktime" link under a bug list).
|
|
editflagtypes:: Allows to create, destroy and edit flag types.
|
|
|
|
[[create-groups]]
|
|
==== Creating Bug Groups
|
|
|
|
To create a new group, follow the steps below:
|
|
|
|
. Select the "Administration" link in the page footer,
|
|
and then select the "Groups" link from the Administration page.
|
|
|
|
. A table of all the existing groups is displayed. To create a new group,
|
|
select the "Add Group" link under the table of existing groups.
|
|
|
|
. Fill the fields and press "Add".
|
|
|
|
. After the new group is created, it can be edited for additional options.
|
|
The "Edit Group" page allows for specifying other groups that should be included
|
|
in this group and which groups should be permitted to add and delete
|
|
users from this group. For more details, see
|
|
<<edit-groups,Editing Groups and Assigning Group Permissions>>.
|
|
|
|
There are five fields to fill out:
|
|
|
|
* *Name* is the group name displayed for users when limitting bugs to a certain set of groups.
|
|
|
|
* *Description* is what will be shown in the bug reports to members of the group where they
|
|
can choose whether the bug will be restricted to others in the same group.
|
|
|
|
* The *Use For Bugs* flag is basically a "Enabled/Disabled" flag. If you uncheck it,
|
|
it will not be possible for users to add bugs to this group, although bugs already
|
|
in the group will remain in it. This flag can be always edited after creating the group.
|
|
|
|
* *User RegExp* is optional, and if filled in, will automatically grant membership to this
|
|
group to anyone with an email address that matches this regular expression (link:http://perldoc.perl.org/perlre.html[Perl regexp] syntax is used).
|
|
+
|
|
--
|
|
NOTE: If their email address changes and no longer matches the regular expression, they
|
|
will be removed from the group. Versions 2.16 and older of Bugzilla did not automatically
|
|
remove users who's email addresses no longer matched the RegExp.
|
|
|
|
WARNING: To automatically add everyone with a e-mail in a given domain to a group,
|
|
specify '@mycompany\.com$' regular expression. Note the '$' in the end is not optional;
|
|
if you don't add it, access will also be granted to 'badperson@mycompany.com.cracker.net'.
|
|
--
|
|
|
|
* *Icon URL* is optional, and is the URL pointing to the icon used to identify the group.
|
|
It may be either a relative URL to the base URL of this installation or an absolute URL.
|
|
This icon will be displayed in comments in bugs besides the name of the author of comments.
|
|
|
|
[[edit-groups]]
|
|
==== Editing Groups and Assigning Group Permissions
|
|
|
|
To access the "Edit Groups" page, select the "Administration" link in the page footer,
|
|
and then select the "Groups" link from the Administration page.
|
|
A table of all the existing groups is displayed. Click on a group name
|
|
you wish to edit or control permissions for.
|
|
|
|
The "Edit Groups" page contains the same five fields present when
|
|
creating a new group. Below that are two additional sections, "Group
|
|
Permissions" and "Mass Remove". The "Mass Remove" option simply removes
|
|
all users from the group who match the regular expression entered. The
|
|
"Group Permissions" section requires further explanation.
|
|
|
|
The "Group Permissions" section on the "Edit Groups" page contains four sets
|
|
of permissions that control the relationship of this group to other
|
|
groups. If the 'usevisibilitygroups' parameter is in use (see
|
|
<<parameters,Parameters>>) two additional sets of permissions are displayed.
|
|
Each set consists of two select boxes. On the left, a select box
|
|
with a list of all existing groups. On the right, a select box listing
|
|
all groups currently selected for this permission setting (this box will
|
|
be empty for new groups). The way these controls allow groups to relate
|
|
to one another is called _inheritance_. Each of the six permissions is described below.
|
|
|
|
_Groups That Are a Member of This Group_::
|
|
Members of any groups selected here will automatically have
|
|
membership in this group. In other words, members of any selected
|
|
group will inherit membership in this group.
|
|
|
|
_Groups That This Group Is a Member Of_::
|
|
Members of this group will inherit membership to any group
|
|
selected here. For example, suppose the group being edited is
|
|
an Admin group. If there are two products (Product1 and Product2)
|
|
and each product has its own group (Group1 and Group2), and the Admin group
|
|
should have access to both products, simply select both Group1 and Group2 here.
|
|
|
|
_Groups That Can Grant Membership in This Group_::
|
|
The members of any group selected here will be able add users
|
|
to this group, even if they themselves are not in this group.
|
|
|
|
_Groups That This Group Can Grant Membership In_::
|
|
Members of this group can add users to any group selected here,
|
|
even if they themselves are not in the selected groups.
|
|
|
|
_Groups That Can See This Group_::
|
|
Members of any selected group can see the users in this group.
|
|
This setting is only visible if the 'usevisibilitygroups' parameter
|
|
is enabled on the Bugzilla Configuration page. See
|
|
<<parameters,Parameters>> for information on configuring Bugzilla.
|
|
|
|
_Groups That This Group Can See_::
|
|
Members of this group can see members in any of the selected groups.
|
|
This setting is only visible if the 'usevisibilitygroups' parameter
|
|
is enabled on the the Bugzilla Configuration page. See
|
|
<<parameters,Parameters>> for information on configuring Bugzilla.
|
|
|
|
[[users-and-groups]]
|
|
==== Assigning Users to Groups
|
|
|
|
A User can become a member of a group in several ways:
|
|
|
|
. The user can be explicitly placed in the group by editing
|
|
the user's profile. This can be done by accessing the "Users" page
|
|
from the "Administration" page. Use the search form to find the user
|
|
you want to edit group membership for, and click on their email
|
|
address in the search results to edit their profile. The profile
|
|
page lists all the groups, and indicates if the user is a member of
|
|
the group either directly or indirectly. More information on indirect
|
|
group membership is below. For more details see <<useradmin,User Administration>>.
|
|
|
|
. The group can include another group of which the user is
|
|
a member. This is indicated by square brackets around the checkbox
|
|
next to the group name in the user's profile.
|
|
See <<edit-groups,Editing Groups and Assigning Group Permissions>> for details on group inheritance.
|
|
|
|
. The user's email address can match the regular expression
|
|
that has been specified to automatically grant membership to
|
|
the group. This is indicated by "*" around the check box by the
|
|
group name in the user's profile.
|
|
See <<create-groups,Creating Groups>> for details on
|
|
the regular expression option when creating groups.
|
|
|
|
==== Assigning Group Controls to Products
|
|
|
|
The primary functionality of groups is derived from the relationship of
|
|
groups to products. The concepts around segregating access to bugs with
|
|
product group controls can be confusing. For details and examples on this
|
|
topic, see <<product-group-controls,Assigning Group Controls to Products>>.
|
|
|
|
[[classifications]]
|
|
=== Classifications
|
|
|
|
Classifications tend to be used in order to group several related
|
|
products into one distinct entity.
|
|
|
|
The classification field is disabled by default; it can be turned
|
|
on or off in _Bug Fields_ administration area.
|
|
|
|
Access to the administration of classifications is controlled using
|
|
the _editclassifications_ system group, which defines
|
|
a privilege for creating, destroying, and editing classifications.
|
|
|
|
When activated, classifications will introduce an additional
|
|
step when filing bugs (dedicated to classification selection), and they
|
|
will also appear in the advanced search form.
|
|
|
|
[[products]]
|
|
=== Products
|
|
|
|
Products typically represent real-world shipping products. Products can be given
|
|
<<classifications,classifications>>. For example, if a company makes computer games,
|
|
they could have a classification of "Games", and a separate
|
|
product for each game. This company might also have a
|
|
"Common" product for units of technology used
|
|
in multiple games, and perhaps a few special products that
|
|
represent items that are not actually shipping products
|
|
(for example, "Website", or "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.
|
|
|
|
Each product has the following properties:
|
|
|
|
Product::
|
|
The name of the product.
|
|
|
|
Description::
|
|
A brief description of the product. May contain (some) HTML code. "Some" means that
|
|
only "safe" tags are allowed here.
|
|
|
|
HTML code to display above the bug form::
|
|
This is the per-product 'entryheaderhtml' parameter - basically an introduction text
|
|
which will be displayed before the bug entry form for this product.
|
|
|
|
Open for bug entry::
|
|
Uncheck this box to disable the product and to prevent new bugs from being entered against it.
|
|
|
|
Allow unconfirmed::
|
|
Allow unconfirmed bug statuses in this product.
|
|
|
|
Wiki URL prefix::
|
|
Allows to override 'wiki_url' parameter for bugs in this product. Each bug will basically
|
|
have a link to '<wiki_url>/Bug_XXX'.
|
|
|
|
Prefer no timetracking::
|
|
Warn users trying to fix worktime in this product about that it shouldn't be done.
|
|
|
|
CC group::
|
|
If you select a group here, Bugzilla will disallow non-members of this group
|
|
to be Assignee, QA or CC in this product. They will still be allowed to see this product
|
|
bugs or even report new ones if group permissions allow them to do so though.
|
|
|
|
Maximum votes per user::
|
|
Maximum votes a user is allowed to give for this product.
|
|
|
|
Maximum votes per user, per single bug::
|
|
Maximum votes a user is allowed to give for any single bug in this product.
|
|
|
|
Confirmation threshold::
|
|
Shown next to 'Allow unconfirmed' when it is checked, this is the number of votes
|
|
needed to automatically move any bug in this product from the UNCONFIRMED to NEW state.
|
|
|
|
These additional options are available when you create a new product:
|
|
|
|
Version::
|
|
Specify an initial version to be created in this product.
|
|
|
|
Create chart datasets for this product::
|
|
Select to make chart datasets available for this product.
|
|
|
|
Create access group for this product::
|
|
Select to create an access group with the same name as the created product
|
|
and associate it as SHOWN/NA with it.
|
|
|
|
The product edit form also includes:
|
|
|
|
* Links to edit its components, versions, target milestones (<<comps-vers-miles-products,see details>>)
|
|
and <<product-group-controls,group access control>>
|
|
* Checkboxes and inputs to edit the properties of custom fields which are configured to depend on product
|
|
in various ways (enable/disable fields, edit legal values, change default value, enable/disable empty
|
|
value and field cloning)
|
|
|
|
[[create-product]]
|
|
==== Creating New Products
|
|
|
|
To create a new product:
|
|
|
|
. Select "Administration" from the footer and then
|
|
choose "Products" from the main administration page.
|
|
|
|
. If you have the Classification field enabled in your setup, choose
|
|
an existing classificaction or create a new one.
|
|
|
|
. Select the 'Add' or 'Add product to classification ...' link.
|
|
|
|
. Fill in the form with the new product properties.
|
|
|
|
. When the product is created, Bugzilla will give a message
|
|
stating that a component must be created before any bugs can
|
|
be entered against the new product. Follow the link to create
|
|
a new component. See <<components,Components>> for more information.
|
|
|
|
[[edit-products]]
|
|
==== Editing Products
|
|
|
|
To edit a product:
|
|
|
|
. Select "Administration" from the footer and then
|
|
choose "Products" from the main administration page.
|
|
|
|
. If you have the Classification field enabled in your setup, choose
|
|
an existing classificaction or create a new one.
|
|
|
|
. Click on the product name to edit its properties and to access links
|
|
to other product attributes such as the product's components, versions,
|
|
milestones, and group access controls.
|
|
|
|
[[comps-vers-miles-products]]
|
|
==== Adding or Editing Components, Versions and Target Milestones
|
|
|
|
To edit existing, or add new, Components, Versions or Target Milestones
|
|
to a Product, select the "Edit Components", "Edit Versions" or "Edit
|
|
Milestones" links from the "Edit Product" page. A table of existing
|
|
Components, Versions or Milestones is displayed. Click on a item name
|
|
to edit the properties of that item. Below the table is a link to add
|
|
a new Component, Version or Milestone.
|
|
|
|
For more information on components, see <<components,Components>>.
|
|
|
|
For more information on versions, see <<versions,Versions>>.
|
|
|
|
For more information on milestones, see <<milestones,Milestones>>.
|
|
|
|
[[product-group-controls]]
|
|
==== Assigning Group Controls to Products
|
|
|
|
The per-product security settings are configured on the 'Edit Group Access Controls' page.
|
|
|
|
The basic security concept is that the access to _every particular bug_ may be restricted by a
|
|
number of Bugzilla groups. The 'more groups' bug is restricted by, the 'more secret' it is.
|
|
|
|
Some of these groups may be optional, in this case 'some people' will be able to decide
|
|
about making the bug more or less secret by setting or clearing the checkboxes shown
|
|
on the bug entry/edit form for such groups.
|
|
|
|
===== MemberControl/OtherControl
|
|
|
|
Product group controls specify 'what groups' the bugs in this product may be restricted with,
|
|
'who may decide' on changing that restriction. This is controlled by a set of groups with
|
|
two properties: 'MemberControl' and 'OtherControl', both of which may be equal to one of 'Mandatory',
|
|
'Default', 'Shown' or 'NA'.
|
|
|
|
Group is optional for the bugs in product when it has 'Shown' or 'Default' MemberControl or OtherControl.
|
|
People who may decide about including each specific bug into the group are 'members of that group'
|
|
for the case of MemberControl and 'everyone else' for OtherControl.
|
|
|
|
[options="header",cols="2*10%,80%"]
|
|
|=====
|
|
| MemberControl | OtherControl | Interpretation
|
|
| Mandatory | Mandatory | Simplest case: all bugs in this product are always restricted by this group.
|
|
| Mandatory | Shown/Default/NA | These combinations are not allowed.
|
|
| Default | Mandatory |
|
|
Members of this group are able to restrict or not to restrict bugs in this product by this group.
|
|
|
|
Non-members are forced to restrict their new bugs by this group and may not change the restriction of existing bugs by this group.
|
|
|
|
Bug entry form has the group checkbox checked by default for group members.
|
|
|
|
| Default | Default |
|
|
Everyone is able to restrict or not to restrict bugs in this product by this group.
|
|
|
|
Bug entry form has the group checkbox checked by default for everyone.
|
|
|
|
| Default | Shown | This combination is not allowed.
|
|
| Default | NA |
|
|
Members of this group are able to restrict or not to restrict bugs in this product by this group.
|
|
|
|
Non-members may not restrict bugs by this group.
|
|
|
|
Bug entry form has the group checkbox checked by default for group members.
|
|
|
|
| Shown | Mandatory |
|
|
Members of this group are able to restrict or not to restrict bugs in this product by this group.
|
|
|
|
Non-members are forced to restrict their new bugs by this group and may not change the restriction of existing bugs by this group.
|
|
|
|
Bug entry form has the group checkbox unchecked by default for group members.
|
|
|
|
| Shown | Default |
|
|
Everyone is able to restrict or not to restrict bugs in this product by this group.
|
|
|
|
Bug entry form has the group checkbox unchecked by default for members of this group, and checked by default for non-members of this group.
|
|
|
|
| Shown | Shown |
|
|
Everyone is able to restrict or not to restrict bugs in this product by this group.
|
|
|
|
Bug entry form has the group checkbox unchecked by default for everyone.
|
|
|
|
| Shown | NA |
|
|
Members of this group are able to restrict or not to restrict bugs in this product by this group.
|
|
|
|
Non-members may not restrict bugs by this group.
|
|
|
|
Bug entry form has the group checkbox unchecked by default.
|
|
|
|
| NA | Mandatory/Default/Shown | These combinations are not allowed.
|
|
| NA | NA |
|
|
Bugs in this product are never restricted by this group. Equivalent to removing the group from the list.
|
|
|
|
|=====
|
|
|
|
===== Additional controls
|
|
|
|
Product group control also configure permissions for some additional actions:
|
|
|
|
Restrict bug entry ('ENTRY'):: By default any user can enter a bug in the product, regardless of the
|
|
basic access controls. Specify one or more groups here to require the user
|
|
to be their member to be able to enter bugs.
|
|
|
|
Restrict editing and commenting bugs ('canedit'):: By default any user who can access the bug
|
|
can also comment/edit it. Specify one or more groups here to make this product bugs
|
|
read-only for all users that are not a member of all specified groups.
|
|
|
|
Allow product and component administration ('editcomponents'):: By default only members of the
|
|
'editcomponents' system group can administer products. Specify some groups here to allow
|
|
members of 'any of them' to administer this product.
|
|
|
|
Allow to confirm bugs ('canconfirm'):: If unconfirmed states are enabled in this product, you may specify
|
|
some groups here to allow members of 'any of them' to move this product bugs from
|
|
unconfirmed to confirmed states. Members of the 'canconfirm' system group will still be able to
|
|
do the same for all products.
|
|
|
|
Allow to change any field of this product bugs ('editbugs'):: By default users that are not members of 'editbugs'
|
|
group are only allowed to comment on most bugs, but not to change the field values
|
|
(see 'editbugs' in <<systemgroups,System Groups>>). Specify some groups here to allow members of
|
|
'any of them' to edit all fields of bugs in this product.
|
|
|
|
[[group-control-examples]]
|
|
===== Common Applications of Group Controls
|
|
|
|
The use of groups is best explained by providing examples that illustrate
|
|
configurations for common use cases. The examples follow a common syntax:
|
|
_Group: Entry, MemberControl, OtherControl, CanEdit, EditComponents, CanConfirm, EditBugs_. Where "Group" is the name
|
|
of the group being edited for this product. The other fields all
|
|
correspond to the table on the "Edit Group Access Controls" page. If any
|
|
of these options are not listed, it means they are not checked.
|
|
|
|
.Basic Product/Group Restriction
|
|
|
|
Suppose there is a product called "Bar". The
|
|
"Bar" product can only have bugs entered against it by users in the
|
|
group "Foo". Additionally, bugs filed against product "Bar" must stay
|
|
restricted to users to "Foo" at all times. Furthermore, only members
|
|
of group "Foo" can edit bugs filed against product "Bar", even if other
|
|
users could see the bug. This arrangement would achieved by the
|
|
following:
|
|
|
|
----
|
|
Product Bar:
|
|
foo: ENTRY, MANDATORY/MANDATORY, CANEDIT
|
|
----
|
|
|
|
Perhaps such strict restrictions are not needed for product "Bar". A
|
|
more lenient way to configure product "Bar" and group "Foo" would be:
|
|
|
|
----
|
|
Product Bar:
|
|
foo: ENTRY, SHOWN/SHOWN, EDITCOMPONENTS, CANCONFIRM, EDITBUGS
|
|
----
|
|
|
|
The above indicates that for product "Bar", members of group "Foo" can
|
|
enter bugs. Any one with permission to edit a bug against product "Bar"
|
|
can put the bug
|
|
in group "Foo", even if they themselves are not in "Foo". Anyone in group
|
|
"Foo" can edit all aspects of the components of product "Bar", can confirm
|
|
bugs against product "Bar", and can edit all fields of any bug against
|
|
product "Bar".
|
|
|
|
.General User Access With Security Group
|
|
|
|
To permit any user to file bugs against "Product A",
|
|
and to permit any user to submit those bugs into a
|
|
group called "Security":
|
|
|
|
----
|
|
Product A:
|
|
security: SHOWN/SHOWN
|
|
----
|
|
|
|
.General User Access With A Security Product
|
|
|
|
To permit any user to file bugs against product called "Security"
|
|
while keeping those bugs from becoming visible to anyone
|
|
outside the group "SecurityWorkers" (unless a member of the
|
|
"SecurityWorkers" group removes that restriction):
|
|
|
|
----
|
|
Product Security:
|
|
securityworkers: DEFAULT/MANDATORY
|
|
----
|
|
|
|
.Product Isolation With a Common Group
|
|
|
|
To permit users of "Product A" to access the bugs for
|
|
"Product A", users of "Product B" to access the bugs for
|
|
"Product B", and support staff, who are members of the "Support
|
|
Group" to access both, three groups are needed:
|
|
|
|
. Support Group: Contains members of the support staff.
|
|
|
|
. AccessA Group: Contains users of product A and the Support group.
|
|
|
|
. AccessB Group: Contains users of product B and the Support group.
|
|
|
|
Once these three groups are defined, the product group controls can be set to:
|
|
|
|
----
|
|
Product A:
|
|
AccessA: ENTRY, MANDATORY/MANDATORY
|
|
Product B:
|
|
AccessB: ENTRY, MANDATORY/MANDATORY
|
|
----
|
|
|
|
Perhaps the "Support Group" wants more control. For example, the "Support Group" could be permitted to make bugs inaccessible to
|
|
users of both groups "AccessA" and "AccessB". Then, the "Support Group" could be permitted to publish
|
|
bugs relevant to all users in a third product (let's call it "Product Common") that is read-only
|
|
to anyone outside the "Support Group". In this way the "Support Group" could control bugs that should be seen by both groups.
|
|
That configuration would be:
|
|
|
|
----
|
|
Product A:
|
|
AccessA: ENTRY, MANDATORY/MANDATORY
|
|
Support: SHOWN/NA
|
|
Product B:
|
|
AccessB: ENTRY, MANDATORY/MANDATORY
|
|
Support: SHOWN/NA
|
|
Product Common:
|
|
Support: ENTRY, DEFAULT/MANDATORY, CANEDIT
|
|
----
|
|
|
|
.Make a Product Read Only
|
|
|
|
Sometimes a product is retired and should no longer have
|
|
new bugs filed against it (for example, an older version of a software
|
|
product that is no longer supported). A product can be made read-only
|
|
by creating a group called "readonly" and adding products to the group as needed:
|
|
|
|
----
|
|
Product A:
|
|
ReadOnly: ENTRY, NA/NA, CANEDIT
|
|
----
|
|
|
|
[NOTE]
|
|
For more information on Groups outside of how they relate to products
|
|
see <<groups,Groups and Group Security>>.
|
|
|
|
[[components]]
|
|
=== 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 name, description (which can contain some "safe" HTML text),
|
|
open/closed state ('Open for bug entry'), optional wiki URL that overrides
|
|
global and per-product settings, and default values for some bug fields:
|
|
|
|
* 'Default Assignee', the primary person who fixes bugs in the component.
|
|
* 'Default QA Contact' (effective only if the QA Contact field is enabled),
|
|
the person who usually ensures these bugs are completely fixed.
|
|
* 'Default CC List', people that is subscribed to bugs in this component by default.
|
|
* Default values for fields configured to have component-dependent default values
|
|
('Target Milestone' is a such field by default).
|
|
* If you have any fields that depend on component in any other way, you can also
|
|
configure these per-component dependencies from the component edit form.
|
|
|
|
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 form and press 'Add Component'.
|
|
|
|
[[versions]]
|
|
=== 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 earliest version known to have the bug.
|
|
|
|
To create and edit Versions:
|
|
|
|
. From the "Edit product" screen, select "Edit Versions".
|
|
. Click the "Add" link in the bottom right, or click the name of one of existing versions.
|
|
. Enter the name of the Version. This field takes text only. Then click the "Add" button.
|
|
|
|
Versions are always sorted using the "version sort" comparison.
|
|
|
|
Old versions may be deactivated if you don't want them to appear in the bug entry form anymore.
|
|
|
|
[[milestones]]
|
|
=== 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.
|
|
|
|
[NOTE]
|
|
Milestone options will only appear for a Product if you turned
|
|
on the 'Target Milestone' field in the 'Bug Fields' page on the Administration screen.
|
|
|
|
To create new Milestones, and set Default Milestones:
|
|
|
|
. Select "Edit milestones" from the "Edit product" page.
|
|
|
|
. Select "Add" in the bottom right corner.
|
|
|
|
. Enter the name of the Milestone in the "Milestone" field. You
|
|
can optionally set the "sortkey", which is a positive or negative
|
|
number 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".
|
|
|
|
Just like versions, old milestones may also be deactivated.
|
|
|
|
[[flags-overview]]
|
|
=== Flags
|
|
|
|
Flags are a way to attach a specific status to a bug or attachment,
|
|
either "+" or "-". The meaning of these symbols depends on the text
|
|
the flag itself, but contextually they could mean pass/fail,
|
|
accept/reject, approved/denied, or even a simple yes/no. If your site
|
|
allows requestable flags, then users may set a flag to "?" as a
|
|
request to another user that they look at the bug/attachment, and set
|
|
the flag to its correct status.
|
|
|
|
[[flags-simpleexample]]
|
|
==== A Simple Example
|
|
|
|
A developer might want to ask their manager,
|
|
"Should we fix this bug before we release version 2.0?"
|
|
They might want to do this for a _lot_ of bugs,
|
|
so it would be nice to streamline the process...
|
|
|
|
In Bugzilla, it would work this way:
|
|
|
|
. The Bugzilla administrator creates a flag type called "blocking2.0"
|
|
that shows up on all bugs in your product.
|
|
+
|
|
--
|
|
It shows up on the "Show Bug" screen as the text "blocking2.0" with a drop-down box next
|
|
to it. The drop-down box contains four values: an empty space, "?", "-", and "+".
|
|
--
|
|
. The developer sets the flag to "?".
|
|
|
|
. The manager sees the blocking2.0 flag with a "?" value.
|
|
|
|
. If the manager thinks the feature should go into the product
|
|
before version 2.0 can be released, he sets the flag to
|
|
"+". Otherwise, he sets it to "-".
|
|
|
|
. Now, every Bugzilla user who looks at the bug knows whether or
|
|
not the bug needs to be fixed before release of version 2.0.
|
|
|
|
[[flags-about]]
|
|
==== About Flags
|
|
|
|
[[flag-values]]
|
|
===== Values
|
|
|
|
Flags can have three values:
|
|
?::
|
|
A user is requesting that a status be set. (Think of it as 'A question is being asked')
|
|
|
|
-::
|
|
The status has been set negatively. (The question has been answered "no")
|
|
|
|
+::
|
|
The status has been set positively. (The question has been answered "yes")
|
|
|
|
Actually, there's a fourth value a flag can have -- "unset" -- which
|
|
shows up as a blank space. This just means that nobody has expressed
|
|
an opinion (or asked someone else to express an opinion) about this bug or attachment.
|
|
|
|
[[flag-askto]]
|
|
==== Using flag requests
|
|
|
|
If a flag has been defined as 'requestable', and a user has enough privileges
|
|
to request it (see below), the user can set the flag's status to "?".
|
|
This status indicates that someone (a.k.a. "the requester") is asking
|
|
someone else to set the flag to either "+" or "-".
|
|
|
|
If a flag has been defined as 'specifically requestable',
|
|
a text box will appear next to the flag into which the requester may
|
|
enter a Bugzilla username. That named person (a.k.a. "the requestee")
|
|
will receive an email notifying them of the request, and pointing them
|
|
to the bug/attachment in question.
|
|
|
|
If a flag has _not_ been defined as 'specifically requestable',
|
|
then no such text-box will appear. A request to set this flag cannot be made of
|
|
any specific individual, but must be asked "to the wind".
|
|
A requester may "ask the wind" on any flag simply by leaving the text-box blank.
|
|
|
|
[[flag-types]]
|
|
==== Two Types of Flags
|
|
|
|
Flags can go in two places: on an attachment, or on a bug.
|
|
|
|
[[flag-type-attachment]]
|
|
===== Attachment Flags
|
|
|
|
Attachment flags are used to ask a question about a specific attachment on a bug.
|
|
|
|
Many Bugzilla installations use this to request that one developer "review" another
|
|
developer's code before they check it in. They attach the code to
|
|
a bug report, and then set a flag on that attachment called "review" to
|
|
'review? boss@domain.com'. boss@domain.com is then notified by email that
|
|
he has to check out that attachment and approve it or deny it.
|
|
|
|
For a Bugzilla user, attachment flags show up in three places:
|
|
|
|
. On the list of attachments in the "Show Bug"
|
|
screen, you can see the current state of any flags that
|
|
have been set to ?, +, or -. You can see who asked about
|
|
the flag (the requester), and who is being asked (the requestee).
|
|
|
|
. When you "Edit" an attachment, you can
|
|
see any settable flag, along with any flags that have
|
|
already been set. This "Edit Attachment"
|
|
screen is where you set flags to ?, -, +, or unset them.
|
|
|
|
. Requests are listed in the "Request Queue", which
|
|
is accessible from the "My Requests" link (if you are
|
|
logged in) or "Requests" link (if you are logged out)
|
|
visible in the footer of all pages.
|
|
|
|
[[flag-type-bug]]
|
|
===== Bug Flags
|
|
|
|
Bug flags are used to set a status on the bug itself. You can
|
|
see Bug Flags in the "Show Bug" and "Requests" screens, as described above.
|
|
|
|
Only users with enough privileges (see below) may set flags on bugs.
|
|
This doesn't necessarily include the assignee, reporter, or users with the editbugs permission.
|
|
|
|
[[flags-admin]]
|
|
==== Administering Flags
|
|
|
|
If you have the "editcomponents" permission, you can
|
|
edit Flag Types from the main administration page. Clicking the
|
|
"Flags" link will bring you to the "Administer
|
|
Flag Types" page. Here, you can select whether you want
|
|
to create (or edit) a Bug flag, or an Attachment flag.
|
|
|
|
No matter which you choose, the interface is the same, so we'll just go over it once.
|
|
|
|
[[flags-edit]]
|
|
===== Editing a Flag
|
|
|
|
To edit a flag's properties, just click the flag's name. That will take you to the same
|
|
form as described below (<<flags-create,Creating a Flag>>).
|
|
|
|
[[flags-create]]
|
|
===== Creating a Flag
|
|
|
|
When you click on the "Create a Flag Type for..."
|
|
link, you will be presented with a form. Here is what the fields in the form mean:
|
|
|
|
Name::
|
|
This is the name of the flag. This will be displayed
|
|
to Bugzilla users who are looking at or setting the flag.
|
|
The name may contain any valid Unicode characters except commas
|
|
and spaces.
|
|
|
|
Description::
|
|
The description describes the flag in more detail. It is visible
|
|
in a tooltip when hovering over a flag either in the "Show Bug"
|
|
or "Edit Attachment" pages. This field can be as
|
|
long as you like, and can contain any character you want.
|
|
|
|
Category::
|
|
+
|
|
--
|
|
Default behaviour for a newly-created flag is to appear on
|
|
products and all components, which is why "__Any__:__Any__"
|
|
is already entered in the "Inclusions" box.
|
|
If this is not your desired behaviour, you must either set some
|
|
exclusions (for products on which you don't want the flag to appear),
|
|
or you must remove "__Any__:__Any__" from the Inclusions box
|
|
and define products/components specifically for this flag.
|
|
|
|
To create an Inclusion, select a Product from the top drop-down box.
|
|
You may also select a specific component from the bottom drop-down box.
|
|
(Setting "__Any__" for Product translates to,
|
|
"all the products in this Bugzilla".
|
|
Selecting "__Any__" in the Component field means
|
|
"all components in the selected product.")
|
|
Selections made, press "Include", and your
|
|
Product/Component pairing will show up in the "Inclusions" box on the right.
|
|
|
|
To create an Exclusion, the process is the same; select a Product from the
|
|
top drop-down box, select a specific component if you want one, and press
|
|
"Exclude". The Product/Component pairing will show up in the "Exclusions" box on the right.
|
|
|
|
This flag _will_ and _can_ be set for any
|
|
products/components that appearing in the "Inclusions" box
|
|
(or which fall under the appropriate "__Any__").
|
|
This flag _will not_ appear (and therefore cannot be set) on
|
|
any products appearing in the "Exclusions" box.
|
|
|
|
IMPORTANT: Exclusions override inclusions.
|
|
|
|
You may select a Product without selecting a specific Component,
|
|
but you can't select a Component without a Product, or to select a
|
|
Component that does not belong to the named Product. If you do so,
|
|
Bugzilla will display an error message, even if all your products
|
|
have a component by that name.
|
|
|
|
NOTE: Example: Let's say you have a product called
|
|
"Jet Plane" that has thousands of components. You want
|
|
to be able to ask if a problem should be fixed in the next model of
|
|
plane you release. We'll call the flag "fixInNext".
|
|
But, there's one component in "Jet Plane,"
|
|
called "Pilot." It doesn't make sense to release a
|
|
new pilot, so you don't want to have the flag show up in that component.
|
|
So, you include "Jet Plane:__Any__" and you exclude
|
|
"Jet Plane:Pilot".
|
|
--
|
|
|
|
Sort Key::
|
|
Flags normally show up in alphabetical order. If you want them to
|
|
show up in a different order, you can use this key set the order on each flag.
|
|
Flags with a lower sort key will appear before flags with a higher
|
|
sort key. Flags that have the same sort key will be sorted alphabetically,
|
|
but they will still be after flags with a lower sort key, and before flags
|
|
with a higher sort key.
|
|
|
|
Active::
|
|
Sometimes, you might want to keep old flag information in the
|
|
Bugzilla database, but stop users from setting any new flags of this type.
|
|
To do this, uncheck "active". Deactivated
|
|
flags will still show up in the UI if they are ?, +, or -, but they
|
|
may only be cleared (unset), and cannot be changed to a new value.
|
|
Once a deactivated flag is cleared, it will completely disappear from a
|
|
bug/attachment, and cannot be set again.
|
|
|
|
Requestable::
|
|
New flags are, by default, "requestable", meaning that they
|
|
offer users the "?" option, as well as "+" and "-".
|
|
To remove the ? option, uncheck "requestable".
|
|
|
|
Specifically Requestable::
|
|
By default this box is checked for new flags, meaning that users may make
|
|
flag requests of specific individuals. Unchecking this box will remove the
|
|
text box next to a flag; if it is still requestable, then requests may
|
|
only be made "to the wind." Removing this after specific
|
|
requests have been made will not remove those requests; that data will
|
|
stay in the database (though it will no longer appear to the user).
|
|
|
|
Multiplicable::
|
|
Any flag with "Multiplicable" set (default for new flags is 'on')
|
|
may be set more than once. After being set once, an unset flag
|
|
of the same type will appear below it with "addl." (short for
|
|
"additional") before the name. There is no limit to the number of
|
|
times a Multiplicable flags may be set on the same bug/attachment.
|
|
|
|
CC List::
|
|
If you want certain users to be notified every time this flag is
|
|
set to ?, -, +, or unset, add them here. This is a comma-separated
|
|
list of Bugzilla user email addresses.
|
|
|
|
Grant Group::
|
|
When this field is set to some given group, only users in the group
|
|
can set the flag to "+" and "-". This field does not affect who can request or cancel the flag.
|
|
For that, see the "Request Group" field below. If this field
|
|
is left blank, all users can set or delete this flag. This field is
|
|
useful for restricting which users can approve or reject requests.
|
|
|
|
Request Group::
|
|
When this field is set to some given group, only users in the group
|
|
can request or cancel this flag. Note that this field has no effect
|
|
if the "grant group" field is empty. You can set the
|
|
value of this field to a different group, but both fields have to be
|
|
set to a group for this field to have an effect.
|
|
|
|
[[flags-delete]]
|
|
===== Deleting a Flag
|
|
|
|
When you are at the "Administer Flag Types" screen,
|
|
you will be presented with a list of Bug flags and a list of Attachment Flags.
|
|
|
|
To delete a flag, click on the "Delete" link next to the flag description.
|
|
|
|
WARNING: Once you delete a flag, it is _gone_ from your Bugzilla. All the data for that flag will be deleted.
|
|
Everywhere that flag was set, it will disappear, and you cannot get that data back.
|
|
If you want to keep flag data, but don't want anybody to set any new flags or change current flags,
|
|
unset "active" in the flag Edit form.
|
|
|
|
WARNING: If you exclude an existing flag from some products/components in which
|
|
it was previously included and if there is no other flag type with the same name
|
|
enabled in those products/components, Bugzilla *ALSO DELETES* all existing flags
|
|
of the excluded type. If another flag type with the same name exists in the excluded
|
|
product/component, Bugzilla changes all existing flags to that type. If you just
|
|
'disable' the flag, Bugzilla does not delete and does not retarget existing flags.
|
|
|
|
=== Bug Fields
|
|
|
|
In Bugzilla4Intranet, it is not only possible to create Custom Fields for bugs,
|
|
but it's also possible to tweak some properties of standard ones. For example,
|
|
enabling/disabling fields like Alias, Classification and et cetera is done
|
|
using the "Disabled" property of these fields, not via the 'use*' parameters
|
|
like in the original Bugzilla.
|
|
|
|
Both custom and normal fields are accessible from the 'Administration -> Bug Fields' page.
|
|
|
|
Custom Fields are treated like any other field - they can be set in bugs
|
|
and used for search queries. Administrators should keep in mind that
|
|
adding too many fields can make the user interface more complicated and
|
|
harder to use. Custom Fields should be added only when necessary and with
|
|
careful consideration.
|
|
|
|
TIP: Before adding a Custom Field, make sure that Bugzilla can not already
|
|
do the desired behavior. Many Bugzilla options are not enabled by
|
|
default, and many times Administrators find that simply enabling
|
|
certain options that already exist is sufficient.
|
|
|
|
==== Tweaking Standard Fields
|
|
|
|
You can tweak the behaviour of standard Bugzilla fields in various ways: enable/disable them,
|
|
set default values, allow or deny empty value, or even make some of them depend on other fields.
|
|
|
|
For example, you can enable/disable Alias, Classification, Platform, Operating System,
|
|
QA Contact, Target Milestone, Status Whiteboard and See Also fields.
|
|
|
|
To change properties of a standard field, select it in the table under the 'Standard fields'
|
|
heading. You can change any property shown on the field form; properties are hidden
|
|
if it is not possible to edit them.
|
|
|
|
==== Field Properties
|
|
|
|
Name::
|
|
The name of the field in the database, used internally. This name
|
|
must begin with "cf_" for custom fields to prevent confusion with
|
|
standard fields. If "cf_" is omitted, it will be automatically added
|
|
to the name entered.
|
|
|
|
Title::
|
|
A brief string which is used as the label for the Custom Field.
|
|
That is the string that users will see, and should be short and explicit.
|
|
For standard fields, the description does not really affect the displayed field label.
|
|
|
|
Sortkey::
|
|
Integer that determines in which order Custom Fields are displayed in the user
|
|
interface when viewing bugs and bug history, and in the e-mail notification messages.
|
|
Fields with lower values are displayed first.
|
|
|
|
Type::
|
|
+
|
|
--
|
|
The type of field. You can choose type when creating a custom field, and you can't
|
|
change it when the field already exists. There are several types available:
|
|
|
|
Free Text::
|
|
A single line edit field for entering free text. Maximum length of values of such fields is 255 characters.
|
|
Large Text Box::
|
|
A multiple line box (textarea) for entering free text. Values of such fields may be up to several megabytes long.
|
|
Numeric::
|
|
A field that allows only numeric (decimal floating point) values.
|
|
Drop Down::
|
|
A list box where only one option can be selected.
|
|
After creating this field, it must be edited to add the selection options. See
|
|
<<edit-values-list,Viewing/Editing legal values>> for information about editing legal values.
|
|
Multiple-Selection Box::
|
|
A list box where multiple options can be selected.
|
|
After creating this field, it must be edited to add the selection options,
|
|
just like the 'Drop Down' fields.
|
|
Date/Time::
|
|
A date field. This field appears with a calendar widget for choosing the date.
|
|
Bug ID::
|
|
A field that is a reference to bug. Besides just appearing in the search form,
|
|
Bug ID fields also allow to use properties of the bug they reference to in searches.
|
|
For example, if there is a Bug ID field named "External Bug", the search form will also
|
|
have "External Bug Summary", "External Bug Status" and similar as options.
|
|
Bug ID reverse::
|
|
A pseudo-field that shows back-references for an existing Bug ID field.
|
|
Only one "reverse" field may be created for a single Bug ID field; you must
|
|
specify that Bug ID field in the "Direct Bug ID field" editbox while creating
|
|
a "reverse" field. +
|
|
For example, for an existing Bug ID field named "External Bug", the reverse field
|
|
should be named "Internal Bugs" (not just "bug" because multiple bugs may reference
|
|
to a single bug as a value of the "External Bug" field).
|
|
External URL::
|
|
A field that links to a URL generated from a given template by replacing "$1" with
|
|
the field value. For example, you may use this type to reference to a single bug in
|
|
an external bugtracker; for the case of Bugzilla4Intranet GitHub issues you should
|
|
specify "https://github.com/vitalif/bugzilla-4intranet/issues/$1" URL template.
|
|
--
|
|
|
|
Deps::
|
|
Effective only for 'Bug ID' fields, this property specifies if the field value should be
|
|
automatically added to the bug dependencies. You may choose "Add field value to blocked"
|
|
or "Add field value to blockers" here.
|
|
|
|
URL::
|
|
Only for 'External URL' fields, this property specifies URL template used in the field.
|
|
|
|
Displayed in bugmail for new bugs::
|
|
A flag (checkbox) that determines whether the value set on this field should appear in
|
|
the "New Bug" bugmail when the bug is filed.
|
|
|
|
Is copied into the cloned bug::
|
|
A flag (checkbox) that determines whether the value of this field should be copied
|
|
to the cloned bugs.
|
|
|
|
Is disabled::
|
|
A flag (checkbox) that determines whether this field should be displayed and used at all.
|
|
Disabled Custom Fields are hidden from the UI. You must disable Custom Fields before
|
|
deleting them.
|
|
|
|
Default value::
|
|
The global default value for this field. This, for example, replaces old 'defaultpriority',
|
|
'defaultseverity' and similar properties of the original Bugzilla. The default value
|
|
can only be set after creating the field and filling the legal values for selectbox fields.
|
|
|
|
Allow empty value::
|
|
A flag (checkbox) that determines whether it is possible to leave this field empty in
|
|
newly created and edited bugs. Note that multiple-selection boxes always allow empty values,
|
|
and because "reverse" bug ID fields don't really store any data, it's also impossible
|
|
to make them nullable or non-nullable.
|
|
|
|
Also there are some properties that specify field dependencies. You can make any field
|
|
depend on other select or multi-select field in various ways:
|
|
|
|
Show/hide the field depending on the value of::
|
|
After you specify another field here (for example, Product), you'll be able to enable or disable
|
|
the field you are editing for every value of that field (for example, per Product).
|
|
|
|
Allow empty value depending on the value of::
|
|
This dependency allows you to enable or disable empty value of edited field for each value
|
|
of field selected as the dependency. Requires the "Allow empty value" property enabled.
|
|
|
|
Clone field depending on the value of::
|
|
This dependency allows you to enable or disable copying of edited field value for each value
|
|
of field selected as the dependency. Requires the "Is copied into the cloned bug" property enabled.
|
|
|
|
Make default value dependent on the value of::
|
|
This dependency allows you to choose different default values for different values
|
|
of field selected as the dependency. Default values only have effect on the bug creation form.
|
|
|
|
Field that controls the values that appear in this field::
|
|
This dependency allows you to have different legal values for different values
|
|
of field selected as the dependency.
|
|
|
|
NOTE: A common usage of dependencies is to make field properties depend on Product or Component. However,
|
|
any select or multi-select field, including custom ones, may be used as the dependency field.
|
|
|
|
==== Adding Custom Fields
|
|
|
|
To add a new Custom Field, click the "Add a new custom field" link, fill the form and press "Create".
|
|
|
|
WARNING: Creating most fields implies database schema modifications which can take some time on
|
|
big bug databases. During that time your Bugzilla4Intranet will look "hung up" for users.
|
|
However, online creation won't result in any runtime errors, as in the original Bugzilla, so
|
|
it's usually possible to create the new fields without long downtime.
|
|
|
|
==== Editing Custom Fields
|
|
|
|
As soon as a Custom Field is created, its name and type cannot be
|
|
changed. If this field is a drop down menu, its legal values can
|
|
be set as described in <<edit-values-list,Viewing/Editing legal values>>. All
|
|
other attributes can be edited just like during creation.
|
|
|
|
==== Deleting Custom Fields
|
|
|
|
Only custom fields which are marked as obsolete, and which never
|
|
have been used, can be deleted completely (else the integrity
|
|
of the bug history would be compromised). For custom fields marked
|
|
as obsolete, a "Delete" link will appear in the "Action"
|
|
column. If the custom field has been used in the past, the deletion
|
|
will be rejected. But marking the field as obsolete is sufficient
|
|
to hide it from the user interface entirely.
|
|
|
|
[[edit-values]]
|
|
=== Legal Values
|
|
|
|
In Bugzilla4Intranet, legal values for all standard select fields
|
|
(Severity, Priority, OS, Platform, Status and Resolution) can be customized
|
|
from the field administration UI directly.
|
|
|
|
[[edit-values-list]]
|
|
==== Viewing/Editing legal values
|
|
|
|
Editing legal values requires being a member of the 'editvalues' system group.
|
|
|
|
Select 'Field Values' from the Administration page. A list of all
|
|
fields, both system fields and Custom Fields, for which legal values
|
|
can be edited appears. Click a field name to edit its legal values.
|
|
|
|
There is no limit to how many values a field can have, but each value
|
|
must be unique to that field.
|
|
|
|
All legal values have 3 properties:
|
|
|
|
Name:: Value name. In Bugzilla4Intranet, maximum name length is 255 characters for all fields.
|
|
Sortkey:: Used to sort values. Values with smaller numbers are displayed first.
|
|
Enabled for bugs:: Used to remove old values from the UI while keeping them in the database.
|
|
|
|
Values of some fields also have additional properties:
|
|
|
|
* Bug Statuses have several semantic flags:
|
|
+
|
|
--
|
|
Is open:: Specifies if a bug in this state hasn't been fixed yet.
|
|
Is it a confirmed state:: For open states, specifies if a bug in this state is confirmed.
|
|
By default, this is off only for the UNCONFIRMED state.
|
|
Is it an assigned state:: Specifies if a bug in this state has someone working on it.
|
|
There should be only one assigned state.
|
|
|
|
These flags are used by Bugzilla4Intranet to work with bug statuses correctly regardless of
|
|
their names.
|
|
--
|
|
* Values of the OS and Platform fields have an additional property named 'User Agent Regexp'
|
|
which is used to guess the value based on HTTP User-Agent header sent by the user browser.
|
|
As always, these are Perl regexes and you can edit them if you want to change the guessed values.
|
|
* Keywords have the description in addition to just name.
|
|
|
|
If the field values of which you are editing has value dependency field ('Field that controls the
|
|
values that appear in this field') there will be also a 'Only appears when ... is set to:' multiple-selection
|
|
box on the field value edit form. You can use it to enable/disable the value for specific values of the
|
|
dependency field.
|
|
|
|
If any other field depends on the one values of which you are editing, the value form will also contain
|
|
checkboxes or inputs allowing to edit the dependent properties for the value you are editing.
|
|
|
|
NOTE: This is usually more convenient to edit dependent properties and values from the
|
|
dependency value page instead of the page of dependent value, for example, edit the set of values
|
|
enabled for a specific product from that product's page.
|
|
|
|
[[edit-values-delete]]
|
|
==== Deleting legal values
|
|
|
|
Legal values from Custom Fields can be deleted, but only if the
|
|
following two conditions are respected:
|
|
|
|
. The value is not used by default for the field.
|
|
|
|
. No bug is currently using this value.
|
|
|
|
If any of these conditions is not respected, the value cannot be deleted.
|
|
The only way to delete these values is to reassign bugs to another value
|
|
and to set another value as default for the field.
|
|
|
|
=== Keywords
|
|
|
|
The administrator can define keywords which can be used to tag and
|
|
categorise bugs. For example, the keyword "regression" is commonly used.
|
|
A company might have a policy stating all regressions must be fixed by the
|
|
next release - this keyword can make tracking those bugs much easier.
|
|
|
|
Keywords are global by default, but you may configure them to depend on product
|
|
or on another select field by setting the value dependency field from the Bug Fields UI.
|
|
|
|
In Bugzilla4Intranet, keywords are more similar to tags: if a user specifies a non-existing
|
|
keyword, Bugzilla asks him to enter a description for it, and the new keyword is created
|
|
automatically afterwards. This is different from the original Bugzilla where each keyword
|
|
must be created by an administrator before usage.
|
|
|
|
[[bug_status_workflow]]
|
|
=== Bug Status Workflow
|
|
|
|
The bug status workflow is no longer hardcoded but can be freely customized
|
|
from the web interface. The configuration page displays all existing bug statuses
|
|
twice, first on the left for bug statuses we come from and on the top for bug statuses we move to.
|
|
If the checkbox is checked, then the transition between the two bug statuses
|
|
is legal, else it's forbidden independently of your privileges. The bug status
|
|
used for the "duplicate_or_move_bug_status" parameter must be part of the
|
|
workflow as that is the bug status which will be used when duplicating or
|
|
moving a bug, so it must be available from each bug status.
|
|
|
|
When the workflow is set, the "View Comments Required on Status Transitions" link below the table
|
|
lets you set which transitions require a comment from the user.
|
|
|
|
[[voting]]
|
|
=== 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" status, users of the bug system can help high-priority bugs garner
|
|
attention so they don't sit for a long time awaiting triage.
|
|
|
|
To enable Voting, enable the "Votes" field in the Bug Fields UI.
|
|
|
|
To modify Voting settings, navigate to the "Edit product" screen for the Product
|
|
you wish to modify.
|
|
|
|
Maximum Votes, per user:: Maximum number of votes a single user can put
|
|
to bugs in this product. Setting this field to "0" disables voting.
|
|
|
|
Maximum Votes, per user, per single bug::
|
|
Maximum number of votes a single user can put to a single bug in this product.
|
|
It should probably be some number lower than the "Maximum votes per user".
|
|
Setting this to "0" of course will also prevent the user from voting on bugs in this product.
|
|
"1" means that a user can only put a single vote to a single bug in this product.
|
|
|
|
Allow unconfirmed:: You must allow unconfirmed bug statuses in the product if you want
|
|
to automatically confirm bugs by their number of votes.
|
|
|
|
and automatically confirm bugs if they get ... votes:: 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 confirmation of bugs.
|
|
|
|
Once you have adjusted the values to your preference, click "Update".
|
|
|
|
[[quips]]
|
|
=== Quips
|
|
|
|
Quips are small text messages that can be configured to appear
|
|
next to search results. A Bugzilla installation can have its own specific
|
|
quips. Whenever a quip needs to be displayed, a random selection
|
|
is made from the pool of already existing quips.
|
|
|
|
Quips are controlled by the 'quip_list_entry_control' parameter.
|
|
It has several possible values: open, moderated or closed.
|
|
In order to enable quips approval you need to set this parameter
|
|
to "moderated". In this way, users are free to submit quips for
|
|
addition but an administrator must explicitly approve them before
|
|
they are actually used.
|
|
|
|
Each user can enable or disable quips by changing their personal
|
|
preference named "Show a quip at the top of each bug list". If you
|
|
want to totally disable quips, you can do it using "Default Preferences"
|
|
administration UI - just set that preference to "off" and disable it.
|
|
|
|
In order to see the user interface for the quips, it is enough to click
|
|
on a quip when it is displayed together with the search results. Or
|
|
it can be seen directly in the browser by visiting the /quips.cgi URL
|
|
(prefixed with the usual web location of the Bugzilla installation).
|
|
Once the quip interface is displayed, it is enough to click the
|
|
"view and edit the whole quip list" in order to see the administration
|
|
page. A page with all the quips available in the database will
|
|
be displayed.
|
|
|
|
Next to each tip there is a checkbox, under the
|
|
"Approved" column. Quips who have this checkbox checked are
|
|
already approved and will appear next to the search results.
|
|
The ones that have it unchecked are still preserved in the
|
|
database but they will not appear on search results pages.
|
|
User submitted quips have initially the checkbox unchecked.
|
|
|
|
Also, there is a delete link next to each quip,
|
|
which can be used in order to permanently delete a quip.
|
|
|
|
[[sanitycheck]]
|
|
=== Checking and Maintaining Database Integrity
|
|
|
|
Bugzilla always uses foreign keys to maintain referential integrity of the database.
|
|
However, there are other types of non-critical logical anomalies which can sometimes
|
|
appear over some time of normal usage or after manual database administration outside
|
|
of the Bugzilla user interface.
|
|
|
|
Bugzilla includes a "Sanity Check" script that can perform some database checks,
|
|
and repair certain problems.
|
|
|
|
To run the "Sanity Check" script, log in as an Administrator and click the
|
|
"Sanity Check" link in the admin page. Any problems that are found will be
|
|
displayed in red letters. If the script is capable of fixing a problem,
|
|
it will present a link to initiate the fix. If the script can not
|
|
fix the problem it will require manual database administration or recovery.
|
|
|
|
The "Sanity Check" script can also be run from the command line via the perl
|
|
script _sanitycheck.pl_. The script can also be run as a _cron_ job. Results
|
|
will be delivered by email.
|
|
|
|
[[security]]
|
|
== Bugzilla Security
|
|
|
|
While some of the items in this chapter are related to the operating
|
|
system Bugzilla is running on or some of the support software required to
|
|
run Bugzilla, it is all related to protecting your data. This is not
|
|
intended to be a comprehensive guide to securing Linux, Apache, MySQL, or
|
|
any other piece of software mentioned. There is no substitute for active
|
|
administration and monitoring of a machine. The key to good security is
|
|
actually right in the middle of the word: _U R It_.
|
|
|
|
While programmers in general always strive to write secure code,
|
|
accidents can and do happen. The best approach to security is to always
|
|
assume that the program you are working with isn't 100% secure and restrict
|
|
its access to other parts of your machine as much as possible.
|
|
|
|
[[security-os]]
|
|
=== Operating System
|
|
|
|
[[security-os-ports]]
|
|
==== TCP/IP Ports
|
|
|
|
The TCP/IP standard defines more than 65,000 ports for sending
|
|
and receiving traffic. Of those, Bugzilla needs exactly one to operate
|
|
(different configurations and options may require up to 3). You should
|
|
audit your server and make sure that you aren't listening on any ports
|
|
you don't need to be. It's also highly recommended that the server
|
|
Bugzilla resides on, along with any other machines you administer, be
|
|
placed behind some kind of firewall.
|
|
|
|
[[security-os-accounts]]
|
|
==== System User Accounts
|
|
|
|
Many daemons, such
|
|
as Apache's _httpd_ or MySQL's
|
|
_mysqld_, run as either "root" or
|
|
"nobody". This is even worse on Windows machines where the
|
|
majority of services
|
|
run as "SYSTEM". While running as "root" or
|
|
"SYSTEM" introduces obvious security concerns, the
|
|
problems introduced by running everything as "nobody" may
|
|
not be so obvious. Basically, if you run every daemon as
|
|
"nobody" and one of them gets compromised it can
|
|
compromise every other daemon running as "nobody" on your
|
|
machine. For this reason, it is recommended that you create a user
|
|
account for each daemon.
|
|
|
|
[NOTE]
|
|
====
|
|
You will need to set the webservergroup option
|
|
in _localconfig_ to the group your web server runs
|
|
as. This will allow _./checksetup.pl_ to set file
|
|
permissions on Unix systems so that nothing is world-writable.
|
|
====
|
|
|
|
[[security-os-chroot]]
|
|
==== The _chroot_ Jail
|
|
|
|
If your system supports it, you may wish to consider running
|
|
Bugzilla inside of a _chroot_ jail. This option
|
|
provides unprecedented security by restricting anything running
|
|
inside the jail from accessing any information outside of it.
|
|
Note that except information stored in client-server DBMS like MySQL or PostgreSQL). If you
|
|
wish to use this option, please consult the documentation that came
|
|
with your system.
|
|
|
|
[[security-webserver]]
|
|
=== Web server
|
|
|
|
[[security-webserver-access]]
|
|
==== Disabling Remote Access to Bugzilla Configuration Files
|
|
|
|
There are many files that are placed in the Bugzilla directory
|
|
area that should not be accessible from the web server. Because of the way
|
|
Bugzilla is currently layed out, the list of what should and should not
|
|
be accessible is rather complicated. A quick way is to run
|
|
_testserver.pl_ to check if your web server serves
|
|
Bugzilla files as expected. If not, you may want to follow the few
|
|
steps below.
|
|
|
|
[TIP]
|
|
====
|
|
Bugzilla ships with the ability to create
|
|
_.htaccess_ files that enforce these rules. Instructions for enabling these
|
|
directives in Apache can be found in <<http-apache,Bugzilla using Apache>>
|
|
====
|
|
|
|
* In the main Bugzilla directory, you should:
|
|
** Block: _*.pl_, _localconfig*_
|
|
* In __data__:
|
|
** Block everything
|
|
* 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
|
|
|
|
Be sure to test that data that should not be accessed remotely is
|
|
properly blocked. Of particular interest is the localconfig file which
|
|
contains your database password. Also, be aware that many editors
|
|
create temporary and backup files in the working directory and that
|
|
those should also not be accessible. For more information, see
|
|
link:$$http://bugzilla.mozilla.org/show_bug.cgi?id=186383$$[bug 186383]
|
|
or
|
|
link:$$http://online.securityfocus.com/bid/6501$$[Bugtraq ID 6501].
|
|
To test, simply run _testserver.pl_, as said above.
|
|
|
|
[TIP]
|
|
====
|
|
Be sure to check <<http,Web server>> for instructions
|
|
specific to the web server you use.
|
|
====
|
|
|
|
[[security-bugzilla]]
|
|
=== Bugzilla
|
|
|
|
[[security-bugzilla-charset]]
|
|
==== Prevent users injecting malicious Javascript
|
|
|
|
If you installed Bugzilla version 2.22 or later from scratch,
|
|
then the _utf8_ parameter is switched on by default.
|
|
This makes Bugzilla explicitly set the character encoding, following
|
|
link:$$http://www.cert.org/tech_tips/malicious_code_mitigation.html#3$$[a CERT advisory] recommending exactly this.
|
|
The following therefore does not apply to you; just keep
|
|
_utf8_ turned on.
|
|
|
|
If you've upgraded from an older version, then it may be possible
|
|
for a Bugzilla user to take advantage of character set encoding
|
|
ambiguities to inject HTML into Bugzilla comments.
|
|
This could include malicious scripts.
|
|
This is because due to internationalization concerns, we are unable to
|
|
turn the _utf8_ parameter on by default for upgraded
|
|
installations.
|
|
Turning it on manually will prevent this problem.
|
|
|
|
[[using]]
|
|
== Using Bugzilla
|
|
|
|
[[using-intro]]
|
|
=== Introduction
|
|
|
|
This section contains information for end-users of Bugzilla. There
|
|
is a Bugzilla test installation, called
|
|
link:$$http://landfill.bugzilla.org/$$[Landfill], which you are
|
|
welcome to play with (if it's up). However, not all of the Bugzilla
|
|
installations there will necessarily have all Bugzilla features enabled,
|
|
and different installations run different versions, so some things may not
|
|
quite work as this document describes.
|
|
|
|
Frequently Asked Questions (FAQ) are available and answered on
|
|
link:$$http://wiki.mozilla.org/Bugzilla:FAQ$$[wiki.mozilla.org].
|
|
They may cover some questions you have which are left unanswered.
|
|
|
|
[[myaccount]]
|
|
=== 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:
|
|
link:$$http://landfill.bugzilla.org/bugzilla-3.6-branch/$$[].
|
|
|
|
. On the home page _index.cgi_, click the
|
|
"Open a new Bugzilla account" link, or the
|
|
"New Account" link available in the footer of pages.
|
|
Now enter your email address, then click the "Send"
|
|
button.
|
|
|
|
[NOTE]
|
|
====
|
|
If none of these links is available, this means that the
|
|
administrator of the installation has disabled self-registration.
|
|
This means that only an administrator can create accounts
|
|
for other users. One reason could be that this installation is
|
|
private.
|
|
====
|
|
|
|
[NOTE]
|
|
====
|
|
Also, if only some users are allowed to create an account on
|
|
the installation, you may see these links but your registration
|
|
may fail if your email address doesn't match the ones accepted
|
|
by the installation. This is another way to restrict who can
|
|
access and edit bugs in this installation.
|
|
====
|
|
|
|
. Within moments, and if your registration is accepted, you should
|
|
receive an email to the address you provided, which contains your
|
|
login name (generally the same as the email address), and two URLs
|
|
with a token (a random string generated by the installation) to
|
|
confirm, respectively cancel, your registration. This is a way to
|
|
prevent users from abusing the generation of user accounts, for
|
|
instance by entering inexistent email addresses, or email addresses
|
|
which do not belong to them.
|
|
|
|
. By default, you have 3 days to confirm your registration. Past this
|
|
timeframe, the token is invalidated and the registration is
|
|
automatically canceled. You can also cancel this registration sooner
|
|
by using the appropriate URL in the email you got.
|
|
|
|
. If you confirm your registration, Bugzilla will ask you your real name
|
|
(optional, but recommended) and your password, which must be between
|
|
3 and 16 characters long.
|
|
|
|
. Now all you need to do is to click the "Log In"
|
|
link in the footer at the bottom of the page in your browser,
|
|
enter your email address and password you just chose into the
|
|
login form, and click the "Log in" button.
|
|
|
|
You are now logged in. Bugzilla uses cookies to remember you are
|
|
logged in so, unless you have cookies disabled or your IP address changes,
|
|
you should not have to log in again during your session.
|
|
|
|
[[bug_page]]
|
|
=== 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.
|
|
link:$$http://landfill.bugzilla.org/bugzilla-3.6-branch/show_bug.cgi?id=1$$[ 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.
|
|
|
|
. _*QA Contact:_
|
|
The person responsible for quality assurance on this 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 prioritize 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.
|
|
|
|
. _*Time Tracking:_
|
|
This form can be used for time tracking.
|
|
To use this feature, you have to be blessed group membership
|
|
specified by the "timetrackinggroup" parameter. +
|
|
_Orig. Est.:_ This field shows the original estimated time. +
|
|
_Current Est.:_ This field shows the current estimated time. This number is calculated from "Hours Worked"and "Hours Left". +
|
|
_Hours Worked:_ This field shows the number of hours worked. +
|
|
_Hours Left:_ This field shows the "Current Est."-"Hours Worked". This value + "Hours Worked" will become the new Current Est. +
|
|
_%Complete:_ This field shows what percentage of the task is complete. +
|
|
_Gain:_ This field shows the number of hours that the bug is ahead of the "Orig. Est.". +
|
|
_Deadline:_ This field shows the deadline for this bug.
|
|
|
|
. _Attachments:_
|
|
You can attach files (e.g. testcases or patches) to bugs. If there
|
|
are any attachments, they are listed in this section. Attachments are
|
|
normally stored in the Bugzilla database, unless they are marked as
|
|
Big Files, which are stored directly on disk.
|
|
|
|
. _*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.
|
|
|
|
[[lifecycle]]
|
|
=== Life Cycle of a Bug
|
|
|
|
The life cycle of a bug, also known as workflow, is customizable to match
|
|
the needs of your organization, see <<bug_status_workflow,Bug Status Workflow>>.
|
|
<<lifecycle-image,Lifecycle of a Bugzilla Bug>> contains a graphical representation of
|
|
the default workflow using the default bug statuses. If you wish to
|
|
customize this image for your site, the
|
|
link:$$images/bzLifecycle.xml$$[diagram file]
|
|
is available in link:$$http://www.gnome.org/projects/dia$$[Dia's]
|
|
native XML format.
|
|
|
|
[[lifecycle-image]]
|
|
.Lifecycle of a Bugzilla Bug
|
|
image::images/bzLifecycle.png[]
|
|
|
|
[[query]]
|
|
=== Searching for Bugs
|
|
|
|
The Bugzilla Search page is the interface where you can find
|
|
any bug report, comment, or patch currently in the Bugzilla system. You
|
|
can play with it here:
|
|
link:$$http://landfill.bugzilla.org/bugzilla-3.6-branch/query.cgi$$[].
|
|
|
|
The Search page has controls for selecting different possible
|
|
values for all of the fields in a bug, as described above. For some
|
|
fields, multiple values can be selected. In those cases, Bugzilla
|
|
returns bugs where the content of the field matches any one of the selected
|
|
values. If none is selected, then the field can take any value.
|
|
|
|
After a search is run, you can save it as a Saved Search, which
|
|
will appear in the page footer. If you are in the group defined
|
|
by the "querysharegroup" parameter, you may share your queries
|
|
with other users, see <<savedsearches,Saved Searches>> for more details.
|
|
|
|
[[boolean]]
|
|
==== Boolean Charts
|
|
|
|
Highly advanced querying is done using Boolean Charts.
|
|
|
|
The boolean charts further restrict the set of results
|
|
returned by a query. It is possible to search for bugs
|
|
based on elaborate combinations of criteria.
|
|
|
|
The simplest boolean searches have only one term. These searches
|
|
permit the selected left _field_
|
|
to be compared using a
|
|
selectable _operator_ to a
|
|
specified _value._
|
|
Using the "And," "Or," and "Add Another Boolean Chart" buttons,
|
|
additional terms can be included in the query, further
|
|
altering the list of bugs returned by the query.
|
|
|
|
There are three fields in each row of a boolean search.
|
|
|
|
* _Field:_
|
|
the items being searched
|
|
|
|
* _Operator:_
|
|
the comparison operator
|
|
|
|
* _Value:_
|
|
the value to which the field is being compared
|
|
|
|
[[pronouns]]
|
|
===== Pronoun Substitution
|
|
|
|
Sometimes, a query needs to compare a user-related field
|
|
(such as ReportedBy) with a role-specific user (such as the
|
|
user running the query or the user to whom each bug is assigned).
|
|
When the operator is either "equals" or "notequals", the value
|
|
can be "%reporter%", "%assignee%", "%qacontact%", or "%user%".
|
|
The user pronoun
|
|
refers to the user who is executing the query or, in the case
|
|
of whining reports, the user who will be the recipient
|
|
of the report. The reporter, assignee, and qacontact
|
|
pronouns refer to the corresponding fields in the bug.
|
|
|
|
Boolean charts also let you type a group name in any user-related
|
|
field if the operator is either "equals", "notequals" or "anyexact".
|
|
This will let you query for any member belonging (or not) to the
|
|
specified group. The group name must be entered following the
|
|
"%group.foo%" syntax, where "foo" is the group name.
|
|
So if you are looking for bugs reported by any user being in the
|
|
"editbugs" group, then you can type "%group.editbugs%".
|
|
|
|
[[negation]]
|
|
===== Negation
|
|
|
|
At first glance, negation seems redundant. Rather than
|
|
searching for
|
|
[quote]
|
|
____
|
|
|
|
NOT("summary" "contains the string" "foo"),
|
|
|
|
____
|
|
|
|
one could search for
|
|
[quote]
|
|
____
|
|
|
|
("summary" "does not contain the string" "foo").
|
|
|
|
____
|
|
|
|
However, the search
|
|
[quote]
|
|
____
|
|
|
|
("CC" "does not contain the string" "@mozilla.org")
|
|
|
|
____
|
|
|
|
would find every bug where anyone on the CC list did not contain
|
|
"@mozilla.org" while
|
|
[quote]
|
|
____
|
|
|
|
NOT("CC" "contains the string" "@mozilla.org")
|
|
|
|
____
|
|
|
|
would find every bug where there was nobody on the CC list who
|
|
did contain the string. Similarly, the use of negation also permits
|
|
complex expressions to be built using terms OR'd together and then
|
|
negated. Negation permits queries such as
|
|
[quote]
|
|
____
|
|
|
|
NOT(("product" "equals" "update") OR
|
|
("component" "equals" "Documentation"))
|
|
|
|
____
|
|
|
|
to find bugs that are neither
|
|
in the update product or in the documentation component or
|
|
[quote]
|
|
____
|
|
|
|
NOT(("commenter" "equals" "%assignee%") OR
|
|
("component" "equals" "Documentation"))
|
|
|
|
____
|
|
|
|
to find non-documentation
|
|
bugs on which the assignee has never commented.
|
|
|
|
[[multiplecharts]]
|
|
===== Multiple Charts
|
|
|
|
The terms within a single row of a boolean chart are all
|
|
constraints on a single piece of data. If you are looking for
|
|
a bug that has two different people cc'd on it, then you need
|
|
to use two boolean charts. A search for
|
|
[quote]
|
|
____
|
|
|
|
("cc" "contains the string" "foo@") AND
|
|
("cc" "contains the string" "@mozilla.org")
|
|
|
|
____
|
|
|
|
would return only bugs with "foo@mozilla.org" on the cc list.
|
|
If you wanted bugs where there is someone on the cc list
|
|
containing "foo@" and someone else containing "@mozilla.org",
|
|
then you would need two boolean charts.
|
|
[quote]
|
|
____
|
|
|
|
First chart: ("cc" "contains the string" "foo@")
|
|
|
|
Second chart: ("cc" "contains the string" "@mozilla.org")
|
|
|
|
____
|
|
|
|
The bugs listed will be only the bugs where ALL the charts are true.
|
|
|
|
[[quicksearch]]
|
|
==== 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 can use it to find a bug by its number or its alias, too.
|
|
|
|
You'll find the Quicksearch box in Bugzilla's footer area.
|
|
On Bugzilla's front page, there is an additional
|
|
link:$$../../page.cgi?id=quicksearch.html$$[Help]
|
|
link which details how to use it.
|
|
|
|
[[casesensitivity]]
|
|
==== Case Sensitivity in Searches
|
|
|
|
Bugzilla queries are case-insensitive and accent-insensitive, when
|
|
used with either MySQL or Oracle databases. When using Bugzilla with
|
|
PostgreSQL, however, some queries are case-sensitive. This is due to
|
|
the way PostgreSQL handles case and accent sensitivity.
|
|
|
|
[[list]]
|
|
==== Bug Lists
|
|
|
|
If you run a search, a list of matching bugs will be returned.
|
|
|
|
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.
|
|
XML::
|
|
get the buglist in the XML format.
|
|
CSV::
|
|
get the buglist as comma-separated values, for import into e.g. a spreadsheet.
|
|
Feed::
|
|
get the buglist as an Atom feed. Copy this link into your
|
|
favorite feed reader. If you are using Firefox, you can also
|
|
save the list as a live bookmark by clicking the live bookmark
|
|
icon in the status bar. To limit the number of bugs in the feed,
|
|
add a limit=n parameter to the URL.
|
|
iCalendar::
|
|
Get the buglist as an iCalendar file. Each bug is represented as a
|
|
to-do item in the imported calendar.
|
|
Change Columns::
|
|
change the bug attributes which appear in the list.
|
|
Change several bugs at once::
|
|
If your account is sufficiently empowered, and more than one bug
|
|
appear in the bug list, this link is displayed which lets you make
|
|
the same change to all the bugs in the list - for example, changing
|
|
their assignee.
|
|
Send mail to bug assignees::
|
|
If more than one bug appear in the bug list and there are at least
|
|
two distinct bug assignees, this links is displayed which lets you
|
|
easily send a mail to the assignees of all bugs on the list.
|
|
Edit Search::
|
|
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.
|
|
Remember Search As::
|
|
You can give a search a name and remember it; a link will appear
|
|
in your page footer giving you quick access to run it again later.
|
|
|
|
If you would like to access the bug list from another program
|
|
it is often useful to have the list returned in something other
|
|
than HTML. By adding the ctype=type parameter into the bug list URL
|
|
you can specify several alternate formats. Besides the types described
|
|
above, the following formats are also supported: ECMAScript, also known
|
|
as JavaScript (ctype=js), and Resource Description Framework RDF/XML
|
|
(ctype=rdf).
|
|
|
|
[[individual-buglists]]
|
|
==== Adding/removing tags to/from bugs
|
|
|
|
You can add and remove tags from individual bugs, which let you find and
|
|
manage them more easily. Creating a new tag automatically generates a saved
|
|
search - whose name is the name of the tag - which lists bugs with this tag.
|
|
This saved search will be displayed in the footer of pages by default, as
|
|
all other saved searches. The main difference between tags and normal saved
|
|
searches is that saved searches, as described in the previous section, are
|
|
stored in the form of a list of matching criteria, while the saved search
|
|
generated by tags is a list of bug numbers. Consequently, you can easily
|
|
edit this list by either adding or removing tags from bugs. To enable this
|
|
feature, you have to turn on the "Enable tags for bugs" user
|
|
preference, see <<userpreferences,User Preferences>>. This feature is disabled
|
|
by default.
|
|
|
|
This feature is useful when you want to keep track of several bugs, but
|
|
for different reasons. Instead of adding yourself to the CC list of all
|
|
these bugs and mixing all these reasons, you can now store these bugs in
|
|
separate lists, e.g. "Keep in mind", "Interesting bugs",
|
|
or "Triage". One big advantage of this way to manage bugs
|
|
is that you can easily add or remove bugs one by one, which is not
|
|
possible to do with saved searches without having to edit the search
|
|
criteria again.
|
|
|
|
[[bugreports]]
|
|
=== Filing Bugs
|
|
|
|
[[fillingbugs]]
|
|
==== Reporting a New Bug
|
|
|
|
Years of bug writing experience has been distilled for your
|
|
reading pleasure into the
|
|
link:$$http://landfill.bugzilla.org/bugzilla-3.6-branch/page.cgi?id=bug-writing.html$$[ 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 bug is as follows:
|
|
|
|
* Click the "New" link available in the footer
|
|
of pages, or the "Enter a new bug report" link
|
|
displayed on the home page of the Bugzilla installation.
|
|
|
|
[NOTE]
|
|
====
|
|
If you want to file a test bug to see how Bugzilla works,
|
|
you can do it on one of our test installations on
|
|
link:$$http://landfill.bugzilla.org/bugzilla-3.6-branch/$$[Landfill].
|
|
====
|
|
|
|
* You first have to select the product in which you found a bug.
|
|
|
|
* You now see a form where you can specify the component (part of
|
|
the product which is affected by the bug you discovered; if you have
|
|
no idea, just select "General" if such a component exists),
|
|
the version of the program you were using, the Operating System and
|
|
platform your program is running on and the severity of the bug (if the
|
|
bug you found crashes the program, it's probably a major or a critical
|
|
bug; if it's a typo somewhere, that's something pretty minor; if it's
|
|
something you would like to see implemented, then that's an enhancement).
|
|
|
|
* You now have to give a short but descriptive summary of the bug you found.
|
|
"My program is crashing all the time" is a very poor summary
|
|
and doesn't help developers at all. Try something more meaningful or
|
|
your bug will probably be ignored due to a lack of precision.
|
|
The next step is to give a very detailed list of steps to reproduce
|
|
the problem you encountered. Try to limit these steps to a minimum set
|
|
required to reproduce the problem. This will make the life of
|
|
developers easier, and the probability that they consider your bug in
|
|
a reasonable timeframe will be much higher.
|
|
|
|
[NOTE]
|
|
====
|
|
Try to make sure that everything in the summary is also in the first
|
|
comment. Summaries are often updated and this will ensure your original
|
|
information is easily accessible.
|
|
====
|
|
|
|
* As you file the bug, you can also attach a document (testcase, patch,
|
|
or screenshot of the problem).
|
|
|
|
* Depending on the Bugzilla installation you are using and the product in
|
|
which you are filing the bug, you can also request developers to consider
|
|
your bug in different ways (such as requesting review for the patch you
|
|
just attached, requesting your bug to block the next release of the
|
|
product, and many other product specific requests).
|
|
|
|
* Now is a good time to read your bug report again. Remove all misspellings,
|
|
otherwise your bug may not be found by developers running queries for some
|
|
specific words, and so your bug would not get any attention.
|
|
Also make sure you didn't forget any important information developers
|
|
should know in order to reproduce the problem, and make sure your
|
|
description of the problem is explicit and clear enough.
|
|
When you think your bug report is ready to go, the last step is to
|
|
click the "Commit" button to add your report into the database.
|
|
|
|
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.
|
|
|
|
[[cloningbugs]]
|
|
==== Clone an Existing Bug
|
|
|
|
Starting with version 2.20, Bugzilla has a feature that allows you
|
|
to clone an existing bug. The newly created bug will inherit
|
|
most settings from the old bug. This allows you to track more
|
|
easily similar concerns in a new bug. To use this, go to the bug
|
|
that you want to clone, then click the "Clone This Bug"
|
|
link on the bug page. This will take you to the "Enter Bug"
|
|
page that is filled with the values that the old bug has.
|
|
You can change those values and/or texts if needed.
|
|
|
|
[[attachments]]
|
|
=== Attachments
|
|
|
|
You should 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.
|
|
|
|
You should make sure to trim screenshots. There's no need to show the
|
|
whole screen if you are pointing out a single-pixel problem.
|
|
|
|
Bugzilla stores and uses a Content-Type for each attachment
|
|
(e.g. text/html). To download an attachment as a different
|
|
Content-Type (e.g. application/xhtml+xml), you can override this
|
|
using a 'content_type' parameter on the URL, e.g.
|
|
_$$&content_type=text/plain$$_.
|
|
|
|
If you have a really large attachment, something that does not need to
|
|
be recorded forever (as most attachments are), or something that is too
|
|
big for your database, you can mark your attachment as a
|
|
"Big File", assuming the administrator of the installation
|
|
has enabled this feature. Big Files are stored directly on disk instead
|
|
of in the database. The maximum size of a "Big File" is
|
|
normally larger than the maximum size of a regular attachment. Independently
|
|
of the storage system used, an administrator can delete these attachments
|
|
at any time. Nevertheless, if these files are stored in the database, the
|
|
"allow_attachment_deletion" parameter (which is turned off
|
|
by default) must be enabled in order to delete them.
|
|
|
|
Also, if the administrator turned on the "allow_attach_url"
|
|
parameter, you can enter the URL pointing to the attachment instead of
|
|
uploading the attachment itself. For example, this is useful if you want to
|
|
point to an external application, a website or a very large file. Note that
|
|
there is no guarantee that the source file will always be available, nor
|
|
that its content will remain unchanged.
|
|
|
|
[[patchviewer]]
|
|
==== Patch Viewer
|
|
|
|
Viewing and reviewing patches in Bugzilla is often difficult due to
|
|
lack of context, improper format and the inherent readability issues that
|
|
raw patches present. Patch Viewer is an enhancement to Bugzilla designed
|
|
to fix that by offering increased context, linking to sections, and
|
|
integrating with Bonsai, LXR and CVS.
|
|
|
|
Patch viewer allows you to:
|
|
|
|
View patches in color, with side-by-side view rather than trying
|
|
to interpret the contents of the patch. +
|
|
See the difference between two patches. +
|
|
Get more context in a patch. +
|
|
Collapse and expand sections of a patch for easy
|
|
reading. +
|
|
Link to a particular section of a patch for discussion or
|
|
review +
|
|
Go to Bonsai or LXR to see more context, blame, and
|
|
cross-references for the part of the patch you are looking at +
|
|
Create a rawtext unified format diff out of any patch, no
|
|
matter what format it came from
|
|
|
|
[[patchviewer_view]]
|
|
===== Viewing Patches in Patch Viewer
|
|
|
|
The main way to view a patch in patch viewer is to click on the
|
|
"Diff" link next to a patch in the Attachments list on a bug. You may
|
|
also do this within the edit window by clicking the "View Attachment As
|
|
Diff" button in the Edit Attachment screen.
|
|
|
|
[[patchviewer_diff]]
|
|
===== Seeing the Difference Between Two Patches
|
|
|
|
To see the difference between two patches, you must first view the
|
|
newer patch in Patch Viewer. Then select the older patch from the
|
|
dropdown at the top of the page ("Differences between [dropdown] and
|
|
this patch") and click the "Diff" button. This will show you what
|
|
is new or changed in the newer patch.
|
|
|
|
[[patchviewer_context]]
|
|
===== Getting More Context in a Patch
|
|
|
|
To get more context in a patch, you put a number in the textbox at
|
|
the top of Patch Viewer ("Patch / File / [textbox]") and hit enter.
|
|
This will give you that many lines of context before and after each
|
|
change. Alternatively, you can click on the "File" link there and it
|
|
will show each change in the full context of the file. This feature only
|
|
works against files that were diffed using "cvs diff".
|
|
|
|
[[patchviewer_collapse]]
|
|
===== Collapsing and Expanding Sections of a Patch
|
|
|
|
To view only a certain set of files in a patch (for example, if a
|
|
patch is absolutely huge and you want to only review part of it at a
|
|
time), you can click the "(+)" and "(-)" links next to each file (to
|
|
expand it or collapse it). If you want to collapse all files or expand
|
|
all files, you can click the "Collapse All" and "Expand All" links at the
|
|
top of the page.
|
|
|
|
[[patchviewer_link]]
|
|
===== Linking to a Section of a Patch
|
|
|
|
To link to a section of a patch (for example, if you want to be
|
|
able to give someone a URL to show them which part you are talking
|
|
about) you simply click the "Link Here" link on the section header. The
|
|
resulting URL can be copied and used in discussion.
|
|
|
|
[[patchviewer_bonsai_lxr]]
|
|
===== Going to Bonsai and LXR
|
|
|
|
To go to Bonsai to get blame for the lines you are interested in,
|
|
you can click the "Lines XX-YY" link on the section header you are
|
|
interested in. This works even if the patch is against an old
|
|
version of the file, since Bonsai stores all versions of the file.
|
|
|
|
To go to LXR, you click on the filename on the file header
|
|
(unfortunately, since LXR only does the most recent version, line
|
|
numbers are likely to rot).
|
|
|
|
[[patchviewer_unified_diff]]
|
|
===== Creating a Unified Diff
|
|
|
|
If the patch is not in a format that you like, you can turn it
|
|
into a unified diff format by clicking the "Raw Unified" link at the top
|
|
of the page.
|
|
|
|
[[hintsandtips]]
|
|
=== Hints and Tips
|
|
|
|
This section distills some Bugzilla tips and best practices
|
|
that have been developed.
|
|
|
|
==== Autolinkification
|
|
|
|
Bugzilla comments are plain text - so typing <U> will
|
|
produce less-than, U, greater-than rather than underlined text.
|
|
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 a link:
|
|
link:$$http://www.bugzilla.org$$[].
|
|
Other strings which get linkified in the obvious manner are:
|
|
|
|
bug 12345 +
|
|
comment 7 +
|
|
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.
|
|
|
|
[[commenting]]
|
|
==== 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,
|
|
if you do it out of habit, but full mail/news-style
|
|
four line ASCII art creations are not.
|
|
|
|
[[comment-wrapping]]
|
|
==== Server-Side Comment Wrapping
|
|
|
|
Bugzilla stores comments unwrapped and wraps them at display time. This
|
|
ensures proper wrapping in all browsers. Lines beginning with the ">"
|
|
character are assumed to be quotes, and are not wrapped.
|
|
|
|
[[dependencytree]]
|
|
==== Dependency Tree
|
|
|
|
On the "Dependency tree" page linked from each bug
|
|
page, you can see the dependency relationship from the bug as a
|
|
tree structure.
|
|
|
|
You can change how much depth to show, and you can hide resolved bugs
|
|
from this page. You can also collaps/expand dependencies for
|
|
each bug on the tree view, using the [-]/[+] buttons that appear
|
|
before its summary. This option is not available for terminal
|
|
bugs in the tree (that don't have further dependencies).
|
|
|
|
[[timetracking]]
|
|
=== Time Tracking Information
|
|
|
|
Users who belong to the group specified by the "timetrackinggroup"
|
|
parameter have access to time-related fields. Developers can see
|
|
deadlines and estimated times to fix bugs, and can provide time spent
|
|
on these bugs.
|
|
|
|
At any time, a summary of the time spent by developers on bugs is
|
|
accessible either from bug lists when clicking the "Time Summary"
|
|
button or from individual bugs when clicking the "Summarize time"
|
|
link in the time tracking table. The _$$summarize_time.cgi$$_
|
|
page lets you view this information either per developer or per bug,
|
|
and can be split on a month basis to have greater details on how time
|
|
is spent by developers.
|
|
|
|
As soon as a bug is marked as RESOLVED, the remaining time expected
|
|
to fix the bug is set to zero. This lets QA people set it again for
|
|
their own usage, and it will be set to zero again when the bug will
|
|
be marked as CLOSED.
|
|
|
|
[[userpreferences]]
|
|
=== User Preferences
|
|
|
|
Once logged in, you can customize various aspects of
|
|
Bugzilla via the "Preferences" link in the page footer.
|
|
The preferences are split into five tabs:
|
|
|
|
[[generalpreferences]]
|
|
==== General Preferences
|
|
|
|
This tab allows you to change several default settings of Bugzilla.
|
|
|
|
[options="compact"]
|
|
|
|
* Bugzilla's general appearance (skin) - select which skin to use.
|
|
Bugzilla supports adding custom skins.
|
|
|
|
* Quote the associated comment when you click on its reply link - sets
|
|
the behavior of the comment "Reply" link. Options include quoting the
|
|
full comment, just reference the comment number, or turn the link off.
|
|
|
|
* Language used in email - select which language email will be sent in,
|
|
from the list of available languages.
|
|
|
|
* After changing a bug - This controls what page is displayed after
|
|
changes to a bug are submitted. The options include to show the bug
|
|
just modified, to show the next bug in your list, or to do nothing.
|
|
|
|
* Enable tags for bugs - turn bug tagging on or off.
|
|
|
|
* Zoom textareas large when in use (requires JavaScript) - enable or
|
|
disable the automatic expanding of text areas when text is being
|
|
entered into them.
|
|
|
|
* Field separator character for CSV files -
|
|
Select between a comma and semi-colon for exported CSV bug lists.
|
|
|
|
* Automatically add me to the CC list of bugs I change - set default
|
|
behavior of CC list. Options include "Always", "Never", and "Only
|
|
if I have no role on them".
|
|
|
|
* When viewing a bug, show comments in this order -
|
|
controls the order of comments. Options include "Oldest
|
|
to Newest", "Newest to Oldest" and "Newest to Oldest, but keep the
|
|
bug description at the top".
|
|
|
|
* Show a quip at the top of each bug list - controls
|
|
whether a quip will be shown on the Bug list page.
|
|
|
|
[[emailpreferences]]
|
|
==== Email Preferences
|
|
|
|
This tab allows you to enable or disable email notification on
|
|
specific events.
|
|
|
|
In general, users have almost complete control over how much (or
|
|
how little) email Bugzilla sends them. If you want to receive the
|
|
maximum amount of email possible, click the "Enable All
|
|
Mail" button. If you don't want to receive any email from
|
|
Bugzilla at all, click the "Disable All Mail" button.
|
|
|
|
[NOTE]
|
|
====
|
|
A Bugzilla administrator can stop a user from receiving
|
|
bugmail by clicking the "Bugmail Disabled" checkbox
|
|
when editing the user account. This is a drastic step
|
|
best taken only for disabled accounts, as it overrides
|
|
the user's individual mail preferences.
|
|
====
|
|
|
|
There are two global options -- "Email me when someone
|
|
asks me to set a flag" and "Email me when someone
|
|
sets a flag I asked for". These define how you want to
|
|
receive bugmail with regards to flags. Their use is quite
|
|
straightforward; enable the checkboxes if you want Bugzilla to
|
|
send you mail under either of the above conditions.
|
|
|
|
If you'd like to set your bugmail to something besides
|
|
'Completely ON' and 'Completely OFF', the
|
|
"Field/recipient specific options" table
|
|
allows you to do just that. The rows of the table
|
|
define events that can happen to a bug -- things like
|
|
attachments being added, new comments being made, the
|
|
priority changing, etc. The columns in the table define
|
|
your relationship with the bug:
|
|
|
|
[options="compact"]
|
|
|
|
* Reporter - Where you are the person who initially
|
|
reported the bug. Your name/account appears in the
|
|
"Reporter:" field.
|
|
|
|
* Assignee - Where you are the person who has been
|
|
designated as the one responsible for the bug. Your
|
|
name/account appears in the "Assigned To:"
|
|
field of the bug.
|
|
|
|
* QA Contact - You are one of the designated
|
|
QA Contacts for the bug. Your account appears in the
|
|
"QA Contact:" text-box of the bug.
|
|
|
|
* CC - You are on the list CC List for the bug.
|
|
Your account appears in the "CC:" text box
|
|
of the bug.
|
|
|
|
* Voter - You have placed one or more votes for the bug.
|
|
Your account appears only if someone clicks on the
|
|
"Show votes for this bug" link on the bug.
|
|
|
|
[NOTE]
|
|
====
|
|
Some columns may not be visible for your installation, depending
|
|
on your site's configuration.
|
|
====
|
|
|
|
To fine-tune your bugmail, decide the events for which you want
|
|
to receive bugmail; then decide if you want to receive it all
|
|
the time (enable the checkbox for every column), or only when
|
|
you have a certain relationship with a bug (enable the checkbox
|
|
only for those columns). For example: if you didn't want to
|
|
receive mail when someone added themselves to the CC list, you
|
|
could uncheck all the boxes in the "CC Field Changes"
|
|
line. As another example, if you never wanted to receive email
|
|
on bugs you reported unless the bug was resolved, you would
|
|
un-check all boxes in the "Reporter" column
|
|
except for the one on the "The bug is resolved or
|
|
verified" row.
|
|
|
|
[NOTE]
|
|
====
|
|
Bugzilla adds the "X-Bugzilla-Reason" header to
|
|
all bugmail it sends, describing the recipient's relationship
|
|
(AssignedTo, Reporter, QAContact, CC, or Voter) to the bug.
|
|
This header can be used to do further client-side filtering.
|
|
====
|
|
|
|
Bugzilla has a feature called "Users Watching".
|
|
When you enter one or more comma-delineated user accounts (usually email
|
|
addresses) into the text entry box, you will receive a copy of all the
|
|
bugmail those users are sent (security settings permitting).
|
|
This powerful functionality enables seamless transitions as developers
|
|
change projects or users go on holiday.
|
|
|
|
[NOTE]
|
|
====
|
|
The ability to watch other users may not be available in all
|
|
Bugzilla installations. If you don't see this feature, and feel
|
|
that you need it, speak to your administrator.
|
|
====
|
|
|
|
Each user listed in the "Users watching you" field
|
|
has you listed in their "Users to watch" list
|
|
and can get bugmail according to your relationship to the bug and
|
|
their "Field/recipient specific options" setting.
|
|
|
|
[[savedsearches]]
|
|
==== Saved Searches
|
|
|
|
On this tab you can view and run any Saved Searches that you have
|
|
created, and also any Saved Searches that other members of the group
|
|
defined in the "querysharegroup" parameter have shared.
|
|
Saved Searches can be added to the page footer from this screen.
|
|
If somebody is sharing a Search with a group she or he is allowed to
|
|
<<groups,assign users to>>, the sharer may opt to have
|
|
the Search show up in the footer of the group's direct members by default.
|
|
|
|
[[accountpreferences]]
|
|
==== Name and Password
|
|
|
|
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.
|
|
|
|
[[permissionsettings]]
|
|
==== Permissions
|
|
|
|
This is a purely informative page which outlines your current
|
|
permissions on this installation of Bugzilla.
|
|
|
|
A complete list of permissions is below. Only users with
|
|
_editusers_ privileges can change the permissions
|
|
of other users.
|
|
|
|
admin::
|
|
Indicates user is an Administrator.
|
|
|
|
bz_canusewhineatothers::
|
|
Indicates user can configure whine reports for other users.
|
|
|
|
bz_canusewhines::
|
|
Indicates user can configure whine reports for self.
|
|
|
|
bz_sudoers::
|
|
Indicates user can perform actions as other users.
|
|
|
|
bz_sudo_protect::
|
|
Indicates user can not be impersonated by other users.
|
|
|
|
canconfirm::
|
|
Indicates user can confirm a bug or mark it a duplicate.
|
|
|
|
creategroups::
|
|
Indicates user can create and destroy groups.
|
|
|
|
editbugs::
|
|
Indicates user can edit all bug fields.
|
|
|
|
editclassifications::
|
|
Indicates user can create, destroy, and edit classifications.
|
|
|
|
editcomponents::
|
|
Indicates user can create, destroy, and edit components.
|
|
|
|
editkeywords::
|
|
Indicates user can create, destroy, and edit keywords.
|
|
|
|
editusers::
|
|
Indicates user can edit or disable users.
|
|
|
|
tweakparams::
|
|
Indicates user can change Parameters.
|
|
|
|
[NOTE]
|
|
====
|
|
For more information on how permissions work in Bugzilla (i.e. who can
|
|
change what), see <<cust-change-permissions,Customizing Who Can Change What>>.
|
|
====
|
|
|
|
[[reporting]]
|
|
=== Reports and Charts
|
|
|
|
As well as the standard buglist, Bugzilla has two more ways of
|
|
viewing sets of bugs. These are the reports (which give different
|
|
views of the current state of the database) and charts (which plot
|
|
the changes in particular sets of bugs over time.)
|
|
|
|
[[reports]]
|
|
==== Reports
|
|
|
|
A report is a view of the current state of the bug database.
|
|
|
|
You can run either an HTML-table-based report, or a graphical
|
|
line/pie/bar-chart-based one. The two have different pages to
|
|
define them, but are close cousins - once you've defined and
|
|
viewed a report, you can switch between any of the different
|
|
views of the data at will.
|
|
|
|
Both report types are based on the idea of defining a set of bugs
|
|
using the standard search interface, and then choosing some
|
|
aspect of that set to plot on the horizontal and/or vertical axes.
|
|
You can also get a form of 3-dimensional report by choosing to have
|
|
multiple images or tables.
|
|
|
|
So, for example, you could use the search form to choose "all
|
|
bugs in the WorldControl product", and then plot their severity
|
|
against their component to see which component had had the largest
|
|
number of bad bugs reported against it.
|
|
|
|
Once you've defined your parameters and hit "Generate Report",
|
|
you can switch between HTML, CSV, Bar, Line and Pie. (Note: Pie
|
|
is only available if you didn't define a vertical axis, as pie
|
|
charts don't have one.) The other controls are fairly self-explanatory;
|
|
you can change the size of the image if you find text is overwriting
|
|
other text, or the bars are too thin to see.
|
|
|
|
[[charts]]
|
|
==== Charts
|
|
|
|
A chart is a view of the state of the bug database over time.
|
|
|
|
Bugzilla currently has two charting systems - Old Charts and New
|
|
Charts. Old Charts have been part of Bugzilla for a long time; they
|
|
chart each status and resolution for each product, and that's all.
|
|
They are deprecated, and going away soon - we won't say any more
|
|
about them.
|
|
New Charts are the future - they allow you to chart anything you
|
|
can define as a search.
|
|
|
|
[NOTE]
|
|
====
|
|
Both charting forms require the administrator to set up the
|
|
data-gathering script. If you can't see any charts, ask them whether
|
|
they have done so.
|
|
====
|
|
|
|
An individual line on a chart is called a data set.
|
|
All data sets are organised into categories and subcategories. The
|
|
data sets that Bugzilla defines automatically use the Product name
|
|
as a Category and Component names as Subcategories, but there is no
|
|
need for you to follow that naming scheme with your own charts if
|
|
you don't want to.
|
|
|
|
Data sets may be public or private. Everyone sees public data sets in
|
|
the list, but only their creator sees private data sets. Only
|
|
administrators can make data sets public.
|
|
No two data sets, even two private ones, can have the same set of
|
|
category, subcategory and name. So if you are creating private data
|
|
sets, one idea is to have the Category be your username.
|
|
|
|
===== Creating Charts
|
|
|
|
You create a chart by selecting a number of data sets from the
|
|
list, and pressing Add To List for each. In the List Of Data Sets
|
|
To Plot, you can define the label that data set will have in the
|
|
chart's legend, and also ask Bugzilla to Sum a number of data sets
|
|
(e.g. you could Sum data sets representing RESOLVED, VERIFIED and
|
|
CLOSED in a particular product to get a data set representing all
|
|
the resolved bugs in that product.)
|
|
|
|
If you've erroneously added a data set to the list, select it
|
|
using the checkbox and click Remove. Once you add more than one
|
|
data set, a "Grand Total" line
|
|
automatically appears at the bottom of the list. If you don't want
|
|
this, simply remove it as you would remove any other line.
|
|
|
|
You may also choose to plot only over a certain date range, and
|
|
to cumulate the results - that is, to plot each one using the
|
|
previous one as a baseline, so the top line gives a sum of all
|
|
the data sets. It's easier to try than to explain :-)
|
|
|
|
Once a data set is in the list, one can also perform certain
|
|
actions on it. For example, one can edit the
|
|
data set's parameters (name, frequency etc.) if it's one you
|
|
created or if you are an administrator.
|
|
|
|
Once you are happy, click Chart This List to see the chart.
|
|
|
|
[[charts-new-series]]
|
|
===== Creating New Data Sets
|
|
|
|
You may also create new data sets of your own. To do this,
|
|
click the "create a new data set" link on the Create Chart page.
|
|
This takes you to a search-like interface where you can define
|
|
the search that Bugzilla will plot. At the bottom of the page,
|
|
you choose the category, sub-category and name of your new
|
|
data set.
|
|
|
|
If you have sufficient permissions, you can make the data set public,
|
|
and reduce the frequency of data collection to less than the default
|
|
seven days.
|
|
|
|
[[flags]]
|
|
=== Flags
|
|
|
|
A flag is a kind of status that can be set on bugs or attachments
|
|
to indicate that the bugs/attachments are in a certain state.
|
|
Each installation can define its own set of flags that can be set
|
|
on bugs or attachments.
|
|
|
|
If your installation has defined a flag, you can set or unset that flag,
|
|
and if your administrator has enabled requesting of flags, you can submit
|
|
a request for another user to set the flag.
|
|
|
|
To set a flag, select either "+" or "-" from the drop-down menu next to
|
|
the name of the flag in the "Flags" list. The meaning of these values are
|
|
flag-specific and thus cannot be described in this documentation,
|
|
but by way of example, setting a flag named "review" to "+" may indicate
|
|
that the bug/attachment has passed review, while setting it to "-"
|
|
may indicate that the bug/attachment has failed review.
|
|
|
|
To unset a flag, click its drop-down menu and select the blank value.
|
|
Note that marking an attachment as obsolete automatically cancels all
|
|
pending requests for the attachment.
|
|
|
|
If your administrator has enabled requests for a flag, request a flag
|
|
by selecting "?" from the drop-down menu and then entering the username
|
|
of the user you want to set the flag in the text field next to the menu.
|
|
|
|
A set flag appears in bug reports and on "edit attachment" pages with the
|
|
abbreviated username of the user who set the flag prepended to the
|
|
flag name. For example, if Jack sets a "review" flag to "+", it appears
|
|
as Jack: review [ + ]
|
|
|
|
A requested flag appears with the user who requested the flag prepended
|
|
to the flag name and the user who has been requested to set the flag
|
|
appended to the flag name within parentheses. For example, if Jack
|
|
asks Jill for review, it appears as Jack: review [ ? ] (Jill).
|
|
|
|
You can browse through open requests made of you and by you by selecting
|
|
'My Requests' from the footer. You can also look at open requests limited
|
|
by other requesters, requestees, products, components, and flag names from
|
|
this page. Note that you can use '-' for requestee to specify flags with
|
|
'no requestee' set.
|
|
|
|
[[whining]]
|
|
=== Whining
|
|
|
|
Whining is a feature in Bugzilla that can regularly annoy users at
|
|
specified times. Using this feature, users can execute saved searches
|
|
at specific times (i.e. the 15th of the month at midnight) or at
|
|
regular intervals (i.e. every 15 minutes on Sundays). The results of the
|
|
searches are sent to the user, either as a single email or as one email
|
|
per bug, along with some descriptive text.
|
|
|
|
[WARNING]
|
|
====
|
|
Throughout this section it will be assumed that all users are members
|
|
of the bz_canusewhines group, membership in which is required in order
|
|
to use the Whining system. You can easily make all users members of
|
|
the bz_canusewhines group by setting the User RegExp to ".*" (without
|
|
the quotes).
|
|
|
|
Also worth noting is the bz_canusewhineatothers group. Members of this
|
|
group can create whines for any user or group in Bugzilla using a
|
|
extended form of the whining interface. Features only available to
|
|
members of the bz_canusewhineatothers group will be noted in the
|
|
appropriate places.
|
|
====
|
|
|
|
[NOTE]
|
|
For whining to work, a special Perl script must be executed at regular
|
|
intervals. More information on this is available in
|
|
<<installation-whining,Whining Installation>>.
|
|
|
|
[NOTE]
|
|
This section does not cover the whineatnews.pl script. See
|
|
<<installation-whining-cron,The Whining Cron>> for more information on
|
|
The Whining Cron.
|
|
|
|
[[whining-overview]]
|
|
==== The Event
|
|
|
|
The whining system defines an "Event" as one or more queries being
|
|
executed at regular intervals, with the results of said queries (if
|
|
there are any) being emailed to the user. Events are created by
|
|
clicking on the "Add new event" button.
|
|
|
|
Once a new event is created, the first thing to set is the "Email
|
|
subject line". The contents of this field will be used in the subject
|
|
line of every email generated by this event. In addition to setting a
|
|
subject, space is provided to enter some descriptive text that will be
|
|
included at the top of each message (to help you in understanding why
|
|
you received the email in the first place).
|
|
|
|
The next step is to specify when the Event is to be run (the Schedule)
|
|
and what searches are to be performed (the Searches).
|
|
|
|
[[whining-schedule]]
|
|
==== Whining Schedule
|
|
|
|
Each whining event is associated with zero or more schedules. A
|
|
schedule is used to specify when the query (specified below) is to be
|
|
run. A new event starts out with no schedules (which means it will
|
|
never run, as it is not scheduled to run). To add a schedule, press
|
|
the "Add a new schedule" button.
|
|
|
|
Each schedule includes an interval, which you use to tell Bugzilla
|
|
when the event should be run. An event can be run on certain days of
|
|
the week, certain days of the month, during weekdays (defined as
|
|
Monday through Friday), or every day.
|
|
|
|
[WARNING]
|
|
====
|
|
Be careful if you set your event to run on the 29th, 30th, or 31st of
|
|
the month, as your event may not run exactly when expected. If you
|
|
want your event to run on the last day of the month, select "Last day
|
|
of the month" as the interval.
|
|
====
|
|
|
|
Once you have specified the day(s) on which the event is to be run, you
|
|
should now specify the time at which the event is to be run. You can
|
|
have the event run at a certain hour on the specified day(s), or
|
|
every hour, half-hour, or quarter-hour on the specified day(s).
|
|
|
|
If a single schedule does not execute an event as many times as you
|
|
would want, you can create another schedule for the same event. For
|
|
example, if you want to run an event on days whose numbers are
|
|
divisible by seven, you would need to add four schedules to the event,
|
|
setting the schedules to run on the 7th, 14th, 21st, and 28th (one day
|
|
per schedule) at whatever time (or times) you choose.
|
|
|
|
[NOTE]
|
|
====
|
|
If you are a member of the bz_canusewhineatothers group, then you
|
|
will be presented with another option: "Mail to". Using this you
|
|
can control who will receive the emails generated by this event. You
|
|
can choose to send the emails to a single user (identified by email
|
|
address) or a single group (identified by group name). To send to
|
|
multiple users or groups, create a new schedule for each additional
|
|
user/group.
|
|
====
|
|
|
|
[[whining-query]]
|
|
==== Whining Searches
|
|
|
|
Each whining event is associated with zero or more searches. A search
|
|
is any saved search to be run as part of the specified schedule (see
|
|
above). You start out without any searches associated with the event
|
|
(which means that the event will not run, as there will never be any
|
|
results to return). To add a search, press the "Include search" button.
|
|
|
|
The first field to examine in your newly added search is the Sort field.
|
|
Searches are run, and results included, in the order specified by the
|
|
Sort field. Searches with smaller Sort values will run before searches
|
|
with bigger Sort values.
|
|
|
|
The next field to examine is the Search field. This is where you
|
|
choose the actual search that is to be run. Instead of defining search
|
|
parameters here, you are asked to choose from the list of saved
|
|
searches (the same list that appears at the bottom of every Bugzilla
|
|
page). You are only allowed to choose from searches that you have
|
|
saved yourself (the default saved search, "My Bugs", is not a valid
|
|
choice). If you do not have any saved searches, you can take this
|
|
opportunity to create one (see <<list,Bug Lists>>).
|
|
|
|
[NOTE]
|
|
====
|
|
When running queries, the whining system acts as if you are the user
|
|
executing the query. This means that the whining system will ignore
|
|
bugs that match your query, but that you can not access.
|
|
====
|
|
|
|
Once you have chosen the saved search to be executed, give the query a
|
|
descriptive title. This title will appear in the email, above the
|
|
results of the query. If you choose "One message per bug", the query
|
|
title will appear at the top of each email that contains a bug matching
|
|
your query.
|
|
|
|
Finally, decide if the results of the query should be sent in a single
|
|
email, or if each bug should appear in its own email.
|
|
|
|
[WARNING]
|
|
====
|
|
Think carefully before checking the "One message per bug" box. If
|
|
you create a query that matches thousands of bugs, you will receive
|
|
thousands of emails!
|
|
====
|
|
|
|
==== Saving Your Changes
|
|
|
|
Once you have defined at least one schedule, and created at least one
|
|
query, go ahead and "Update/Commit". This will save your Event and make
|
|
it available for immediate execution.
|
|
|
|
[NOTE]
|
|
====
|
|
If you ever feel like deleting your event, you may do so using the
|
|
"Remove Event" button in the upper-right corner of each Event. You
|
|
can also modify an existing event, so long as you "Update/Commit"
|
|
after completing your modifications.
|
|
====
|
|
|
|
[[customization]]
|
|
== Customizing Bugzilla
|
|
|
|
[[extensions]]
|
|
=== Bugzilla Extensions
|
|
|
|
One of the best ways to customize Bugzilla is by writing a Bugzilla
|
|
Extension. Bugzilla Extensions let you modify both the code and
|
|
UI of Bugzilla in a way that can be distributed to other Bugzilla
|
|
users and ported forward to future versions of Bugzilla with minimal
|
|
effort.
|
|
|
|
See the link:$$api/Bugzilla/Extension.html$$[Bugzilla Extension documentation] for information on how to write an Extension.
|
|
|
|
[[cust-skins]]
|
|
=== Custom Skins
|
|
|
|
Bugzilla allows you to have multiple skins. These are custom CSS and possibly
|
|
also custom images for Bugzilla. To create a new custom skin, you have two
|
|
choices:
|
|
|
|
* Make a single CSS file, and put it in the
|
|
_skins/contrib_ directory.
|
|
|
|
* Make a directory that contains all the same CSS file
|
|
names as _skins/standard/_, and put
|
|
your directory in _skins/contrib/_.
|
|
|
|
After you put the file or the directory there, make sure to run checksetup.pl
|
|
so that it can reset the file permissions correctly.
|
|
|
|
After you have installed the new skin, it will show up as an option in the
|
|
user's General Preferences. If you would like to force a particular skin on all
|
|
users, just select it in the Default Preferences and then uncheck "Enabled" on
|
|
the preference.
|
|
|
|
[[cust-templates]]
|
|
=== Template Customization
|
|
|
|
Administrators can configure the look and feel of Bugzilla without
|
|
having to edit Perl files or face the nightmare of massive merge
|
|
conflicts when they upgrade to a newer version in the future.
|
|
|
|
Templatization also makes localized versions of Bugzilla possible,
|
|
for the first time. It's possible to have Bugzilla's UI language
|
|
determined by the user's browser. More information is available in
|
|
<<template-http-accept,Configuring Bugzilla to Detect the User's Language>>.
|
|
|
|
[[template-directory]]
|
|
==== Template Directory Structure
|
|
|
|
The template directory structure starts with top level directory
|
|
named _template_, which contains a directory
|
|
for each installed localization. The next level defines the
|
|
language used in the templates. Bugzilla comes with English
|
|
templates, so the directory name is _en_,
|
|
and we will discuss _template/en_ throughout
|
|
the documentation. Below _template/en_ is the
|
|
_default_ directory, which contains all the
|
|
standard templates shipped with Bugzilla.
|
|
|
|
[WARNING]
|
|
====
|
|
A directory _data/templates_ also exists;
|
|
this is where Template Toolkit puts the compiled versions of
|
|
the templates from either the default or custom directories.
|
|
_Do not_ directly edit the files in this
|
|
directory, or all your changes will be lost the next time
|
|
Template Toolkit recompiles the templates.
|
|
====
|
|
|
|
[[template-method]]
|
|
==== Choosing a Customization Method
|
|
|
|
If you want to edit Bugzilla's templates, the first decision
|
|
you must make is how you want to go about doing so. There are two
|
|
choices, and which you use depends mainly on the scope of your
|
|
modifications, and the method you plan to use to upgrade Bugzilla.
|
|
|
|
The first method of making customizations is to directly edit the
|
|
templates found in _template/en/default_.
|
|
This is probably the best way to go about it if you are going to
|
|
be upgrading Bugzilla through CVS, because if you then execute
|
|
a _cvs update_, any changes you have made will
|
|
be merged automagically with the updated versions.
|
|
|
|
[NOTE]
|
|
====
|
|
If you use this method, and CVS conflicts occur during an
|
|
update, the conflicted templates (and possibly other parts
|
|
of your installation) will not work until they are resolved.
|
|
====
|
|
|
|
The second method is to copy the templates to be modified
|
|
into a mirrored directory structure under
|
|
_template/en/custom_. Templates in this
|
|
directory structure automatically override any identically-named
|
|
and identically-located templates in the
|
|
_default_ directory.
|
|
|
|
[NOTE]
|
|
====
|
|
The _custom_ directory does not exist
|
|
at first and must be created if you want to use it.
|
|
====
|
|
|
|
The second method of customization should be used if you
|
|
use the overwriting method of upgrade, because otherwise
|
|
your changes will be lost. This method may also be better if
|
|
you are using the 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.
|
|
|
|
Using this method, your installation may break if incompatible
|
|
changes are made to the template interface. Such changes should
|
|
be documented in the release notes, provided you are using a
|
|
stable release of Bugzilla. If you use using unstable code, you will
|
|
need to deal with this one yourself, although if possible the changes
|
|
will be mentioned before they occur in the deprecations section of the
|
|
previous stable release's release notes.
|
|
|
|
[NOTE]
|
|
====
|
|
Regardless of which method you choose, it is recommended that
|
|
you run _./checksetup.pl_ after
|
|
editing any templates in the _template/en/default_
|
|
directory, and after creating or editing any templates in the
|
|
_custom_ directory.
|
|
====
|
|
|
|
[WARNING]
|
|
====
|
|
It is _required_ that you run
|
|
_./checksetup.pl_ after creating a new
|
|
template in the _custom_ directory. Failure
|
|
to do so will raise an incomprehensible error message.
|
|
====
|
|
|
|
[[template-edit]]
|
|
==== How To Edit Templates
|
|
|
|
[NOTE]
|
|
====
|
|
If you are making template changes that you intend on submitting back
|
|
for inclusion in standard Bugzilla, you should read the relevant
|
|
sections of the
|
|
link:$$http://www.bugzilla.org/docs/developer.html$$[Developers' Guide].
|
|
====
|
|
|
|
The syntax of the Template Toolkit language is beyond the scope of
|
|
this guide. It's reasonably easy to pick up by looking at the current
|
|
templates; or, you can read the manual, available on the
|
|
link:$$http://www.template-toolkit.org$$[Template Toolkit home page].
|
|
|
|
One thing you should take particular care about is the need
|
|
to properly HTML filter data that has been passed into the template.
|
|
This means that if the data can possibly contain special HTML characters
|
|
such as <, and the data was not intended to be HTML, they need to be
|
|
converted to entity form, i.e. &lt;. You use the 'html' filter in the
|
|
Template Toolkit to do this. If you forget, 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, i.e. %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.
|
|
|
|
[[template-formats]]
|
|
==== Template Formats and Types
|
|
|
|
Some CGI's have the ability to use more than one template. For example,
|
|
_buglist.cgi_ can output itself as RDF, or as two
|
|
formats of HTML (complex and simple). The mechanism that provides this
|
|
feature is extensible.
|
|
|
|
Bugzilla can support different types of output, which again can have
|
|
multiple formats. In order to request a certain type, you can append
|
|
the &ctype=<contenttype> (such as rdf or html) to the
|
|
_<cginame>.cgi_ URL. If you would like to
|
|
retrieve a certain format, you can use the &format=<format>
|
|
(such as simple or complex) in the URL.
|
|
|
|
To see if a CGI supports multiple output formats and types, grep the
|
|
CGI for "get_format". If it's not present, adding
|
|
multiple format/type support isn't too hard - see how it's done in
|
|
other CGIs, e.g. config.cgi.
|
|
|
|
To make a new format template for a CGI which supports this,
|
|
open a current template for
|
|
that CGI and take note of the INTERFACE comment (if present.) This
|
|
comment defines what variables are passed into this template. If
|
|
there isn't one, I'm afraid you'll have to read the template and
|
|
the code to find out what information you get.
|
|
|
|
Write your template in whatever markup or text style is appropriate.
|
|
|
|
You now need to decide what content type you want your template
|
|
served as. The content types are defined in the
|
|
_Bugzilla/Constants.pm_ file in the
|
|
_contenttypes_
|
|
constant. If your content type is not there, add it. Remember
|
|
the three- or four-letter tag assigned to your content type.
|
|
This tag will be part of the template filename.
|
|
|
|
[NOTE]
|
|
====
|
|
After adding or changing a content type, it's suitable to edit
|
|
_Bugzilla/Constants.pm_ in order to reflect
|
|
the changes. Also, the file should be kept up to date after an
|
|
upgrade if content types have been customized in the past.
|
|
====
|
|
|
|
Save the template as _<stubname>-<formatname>.<contenttypetag>.tmpl_.
|
|
Try out the template by calling the CGI as
|
|
_<cginame>.cgi?format=<formatname>&ctype=<type>_ .
|
|
|
|
[[template-specific]]
|
|
==== Particular Templates
|
|
|
|
There are a few templates you may be particularly interested in
|
|
customizing for your installation.
|
|
|
|
__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.
|
|
|
|
__global/variables.none.tmpl__:
|
|
This defines a list of terms that may be changed in order to
|
|
"brand" the Bugzilla instance In this way, terms
|
|
like "bugs" can be replaced with "issues"
|
|
across the whole Bugzilla installation. The name
|
|
"Bugzilla" and other words can be customized as well.
|
|
|
|
__list/table.html.tmpl__:
|
|
This template controls the appearance of the bug lists created
|
|
by Bugzilla. Editing this template allows per-column control of
|
|
the width and title of a column, the maximum display length of
|
|
each entry, and the wrap behaviour of long entries.
|
|
For long bug lists, Bugzilla inserts a 'break' every 100 bugs by
|
|
default; this behaviour is also controlled by this template, and
|
|
that value can be modified here.
|
|
|
|
__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 not wish to go to the effort of creating custom fields in
|
|
Bugzilla, yet you want to make sure that each bug report contains
|
|
a number of pieces of important information for which there is not
|
|
a special field. The bug entry system has been designed in an
|
|
extensible fashion to enable you to add arbitrary HTML widgets,
|
|
such as drop-down lists or textboxes, to the bug entry page
|
|
and have their values appear formatted in the initial comment.
|
|
A hidden field that indicates the format should be added inside
|
|
the form in order to make the template functional. Its value should
|
|
be the suffix of the template filename. For example, if the file
|
|
is called _create-cust.html.tmpl_, then
|
|
|
|
----
|
|
<input type="hidden" name="format" value="cust">
|
|
----
|
|
|
|
should be used inside the form.
|
|
|
|
An example of this is the mozilla.org
|
|
link:$$http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl&format=guided$$[guided bug submission form]. The code for this comes with the Bugzilla
|
|
distribution as an example for you to copy. It can be found in the
|
|
files
|
|
_create-guided.html.tmpl_ and
|
|
_comment-guided.html.tmpl_.
|
|
|
|
So to use this feature, create a custom template for
|
|
_$$enter_bug.cgi$$_. The default template, on which you
|
|
could base it, is
|
|
_custom/bug/create/create.html.tmpl_.
|
|
Call it _create-<formatname>.html.tmpl_, and
|
|
in it, add widgets for each piece of information you'd like
|
|
collected - such as a build number, or set of steps to reproduce.
|
|
|
|
Then, create a template like
|
|
_custom/bug/create/comment.txt.tmpl_, and call it
|
|
_comment-<formatname>.txt.tmpl_. This
|
|
template should reference the form fields you have created using
|
|
the syntax _[% form.<fieldname> %]_. When a
|
|
bug report is
|
|
submitted, the initial comment attached to the bug report will be
|
|
formatted according to the layout of this template.
|
|
|
|
For example, if your custom enter_bug template had a field
|
|
|
|
----
|
|
<input type="text" name="buildid" size="30">
|
|
----
|
|
|
|
and then your comment.txt.tmpl had
|
|
|
|
----
|
|
BuildID: [% form.buildid %]
|
|
----
|
|
|
|
then something like
|
|
|
|
----
|
|
BuildID: 20020303
|
|
----
|
|
|
|
would appear in the initial comment.
|
|
|
|
[[template-http-accept]]
|
|
==== Configuring Bugzilla to Detect the User's Language
|
|
|
|
Bugzilla honours the user's Accept: HTTP header. You can install
|
|
templates in other languages, and Bugzilla will pick the most appropriate
|
|
according to a priority order defined by you. Many
|
|
language templates can be obtained from link:$$http://www.bugzilla.org/download.html#localizations$$[]. Instructions
|
|
for submitting new languages are also available from that location.
|
|
|
|
[[cust-change-permissions]]
|
|
=== Customizing Who Can Change What
|
|
|
|
[WARNING]
|
|
====
|
|
This feature should be considered experimental; the Bugzilla code you
|
|
will be changing is not stable, and could change or move between
|
|
versions. Be aware that if you make modifications as outlined here,
|
|
you may have
|
|
to re-make them or port them if Bugzilla changes internally between
|
|
versions, and you upgrade.
|
|
====
|
|
|
|
Companies often have rules about which employees, or classes of employees,
|
|
are allowed to change certain things in the bug system. For example,
|
|
only the bug's designated QA Contact may be allowed to VERIFY the bug.
|
|
Bugzilla has been
|
|
designed to make it easy for you to write your own custom rules to define
|
|
who is allowed to make what sorts of value transition.
|
|
|
|
By default, assignees, QA owners and users
|
|
with _editbugs_ privileges can edit all fields of bugs,
|
|
except group restrictions (unless they are members of the groups they
|
|
are trying to change). Bug reporters also have the ability to edit some
|
|
fields, but in a more restrictive manner. Other users, without
|
|
_editbugs_ privileges, can not edit
|
|
bugs, except to comment and add themselves to the CC list.
|
|
|
|
For maximum flexibility, customizing this means editing Bugzilla's Perl
|
|
code. This gives the administrator complete control over exactly who is
|
|
allowed to do what. The relevant method is called
|
|
_$$check_can_change_field()$$_,
|
|
and is found in _Bug.pm_ in your
|
|
Bugzilla/ directory. If you open that file and search for
|
|
"sub check_can_change_field", you'll find it.
|
|
|
|
This function has been carefully commented to allow you to see exactly
|
|
how it works, and give you an idea of how to make changes to it.
|
|
Certain marked sections should not be changed - these are
|
|
the "plumbing" which makes the rest of the function work.
|
|
In between those sections, you'll find snippets of code like:
|
|
|
|
----
|
|
# Allow the assignee to change anything.
|
|
if ($ownerid eq $whoid) {
|
|
return 1;
|
|
}
|
|
----
|
|
|
|
It's fairly obvious what this piece of code does.
|
|
|
|
So, how does one go about changing this function? Well, simple changes
|
|
can be made just by removing pieces - for example, if you wanted to
|
|
prevent any user adding a comment to a bug, just remove the lines marked
|
|
"Allow anyone to change comments." If you don't want the
|
|
Reporter to have any special rights on bugs they have filed, just
|
|
remove the entire section that deals with the Reporter.
|
|
|
|
More complex customizations are not much harder. Basically, you add
|
|
a check in the right place in the function, i.e. after all the variables
|
|
you are using have been set up. So, don't look at $ownerid before
|
|
$ownerid has been obtained from the database. You can either add a
|
|
positive check, which returns 1 (allow) if certain conditions are true,
|
|
or a negative check, which returns 0 (deny.) E.g.:
|
|
|
|
----
|
|
if ($field eq "qacontact") {
|
|
if (Bugzilla->user->in_group("quality_assurance")) {
|
|
return 1;
|
|
}
|
|
else {
|
|
return 0;
|
|
}
|
|
}
|
|
----
|
|
|
|
This says that only users in the group "quality_assurance" can change
|
|
the QA Contact field of a bug.
|
|
|
|
Getting more weird:
|
|
|
|
----
|
|
if (($field eq "priority") &&
|
|
(Bugzilla->user->email =~ /.*\@example\.com$/))
|
|
{
|
|
if ($oldvalue eq "P1") {
|
|
return 1;
|
|
}
|
|
else {
|
|
return 0;
|
|
}
|
|
}
|
|
----
|
|
|
|
This says that if the user is trying to change the priority field,
|
|
and their email address is @example.com, they can only do so if the
|
|
old value of the field was "P1". Not very useful, but illustrative.
|
|
|
|
[WARNING]
|
|
====
|
|
If you are modifying _$$process_bug.cgi$$_ in any
|
|
way, do not change the code that is bounded by DO_NOT_CHANGE blocks.
|
|
Doing so could compromise security, or cause your installation to
|
|
stop working entirely.
|
|
====
|
|
|
|
For a list of possible field names, look at the bugs table in the
|
|
database. If you need help writing custom rules for your organization,
|
|
ask in the newsgroup.
|
|
|
|
[[integration]]
|
|
=== Integrating Bugzilla with Third-Party Tools
|
|
|
|
Many utilities and applications can integrate with Bugzilla,
|
|
either on the client- or server-side. None of them are maintained
|
|
by the Bugzilla community, nor are they tested during our
|
|
QA tests, so use them at your own risk. They are listed at
|
|
link:$$https://wiki.mozilla.org/Bugzilla:Addons$$[].
|
|
|
|
[[troubleshooting]]
|
|
[appendix]
|
|
== Troubleshooting
|
|
|
|
This section gives solutions to common Bugzilla installation
|
|
problems. If none of the section headings seems to match your
|
|
problem, read the general advice.
|
|
|
|
[[general-advice]]
|
|
=== General Advice
|
|
|
|
If you can't get _checksetup.pl_ to run to
|
|
completion, it normally explains what's wrong and how to fix it.
|
|
If you can't work it out, or if it's being uncommunicative, post
|
|
the errors in the
|
|
link:$$news://news.mozilla.org/mozilla.support.bugzilla$$[mozilla.support.bugzilla]
|
|
newsgroup.
|
|
|
|
If you have made it all the way through
|
|
<<installation,Installation>> and
|
|
<<configuration,Configuration>> but accessing the Bugzilla
|
|
URL doesn't work, the first thing to do is to check your web server error
|
|
log. For Apache, this is often located at
|
|
_$$/etc/logs/httpd/error_log$$_. The error messages
|
|
you see may be self-explanatory enough to enable you to diagnose and
|
|
fix the problem. If not, see below for some commonly-encountered
|
|
errors. If that doesn't help, post the errors to the newsgroup.
|
|
|
|
Bugzilla can also log all user-based errors (and many code-based errors)
|
|
that occur, without polluting the web server's error log. To enable
|
|
Bugzilla error logging, create a file that Bugzilla can write to, named
|
|
_errorlog_, in the Bugzilla _data_
|
|
directory. Errors will be logged as they occur, and will include the type
|
|
of the error, the IP address and username (if available) of the user who
|
|
triggered the error, and the values of all environment variables; if a
|
|
form was being submitted, the data in the form will also be included.
|
|
To disable error logging, delete or rename the
|
|
_errorlog_ file.
|
|
|
|
[[trbl-testserver]]
|
|
=== The Apache web server is not serving Bugzilla pages
|
|
|
|
After you have run _checksetup.pl_ twice,
|
|
run _testserver.pl http://yoursite.yourdomain/yoururl_
|
|
to confirm that your web server is configured properly for
|
|
Bugzilla.
|
|
|
|
----
|
|
bash$ ./testserver.pl http://landfill.bugzilla.org/bugzilla-tip
|
|
TEST-OK Webserver is running under group id in $webservergroup.
|
|
TEST-OK Got ant picture.
|
|
TEST-OK Webserver is executing CGIs.
|
|
TEST-OK Webserver is preventing fetch of http://landfill.bugzilla.org/bugzilla-tip/localconfig.
|
|
----
|
|
|
|
[[trbl-perlmodule]]
|
|
=== I installed a Perl module, but _checksetup.pl_ claims it's not installed!
|
|
|
|
This could be caused by one of two things:
|
|
|
|
. You have two versions of Perl on your machine. You are installing
|
|
modules into one, and Bugzilla is using the other. Rerun the CPAN
|
|
commands (or manual compile) using the full path to Perl from the
|
|
top of _checksetup.pl_. This will make sure you
|
|
are installing the modules in the right place.
|
|
|
|
. The permissions on your library directories are set incorrectly.
|
|
They must, at the very least, be readable by the web server user or
|
|
group. It is recommended that they be world readable.
|
|
|
|
[[trbl-dbdSponge]]
|
|
=== 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):
|
|
|
|
----
|
|
DBD::Sponge::db prepare failed: Cannot determine NUM_OF_FIELDS at D:/Perl/site/lib/DBD/mysql.pm line 248.
|
|
SV = NULL(0x0) at 0x20fc444
|
|
REFCNT = 1
|
|
FLAGS = (PADBUSY,PADMY)
|
|
|
|
----
|
|
|
|
To fix this, go to
|
|
_<path-to-perl>/lib/DBD/sponge.pm_
|
|
in your Perl installation and replace
|
|
|
|
----
|
|
my $numFields;
|
|
if ($attribs->{'NUM_OF_FIELDS'}) {
|
|
$numFields = $attribs->{'NUM_OF_FIELDS'};
|
|
} elsif ($attribs->{'NAME'}) {
|
|
$numFields = @{$attribs->{NAME}};
|
|
|
|
----
|
|
|
|
with
|
|
|
|
----
|
|
my $numFields;
|
|
if ($attribs->{'NUM_OF_FIELDS'}) {
|
|
$numFields = $attribs->{'NUM_OF_FIELDS'};
|
|
} elsif ($attribs->{'NAMES'}) {
|
|
$numFields = @{$attribs->{NAMES}};
|
|
|
|
----
|
|
|
|
(note the S added to NAME.)
|
|
|
|
[[paranoid-security]]
|
|
=== 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:
|
|
|
|
----
|
|
cannot chdir(/var/spool/mqueue): Permission denied
|
|
|
|
----
|
|
|
|
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. This will allow any process running on your
|
|
machine the ability to _read_ the
|
|
_/var/spool/mqueue_ directory.
|
|
|
|
[[trbl-relogin-everyone]]
|
|
=== Everybody is constantly being forced to relogin
|
|
|
|
The most-likely cause is that the "cookiepath" parameter
|
|
is not set correctly in the Bugzilla configuration. You can change this (if
|
|
you're a Bugzilla administrator) from the editparams.cgi page via the web interface.
|
|
|
|
The value of the cookiepath parameter should be the actual directory
|
|
containing your Bugzilla installation, _as seen by the end-user's web browser_. Leading and trailing slashes are mandatory. You can
|
|
also set the cookiepath to any directory which is a parent of the Bugzilla
|
|
directory (such as '/', the root directory). But you can't put something
|
|
that isn't at least a partial match or it won't work. What you're actually
|
|
doing is restricting the end-user's browser to sending the cookies back only
|
|
to that directory.
|
|
|
|
How do you know if you want your specific Bugzilla directory or the
|
|
whole site?
|
|
|
|
If you have only one Bugzilla running on the server, and you don't
|
|
mind having other applications on the same server with it being able to see
|
|
the cookies (you might be doing this on purpose if you have other things on
|
|
your site that share authentication with Bugzilla), then you'll want to have
|
|
the cookiepath set to "/", or to a sufficiently-high enough directory that
|
|
all of the involved apps can see the cookies.
|
|
|
|
.Examples of urlbase/cookiepath pairs for sharing login cookies
|
|
====
|
|
urlbase is http://bugzilla.mozilla.org/ +
|
|
cookiepath is /
|
|
|
|
urlbase is http://tools.mysite.tld/bugzilla/ +
|
|
but you have http://tools.mysite.tld/someotherapp/ which shares authentication with your Bugzilla. +
|
|
cookiepath is /
|
|
====
|
|
|
|
On the other hand, if you have more than one Bugzilla running on the
|
|
server (some people do - we do on landfill) then you need to have the
|
|
cookiepath restricted enough so that the different Bugzillas don't
|
|
confuse their cookies with one another.
|
|
|
|
.Examples of urlbase/cookiepath pairs to restrict the login cookie
|
|
====
|
|
urlbase is http://landfill.bugzilla.org/bugzilla-tip/ +
|
|
cookiepath is /bugzilla-tip/
|
|
|
|
urlbase is http://landfill.bugzilla.org/bugzilla-2.16-branch/ +
|
|
cookiepath is /bugzilla-2.16-branch/
|
|
====
|
|
|
|
If you had cookiepath set to "/" at any point in the
|
|
past and need to set it to something more restrictive
|
|
(i.e. "/bugzilla/"), you can safely do this without
|
|
requiring users to delete their Bugzilla-related cookies in their
|
|
browser (this is true starting with Bugzilla 2.18 and Bugzilla 2.16.5).
|
|
|
|
[[trbl-index]]
|
|
=== _index.cgi_ doesn't show up unless specified in the URL
|
|
|
|
You probably need to set up your web server in such a way that it
|
|
will serve the index.cgi page as an index page.
|
|
|
|
If you are using Apache, you can do this by adding
|
|
_index.cgi_ to the end of the
|
|
DirectoryIndex line
|
|
as mentioned in <<http-apache,Bugzilla using Apache>>.
|
|
|
|
[[trbl-passwd-encryption]]
|
|
=== checksetup.pl reports "Client does not support authentication protocol requested by server..."
|
|
|
|
This error is occurring because you are using the new password
|
|
encryption that comes with MySQL 4.1, while your
|
|
_DBD::mysql_ module was compiled against an
|
|
older version of MySQL. If you recompile _DBD::mysql_
|
|
against the current MySQL libraries (or just obtain a newer version
|
|
of this module) then the error may go away.
|
|
|
|
If that does not fix the problem, or if you cannot recompile the
|
|
existing module (e.g. you're running Windows) and/or don't want to
|
|
replace it (e.g. you want to keep using a packaged version), then a
|
|
workaround is available from the MySQL docs:
|
|
link:$$http://dev.mysql.com/doc/mysql/en/Old_client.html$$[]
|
|
|
|
[[patches]]
|
|
[appendix]
|
|
== Contrib
|
|
|
|
There are a number of unofficial Bugzilla add-ons in the
|
|
_$$$BUGZILLA_ROOT/contrib/$$_
|
|
directory. This section documents them.
|
|
|
|
[[cmdline]]
|
|
=== Command-line Search Interface
|
|
|
|
There are a suite of Unix utilities for searching Bugzilla from the
|
|
command line. They live in the
|
|
_contrib/cmdline_ directory.
|
|
There are three files - _query.conf_,
|
|
_buglist_ and _bugs_.
|
|
|
|
[WARNING]
|
|
====
|
|
These files pre-date the templatization work done as part of the
|
|
2.16 release, and have not been updated.
|
|
====
|
|
|
|
_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 that 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
|
|
that is available 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_
|
|
|
|
[[cmdline-bugmail]]
|
|
=== Command-line 'Send Unsent Bug-mail' tool
|
|
|
|
Within the _contrib_ directory
|
|
exists a utility with the descriptive (if compact) name
|
|
of _sendunsentbugmail.pl_. The purpose of this
|
|
script is, simply, to send out any bug-related mail that should
|
|
have been sent by now, but for one reason or another has not.
|
|
|
|
To accomplish this task, _sendunsentbugmail.pl_ uses
|
|
the same mechanism as the _sanitycheck.cgi_ script;
|
|
it scans through the entire database looking for bugs with changes that
|
|
were made more than 30 minutes ago, but where there is no record of
|
|
anyone related to that bug having been sent mail. Having compiled a list,
|
|
it then uses the standard rules to determine who gets mail, and sends it
|
|
out.
|
|
|
|
As the script runs, it indicates the bug for which it is currently
|
|
sending mail; when it has finished, it gives a numerical count of how
|
|
many mails were sent and how many people were excluded. (Individual
|
|
user names are not recorded or displayed.) If the script produces
|
|
no output, that means no unsent mail was detected.
|
|
|
|
__Usage__: move the sendunsentbugmail.pl script
|
|
up into the main directory, ensure it has execute permission, and run it
|
|
from the command line (or from a cron job) with no parameters.
|
|
|
|
[[install-perlmodules-manual]]
|
|
[appendix]
|
|
== Manual Installation of Perl Modules
|
|
|
|
If you need to install Perl modules manually, here's how it's done.
|
|
Find the module on http://cpan.org/ site, download the _.tar.gz_ package using your browser,
|
|
and then apply this magic incantation, as root:
|
|
|
|
----
|
|
bash# tar -xzvf <module>.tar.gz
|
|
bash# cd <module>
|
|
----
|
|
|
|
Then, if a Build.PL file exists in the module directory, run:
|
|
|
|
----
|
|
bash# perl Build.PL
|
|
bash# perl Build
|
|
bash# perl Build test
|
|
bash# perl Build install
|
|
----
|
|
|
|
Else run:
|
|
|
|
----
|
|
bash# perl Makefile.PL
|
|
bash# make
|
|
bash# make test
|
|
bash# make install
|
|
----
|
|
|
|
[NOTE]
|
|
====
|
|
In order to compile source code under Windows you will need to obtain
|
|
a working compiler toolchain including a 'make' utility;
|
|
link:http://strawberryperl.com/[Strawberry Perl] contains one.
|
|
====
|
|
|
|
[[gfdl]]
|
|
[appendix]
|
|
== GNU Free Documentation License
|
|
|
|
Version 1.1, March 2000
|
|
|
|
[quote]
|
|
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.
|
|
|
|
[[gfdl-0]]
|
|
=== Preamble
|
|
|
|
The purpose of this License is to make a manual, textbook, or other
|
|
written document "free" in the sense of freedom: to assure everyone the
|
|
effective freedom to copy and redistribute it, with or without modifying
|
|
it, either commercially or noncommercially. Secondarily, this License
|
|
preserves for the author and publisher a way to get credit for their
|
|
work, while not being considered responsible for modifications made by
|
|
others.
|
|
|
|
This License is a kind of "copyleft", which means that derivative
|
|
works of the document must themselves be free in the same sense. It
|
|
complements the GNU General Public License, which is a copyleft license
|
|
designed for free software.
|
|
|
|
We have designed this License in order to use it for manuals for
|
|
free software, because free software needs free documentation: a free
|
|
program should come with manuals providing the same freedoms that the
|
|
software does. But this License is not limited to software manuals; it
|
|
can be used for any textual work, regardless of subject matter or whether
|
|
it is published as a printed book. We recommend this License principally
|
|
for works whose purpose is instruction or reference.
|
|
|
|
[[gfdl-1]]
|
|
=== Applicability and Definition
|
|
|
|
This License applies to any manual or other work that contains a
|
|
notice placed by the copyright holder saying it can be distributed under
|
|
the terms of this License. The "Document", below, refers to any such
|
|
manual or work. Any member of the public is a licensee, and is addressed
|
|
as "you".
|
|
|
|
A "Modified Version" of the Document means any work containing the
|
|
Document or a portion of it, either copied verbatim, or with
|
|
modifications and/or translated into another language.
|
|
|
|
A "Secondary Section" is a named appendix or a front-matter section
|
|
of the Document that deals exclusively with the relationship of the
|
|
publishers or authors of the Document to the Document's overall subject
|
|
(or to related matters) and contains nothing that could fall directly
|
|
within that overall subject. (For example, if the Document is in part a
|
|
textbook of mathematics, a Secondary Section may not explain any
|
|
mathematics.) The relationship could be a matter of historical connection
|
|
with the subject or with related matters, or of legal, commercial,
|
|
philosophical, ethical or political position regarding them.
|
|
|
|
The "Invariant Sections" are certain Secondary Sections whose
|
|
titles are designated, as being those of Invariant Sections, in the
|
|
notice that says that the Document is released under this License.
|
|
|
|
The "Cover Texts" are certain short passages of text that are
|
|
listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says
|
|
that the Document is released under this License.
|
|
|
|
A "Transparent" copy of the Document means a machine-readable copy,
|
|
represented in a format whose specification is available to the general
|
|
public, whose contents can be viewed and edited directly and
|
|
straightforwardly with generic text editors or (for images composed of
|
|
pixels) generic paint programs or (for drawings) some widely available
|
|
drawing editor, and that is suitable for input to text formatters or for
|
|
automatic translation to a variety of formats suitable for input to text
|
|
formatters. A copy made in an otherwise Transparent file format whose
|
|
markup has been designed to thwart or discourage subsequent modification
|
|
by readers is not Transparent. A copy that is not "Transparent" is called
|
|
"Opaque".
|
|
|
|
Examples of suitable formats for Transparent copies include plain
|
|
ASCII without markup, Texinfo input format, LaTeX input format, SGML or
|
|
XML using a publicly available DTD, and standard-conforming simple HTML
|
|
designed for human modification. Opaque formats include PostScript, PDF,
|
|
proprietary formats that can be read and edited only by proprietary word
|
|
processors, SGML or XML for which the DTD and/or processing tools are not
|
|
generally available, and the machine-generated HTML produced by some word
|
|
processors for output purposes only.
|
|
|
|
The "Title Page" means, for a printed book, the title page itself,
|
|
plus such following pages as are needed to hold, legibly, the material
|
|
this License requires to appear in the title page. For works in formats
|
|
which do not have any title page as such, "Title Page" means the text
|
|
near the most prominent appearance of the work's title, preceding the
|
|
beginning of the body of the text.
|
|
|
|
[[gfdl-2]]
|
|
=== Verbatim Copying
|
|
|
|
You may copy and distribute the Document in any medium, either
|
|
commercially or noncommercially, provided that this License, the
|
|
copyright notices, and the license notice saying this License applies to
|
|
the Document are reproduced in all copies, and that you add no other
|
|
conditions whatsoever to those of this License. You may not use technical
|
|
measures to obstruct or control the reading or further copying of the
|
|
copies you make or distribute. However, you may accept compensation in
|
|
exchange for copies. If you distribute a large enough number of copies
|
|
you must also follow the conditions in section 3.
|
|
|
|
You may also lend copies, under the same conditions stated above,
|
|
and you may publicly display copies.
|
|
|
|
[[gfdl-3]]
|
|
=== Copying in Quantity
|
|
|
|
If you publish printed copies of the Document numbering more than
|
|
100, and the Document's license notice requires Cover Texts, you must
|
|
enclose the copies in covers that carry, clearly and legibly, all these
|
|
Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts
|
|
on the back cover. Both covers must also clearly and legibly identify you
|
|
as the publisher of these copies. The front cover must present the full
|
|
title with all words of the title equally prominent and visible. You may
|
|
add other material on the covers in addition. Copying with changes
|
|
limited to the covers, as long as they preserve the title of the Document
|
|
and satisfy these conditions, can be treated as verbatim copying in other
|
|
respects.
|
|
|
|
If the required texts for either cover are too voluminous to fit
|
|
legibly, you should put the first ones listed (as many as fit reasonably)
|
|
on the actual cover, and continue the rest onto adjacent pages.
|
|
|
|
If you publish or distribute Opaque copies of the Document
|
|
numbering more than 100, you must either include a machine-readable
|
|
Transparent copy along with each Opaque copy, or state in or with each
|
|
Opaque copy a publicly-accessible computer-network location containing a
|
|
complete Transparent copy of the Document, free of added material, which
|
|
the general network-using public has access to download anonymously at no
|
|
charge using public-standard network protocols. If you use the latter
|
|
option, you must take reasonably prudent steps, when you begin
|
|
distribution of Opaque copies in quantity, to ensure that this
|
|
Transparent copy will remain thus accessible at the stated location until
|
|
at least one year after the last time you distribute an Opaque copy
|
|
(directly or through your agents or retailers) of that edition to the
|
|
public.
|
|
|
|
It is requested, but not required, that you contact the authors of
|
|
the Document well before redistributing any large number of copies, to
|
|
give them a chance to provide you with an updated version of the
|
|
Document.
|
|
|
|
[[gfdl-4]]
|
|
=== Modifications
|
|
|
|
You may copy and distribute a Modified Version of the Document
|
|
under the conditions of sections 2 and 3 above, provided that you release
|
|
the Modified Version under precisely this License, with the Modified
|
|
Version filling the role of the Document, thus licensing distribution and
|
|
modification of the Modified Version to whoever possesses a copy of it.
|
|
In addition, you must do these things in the Modified Version:
|
|
|
|
. Use in the Title Page (and on the covers, if any) a title
|
|
distinct from that of the Document, and from those of previous
|
|
versions (which should, if there were any, be listed in the History
|
|
section of the Document). You may use the same title as a previous
|
|
version if the original publisher of that version gives
|
|
permission.
|
|
|
|
. List on the Title Page, as authors, one or more persons or
|
|
entities responsible for authorship of the modifications in the
|
|
Modified Version, together with at least five of the principal
|
|
authors of the Document (all of its principal authors, if it has less
|
|
than five).
|
|
|
|
. State on the Title page the name of the publisher of the
|
|
Modified Version, as the publisher.
|
|
|
|
. Preserve all the copyright notices of the Document.
|
|
|
|
. Add an appropriate copyright notice for your modifications
|
|
adjacent to the other copyright notices.
|
|
|
|
. Include, immediately after the copyright notices, a license
|
|
notice giving the public permission to use the Modified Version under
|
|
the terms of this License, in the form shown in the Addendum
|
|
below.
|
|
|
|
. Preserve in that license notice the full lists of Invariant
|
|
Sections and required Cover Texts given in the Document's license
|
|
notice.
|
|
|
|
. Include an unaltered copy of this License.
|
|
|
|
. Preserve the section entitled "History", and its title, and add
|
|
to it an item stating at least the title, year, new authors, and
|
|
publisher of the Modified Version as given on the Title Page. If
|
|
there is no section entitled "History" in the Document, create one
|
|
stating the title, year, authors, and publisher of the Document as
|
|
given on its Title Page, then add an item describing the Modified
|
|
Version as stated in the previous sentence.
|
|
|
|
. Preserve the network location, if any, given in the Document
|
|
for public access to a Transparent copy of the Document, and likewise
|
|
the network locations given in the Document for previous versions it
|
|
was based on. These may be placed in the "History" section. You may
|
|
omit a network location for a work that was published at least four
|
|
years before the Document itself, or if the original publisher of the
|
|
version it refers to gives permission.
|
|
|
|
. In any section entitled "Acknowledgements" or "Dedications",
|
|
preserve the section's title, and preserve in the section all the
|
|
substance and tone of each of the contributor acknowledgements and/or
|
|
dedications given therein.
|
|
|
|
. Preserve all the Invariant Sections of the Document, unaltered
|
|
in their text and in their titles. Section numbers or the equivalent
|
|
are not considered part of the section titles.
|
|
|
|
. Delete any section entitled "Endorsements". Such a section may
|
|
not be included in the Modified Version.
|
|
|
|
. Do not retitle any existing section as "Endorsements" or to
|
|
conflict in title with any Invariant Section.
|
|
|
|
If the Modified Version includes new front-matter sections or
|
|
appendices that qualify as Secondary Sections and contain no material
|
|
copied from the Document, you may at your option designate some or all of
|
|
these sections as invariant. To do this, add their titles to the list of
|
|
Invariant Sections in the Modified Version's license notice. These titles
|
|
must be distinct from any other section titles.
|
|
|
|
You may add a section entitled "Endorsements", provided it contains
|
|
nothing but endorsements of your Modified Version by various parties--for
|
|
example, statements of peer review or that the text has been approved by
|
|
an organization as the authoritative definition of a standard.
|
|
|
|
You may add a passage of up to five words as a Front-Cover Text,
|
|
and a passage of up to 25 words as a Back-Cover Text, to the end of the
|
|
list of Cover Texts in the Modified Version. Only one passage of
|
|
Front-Cover Text and one of Back-Cover Text may be added by (or through
|
|
arrangements made by) any one entity. If the Document already includes a
|
|
cover text for the same cover, previously added by you or by arrangement
|
|
made by the same entity you are acting on behalf of, you may not add
|
|
another; but you may replace the old one, on explicit permission from the
|
|
previous publisher that added the old one.
|
|
|
|
The author(s) and publisher(s) of the Document do not by this
|
|
License give permission to use their names for publicity for or to assert
|
|
or imply endorsement of any Modified Version.
|
|
|
|
[[gfdl-5]]
|
|
=== Combining Documents
|
|
|
|
You may combine the Document with other documents released under
|
|
this License, under the terms defined in section 4 above for modified
|
|
versions, provided that you include in the combination all of the
|
|
Invariant Sections of all of the original documents, unmodified, and list
|
|
them all as Invariant Sections of your combined work in its license
|
|
notice.
|
|
|
|
The combined work need only contain one copy of this License, and
|
|
multiple identical Invariant Sections may be replaced with a single copy.
|
|
If there are multiple Invariant Sections with the same name but different
|
|
contents, make the title of each such section unique by adding at the end
|
|
of it, in parentheses, the name of the original author or publisher of
|
|
that section if known, or else a unique number. Make the same adjustment
|
|
to the section titles in the list of Invariant Sections in the license
|
|
notice of the combined work.
|
|
|
|
In the combination, you must combine any sections entitled
|
|
"History" in the various original documents, forming one section entitled
|
|
"History"; likewise combine any sections entitled "Acknowledgements", and
|
|
any sections entitled "Dedications". You must delete all sections
|
|
entitled "Endorsements."
|
|
|
|
[[gfdl-6]]
|
|
=== Collections of Documents
|
|
|
|
You may make a collection consisting of the Document and other
|
|
documents released under this License, and replace the individual copies
|
|
of this License in the various documents with a single copy that is
|
|
included in the collection, provided that you follow the rules of this
|
|
License for verbatim copying of each of the documents in all other
|
|
respects.
|
|
|
|
You may extract a single document from such a collection, and
|
|
distribute it individually under this License, provided you insert a copy
|
|
of this License into the extracted document, and follow this License in
|
|
all other respects regarding verbatim copying of that document.
|
|
|
|
[[gfdl-7]]
|
|
=== Aggregation with Independent Works
|
|
|
|
A compilation of the Document or its derivatives with other
|
|
separate and independent documents or works, in or on a volume of a
|
|
storage or distribution medium, does not as a whole count as a Modified
|
|
Version of the Document, provided no compilation copyright is claimed for
|
|
the compilation. Such a compilation is called an "aggregate", and this
|
|
License does not apply to the other self-contained works thus compiled
|
|
with the Document, on account of their being thus compiled, if they are
|
|
not themselves derivative works of the Document.
|
|
|
|
If the Cover Text requirement of section 3 is applicable to these
|
|
copies of the Document, then if the Document is less than one quarter of
|
|
the entire aggregate, the Document's Cover Texts may be placed on covers
|
|
that surround only the Document within the aggregate. Otherwise they must
|
|
appear on covers around the whole aggregate.
|
|
|
|
[[gfdl-8]]
|
|
=== Translation
|
|
|
|
Translation is considered a kind of modification, so you may
|
|
distribute translations of the Document under the terms of section 4.
|
|
Replacing Invariant Sections with translations requires special
|
|
permission from their copyright holders, but you may include translations
|
|
of some or all Invariant Sections in addition to the original versions of
|
|
these Invariant Sections. You may include a translation of this License
|
|
provided that you also include the original English version of this
|
|
License. In case of a disagreement between the translation and the
|
|
original English version of this License, the original English version
|
|
will prevail.
|
|
|
|
[[gfdl-9]]
|
|
=== Termination
|
|
|
|
You may not copy, modify, sublicense, or distribute the Document
|
|
except as expressly provided for under this License. Any other attempt to
|
|
copy, modify, sublicense or distribute the Document is void, and will
|
|
automatically terminate your rights under this License. However, parties
|
|
who have received copies, or rights, from you under this License will not
|
|
have their licenses terminated so long as such parties remain in full
|
|
compliance.
|
|
|
|
[[gfdl-10]]
|
|
=== Future Revisions of this License
|
|
|
|
The Free Software Foundation may publish new, revised versions of
|
|
the GNU Free Documentation License from time to time. Such new versions
|
|
will be similar in spirit to the present version, but may differ in
|
|
detail to address new problems or concerns. See
|
|
link:$$http://www.gnu.org/copyleft/$$[].
|
|
|
|
Each version of the License is given a distinguishing version
|
|
number. If the Document specifies that a particular numbered version of
|
|
this License "or any later version" applies to it, you have the option of
|
|
following the terms and conditions either of that specified version or of
|
|
any later version that has been published (not as a draft) by the Free
|
|
Software Foundation. If the Document does not specify a version number of
|
|
this License, you may choose any version ever published (not as a draft)
|
|
by the Free Software Foundation.
|
|
|
|
[[gfdl-howto]]
|
|
=== How to use this License for your documents
|
|
|
|
To use this License in a document you have written, include a copy
|
|
of the License in the document and put the following copyright and
|
|
license notices just after the title page:
|
|
|
|
[quote]
|
|
____
|
|
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.
|
|
|
|
[[glossary]]
|
|
[glossary]
|
|
== Glossary
|
|
|
|
[glossary]
|
|
_.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.
|
|
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.
|
|
+
|
|
For more information about how to configure Apache for Bugzilla, see <<http-apache,Bugzilla using Apache>>.
|
|
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.
|
|
Common Gateway Interface::
|
|
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 (Comprehensive Perl Archive Network)::
|
|
CPAN maintains a large number of extremely useful Perl
|
|
modules - encapsulated chunks of code for performing a
|
|
particular task.
|
|
_contrib_::
|
|
The _contrib_ directory is
|
|
a location to put scripts that have been contributed to Bugzilla but
|
|
are not a part of the official distribution. These scripts are written
|
|
by third parties and may be in languages other than perl. For those
|
|
that are in perl, there may be additional modules or other requirements
|
|
than those of the official distribution.
|
|
+
|
|
Scripts in the _contrib_ directory are not officially supported by the Bugzilla
|
|
team and may break in between versions.
|
|
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.
|
|
DOS Attack::
|
|
A DOS, or Denial of Service attack, is when a user attempts to
|
|
deny access to a web server by repeatedly accessing a page or sending
|
|
malformed requests to a webserver. A D-DOS, or
|
|
Distributed Denial of Service attack, is when these requests come
|
|
from multiple sources at the same time. Unfortunately, these are much
|
|
more difficult to defend against.
|
|
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.
|
|
JavaScript::
|
|
JavaScript is cool, we should talk about it.
|
|
Message Transport Agent::
|
|
A Message Transport Agent is used to control the flow of email on a system.
|
|
The link:$$http://search.cpan.org/dist/Email-Send/lib/Email/Send.pm$$[Email::Send]
|
|
Perl module, which Bugzilla uses to send email, can be configured to
|
|
use many different underlying implementations for actually sending the
|
|
mail using the mail_delivery_method parameter.
|
|
Implementations other than +sendmail+ require that the
|
|
sendmailnow param be set to +on+.
|
|
MySQL::
|
|
MySQL is currently the required RDBMS for Bugzilla. MySQL
|
|
can be downloaded from link:$$http://www.mysql.com$$[]. While you
|
|
should familiarize yourself with all of the documentation, some high points are: +
|
|
link:$$http://www.mysql.com/doc/en/Backup.html$$[Backup]: Methods for backing up your Bugzilla database. +
|
|
link:$$http://www.mysql.com/doc/en/Option_files.html$$[Option Files]: Information about how to configure MySQL using _my.cnf_. +
|
|
link:$$http://www.mysql.com/doc/en/Privilege_system.html$$[Privilege System]: Information about how to protect your MySQL server.
|
|
Perl Package Manager::
|
|
link:$$http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/$$[]
|
|
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.
|
|
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.
|
|
Relational DataBase Management System::
|
|
A relational database management system is a database system
|
|
that stores information in tables that are related to each other.
|
|
Regular Expression::
|
|
A regular expression is an expression used for pattern matching.
|
|
link:$$http://perldoc.perl.org/perlre.html#Regular-Expressions$$[Documentation]
|
|
Service::
|
|
In Windows NT environment, a boot-time background application
|
|
is referred to as a service. These are generally managed through the
|
|
control panel while logged in as an account with
|
|
"Administrator" level capabilities. For more
|
|
information, consult your Windows manual or the MSKB.
|
|
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.
|
|
TCL (Tool Command Language)::
|
|
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.
|
|
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:
|
|
+
|
|
+
|
|
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...
|