WIP
git-svn-id: svn://10.0.0.236/trunk@265708 18797224-902f-48f8-a5cc-f745e15eee43
This commit is contained in:
bzrmirror%bugzilla.org
parent
49667f6a5d
commit
6f6b960826
@ -1 +1 @@
|
||||
acce4dbe67bc0e1576bcc927cd4345b9481ab20a
|
||||
183bf9ac1928e570a922057954aa38e1d40dadb7
|
||||
@ -1,3 +1,10 @@
|
||||
@import 'default.css';
|
||||
|
||||
dt { font-weight: bold; }
|
||||
|
||||
/* Custom roles */
|
||||
.param { font-weight: bold; }
|
||||
.paramval { font-family: monospace; }
|
||||
.group { font-family: monospace; }
|
||||
.field { font-weight: bold; }
|
||||
.command { font-family: monospace; font-size: 130% }
|
||||
|
||||
@ -26,6 +26,7 @@ A sample of code is illustrated like this:
|
||||
This documentation is maintained in reStructured Text format using the
|
||||
`Sphinx <http://www.sphinx-doc.org/>`_ documentation system.
|
||||
Changes are best submitted as diffs, attached
|
||||
to a bug filed in the `Bugzilla Documentation <https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla;component=Documentation>`_
|
||||
component.
|
||||
to a bug filed in the `Bugzilla Documentation
|
||||
<https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla;component=Documentation>`_
|
||||
component. There is a :ref:`Style Guide <style-guide>` to help you.
|
||||
|
||||
|
||||
@ -3,7 +3,8 @@
|
||||
Evaluating Bugzilla
|
||||
###################
|
||||
|
||||
If you want to evaluate Bugzilla, you can try it out on "`Landfill <https://landfill.bugzilla.org/bugzilla-4.4-branch/>`_", our test
|
||||
If you want to evaluate Bugzilla, you can try it out on
|
||||
`Landfill <https://landfill.bugzilla.org/bugzilla-4.4-branch/>`_, our test
|
||||
server. The `Bugzilla FAQ <https://wiki.mozilla.org/Bugzilla:FAQ>`_ may also
|
||||
be helpful, as it answers a number of questions people sometimes have about
|
||||
whether Bugzilla can do what they need.
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
.. _help:
|
||||
.. _getting-help:
|
||||
|
||||
Getting More Help
|
||||
#################
|
||||
|
||||
@ -9,4 +9,4 @@ that tracks millions of bugs and issues for thousands of organizations around
|
||||
the world.
|
||||
|
||||
The most current version of this document can always be found on the
|
||||
`Bugzilla Documentation Page <http://www.bugzilla.org/docs/>`_.
|
||||
`Bugzilla website <http://www.bugzilla.org/docs/>`_.
|
||||
|
||||
@ -16,6 +16,7 @@ to worry about that; it's only relevant if you redistribute the code or any
|
||||
changes you make.
|
||||
|
||||
Bugzilla's documentation is made available under the
|
||||
`Creative Commons CC-BY-SA International License 4.0 <https://creativecommons.org/licenses/by-sa/4.0/>`_,
|
||||
`Creative Commons CC-BY-SA International License 4.0
|
||||
<https://creativecommons.org/licenses/by-sa/4.0/>`_,
|
||||
or any later version.
|
||||
|
||||
|
||||
@ -4,6 +4,10 @@
|
||||
Administering Bugzilla
|
||||
======================
|
||||
|
||||
For those with :group:`admin` privileges, Bugzilla can be administered using
|
||||
the :guilabel:`Administration` link in the header. The administrative
|
||||
controls are divided into several sections:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
@ -18,85 +22,5 @@ Administering Bugzilla
|
||||
administering/groups
|
||||
administering/keywords
|
||||
administering/whining
|
||||
administering/quips
|
||||
administering/extensions
|
||||
|
||||
.. _voting:
|
||||
|
||||
Voting
|
||||
######
|
||||
|
||||
All of the code for voting in Bugzilla has been moved into an
|
||||
extension, called "Voting", in the :file:`extensions/Voting/`
|
||||
directory. To enable it, you must remove the :file:`disabled`
|
||||
file from that directory, and run :file:`checksetup.pl`.
|
||||
|
||||
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
|
||||
"CONFIRMED", users of the bug system can help high-priority bugs garner
|
||||
attention so they don't sit for a long time awaiting triage.
|
||||
|
||||
To modify Voting settings:
|
||||
|
||||
#. Navigate to the "Edit product" screen for the Product you
|
||||
wish to modify
|
||||
|
||||
#. *Maximum Votes per person*:
|
||||
Setting this field to "0" disables voting.
|
||||
|
||||
#. *Maximum Votes a person can put on a single
|
||||
bug*:
|
||||
It should probably be some number lower than the
|
||||
"Maximum votes per person". Don't set this field to "0" if
|
||||
"Maximum votes per person" is non-zero; that doesn't make
|
||||
any sense.
|
||||
|
||||
#. *Number of votes a bug in this product needs to
|
||||
automatically get out of the UNCONFIRMED state*:
|
||||
Setting this field to "0" disables the automatic move of
|
||||
bugs from UNCONFIRMED to CONFIRMED.
|
||||
|
||||
#. 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.
|
||||
|
||||
Quip submission is 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.
|
||||
|
||||
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 quip 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.
|
||||
|
||||
Display of quips is controlled by the *display_quips*
|
||||
user preference. Possible values are "on" and "off".
|
||||
|
||||
|
||||
@ -4,8 +4,8 @@ Parameters
|
||||
##########
|
||||
|
||||
Bugzilla is configured by changing various parameters, accessed
|
||||
from the "Parameters" link, which is found on the Administration page.
|
||||
The parameters are divided into several categories,
|
||||
from the :guilabel:`Parameters` link, which is found on the Administration
|
||||
page. The parameters are divided into several categories,
|
||||
accessed via the menu on the left.
|
||||
|
||||
.. _param-required-settings:
|
||||
@ -14,7 +14,7 @@ Required Settings
|
||||
=================
|
||||
|
||||
The core required parameters for any Bugzilla installation are set
|
||||
here. :guilabel:`urlbase` is always required; the other parameters should be
|
||||
here. :param:`urlbase` is always required; the other parameters should be
|
||||
set, or it must be explicitly decided not to
|
||||
set them, before the new Bugzilla installation starts to be used.
|
||||
|
||||
@ -23,30 +23,30 @@ urlbase
|
||||
server path to this Bugzilla installation.
|
||||
For example, if the Bugzilla query page is
|
||||
:file:`http://www.foo.com/bugzilla/query.cgi`,
|
||||
the :guilabel:`urlbase` should be set
|
||||
to :file:`http://www.foo.com/bugzilla/`.
|
||||
the :param:`urlbase` should be set
|
||||
to :paramval:`http://www.foo.com/bugzilla/`.
|
||||
|
||||
ssl_redirect
|
||||
If enabled, Bugzilla will force HTTPS (SSL) connections, by
|
||||
automatically redirecting any users who try to use a non-SSL
|
||||
connection. Also, when this is enabled, Bugzilla will send out links
|
||||
using sslbase in emails instead of urlbase.
|
||||
using :param:`sslbase` in emails instead of :param:`urlbase`.
|
||||
|
||||
sslbase
|
||||
Defines the fully qualified domain name and web
|
||||
server path for HTTPS (SSL) connections to this Bugzilla installation.
|
||||
For example, if the Bugzilla main page is
|
||||
:file:`https://www.foo.com/bugzilla/index.cgi`,
|
||||
the :guilabel:`sslbase` should be set
|
||||
to :file:`https://www.foo.com/bugzilla/`.
|
||||
the :param:`sslbase` should be set
|
||||
to :paramval:`https://www.foo.com/bugzilla/`.
|
||||
|
||||
cookiepath
|
||||
Defines a path, relative to the web document root, that Bugzilla
|
||||
cookies will be restricted to. For example, if the
|
||||
:guilabel:`urlbase` is set to
|
||||
:param:`urlbase` is set to
|
||||
:file:`http://www.foo.com/bugzilla/`, the
|
||||
:guilabel:`cookiepath` should be set to
|
||||
:file:`/bugzilla/`. Setting it to "/" will allow all sites
|
||||
:param:`cookiepath` should be set to
|
||||
:paramval:`/bugzilla/`. Setting it to :paramval:`/` will allow all sites
|
||||
served by this web server or virtual host to read Bugzilla cookies.
|
||||
|
||||
.. _param-general:
|
||||
@ -79,7 +79,7 @@ shutdownhtml
|
||||
of site maintenance or outage situations.
|
||||
|
||||
.. note:: Although regular log-in capability is disabled
|
||||
while :guilabel:`shutdownhtml`
|
||||
while :param:`shutdownhtml`
|
||||
is enabled, safeguards are in place to protect the unfortunate
|
||||
admin who loses connection to Bugzilla. Should this happen to you,
|
||||
go directly to the :file:`editparams.cgi` (by typing
|
||||
@ -100,12 +100,12 @@ announcehtml
|
||||
upgrade_notification
|
||||
Enable or disable a notification on the homepage of this Bugzilla
|
||||
installation when a newer version of Bugzilla is available. This
|
||||
notification is only visible to administrators. Choose "disabled",
|
||||
notification is only visible to administrators. Choose :paramval:`disabled`,
|
||||
to turn off the notification. Otherwise, choose which version of
|
||||
Bugzilla you want to be notified about: "development_snapshot" is the
|
||||
latest release on the trunk; "latest_stable_release" is the most
|
||||
Bugzilla you want to be notified about: :paramval:`development_snapshot` is the
|
||||
latest release on the trunk:paramval:`latest_stable_release` is the most
|
||||
recent release available on the most recent stable branch;
|
||||
"stable_branch_release" the most recent release on the branch
|
||||
:paramval:`stable_branch_release` the most recent release on the branch
|
||||
this installation is based on.
|
||||
|
||||
.. _param-administrative-policies:
|
||||
@ -154,22 +154,22 @@ auth_env_realname
|
||||
user_info_class
|
||||
Mechanism(s) to be used for gathering a user's login information. More than one may be selected. If the first one returns nothing, the second is tried, and so on. The types are:
|
||||
|
||||
* CGI: asks for username and password via CGI form interface.
|
||||
* Env: info for a pre-authenticated user is passed in system environment variables.
|
||||
* :paramval:`CGI`: asks for username and password via CGI form interface.
|
||||
* :paramval:`Env`: info for a pre-authenticated user is passed in system environment variables.
|
||||
|
||||
user_verify_class
|
||||
Mechanism(s) to be used for verifying (authenticating) information gathered by user_info_class. More than one may be selected. If the first one cannot find the user, the second is tried, and so on. The types are:
|
||||
|
||||
* DB: Bugzilla's built-in authentication. This is the most common choice.
|
||||
* RADIUS: RADIUS authentication using a RADIUS server. Using this method requires additional parameters to be set. Please see :ref:`param-radius` for more information.
|
||||
* LDAP: LDAP authentication using an LDAP server. Using this method requires additional parameters to be set. Please see :ref:`param-ldap` for more information.
|
||||
* :paramval:`DB`: Bugzilla's built-in authentication. This is the most common choice.
|
||||
* :paramval:`RADIUS`: RADIUS authentication using a RADIUS server. Using this method requires additional parameters to be set. Please see :ref:`param-radius` for more information.
|
||||
* :paramval:`LDAP1: LDAP authentication using an LDAP server. Using this method requires additional parameters to be set. Please see :ref:`param-ldap` for more information.
|
||||
|
||||
rememberlogin
|
||||
Controls management of session cookies.
|
||||
|
||||
* on - Session cookies never expire (the user has to login only once per browser).
|
||||
* off - Session cookies last until the users session ends (the user will have to login in each new browser session).
|
||||
* defaulton/defaultoff - Default behavior as described above, but user can choose whether Bugzilla will remember their login or not.
|
||||
* :paramval:`on` - Session cookies never expire (the user has to login only once per browser).
|
||||
* :paramval:`off` - Session cookies last until the users session ends (the user will have to login in each new browser session).
|
||||
* :paramval:`defaulton`/:paramval:`defaultoff` - Default behavior as described above, but user can choose whether Bugzilla will remember their login or not.
|
||||
|
||||
requirelogin
|
||||
If this option is set, all access to the system beyond the front page will require a login. No anonymous users will be permitted.
|
||||
@ -180,26 +180,26 @@ webservice_email_filter
|
||||
emailregexp
|
||||
Defines the regular expression used to validate email addresses
|
||||
used for login names. The default attempts to match fully
|
||||
qualified email addresses (i.e. 'user@example.com') in a slightly
|
||||
qualified email addresses (i.e. 'user\@example.com') in a slightly
|
||||
more restrictive way than what is allowed in RFC 2822.
|
||||
Another popular value to put here is ^[^@]+, which means 'local usernames, no @ allowed.'
|
||||
Another popular value to put here is :paramval:``^[^@]+`, which means 'local usernames, no @ allowed.'
|
||||
|
||||
emailregexpdesc
|
||||
This description is shown to the user to explain which email addresses are allowed by the emailregexp param.
|
||||
This description is shown to the user to explain which email addresses are allowed by the :param:`emailregexp` param.
|
||||
|
||||
emailsuffix
|
||||
This is a string to append to any email addresses when actually sending mail to that address. It is useful if you have changed the emailregexp param to only allow local usernames, but you want the mail to be delivered to username@my.local.hostname.
|
||||
This is a string to append to any email addresses when actually sending mail to that address. It is useful if you have changed the :param:`emailregexp` param to only allow local usernames, but you want the mail to be delivered to username\@my.local.hostname.
|
||||
|
||||
createemailregexp
|
||||
This defines the (case-insensitive) regexp to use for email addresses that are permitted to self-register using a 'New Account' feature. The default (.*) permits any account matching the emailregexp to be created. If this parameter is left blank, no users will be permitted to create their own accounts and all accounts will have to be created by an administrator.
|
||||
This defines the (case-insensitive) regexp to use for email addresses that are permitted to self-register. The default (.*) permits any account matching the emailregexp to be created. If this parameter is left blank, no users will be permitted to create their own accounts and all accounts will have to be created by an administrator.
|
||||
|
||||
password_complexity
|
||||
Set the complexity required for passwords. In all cases must the passwords be at least 6 characters long.
|
||||
|
||||
* no_constraints - No complexity required.
|
||||
* mixed_letters - Passwords must contain at least one UPPER and one lower case letter.
|
||||
* letters_numbers - Passwords must contain at least one UPPER and one lower case letter and a number.
|
||||
* letters_numbers_specialchars - Passwords must contain at least one letter, a number and a special character.
|
||||
* :paramval:`no_constraints` - No complexity required.
|
||||
* :paramval:`mixed_letters` - Passwords must contain at least one UPPER and one lower case letter.
|
||||
* :paramval:`letters_numbers` - Passwords must contain at least one UPPER and one lower case letter and a number.
|
||||
* :paramval:`letters_numbers_specialchars` - Passwords must contain at least one letter, a number and a special character.
|
||||
|
||||
password_check_on_login
|
||||
If set, Bugzilla will check that the password meets the current complexity rules and minimum length requirements when the user logs into the Bugzilla web interface. If it doesn't, the user would not be able to log in, and will receive a message to reset their password.
|
||||
@ -216,14 +216,14 @@ and whether to allow pointing to external files via a URI.
|
||||
allow_attachment_display
|
||||
If this option is on, users will be able to view attachments from their browser, if their browser supports the attachment's MIME type. If this option is off, users are forced to download attachments, even if the browser is able to display them.
|
||||
|
||||
If you do not trust your users (e.g. if your Bugzilla is public), you should either leave this option off, or configure and set the :guilabel:`attachment_base` parameter (see below). Untrusted users may upload attachments that could be potentially damaging if viewed directly in the browser.
|
||||
If you do not trust your users (e.g. if your Bugzilla is public), you should either leave this option off, or configure and set the :param:`attachment_base` parameter (see below). Untrusted users may upload attachments that could be potentially damaging if viewed directly in the browser.
|
||||
|
||||
attachment_base
|
||||
When the :guilabel:`allow_attachment_display` parameter is on, it is possible for a malicious attachment to steal your cookies or perform an attack on Bugzilla using your credentials.
|
||||
When the :param:`allow_attachment_display` parameter is on, it is possible for a malicious attachment to steal your cookies or perform an attack on Bugzilla using your credentials.
|
||||
|
||||
If you would like additional security on attachments to avoid this, set this parameter to an alternate URL for your Bugzilla that is not the same as :guilabel:`urlbase` or :guilabel:`sslbase`. That is, a different domain name that resolves to this exact same Bugzilla installation.
|
||||
If you would like additional security on attachments to avoid this, set this parameter to an alternate URL for your Bugzilla that is not the same as :param:`urlbase` or :param:`sslbase`. That is, a different domain name that resolves to this exact same Bugzilla installation.
|
||||
|
||||
Note that if you have set the :guilabel:`cookiedomain` parameter, you should set :guilabel:`attachment_base` to use a domain that would not be matched by :guilabel:`cookiedomain`.
|
||||
Note that if you have set the :param:`cookiedomain` parameter, you should set :param:`attachment_base` to use a domain that would not be matched by :param:`cookiedomain`.
|
||||
|
||||
For added security, you can insert ``%bugid%`` into the URL, which will be replaced with the ID of the current bug that the attachment is on, when you access an attachment. This will limit attachments to accessing only other attachments on the same bug. Remember, though, that all those possible domain names (such as 1234.your.domain.com) must point to this same Bugzilla instance.
|
||||
|
||||
@ -240,7 +240,7 @@ maxattachmentsize
|
||||
XXX Talk about MySQL max_allowed_packet
|
||||
|
||||
maxlocalattachment
|
||||
The maximum size (in megabytes) of attachments to be stored locally on the web server. If set to a value lower than the maxattachmentsize parameter, attachments will never be kept on the local filesystem.
|
||||
The maximum size (in megabytes) of attachments to be stored locally on the web server. If set to a value lower than the :param:`maxattachmentsize` parameter, attachments will never be kept on the local filesystem.
|
||||
|
||||
XXX When should people use this feature?
|
||||
|
||||
@ -300,13 +300,15 @@ Bug Fields
|
||||
The parameters in this section determine the default settings of
|
||||
several Bugzilla fields for new bugs, and also control whether
|
||||
certain fields are used. For example, choose whether to use the
|
||||
"target milestone" field or the "status whiteboard" field.
|
||||
:field:`Target Milestone` field or the :field:`Status Whiteboard` field.
|
||||
|
||||
useclassification
|
||||
If this is on, Bugzilla will associate each product with a specific classification. But you must have 'editclassification' permissions enabled in order to edit classifications.
|
||||
If this is on, Bugzilla will associate each product with a specific
|
||||
classification. But you must have :group:`editclassification` permissions
|
||||
enabled in order to edit classifications.
|
||||
|
||||
usetargetmilestone
|
||||
Do you wish to use the Target Milestone field?
|
||||
Do you wish to use the :field:`Target Milestone` field?
|
||||
|
||||
useqacontact
|
||||
This allows you to define an email address for each component,
|
||||
@ -315,13 +317,16 @@ useqacontact
|
||||
|
||||
usestatuswhiteboard
|
||||
This defines whether you wish to have a free-form, overwritable field
|
||||
associated with each bug. The advantage of the Status Whiteboard is
|
||||
that it can be deleted or modified with ease, and provides an
|
||||
associated with each bug. The advantage of the :field:`Status Whiteboard`
|
||||
is that it can be deleted or modified with ease, and provides an
|
||||
easily-searchable field for indexing some bugs that have some trait
|
||||
in common.
|
||||
|
||||
use_see_also
|
||||
Do you wish to use the See Also field? It allows you mark bugs in other bug tracker installations as being related. Disabling this field prevents addition of new relationships, but existing ones will continue to appear.
|
||||
Do you wish to use the :field:`See Also` field? It allows you mark bugs
|
||||
in other bug tracker installations as being related. Disabling this field
|
||||
prevents addition of new relationships, but existing ones will continue to
|
||||
appear.
|
||||
|
||||
defaultpriority
|
||||
This is the priority that newly entered bugs are set to.
|
||||
@ -331,14 +336,17 @@ defaultseverity
|
||||
|
||||
defaultplatform
|
||||
This is the platform that is preselected on the bug entry form.
|
||||
You can leave this empty; Bugzilla will then use the platform that the browser is running on as the default.
|
||||
You can leave this empty; Bugzilla will then use the platform that the
|
||||
browser is running on as the default.
|
||||
|
||||
defaultopsys
|
||||
This is the operating system that is preselected on the bug entry form.
|
||||
You can leave this empty; Bugzilla will then use the operating system that the browser reports to be running on as the default.
|
||||
You can leave this empty; Bugzilla will then use the operating system
|
||||
that the browser reports to be running on as the default.
|
||||
|
||||
collapsed_comment_tags
|
||||
A comma separated list of tags which, when applied to comments, will cause them to be collapsed by default.
|
||||
A comma separated list of tags which, when applied to comments, will
|
||||
cause them to be collapsed by default.
|
||||
|
||||
.. _param-dependency-graphs:
|
||||
|
||||
@ -359,7 +367,7 @@ webdotbase
|
||||
* A URL prefix pointing to an installation of the webdot package will generate the graphs remotely.
|
||||
* A blank value will disable dependency graphing.
|
||||
|
||||
The default value is a publicly-accessible webdot server. If you change this value, make certain that the webdot server can read files from your webdot directory. On Apache you do this by editing the .htaccess file, for other systems the needed measures may vary. You can run checksetup.pl to recreate the .htaccess file if it has been lost.
|
||||
The default value is a publicly-accessible webdot server. If you change this value, make certain that the webdot server can read files from your webdot directory. On Apache you do this by editing the :file:`.htaccess` file, for other systems the needed measures may vary. You can run :command:`checksetup.pl` to recreate the :file:`.htaccess` file if it has been lost.
|
||||
|
||||
font_file
|
||||
You can specify the full path to a TrueType font file which will be used to display text (labels, legends, ...) in charts and graphical reports. To support as many languages as possible, we recommend to specify a TrueType font such as Unifont which supports all printable characters in the Basic Multilingual Plane. If you leave this parameter empty, a default font will be used, but its support is limited to English characters only and so other characters will be displayed incorrectly.
|
||||
@ -375,8 +383,9 @@ specific users. Specific products can also be associated with
|
||||
groups, and users restricted to only see products in their groups.
|
||||
Several parameters are described in more detail below. Most of the
|
||||
configuration of groups and their relationship to products is done
|
||||
on the "Groups" and "Product" pages of the "Administration" area.
|
||||
The options on this page control global default behavior.
|
||||
on the :guilabel:`Groups` and :guilabel:`Product` pages of the
|
||||
:guilabel:`Administration` area.
|
||||
The options on this page control global default behaviour.
|
||||
For more information on Groups and Group Security, see
|
||||
:ref:`groups`.
|
||||
|
||||
@ -434,8 +443,8 @@ than replacing it. The initial log-in is done with a username and
|
||||
password for the LDAP directory. Bugzilla tries to bind to LDAP using
|
||||
those credentials and, if successful, tries to map this account to a
|
||||
Bugzilla account. If an LDAP mail attribute is defined, the value of this
|
||||
attribute is used, otherwise the "emailsuffix" parameter is appended to LDAP
|
||||
username to form a full email address. If an account for this address
|
||||
attribute is used, otherwise the :param:`emailsuffix` parameter is appended to
|
||||
the LDAP username to form a full email address. If an account for this address
|
||||
already exists in the Bugzilla installation, it will log in to that account.
|
||||
If no account for that email address exists, one is created at the time
|
||||
of login. (In this case, Bugzilla will attempt to use the "displayName"
|
||||
@ -457,21 +466,21 @@ email address and users are still queried by email address.
|
||||
Parameters required to use LDAP Authentication:
|
||||
|
||||
user_verify_class (in the Authentication section)
|
||||
If you want to list ``LDAP`` here,
|
||||
If you want to list :paramval:`LDAP` here,
|
||||
make sure to have set up the other parameters listed below.
|
||||
Unless you have other (working) authentication methods listed as
|
||||
well, you may otherwise not be able to log back in to Bugzilla once
|
||||
you log out.
|
||||
If this happens to you, you will need to manually edit
|
||||
:file:`data/params` and set :guilabel:`user_verify_class` to
|
||||
``DB``.
|
||||
:file:`data/params` and set :param:`user_verify_class` to
|
||||
:paramval:`DB`.
|
||||
|
||||
LDAPserver
|
||||
This parameter should be set to the name (and optionally the
|
||||
port) of your LDAP server. If no port is specified, it assumes
|
||||
the default LDAP port of 389.
|
||||
For example: ``ldap.company.com``
|
||||
or ``ldap.company.com:3268``
|
||||
For example: :paramval:`ldap.company.com`
|
||||
or :paramval:`ldap.company.com:3268`
|
||||
You can also specify a LDAP URI, so as to use other
|
||||
protocols, such as LDAPS or LDAPI. If port was not specified in
|
||||
the URI, the default is either 389 or 636 for 'LDAP' and 'LDAPS'
|
||||
@ -480,41 +489,43 @@ LDAPserver
|
||||
.. note:: In order to use SSL with LDAP, specify a URI with "ldaps://".
|
||||
This will force the use of SSL over port 636.
|
||||
For example, normal LDAP:
|
||||
``ldap://ldap.company.com``, LDAP over SSL:
|
||||
``ldaps://ldap.company.com`` or LDAP over a UNIX
|
||||
domain socket ``ldapi://%2fvar%2flib%2fldap_sock``.
|
||||
:paramval:`ldap://ldap.company.com`, LDAP over SSL:
|
||||
:paramval:`ldaps://ldap.company.com` or LDAP over a UNIX
|
||||
domain socket :paramval:`ldapi://%2fvar%2flib%2fldap_sock`.
|
||||
|
||||
LDAPstarttls
|
||||
Whether to require encrypted communication once a normal LDAP connection is achieved with the server.
|
||||
Whether to require encrypted communication once a normal LDAP connection
|
||||
is achieved with the server.
|
||||
|
||||
LDAPbinddn [Optional]
|
||||
Some LDAP servers will not allow an anonymous bind to search
|
||||
the directory. If this is the case with your configuration you
|
||||
should set the :guilabel:`LDAPbinddn` parameter to the user account Bugzilla
|
||||
should set the :param:`LDAPbinddn` parameter to the user account Bugzilla
|
||||
should use instead of the anonymous bind.
|
||||
Ex. ``cn=default,cn=user:password``
|
||||
Ex. :paramval:`cn=default,cn=user:password`
|
||||
|
||||
LDAPBaseDN
|
||||
The location in
|
||||
your LDAP tree that you would like to search for email addresses.
|
||||
Your uids should be unique under the DN specified here.
|
||||
Ex. ``ou=People,o=Company``
|
||||
Ex. :paramval:`ou=People,o=Company`
|
||||
|
||||
LDAPuidattribute
|
||||
The attribute
|
||||
which contains the unique UID of your users. The value retrieved
|
||||
from this attribute will be used when attempting to bind as the
|
||||
user to confirm their password.
|
||||
Ex. ``uid``
|
||||
Ex. :paramval:`uid`
|
||||
|
||||
LDAPmailattribute
|
||||
The name of the
|
||||
attribute which contains the email address your users will enter
|
||||
into the Bugzilla login boxes.
|
||||
Ex. ``mail``
|
||||
Ex. :paramval:`mail`
|
||||
|
||||
LDAPfilter
|
||||
LDAP filter to AND with the LDAPuidattribute for filtering the list of valid users.
|
||||
LDAP filter to AND with the LDAPuidattribute for filtering the list of
|
||||
valid users.
|
||||
|
||||
.. _param-radius:
|
||||
|
||||
@ -531,24 +542,24 @@ necessary for configuring Bugzilla to use RADIUS authentication.
|
||||
Parameters required to use RADIUS Authentication:
|
||||
|
||||
user_verify_class (in the Authentication section)
|
||||
If you want to list ``RADIUS`` here,
|
||||
If you want to list :paramval:`RADIUS` here,
|
||||
make sure to have set up the other parameters listed below.
|
||||
Unless you have other (working) authentication methods listed as
|
||||
well, you may otherwise not be able to log back in to Bugzilla once
|
||||
you log out.
|
||||
If this happens to you, you will need to manually edit
|
||||
:file:`data/params` and set user_verify_class to
|
||||
``DB``.
|
||||
:file:`data/params` and set :param:`user_verify_class` to
|
||||
:paramval:`DB`.
|
||||
|
||||
RADIUS_server
|
||||
The name (and optionally the
|
||||
port) of your RADIUS server.
|
||||
The name (and optionally the port) of your RADIUS server.
|
||||
|
||||
RADIUS_secret
|
||||
The RADIUS server's secret.
|
||||
|
||||
RADIUS_NAS_IP
|
||||
The NAS-IP-Address attribute to be used when exchanging data with your RADIUS server. If unspecified, 127.0.0.1 will be used.
|
||||
The NAS-IP-Address attribute to be used when exchanging data with your
|
||||
RADIUS server. If unspecified, 127.0.0.1 will be used.
|
||||
|
||||
RADIUS_email_suffix
|
||||
Bugzilla needs an e-mail address for each user account.
|
||||
@ -576,9 +587,9 @@ mail_delivery_method
|
||||
This is used to specify how email is sent, or if it is sent at
|
||||
all. There are several options included for different MTAs,
|
||||
along with two additional options that disable email sending.
|
||||
"Test" does not send mail, but instead saves it in
|
||||
:paramval:`Test` does not send mail, but instead saves it in
|
||||
:file:`data/mailer.testfile` for later review.
|
||||
"None" disables email sending entirely.
|
||||
:paramval:`None` disables email sending entirely.
|
||||
|
||||
mailfrom
|
||||
This is the email address that will appear in the "From" field
|
||||
@ -590,8 +601,8 @@ use_mailer_queue
|
||||
In a large Bugzilla installation, updating bugs can be very slow, because Bugzilla sends all email at once. If you enable this parameter, Bugzilla will queue all mail and then send it in the background. This requires that you have installed certain Perl modules (as listed by :file:`checksetup.pl` for this feature), and that you are running the :file:`jobqueue.pl` daemon (otherwise your mail won't get sent). This affects all mail sent by Bugzilla, not just bug updates.
|
||||
|
||||
smtpserver
|
||||
The SMTP server address, if the :guilabel:`mail_delivery_method`
|
||||
parameter is set to SMTP. Use "localhost" if you have a local MTA
|
||||
The SMTP server address, if the :param:`mail_delivery_method`
|
||||
parameter is set to :paramval:`SMTP`. Use :paramval:`localhost` if you have a local MTA
|
||||
running, otherwise use a remote SMTP server. Append ":" and the port
|
||||
number if a non-default port is needed.
|
||||
|
||||
@ -601,7 +612,7 @@ smtp_username
|
||||
|
||||
smtp_password
|
||||
Password to use for SASL authentication to the SMTP server. This
|
||||
parameter will be ignored if the :guilabel:`smtp_username`
|
||||
parameter will be ignored if the :param:`smtp_username`
|
||||
parameter is left empty.
|
||||
|
||||
smtp_ssl
|
||||
@ -667,9 +678,9 @@ needed to add a bug to the "most frequently reported" list.
|
||||
quip_list_entry_control
|
||||
Controls how easily users can add entries to the quip list.
|
||||
|
||||
* open - Users may freely add to the quip list, and their entries will immediately be available for viewing.
|
||||
* moderated - quips can be entered, but need to be approved by a moderator before they will be shown.
|
||||
* closed - no new additions to the quips list are allowed.
|
||||
* :paramval:`open` - Users may freely add to the quip list, and their entries will immediately be available for viewing.
|
||||
* :paramval:`moderated` - quips can be entered, but need to be approved by a moderator before they will be shown.
|
||||
* :paramval:`closed` - no new additions to the quips list are allowed.
|
||||
|
||||
mybugstemplate
|
||||
This is the URL to use to bring up a simple 'all of my bugs' list for a user. %userid% will get replaced with the login name of a user. Special characters must be URL-encoded.
|
||||
@ -720,7 +731,10 @@ Memcached
|
||||
=========
|
||||
|
||||
memcached_servers
|
||||
If this option is set, Bugzilla will integrate with XXXlink Memcached. Specify one of more server, separated by spaces, using hostname:port notation (for example: 127.0.0.1:11211).
|
||||
If this option is set, Bugzilla will integrate with `Memcached
|
||||
<http://www.memcached.org/>`_. Specify one of more server, separated by
|
||||
spaces, using hostname:port notation (for example:
|
||||
:paramval:`127.0.0.1:11211`).
|
||||
|
||||
memcached_namespace
|
||||
Specify a string to prefix to each key on Memcached.
|
||||
@ -765,23 +779,23 @@ cookiedomain
|
||||
require the same cookie, then this parameter can be utilized. For
|
||||
example, If your website is at
|
||||
``https://bugzilla.example.com/``, setting this to
|
||||
``.example.com/`` will also allow
|
||||
:paramval:`.example.com/` will also allow
|
||||
``attachments.example.com/`` to access Bugzilla cookies.
|
||||
|
||||
inbound_proxies
|
||||
When inbound traffic to Bugzilla goes through a proxy, Bugzilla thinks that the IP address of the proxy is the IP address of every single user. If you enter a comma-separated list of IPs in this parameter, then Bugzilla will trust any X-Forwarded-For header sent from those IPs, and use the value of that header as the end user's IP address.
|
||||
When inbound traffic to Bugzilla goes through a proxy, Bugzilla thinks that the IP address of the proxy is the IP address of every single user. If you enter a comma-separated list of IPs in this parameter, then Bugzilla will trust any ``X-Forwarded-For`` header sent from those IPs, and use the value of that header as the end user's IP address.
|
||||
|
||||
proxy_url
|
||||
If this Bugzilla installation is behind a proxy, enter the proxy
|
||||
information here to enable Bugzilla to access the Internet. Bugzilla
|
||||
requires Internet access to utilize the
|
||||
:guilabel:`upgrade_notification` parameter. If the
|
||||
:param:`upgrade_notification` parameter. If the
|
||||
proxy requires authentication, use the syntax:
|
||||
:file:`http://user:pass@proxy_url/`.
|
||||
:paramval:`http://user:pass@proxy_url/`.
|
||||
|
||||
strict_transport_security
|
||||
Enables the sending of the Strict-Transport-Security header along with HTTP responses on SSL connections. This adds greater security to your SSL connections by forcing the browser to always access your domain over SSL and never accept an invalid certificate. However, it should only be used if you have the :guilabel:`ssl_redirect` parameter turned on, Bugzilla is the only thing running on its domain (i.e., your urlbase is something like http://bugzilla.example.com/), and you never plan to stop supporting SSL.
|
||||
Enables the sending of the Strict-Transport-Security header along with HTTP responses on SSL connections. This adds greater security to your SSL connections by forcing the browser to always access your domain over SSL and never accept an invalid certificate. However, it should only be used if you have the :param:`ssl_redirect` parameter turned on, Bugzilla is the only thing running on its domain (i.e., your :param:`urlbase` is something like :paramval:`http://bugzilla.example.com/`), and you never plan to stop supporting SSL.
|
||||
|
||||
* off - Don't send the Strict-Transport-Security header with requests.
|
||||
* this_domain_only - Send the Strict-Transport-Security header with all requests, but only support it for the current domain.
|
||||
* include_subdomains - Send the Strict-Transport-Security header along with the includeSubDomains flag, which will apply the security change to all subdomains. This is especially useful when combined with an :guilabel:`attachment_base` that exists as (a) subdomain(s) under the main Bugzilla domain.
|
||||
* :paramval:`off` - Don't send the Strict-Transport-Security header with requests.
|
||||
* :paramval:`this_domain_only` - Send the Strict-Transport-Security header with all requests, but only support it for the current domain.
|
||||
* :paramval:`include_subdomains` - Send the Strict-Transport-Security header along with the includeSubDomains flag, which will apply the security change to all subdomains. This is especially useful when combined with an :param:`attachment_base` that exists as (a) subdomain(s) under the main Bugzilla domain.
|
||||
|
||||
@ -0,0 +1,39 @@
|
||||
.. _quips:
|
||||
|
||||
Quips
|
||||
#####
|
||||
|
||||
Quips are small user-defined messages (often quotes or witty sayings) that
|
||||
can be configured to appear at the top of thesearch results. Each Bugzilla
|
||||
installation has its own specific quips. Whenever a quip needs to be
|
||||
displayed, a random selection is made from the pool of already existing quips.
|
||||
|
||||
Quip submission is 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.
|
||||
|
||||
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 quip 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.
|
||||
|
||||
Display of quips is controlled by the *display_quips*
|
||||
user preference. Possible values are "on" and "off".
|
||||
|
||||
@ -28,7 +28,7 @@ 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 :guilabel:`emailsuffix` parameter is set).
|
||||
of the email address if the :param:`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),
|
||||
|
||||
@ -13,7 +13,7 @@ Only one bug status, UNCONFIRMED, can never be renamed nor deleted. However,
|
||||
it can be disabled entirely on a per-product basis (see :ref:`categorization`).
|
||||
One other status may be
|
||||
marked as undeletable, because it's the value of the
|
||||
:guilabel:`duplicate_or_move_bug_status` parameter. To make it deletable,
|
||||
:param:`duplicate_or_move_bug_status` parameter. To make it deletable,
|
||||
simply set the value of that parameter to a different status.
|
||||
|
||||
Aside from the empty value, two resolutions, DUPLICATE and FIXED, cannot be
|
||||
@ -27,7 +27,7 @@ starting status and on the top for the target status in the transition.
|
||||
If the checkbox is checked, then the transition from the left to the top
|
||||
status is legal; if it's unchecked, that transition is forbidden.
|
||||
|
||||
The status used as the :guilabel:`duplicate_or_move_bug_status` parameter
|
||||
The status used as the :param:`duplicate_or_move_bug_status` parameter
|
||||
(normally RESOLVED or its equivalent) is required to be a legal transition
|
||||
from every other bug status, and so this is enforced on the page.
|
||||
|
||||
|
||||
@ -183,6 +183,21 @@ html_show_copyright = False
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = 'Bugzilladoc'
|
||||
|
||||
rst_prolog = """
|
||||
.. role:: param
|
||||
:class: param
|
||||
|
||||
.. role:: paramval
|
||||
:class: paramval
|
||||
|
||||
.. role:: group
|
||||
:class: group
|
||||
|
||||
.. role:: field
|
||||
:class: field
|
||||
|
||||
.. |min-perl-ver| replace:: 5.10.1
|
||||
"""
|
||||
|
||||
# -- Options for LaTeX output --------------------------------------------------
|
||||
|
||||
@ -258,11 +273,6 @@ texinfo_documents = [
|
||||
# How to display URL addresses: 'footnote', 'no', or 'inline'.
|
||||
#texinfo_show_urls = 'footnote'
|
||||
|
||||
# Global substitutions and other markup required in every page
|
||||
rst_epilog = """
|
||||
.. |min-perl-ver| replace:: 5.10.1
|
||||
"""
|
||||
|
||||
# -- Options for PDF output --------------------------------------------------
|
||||
|
||||
# Grouping the document tree into PDF files. List of tuples
|
||||
|
||||
@ -19,7 +19,7 @@ operating system that provides an ideal environment for Bugzilla. In that
|
||||
case, you may want to read the :ref:`Quick Start instructions <quick-start>`.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:maxdepth: 2
|
||||
|
||||
installing/quick-start
|
||||
installing/linux
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
.. _http-apache:
|
||||
.. _apache:
|
||||
|
||||
Apache
|
||||
######
|
||||
@ -8,7 +8,7 @@ default) and mod_perl. mod_perl is faster but takes more resources. You
|
||||
should probably only consider mod_perl if your Bugzilla is going to be heavily
|
||||
used.
|
||||
|
||||
.. _http-apache-mod_cgi:
|
||||
.. _apache-mod_cgi:
|
||||
|
||||
Apache with mod_cgi
|
||||
===================
|
||||
@ -16,6 +16,8 @@ Apache with mod_cgi
|
||||
To configure your Apache web server to work with Bugzilla while using
|
||||
mod_cgi, do the following:
|
||||
|
||||
XXX Shouldn't we be using sites-available/sites-enabled here?
|
||||
|
||||
#. Load :file:`httpd.conf` in your editor.
|
||||
In Fedora and Red Hat Linux, this file is found in
|
||||
:file:`/etc/httpd/conf`.
|
||||
@ -46,21 +48,13 @@ some global permissions.
|
||||
|
||||
.. note:: On Windows, you may have to also add the
|
||||
``ScriptInterpreterSource Registry-Strict``
|
||||
line, see :ref:`Windows specific notes <win32-http>`.
|
||||
line; see :ref:`Windows specific notes <win32-http>`.
|
||||
|
||||
XXX Does this link still work?
|
||||
|
||||
.. _http-apache-mod_perl:
|
||||
.. _apache-mod_perl:
|
||||
|
||||
Apache with mod_perl
|
||||
====================
|
||||
|
||||
Bugzilla requires version 1.999022 (AKA 2.0.0-RC5) of mod_perl.
|
||||
|
||||
XXX Is this relevant any more - how old is that version?
|
||||
|
||||
XXX Can one use mod_perl on Windows?
|
||||
|
||||
Some configuration is required to make Bugzilla work with Apache
|
||||
and mod_perl.
|
||||
|
||||
@ -83,7 +77,7 @@ and mod_perl.
|
||||
.. warning:: You should also ensure that you have disabled ``KeepAlive``
|
||||
support in your Apache install when utilizing Bugzilla under mod_perl
|
||||
|
||||
XXX How?
|
||||
XXX How? Why?
|
||||
|
||||
On restarting Apache, Bugzilla should now be running within the
|
||||
mod_perl environment.
|
||||
|
||||
@ -21,20 +21,20 @@ other ways wrong.
|
||||
Use Another Mail Server
|
||||
=======================
|
||||
|
||||
This section corresponds to choosing a :guilabel:`mail_delivery_method` of
|
||||
``SMTP``.
|
||||
This section corresponds to choosing a :param:`mail_delivery_method` of
|
||||
:paramval:`SMTP`.
|
||||
|
||||
This method passes the email off to an existing mail server. Your
|
||||
organization may well already have one running for their internal email, and
|
||||
may prefer to use it for confidentiality reasons. If so, you need the
|
||||
following information about it:
|
||||
|
||||
* The domain name of the server (Parameter: :guilabel:`smtpserver`)
|
||||
* The username and password to use (Parameters: :guilabel:`smtp_username` and
|
||||
:guilabel:`smtp_password`)
|
||||
* Whether the server uses SSL (Parameter: :guilabel:`smtp_ssl`)
|
||||
* The domain name of the server (Parameter: :param:`smtpserver`)
|
||||
* The username and password to use (Parameters: :param:`smtp_username` and
|
||||
:param:`smtp_password`)
|
||||
* Whether the server uses SSL (Parameter: :param:`smtp_ssl`)
|
||||
* The address you should be sending mail 'From' (Parameter:
|
||||
:guilabel:`mailfrom``)
|
||||
:param:`mailfrom``)
|
||||
|
||||
If your organization does not run its own mail server, you can use the
|
||||
services of one of any number of popular email providers.
|
||||
@ -45,18 +45,18 @@ Gmail
|
||||
Visit https://gmail.com and create a new Gmail account for your Bugzilla to
|
||||
use. Then, set the following parameter values in the "Email" section:
|
||||
|
||||
* :guilabel:`mail_delivery_method`: ``SMTP``
|
||||
* :guilabel:`mailfrom`: ``new_gmail_address@gmail.com``
|
||||
* :guilabel:`smtpserver`: ``smtp.gmail.com:465``
|
||||
* :guilabel:`smtp_username`: ``new_gmail_address@gmail.com``
|
||||
* :guilabel:`smtp_password`: ``new_gmail_password``
|
||||
* :guilabel:`smtp_ssl`: ``On``
|
||||
* :param:`mail_delivery_method`: :paramval:`SMTP`
|
||||
* :param:`mailfrom`: :paramval:`new_gmail_address@gmail.com`
|
||||
* :param:`smtpserver`: :paramval:`smtp.gmail.com:465`
|
||||
* :param:`smtp_username`: :paramval:`new_gmail_address@gmail.com`
|
||||
* :param:`smtp_password`: :paramval:`new_gmail_password`
|
||||
* :param:`smtp_ssl`: :paramval:`On`
|
||||
|
||||
Run Your Own Mail Server
|
||||
========================
|
||||
|
||||
This section corresponds to choosing a :guilabel:`mail_delivery_method` of
|
||||
``Sendmail``.
|
||||
This section corresponds to choosing a :param:`mail_delivery_method` of
|
||||
:paramval:`Sendmail`.
|
||||
|
||||
XXX Do we still need this? Why would anyone want to do this in 2014?
|
||||
|
||||
@ -84,5 +84,5 @@ ensure that the mail is delivered properly. They are implemented
|
||||
as services, and you should ensure that the MTA is in the auto-start
|
||||
list of services for the machine.
|
||||
|
||||
If a simple mail sent with the command-line 'mail' program
|
||||
If a simple mail sent with the command-line :file:`mail` program
|
||||
succeeds, then Bugzilla should also be fine.
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
:orphan:
|
||||
|
||||
.. _http-iis:
|
||||
.. _iis:
|
||||
|
||||
Microsoft IIS
|
||||
#############
|
||||
|
||||
@ -15,7 +15,7 @@ things should still work.
|
||||
|
||||
1. Shut down your Bugzilla by loading the front page, going to
|
||||
:guilabel:`Administration` | :guilabel:`Parameters` | :guilabel:`General`
|
||||
and putting some text into the :guilabel:`shutdownhtml` parameter.
|
||||
and putting some text into the :param:`shutdownhtml` parameter.
|
||||
|
||||
2. Make a backup of the bugs database. For a typical Bugzilla setup using
|
||||
MySQL, such a command might look like this:
|
||||
@ -30,8 +30,6 @@ things should still work.
|
||||
:ref:`installing`. Look at the old machine if you need to know what values
|
||||
you used for configuring e.g. MySQL.
|
||||
|
||||
XXX Need to say how far to go on the install
|
||||
|
||||
4. Copy the :file:`data` directory and the :file:`localconfig` file from the
|
||||
old Bugzilla installation to the new one.
|
||||
|
||||
@ -40,22 +38,22 @@ things should still work.
|
||||
appropriate variables in :file:`localconfig`.
|
||||
|
||||
6. If the new URL to your new Bugzilla installation is different from the old
|
||||
one, update the :guilabel:`urlbase` parameter in :file:`data/params` using
|
||||
one, update the :param:`urlbase` parameter in :file:`data/params` using
|
||||
a text editor.
|
||||
|
||||
7. Copy the database backup file :file:`bugzilla-backup.sql` file from your
|
||||
old server to the new one.
|
||||
|
||||
8. Create an empty "bugs" database on the new server:
|
||||
8. Create an empty ``bugs`` database on the new server:
|
||||
|
||||
:command:`mysql -u root -p -e "CREATE DATABASE bugs DEFAULT CHARACTER SET utf8;"`
|
||||
|
||||
9. Import your :file:`bugzilla-backup.sql` file into your new "bugs" database:
|
||||
9. Import your :file:`bugzilla-backup.sql` file into your new ``bugs`` database:
|
||||
|
||||
:command:`mysql -u root -p bugs < bugzilla-backup.sql`
|
||||
|
||||
If you get an error about "packet too large" or "mysql server has gone
|
||||
away", you need to adjust the :guilabel:`max_allowed_packet` setting in
|
||||
If you get an error about "packet too large" or "MySQL server has gone
|
||||
away", you need to adjust the ``max_allowed_packet`` setting in
|
||||
your :file:`my.cnf` file (usually :file:`/etc/my.cnf`) file to be larger
|
||||
than the largest attachment ever added to your Bugzilla.
|
||||
|
||||
@ -70,4 +68,4 @@ things should still work.
|
||||
|
||||
11. Activate your new Bugzilla by loading the front page, going to
|
||||
:guilabel:`Administration` | :guilabel:`Parameters` | :guilabel:`General`
|
||||
and removing the text from the :guilabel:`shutdownhtml` parameter.
|
||||
and removing the text from the :param:`shutdownhtml` parameter.
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
.. _install-mysql:
|
||||
.. _mysql:
|
||||
|
||||
MySQL
|
||||
#####
|
||||
@ -12,7 +12,7 @@ You need MySQL version 5.0.15 or higher.
|
||||
If you install MySQL manually rather than from a package, make sure the
|
||||
server is started when the machine boots.
|
||||
|
||||
.. _secure-mysql:
|
||||
.. _mysql-secure:
|
||||
|
||||
Secure MySQL
|
||||
============
|
||||
@ -23,7 +23,9 @@ On non-Windows platforms, run
|
||||
|
||||
and follow its advice.
|
||||
|
||||
Add a user
|
||||
.. _mysql-add-user:
|
||||
|
||||
Add a User
|
||||
==========
|
||||
|
||||
You need to add a new MySQL user for Bugzilla to use. Run the :file:`mysql`
|
||||
@ -34,11 +36,11 @@ command-line client and enter:
|
||||
GRANT SELECT, INSERT,
|
||||
UPDATE, DELETE, INDEX, ALTER, CREATE, LOCK TABLES,
|
||||
CREATE TEMPORARY TABLES, DROP, REFERENCES ON bugs.*
|
||||
TO bugs@localhost IDENTIFIED BY '$db_pass';
|
||||
TO bugs@localhost IDENTIFIED BY '$DB_PASS';
|
||||
|
||||
FLUSH PRIVILEGES;
|
||||
|
||||
You need to replace ``$db_pass`` with a strong password you have chosen.
|
||||
You need to replace ``$DB_PASS`` with a strong password you have chosen.
|
||||
Write that password down somewhere.
|
||||
|
||||
The above command permits an account called ``bugs``
|
||||
@ -48,7 +50,7 @@ machine or as a different user.
|
||||
|
||||
.. _mysql-max-allowed-packet:
|
||||
|
||||
Allow large attachments and many comments
|
||||
Allow Large Attachments and Many Comments
|
||||
=========================================
|
||||
|
||||
To change MySQL's configuration, you need to edit your MySQL
|
||||
@ -78,7 +80,9 @@ XXX is "adding" right? Surely it's normally present?
|
||||
# Allow packets up to 16MB
|
||||
max_allowed_packet=16M
|
||||
|
||||
Allow small words in full-text indexes
|
||||
.. _mysql-small-words:
|
||||
|
||||
Allow Small Words in Full-Text Indexes
|
||||
======================================
|
||||
|
||||
By default, words must be at least four characters in length
|
||||
@ -95,9 +99,9 @@ MySQL can be configured to index those words by setting the
|
||||
# Allow small words in full-text indexes
|
||||
ft_min_word_len=2
|
||||
|
||||
.. _install-setupdatabase-adduser:
|
||||
.. _mysql-attach-table-size:
|
||||
|
||||
Permit attachments table to grow beyond 4GB
|
||||
Permit Attachments Table to Grow Beyond 4GB
|
||||
===========================================
|
||||
|
||||
This is optional configuration for Bugzillas which are expected to become
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
.. _install-oracle:
|
||||
.. _oracle:
|
||||
|
||||
Oracle
|
||||
######
|
||||
@ -8,6 +8,8 @@ Oracle
|
||||
|
||||
You need Oracle version 10.02.0 or later.
|
||||
|
||||
.. _oracle-tablespace:
|
||||
|
||||
Create a New Tablespace
|
||||
=======================
|
||||
|
||||
@ -27,6 +29,8 @@ the path to the file containing your database, for instance
|
||||
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.
|
||||
|
||||
.. _oracle-add-user:
|
||||
|
||||
Add a User to Oracle
|
||||
====================
|
||||
|
||||
@ -49,6 +53,8 @@ as above.
|
||||
GRANT UNLIMITED TABLESPACE TO bugs;
|
||||
GRANT EXECUTE ON CTXSYS.CTX_DDL TO bugs;
|
||||
|
||||
.. _oracle_webserver:
|
||||
|
||||
Configure the Web Server
|
||||
========================
|
||||
|
||||
|
||||
@ -17,26 +17,26 @@ explicitly decide not to change).
|
||||
|
||||
The first set of these are in the :guilabel:`Required Settings` section.
|
||||
|
||||
* :guilabel:`urlbase`: this is the URL by which people should access
|
||||
* :param:`urlbase`: this is the URL by which people should access
|
||||
Bugzilla's front page.
|
||||
* :guilabel:`sslbase`: if you have configured SSL on your Bugzilla server,
|
||||
* :param:`sslbase`: if you have configured SSL on your Bugzilla server,
|
||||
this is the SSL URL by which people should access Bugzilla's front page.
|
||||
* :guilabel:`ssl_redirect`: Set this if you want everyone to be redirected
|
||||
* :param:`ssl_redirect`: Set this if you want everyone to be redirected
|
||||
to use the SSL version. Recommended if you have set up SSL.
|
||||
* :guilabel:`cookiebase`: Bugzilla uses cookies to remember who each user is.
|
||||
* :param:`cookiebase`: Bugzilla uses cookies to remember who each user is.
|
||||
In order to set those cookies in the correct scope, you may need to set a
|
||||
cookiebase. If your Bugzilla is at the root of your domain, you don't need
|
||||
to change the default value.
|
||||
|
||||
You will also need to tell Bugzilla how to :ref:`send email <email>`.
|
||||
|
||||
You may want to put your email address in the :guilabel:`maintainer`
|
||||
You may want to put your email address in the :param:`maintainer`
|
||||
parameter in the :guilabel:`General` section. This will then let people
|
||||
know who to contact if they see problems or hit errors.
|
||||
|
||||
If you don't want just anyone able to read your Bugzilla, set the
|
||||
:guilabel:`requirelogin` parameter in the :guilabel:`User Authentication`
|
||||
section, and change or clear the :guilabel:`createemailregexp` parameter.
|
||||
:param:`requirelogin` parameter in the :guilabel:`User Authentication`
|
||||
section, and change or clear the :param:`createemailregexp` parameter.
|
||||
|
||||
.. _optional-features:
|
||||
|
||||
@ -129,30 +129,6 @@ graphs. This example runs it every 15 minutes.
|
||||
third-party tools that can be used to implement cron, such as
|
||||
`nncron <http://www.nncron.ru/>`_.
|
||||
|
||||
.. _apache-addtype:
|
||||
|
||||
Serving Alternate Formats with the right MIME type
|
||||
--------------------------------------------------
|
||||
|
||||
Some Bugzilla pages have alternate formats, other than just plain
|
||||
HTML. In particular, a few Bugzilla pages can
|
||||
output their contents as either XUL (a special
|
||||
Mozilla format, that looks like a program GUI)
|
||||
or RDF (a type of structured XML
|
||||
that can be read by various programs).
|
||||
|
||||
In order for your users to see these pages correctly, Apache must
|
||||
send them with the right MIME type. To do this,
|
||||
add the following lines to your Apache configuration, either in the
|
||||
``<VirtualHost>`` section for your
|
||||
Bugzilla, or in the ``<Directory>``
|
||||
section for your Bugzilla:
|
||||
|
||||
.. code-block:: apache
|
||||
|
||||
AddType application/vnd.mozilla.xul+xml .xul
|
||||
AddType application/rdf+xml .rdf
|
||||
|
||||
.. _multiple-bz-dbs:
|
||||
|
||||
Multiple Bugzilla databases with a single installation
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
.. _install-pg:
|
||||
.. _postgresql:
|
||||
|
||||
PostgreSQL
|
||||
##########
|
||||
@ -12,6 +12,8 @@ You need PostgreSQL version 8.03.0000 or higher.
|
||||
If you install PostgreSQL manually rather than from a package, make sure the
|
||||
server is started when the machine boots.
|
||||
|
||||
.. _posgresql-add-user:
|
||||
|
||||
Add a User
|
||||
==========
|
||||
|
||||
@ -34,6 +36,8 @@ When asked for a password, provide one and write it down for later reference.
|
||||
The created user will not be a superuser (-S) and will not be able to create
|
||||
new users (-R). He will only have the ability to create databases (-d).
|
||||
|
||||
.. _postgresql-access:
|
||||
|
||||
Permit Access
|
||||
=============
|
||||
|
||||
|
||||
@ -22,7 +22,7 @@ home page. It requires a little familiarity with Linux and the command line.
|
||||
Here are some tips:
|
||||
|
||||
* Choose any server name you like.
|
||||
* When creating the initial Linux user, call it "bugzilla", give it a
|
||||
* When creating the initial Linux user, call it ``bugzilla``, give it a
|
||||
strong password, and write that password down.
|
||||
* You do not need an encrypted home directory.
|
||||
* Choose all the defaults for the "partitioning" part (excepting of course
|
||||
@ -84,7 +84,7 @@ home page. It requires a little familiarity with Linux and the command line.
|
||||
make it possible to search for short words and terms:
|
||||
|
||||
* Alter on Line 52: ``max_allowed_packet=100M``
|
||||
* Add as new line 31, in [mysqld] section: ``ft_min_word_len=2``
|
||||
* Add as new line 31, in the ``[mysqld]`` section: ``ft_min_word_len=2``
|
||||
|
||||
Save and exit.
|
||||
|
||||
@ -139,10 +139,10 @@ home page. It requires a little familiarity with Linux and the command line.
|
||||
|
||||
You will need to set the following values:
|
||||
|
||||
* Line 29: set $webservergroup to ``www-data``
|
||||
* Line 60: set $db_user to ``root``
|
||||
* Line 67: set $db_pass to the MySQL root user password you created when
|
||||
installing Ubuntu
|
||||
* Line 29: set ``$webservergroup`` to ``www-data``
|
||||
* Line 60: set ``$db_user`` to ``root``
|
||||
* Line 67: set ``$db_pass`` to the MySQL root user password you created
|
||||
when installing Ubuntu
|
||||
|
||||
XXX Given this is a quick setup on a dedicated box, is it OK to use the
|
||||
MySQL root user?
|
||||
@ -189,31 +189,32 @@ home page. It requires a little familiarity with Linux and the command line.
|
||||
13. Configure Bugzilla
|
||||
|
||||
Once you have worked out how to access your Bugzilla in a graphical
|
||||
web browser, bring up the front page, click "Log In" in the header, and
|
||||
log in as the admin user you defined in step 10.
|
||||
web browser, bring up the front page, click :guilabel:`Log In` in the
|
||||
header, and log in as the admin user you defined in step 10.
|
||||
|
||||
Click the "Parameters" link on the page it gives you, and set the
|
||||
following parameters in the 'Required Settings' section:
|
||||
Click the :guilabel:`Parameters` link on the page it gives you, and set
|
||||
the following parameters in the :guilabel:`Required Settings` section:
|
||||
|
||||
* urlbase: ``http://<servername>/`` or ``http://<ip address>/``
|
||||
* :param:`urlbase`:
|
||||
:paramval:`http://<servername>/` or :paramval:`http://<ip address>/`
|
||||
|
||||
Click "Save Changes" at the bottom of the page.
|
||||
Click :guilabel:`Save Changes` at the bottom of the page.
|
||||
|
||||
There are several ways to get Bugzilla to send email. The easiest is to
|
||||
use Gmail, so we do that here so you have it working. Visit
|
||||
https://gmail.com and create a new Gmail account for your Bugzilla to use.
|
||||
Then, open the "Email" section of the Parameters using the link in the
|
||||
left column, and set the following parameter values:
|
||||
Then, open the :guilabel:`Email` section of the Parameters using the link
|
||||
in the left column, and set the following parameter values:
|
||||
|
||||
* mail_delivery_method: SMTP
|
||||
* mailfrom: ``new_gmail_address@gmail.com``
|
||||
* smtpserver: ``smtp.gmail.com:465``
|
||||
* smtp_username: ``new_gmail_address@gmail.com``
|
||||
* smtp_password: ``new_gmail_password``
|
||||
* smtp_ssl: On
|
||||
* :param:`mail_delivery_method`: :paramval:`SMTP`
|
||||
* :param:`mailfrom`: :paramval:`new_gmail_address@gmail.com`
|
||||
* :param:`smtpserver`: :paramval:`smtp.gmail.com:465`
|
||||
* :param:`smtp_username`: :paramval:`new_gmail_address@gmail.com`
|
||||
* :param:`smtp_password`: :paramval:`new_gmail_password`
|
||||
* :param:`smtp_ssl`: :paramval:`On`
|
||||
|
||||
Click "Save Changes" at the bottom of the page.
|
||||
Click :guilabel:`Save Changes` at the bottom of the page.
|
||||
|
||||
XXX There should be a "send test email" button on that page
|
||||
|
||||
Now proceed to Chapter XXX, "Initial Configuration".
|
||||
And you're all ready to go. :-)
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
.. _install-sqlite:
|
||||
.. _sqlite:
|
||||
|
||||
SQLite
|
||||
######
|
||||
@ -8,7 +8,7 @@ SQLite
|
||||
small and development Bugzilla installations.
|
||||
|
||||
Once you have SQLite installed, no additional configuration is required to
|
||||
run Bugzilla. Simply set $db_driver to "Sqlite" (case-sensitive) in
|
||||
run Bugzilla. Simply set ``$db_driver`` to ``Sqlite`` (case-sensitive) in
|
||||
:file:`localconfig`, when you get to that point in the installation.
|
||||
|
||||
XXX This doesn't work - gives a timezone-related error on my box.
|
||||
|
||||
@ -14,7 +14,6 @@ adjustments. A detailed step-by-step
|
||||
`installation guide for Windows <https://wiki.mozilla.org/Bugzilla:Win32Install>`_ is also available
|
||||
if you need more help with your installation.
|
||||
|
||||
|
||||
:file:`checksetup.pl` will print out a list of the
|
||||
required and optional Perl modules, together with the versions
|
||||
(if any) installed on your machine.
|
||||
|
||||
@ -4,44 +4,57 @@ APIs
|
||||
####
|
||||
|
||||
Bugzilla has a number of APIs that you can call in your code to extract
|
||||
information from and put information into it. The APIs currently supported
|
||||
are as follows:
|
||||
information from and put information into Bugzilla. Some are deprecated and
|
||||
will soon be removed. Which one to use? Short answer: the
|
||||
`REST API
|
||||
<http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/WebService/Server/REST.html>`_
|
||||
should be used for all new integrations, but keep an eye out for version 2,
|
||||
coming soon.
|
||||
|
||||
The APIs currently available are as follows:
|
||||
|
||||
Ad-Hoc APIs
|
||||
===========
|
||||
|
||||
Various pages on Bugzilla are available in machine-readable formats. For
|
||||
example, bugs can be downloaded as XML, and buglists as CSV. While the team
|
||||
attempts not to break these APIs, they should not be used for new code.
|
||||
Various pages on Bugzilla are available in machine-parseable formats as well
|
||||
as HTML. For example, bugs can be downloaded as XML, and buglists as CSV.
|
||||
While the team attempts not to break these ad-hoc APIs, they should not be
|
||||
used for new code.
|
||||
|
||||
XML-RPC
|
||||
=======
|
||||
|
||||
Bugzilla has an XXXLINK XML-RPC API. This will receive no further updates and will
|
||||
be removed in a future version of Bugzilla.
|
||||
Bugzilla has an `XML-RPC API
|
||||
<http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/WebService/Server/XMLRPC.html>`_.
|
||||
This will receive no further updates and will be removed in a future version
|
||||
of Bugzilla.
|
||||
|
||||
JSON-RPC
|
||||
========
|
||||
|
||||
Bugzilla has a XXXLINK JSON-RPC API. This will receive no further updates and will
|
||||
be removed in a future version of Bugzilla.
|
||||
Bugzilla has a `JSON-RPC API
|
||||
<http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/WebService/Server/JSONRPC.html>`_.
|
||||
This will receive no further updates and will be removed in a future version
|
||||
of Bugzilla.
|
||||
|
||||
REST
|
||||
====
|
||||
|
||||
Bugzilla has a XXXLINK REST API which is the currently-recommended API for
|
||||
integrating with Bugzilla. The current REST API is version 1. It is stable,
|
||||
and so will not be changed in a backwardly-incompatible way.
|
||||
Bugzilla has a `REST API
|
||||
<http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/WebService/Server/REST.html>`_
|
||||
which is the currently-recommended API for integrating with Bugzilla. The
|
||||
current REST API is version 1. It is stable, and so will not be changed in a
|
||||
backwardly-incompatible way.
|
||||
|
||||
BzAPI-Compatible REST
|
||||
=====================
|
||||
|
||||
The first ever REST API for Bugzilla was implemented using an external proxy
|
||||
called BzAPI. This became popular enough that a BzAPI-compatible shim on top
|
||||
of the (native) REST API has been written, to allow code which used the BzAPI
|
||||
API to take advantage of the speed improvements of direct integration without
|
||||
needing to be rewritten. The shim is an extension which you would need to
|
||||
install in your Bugzilla.
|
||||
called `BzAPI <https://wiki.mozilla.org/Bugzilla:BzAPI>`_. This became popular
|
||||
enough that a BzAPI-compatible shim on top of the (native) REST API has been
|
||||
written, to allow code which used the BzAPI API to take advantage of the
|
||||
speed improvements of direct integration without needing to be rewritten.
|
||||
The shim is an extension which you would need to install in your Bugzilla.
|
||||
|
||||
Neither BzAPI nor this BzAPI-compatible API shim will receive any further
|
||||
updates, and they should not be used for new code.
|
||||
|
||||
@ -1,5 +1,7 @@
|
||||
:orphan:
|
||||
|
||||
.. _style-guide:
|
||||
|
||||
==============================
|
||||
Writing Bugzilla Documentation
|
||||
==============================
|
||||
@ -86,11 +88,23 @@ Inline Directives
|
||||
.. warning:: Remember that reST does not support nested inline markup. So you
|
||||
can't have a substitution inside a link, or bold inside italics.
|
||||
|
||||
A filename or a path to a filename is displayed like this:
|
||||
:file:`/path/to/{variable-bit-of-path}/filename.ext`
|
||||
* A filename or a path to a filename:
|
||||
:file:`/path/to/{variable-bit-of-path}/filename.ext`
|
||||
|
||||
A command to type in the shell is displayed like this:
|
||||
:command:`command --arguments`
|
||||
* A command to type in the shell:
|
||||
:command:`command --arguments`
|
||||
|
||||
A parameter name is displayed like this:
|
||||
:guilabel:`shutdownhtml`
|
||||
* A parameter name:
|
||||
:param:`shutdownhtml`
|
||||
|
||||
* A parameter value:
|
||||
:paramval:`DB`
|
||||
|
||||
* A group name:
|
||||
:group:`editbugs`
|
||||
|
||||
* A bug field name:
|
||||
:field:`Summary`
|
||||
|
||||
* Any string from the UI:
|
||||
:guilabel:`Administration`
|
||||
|
||||
@ -5,7 +5,7 @@ Using Bugzilla
|
||||
==============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:maxdepth: 2
|
||||
|
||||
using/creating-an-account
|
||||
using/filing
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user