diff options
| -rw-r--r-- | docs/en/xml/administration.xml | 1390 |
1 files changed, 795 insertions, 595 deletions
diff --git a/docs/en/xml/administration.xml b/docs/en/xml/administration.xml index 12c72dd84..a82a659bf 100644 --- a/docs/en/xml/administration.xml +++ b/docs/en/xml/administration.xml @@ -38,24 +38,27 @@ <step> <para> - <command>makeproductgroups</command>: - This dictates whether or not to automatically create groups - when new products are created. - </para> + <command>usebuggroups</command>: + This dictates whether or not to implement group-based security for + Bugzilla. If set, Bugzilla bugs can have an associated 'group', + defining which users are allowed to see and edit the + bug.</para> + + <para>Set "usebuggroups" to "on" + <emphasis>only</emphasis> + if you may wish to restrict access to particular bugs to certain + groups of users. I suggest leaving + this parameter <emphasis>off</emphasis> + while initially testing your Bugzilla.</para> </step> <step> <para> - <command>useentrygroupdefault</command>: - Bugzilla products can have a group associated with them, so that - certain users can only see bugs in certain products. When this - parameter is set to <quote>on</quote>, this - causes the initial group controls on newly created products - to place all newly-created bugs in the group - having the same name as the product immediately. - After a product is initially created, the group controls - can be further adjusted without interference by - this mechanism.</para> + <command>usebuggroupsentry</command>: + Bugzilla Products can have a group associated with them, so that + certain users can only see bugs in certain products. When this parameter + is set to <quote>on</quote>, this places all newly-created bugs in the + group for their product immediately.</para> </step> <step> @@ -66,14 +69,8 @@ write locking. What this means is that if someone needs to make a change to a bug, they will lock the entire table until the operation is complete. Locking for write also blocks reads until the write is - complete. Note that more recent versions of mysql support row level - locking using different table types. These types are slower than the - standard type, and Bugzilla does not yet take advantage of features - such as transactions which would justify this speed decrease. The - Bugzilla team are, however, happy to hear about any experiences with - row level locking and Bugzilla.</para> - - <para>The <quote>shadowdb</quote> + complete. The + <quote>shadowdb</quote> parameter was designed to get around this limitation. While only a single user is allowed to write to a table at a time, reads can continue unimpeded on a read-only shadow copy of the database. @@ -82,16 +79,29 @@ high-traffic Bugzilla databases.</para> <para> - As a guide, on reasonably old hardware, mozilla.org began needing + As a guide, mozilla.org began needing <quote>shadowdb</quote> when they reached around 40,000 Bugzilla users with several hundred Bugzilla bug changes and comments per day.</para> <para>The value of the parameter defines the name of the - shadow bug database. You will need to set the host and port settings - from the params page, and set up replication in your database server - so that updates reach this readonly mirror. Consult your database - documentation for more detail.</para> + shadow bug database. + Set "shadowdb" to e.g. "bug_shadowdb" if you will be running a + *very* large installation of Bugzilla. + <note> + <para>Enabling "shadowdb" can adversely affect the stability of + your installation of Bugzilla. You should regularly check that your + database is in sync. It is often advisable to force a shadow + database sync nightly via + <quote>cron</quote>. + </para> + </note> + </para> + + <para>If you use the "shadowdb" option, it is only natural that you + should turn the "queryagainstshadowdb" option on as well. Otherwise + you are replicating data into a shadow database for no reason!</para> + </step> <step> @@ -119,19 +129,6 @@ blurb about how to use Bugzilla at your site.</para> </step> - - <step> - <para> - <command>movebugs</command>: - - This option is an undocumented feature to allow moving bugs - between separate Bugzilla installations. You will need to understand - the source code in order to use this feature. Please consult - <filename>movebugs.pl</filename> in your Bugzilla source tree for - further documentation, such as it is. - </para> - </step> - <step> <para> <command>useqacontact</command>: @@ -215,11 +212,33 @@ you for this username and password.</para> <tip> - <para>If you wish to add more administrative users, add them to - the "admin" group and, optionally, add edit the tweakparams, editusers, - creategroups, editcomponents, and editkeywords groups to add the - entire admin group to those groups. + <para>If you wish to add more administrative users, you must use the + MySQL interface. Run "mysql" from the command line, and use these + commands: + <simplelist> + <member> + <prompt>mysql></prompt> + <command>use bugs;</command> + </member> + + <member> + <prompt>mysql></prompt> + + <command> + update profiles set groupset=0x7ffffffffffffff where login_name = + "(user's login name)"; + </command> + </member> + </simplelist> </para> + + <para>Yes, that is + <emphasis>fourteen</emphasis> + + <quote>f</quote> + + 's. A whole lot of f-ing going on if you want to create a new + administator.</para> </tip> </section> @@ -321,7 +340,7 @@ they attempt to perform these actions, and should explain why the account was disabled. <warning> - <para>Don't disable all the administrator accounts!</para> + <para>Don't disable the administrator account!</para> </warning> <note> @@ -418,167 +437,178 @@ </section> </section> - <section id="products"> - <title>Products</title> + <section id="programadmin"> + <title>Product, Component, Milestone, and Version Administration</title> - <para> - <glossterm linkend="gloss-product" baseform="product"> - Products</glossterm> + <section id="products"> + <title>Products</title> - are the broadest category in Bugzilla, and tend to represent real-world - shipping products. E.g. if your company makes computer games, - you should have one product per game, perhaps a "Common" product for - units of technology used in multiple games, and maybe a few special - products (Website, Administration...)</para> + <para> + <glossterm linkend="gloss-product" baseform="product"> + Products</glossterm> - <para>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.</para> + are the broadest category in Bugzilla, and tend to represent real-world + shipping products. E.g. if your company makes computer games, + you should have one product per game, perhaps a "Common" product for + units of technology used in multiple games, and maybe a few special + products (Website, Administration...)</para> - <para>To create a new product:</para> + <para>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.</para> - <orderedlist> - <listitem> - <para>Select "products" from the footer</para> + <para>To create a new product:</para> - </listitem> + <orderedlist> + <listitem> + <para>Select "products" from the footer</para> - <listitem> - <para>Select the "Add" link in the bottom right</para> - </listitem> + </listitem> - <listitem> - <para>Enter the name of the product and a description. The - Description field may contain HTML.</para> - </listitem> - </orderedlist> + <listitem> + <para>Select the "Add" link in the bottom right</para> + </listitem> - <para>Don't worry about the "Closed for bug entry", "Maximum Votes - per person", "Maximum votes a person can put on a single bug", - "Number of votes a bug in this Product needs to automatically get out - of the UNCOMFIRMED state", and "Version" options yet. We'll cover - those in a few moments. - </para> - </section> + <listitem> + <para>Enter the name of the product and a description. The + Description field may contain HTML.</para> + </listitem> + </orderedlist> - <section id="components"> - <title>Components</title> + <para>Don't worry about the "Closed for bug entry", "Maximum Votes + per person", "Maximum votes a person can put on a single bug", + "Number of votes a bug in this Product needs to automatically get out + of the UNCOMFIRMED state", and "Version" options yet. We'll cover + those in a few moments. + </para> + </section> - <para>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.</para> + <section id="components"> + <title>Components</title> - <para> - Each component has a owner and (if you turned it on in the parameters), - a QA Contact. The owner should be the primary person who fixes bugs in - that component. The QA Contact should be the person who will ensure - these bugs are completely fixed. The Owner, QA Contact, and Reporter - will get email when new bugs are created in this Component and when - these bugs change. Default Owner and Default QA Contact fields only - dictate the - <emphasis>default assignments</emphasis>; - these can be changed on bug submission, or at any later point in - a bug's life.</para> - - <para>To create a new Component:</para> + <para>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.</para> + + <para> + Each component has a owner and (if you turned it on in the parameters), + a QA Contact. The owner should be the primary person who fixes bugs in + that component. The QA Contact should be the person who will ensure + these bugs are completely fixed. The Owner, QA Contact, and Reporter + will get email when new bugs are created in this Component and when + these bugs change. Default Owner and Default QA Contact fields only + dictate the + <emphasis>default assignments</emphasis>; + these can be changed on bug submission, or at any later point in + a bug's life.</para> + + <para>To create a new Component:</para> - <orderedlist> - <listitem> - <para>Select the "Edit components" link from the "Edit product" - page</para> - </listitem> + <orderedlist> + <listitem> + <para>Select the "Edit components" link from the "Edit product" + page</para> + </listitem> - <listitem> - <para>Select the "Add" link in the bottom right.</para> - </listitem> + <listitem> + <para>Select the "Add" link in the bottom right.</para> + </listitem> - <listitem> - <para>Fill out the "Component" field, a short "Description", - the "Initial Owner" and "Initial QA Contact" (if enabled.) - The Component and Description fields may contain HTML; - the "Initial Owner" field must be a login name - already existing in the database. - </para> - </listitem> - </orderedlist> - </section> + <listitem> + <para>Fill out the "Component" field, a short "Description", + the "Initial Owner" and "Initial QA Contact" (if enabled.) + The Component and Description fields may contain HTML; + the "Initial Owner" field must be a login name + already existing in the database. + </para> + </listitem> + </orderedlist> + </section> - <section id="versions"> - <title>Versions</title> + <section id="versions"> + <title>Versions</title> - <para>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. - </para> + <para>Versions are the revisions of the product, such as "Flinders + 3.1", "Flinders 95", and "Flinders 2000". Version is not a multi-select + field; the usual practice is to select the most recent version with + the bug. + </para> - <para>To create and edit Versions:</para> + <para>To create and edit Versions:</para> - <orderedlist> - <listitem> - <para>From the "Edit product" screen, select "Edit Versions"</para> - </listitem> + <orderedlist> + <listitem> + <para>From the "Edit product" screen, select "Edit Versions"</para> + </listitem> - <listitem> - <para>You will notice that the product already has the default - version "undefined". Click the "Add" link in the bottom right.</para> - </listitem> + <listitem> + <para>You will notice that the product already has the default + version "undefined". Click the "Add" link in the bottom right.</para> + </listitem> - <listitem> - <para>Enter the name of the Version. This field takes text only. - Then click the "Add" button.</para> - </listitem> + <listitem> + <para>Enter the name of the Version. This field takes text only. + Then click the "Add" button.</para> + </listitem> - </orderedlist> - </section> + </orderedlist> + </section> - <section id="milestones"> - <title>Milestones</title> + <section id="milestones"> + <title>Milestones</title> - <para>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.</para> + <para>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.</para> - <note> - <para>Milestone options will only appear for a Product if you turned - on the "usetargetmilestone" Param in the "Edit Parameters" screen. - </para> - </note> + <note> + <para>Milestone options will only appear for a Product if you turned + on the "usetargetmilestone" Param in the "Edit Parameters" screen. + </para> + </note> - <para>To create new Milestones, set Default Milestones, and set - Milestone URL:</para> + <para>To create new Milestones, set Default Milestones, and set + Milestone URL:</para> - <orderedlist> - <listitem> - <para>Select "Edit milestones" from the "Edit product" page.</para> - </listitem> + <orderedlist> + <listitem> + <para>Select "Edit milestones" from the "Edit product" page.</para> + </listitem> - <listitem> - <para>Select "Add" in the bottom right corner. - text</para> - </listitem> + <listitem> + <para>Select "Add" in the bottom right corner. + text</para> + </listitem> - <listitem> - <para>Enter the name of the Milestone in the "Milestone" field. You - can optionally set the "sortkey", which is a positive or negative - number (-255 to 255) that defines where in the list this particular - milestone appears. This is because milestones often do not - occur in alphanumeric order For example, "Future" might be - after "Release 1.2". Select "Add".</para> - </listitem> + <listitem> + <para>Enter the name of the Milestone in the "Milestone" field. You + can optionally set the "sortkey", which is a positive or negative + number (-255 to 255) that defines where in the list this particular + milestone appears. This is because milestones often do not + occur in alphanumeric order For example, "Future" might be + after "Release 1.2". Select "Add".</para> + </listitem> - <listitem> - <para>From the Edit product screen, you can enter the URL of a - page which gives information about your milestones and what - they mean. </para> - </listitem> - </orderedlist> + <listitem> + <para>From the Edit product screen, you can enter the URL of a + page which gives information about your milestones and what + they mean. </para> + + <tip> + <para>If you want your milestone document to be restricted so + that it can only be viewed by people in a particular Bugzilla + group, the best way is to attach the document to a bug in that + group, and make the URL the URL of that attachment.</para> + </tip> + </listitem> + </orderedlist> + </section> </section> <section id="voting"> @@ -607,7 +637,7 @@ <listitem> <para><emphasis>Maximum Votes a person can put on a single - bug</emphasis>: + bug"</emphasis>: 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 @@ -629,484 +659,654 @@ </orderedlist> </section> - <section id="quips"> - <title>Quips</title> + <section id="groups"> + <title>Groups and Group Security</title> - <para> - 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. + <para>Groups allow the administrator + to isolate bugs or products that should only be seen by certain people. + There are two types of group - Generic Groups, and Product-Based Groups. </para> - + <para> - Quips are controlled by the <emphasis>enablequips</emphasis> parameter. - It has several possible values: on, approved, frozen or off. - In order to enable quips approval you need to set this parameter - to "approved". In this way, users are free to submit quips for - addition but an administrator must explicitly approve them before - they are actually used. + Product-Based Groups are matched with products, and allow you to restrict + access to bugs on a per-product basis. They are enabled using the + usebuggroups Param. Turning on the usebuggroupsentry + Param will mean bugs automatically get added to their product group when + filed. </para> - + <para> - 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. + Generic Groups have no special relationship to products; + you create them, and put bugs in them + as required. One example of the use of Generic Groups + is Mozilla's "Security" group, + into which security-sensitive bugs are placed until fixed. Only the + Mozilla Security Team are members of this group. </para> + + <para>To create Generic Groups:</para> - <para> - 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. - </para> - - <para> - Also, there is a delete link next to each quip, - which can be used in order to permanently delete a quip. - </para> - </section> + <orderedlist> + <listitem> + <para>Select the "groups" + link in the footer.</para> + </listitem> - <section id="groups"> - <title>Groups and Group Security</title> + <listitem> + <para>Take a moment to understand the instructions on the "Edit + Groups" screen, then select the "Add Group" link.</para> + </listitem> - <para>Groups allow the administrator - to isolate bugs or products that should only be seen by certain people. - The association between products and groups is controlled from - the product edit page under <quote>Edit Group Controls.</quote> - </para> + <listitem> + <para>Fill out the "New Name", "New Description", and + "New User RegExp" fields. "New User RegExp" allows you to automatically + place all users who fulfill the Regular Expression into the new group. + When you have finished, click "Add".</para> + </listitem> + </orderedlist> + + <para>To use Product-Based Groups:</para> + + <orderedlist> + <listitem> + <para>Turn on "usebuggroups" and "usebuggroupsentry" in the "Edit + Parameters" screen.</para> + + <warning> + <para>XXX is this still true? + "usebuggroupsentry" has the capacity to prevent the + administrative user from directly altering bugs because of + conflicting group permissions. If you plan on using + "usebuggroupsentry", you should plan on restricting + administrative account usage to administrative duties only. In + other words, manage bugs with an unpriveleged user account, and + manage users, groups, Products, etc. with the administrative + account.</para> + </warning> + </listitem> + + <listitem> + <para>In future, when you create a Product, a matching group will be + automatically created. If you need to add a Product Group to + a Product which was created before you turned on usebuggroups, + then simply create a new group, as outlined above, with the + same name as the Product.</para> + </listitem> + </orderedlist> + + <warning> + <para>Bugzilla currently has a limit of 64 groups per installation. If + you have more than about 50 products, you should consider + running multiple Bugzillas. Ask in the newsgroup for other + suggestions for working around this restriction.</para> + </warning> - <para> - If the makeproductgroups param is on, a new group will be automatically - created for every new product. It is primarily available for backward - compatibility with older sites. - </para> <para> Note that group permissions are such that you need to be a member of <emphasis>all</emphasis> the groups a bug is in, for whatever - reason, to see that bug. Similarly, you must be a member - of <emphasis>all</emphasis> of the entry groups for a product - to add bugs to a product and you must be a member - of <emphasis>all</emphasis> of the canedit groups for a product - in order to make <emphasis>any</emphasis> change to bugs in that - product. + reason, to see that bug. </para> - <section> - <title>Creating Groups</title> - <para>To create Groups:</para> - - <orderedlist> - <listitem> - <para>Select the <quote>groups</quote> - link in the footer.</para> - </listitem> - - <listitem> - <para>Take a moment to understand the instructions on the <quote>Edit - Groups</quote> screen, then select the <quote>Add Group</quote> link.</para> - </listitem> - - <listitem> - <para>Fill out the <quote>Group</quote>, <quote>Description</quote>, - and <quote>User RegExp</quote> fields. - <quote>User RegExp</quote> allows you to automatically - place all users who fulfill the Regular Expression into the new group. - When you have finished, click <quote>Add</quote>.</para> - <para>Users whose email addresses match the regular expression - will automatically be members of the group as long as their - email addresses continue to match the regular expression.</para> - <note> - <para>This is a change from 2.16 where the regular expression - resulted in a user acquiring permanent membership in a group. - To remove a user from a group the user was in due to a regular - expression in version 2.16 or earlier, the user must be explicitly - removed from the group.</para> - </note> - <warning> - <para>If specifying a domain in the regexp, make sure you end - the regexp with a $. Otherwise, when granting access to - "@mycompany\.com", you will allow access to - 'badperson@mycompany.com.cracker.net'. You need to use - '@mycompany\.com$' as the regexp.</para> - </warning> - </listitem> - <listitem> - <para>If you plan to use this group to directly control - access to bugs, check the "use for bugs" box. Groups - not used for bugs are still useful because other groups - can include the group as a whole.</para> - </listitem> - <listitem> - <para>After you add your new group, edit the new group. On the - edit page, you can specify other groups that should be included - in this group and which groups should be permitted to add and delete - users from this group.</para> - </listitem> - </orderedlist> - - </section> - <section> - <title>Assigning Users to Groups</title> - <para>Users can become a member of a group in several ways.</para> - <orderedlist> - <listitem> - <para>The user can be explicitly placed in the group by editing - the user's own profile</para> - </listitem> - <listitem> - <para>The group can include another group of which the user is - a member.</para> - </listitem> - <listitem> - <para>The user's email address can match a regular expression - that the group specifies to automatically grant membership to - the group.</para> - </listitem> - </orderedlist> - </section> - - <section> - <title>Assigning Group Controls to Products</title> - <para> - On the product edit page, there is a page to edit the - <quote>Group Controls</quote> - for a product. This allows you to - configure how a group relates to the product. - Groups may be applicable, default, - and mandatory as well as used to control entry - or used to make bugs in the product - totally read-only unless the group restrictions are met. - </para> - - <para> - For each group, it is possible to specify if membership in that - group is... - </para> - <orderedlist> - <listitem> - <para> - required for bug entry, - </para> - </listitem> - <listitem> - <para> - Not applicable to this product(NA), - a possible restriction for a member of the - group to place on a bug in this product(Shown), - a default restriction for a member of the - group to place on a bug in this product(Default), - or a mandatory restriction to be placed on bugs - in this product(Mandatory). - </para> - </listitem> - <listitem> - <para> - Not applicable by non-members to this product(NA), - a possible restriction for a non-member of the - group to place on a bug in this product(Shown), - a default restriction for a non-member of the - group to place on a bug in this product(Default), - or a mandatory restriction to be placed on bugs - in this product when entered by a non-member(Mandatory). - </para> - </listitem> - <listitem> - <para> - required in order to make <emphasis>any</emphasis> change - to bugs in this product <emphasis>including comments.</emphasis> - </para> - </listitem> - </orderedlist> - <para>These controls are often described in this order, so a - product that requires a user to be a member of group "foo" - to enter a bug and then requires that the bug stay resticted - to group "foo" at all times and that only members of group "foo" - can edit the bug even if they otherwise could see the bug would - have its controls summarized by...</para> - <programlisting> -foo: ENTRY, MANDATORY/MANDATORY, CANEDIT - </programlisting> - - </section> - <section> - <title>Common Applications of Group Controls</title> - <section> - <title>General User Access With Security Group</title> - <para>To permit any user to file bugs in each product (A, B, C...) - and to permit any user to submit those bugs into a security - group....</para> - <programlisting> -Product A... -security: SHOWN/SHOWN -Product B... -security: SHOWN/SHOWN -Product C... -security: SHOWN/SHOWN - </programlisting> - </section> - <section> - <title>General User Access With A Security Product</title> - <para>To permit any user to file bugs in a Security product - while keeping those bugs from becoming visible to anyone - outside the securityworkers group unless a member of the - securityworkers group removes that restriction....</para> - <programlisting> -Product Security... -securityworkers: DEFAULT/MANDATORY - </programlisting> - </section> - <section> - <title>Product Isolation With Common Group</title> - <para>To permit users of product A to access the bugs for - product A, users of product B to access product B, and support - staff to access both, 3 groups are needed</para> - <orderedlist> - <listitem> - <para>Support: Contains members of the support staff.</para> - </listitem> - <listitem> - <para>AccessA: Contains users of product A and the Support group.</para> - </listitem> - <listitem> - <para>AccessB: Contains users of product B and the Support group.</para> - </listitem> - </orderedlist> - <para>Once these 3 groups are defined, the products group controls - can be set to..</para> - <programlisting> -Product A... -AccessA: ENTRY, MANDATORY/MANDATORY -Product B... -AccessB: ENTRY, MANDATORY/MANDATORY - </programlisting> - <para>Optionally, the support group could be permitted to make - bugs inaccessible to the users and could be permitted to publish - bugs relevant to all users in a common product that is read-only - to anyone outside the support group. That configuration could - be...</para> - <programlisting> -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 - </programlisting> - </section> - </section> </section> - <section id="upgrading"> - <title>Upgrading to New Releases</title> + + <section id="security"> + <title>Bugzilla Security</title> <warning> - <para>Upgrading is a one-way process. You should backup your database - and current Bugzilla directory before attempting the upgrade. If you wish - to revert to the old Bugzilla version for any reason, you will have to - restore from these backups. - </para> + <para>Poorly-configured MySQL and Bugzilla installations have + given attackers full access to systems in the past. Please take these + guidelines seriously, even for Bugzilla machines hidden away behind + your firewall. 80% of all computer trespassers are insiders, not + anonymous crackers.</para> </warning> - <para>Upgrading Bugzilla is something we all want to do from time to time, - be it to get new features or pick up the latest security fix. How easy - it is to update depends on a few factors. - </para> + <note> + <para>These instructions must, of necessity, be somewhat vague since + Bugzilla runs on so many different platforms. If you have refinements + of these directions for specific platforms, please submit them to + <ulink url="mailto://mozilla-webtools@mozilla.org"> + mozilla-webtools@mozilla.org</ulink> + </para> + </note> - <itemizedlist> + <para>To secure your installation: + + <orderedlist> <listitem> - <para>If the new version is a revision or a new point release</para> + <para>Ensure you are running at least MysQL version 3.22.32 or newer. + Earlier versions had notable security holes and (from a security + point of view) poor default configuration choices.</para> </listitem> + <listitem> - <para>How many, if any, local changes have been made</para> - </listitem> - </itemizedlist> + <para> + <emphasis>There is no substitute for understanding the tools on your + system!</emphasis> - <para>There are also three different methods to upgrade your installation. - </para> + Read + <ulink url="http://www.mysql.com/doc/P/r/Privilege_system.html"> + The MySQL Privilege System</ulink> + until you can recite it from memory!</para> + </listitem> - <orderedlist> <listitem> - <para>Using CVS (<xref linkend="upgrade-cvs"/>)</para> + <para>Lock down /etc/inetd.conf. Heck, disable inet entirely on this + box. It should only listen to port 25 for Sendmail and port 80 for + Apache.</para> </listitem> + <listitem> - <para>Downloading a new tarball (<xref linkend="upgrade-tarball"/>)</para> + <para>Do not run Apache as + <quote>nobody</quote> + + . This will require very lax permissions in your Bugzilla + directories. Run it, instead, as a user with a name, set via your + httpd.conf file. + <note> + <para> + <quote>nobody</quote> + + is a real user on UNIX systems. Having a process run as user id + <quote>nobody</quote> + + is absolutely no protection against system crackers versus using + any other user account. As a general security measure, I recommend + you create unique user ID's for each daemon running on your system + and, if possible, use "chroot" to jail that process away from the + rest of your system.</para> + </note> + </para> </listitem> + <listitem> - <para>Applying the relevant patches (<xref linkend="upgrade-patches"/>)</para> - </listitem> - </orderedlist> + <para>Ensure you have adequate access controls for the + $BUGZILLA_HOME/data/ directory, as well as the + $BUGZILLA_HOME/localconfig file. + The localconfig file stores your "bugs" database account password. + In addition, some + files under $BUGZILLA_HOME/data/ store sensitive information. + </para> - <para>Which options are available to you may depend on how large a jump - you are making and/or your network configuration. - </para> + <para>Bugzilla provides default .htaccess files to protect the most + common Apache installations. However, you should verify these are + adequate according to the site-wide security policy of your web + server, and ensure that the .htaccess files are allowed to + "override" default permissions set in your Apache configuration + files. Covering Apache security is beyond the scope of this Guide; + please consult the Apache documentation for details.</para> + + <para>If you are using a web server that does not support the + .htaccess control method, + <emphasis>you are at risk!</emphasis> + + After installing, check to see if you can view the file + "localconfig" in your web browser (e.g.: + <ulink url="http://bugzilla.mozilla.org/localconfig"> + http://bugzilla.mozilla.org/localconfig</ulink> + + ). If you can read the contents of this file, your web server has + not secured your bugzilla directory properly and you must fix this + problem before deploying Bugzilla. If, however, it gives you a + "Forbidden" error, then it probably respects the .htaccess + conventions and you are good to go.</para> + + <para>When you run checksetup.pl, the script will attempt to modify + various permissions on files which Bugzilla uses. If you do not have + a webservergroup set in the localconfig file, then Bugzilla will have + to make certain files world readable and/or writable. + <emphasis>THIS IS INSECURE!</emphasis> + + . This means that anyone who can get access to your system can do + whatever they want to your Bugzilla installation.</para> - <para>Revisions are normally released to fix security vulnerabilities - and are distinguished by an increase in the third number. For example, - when 2.16.6 was released, it was a revision to 2.16.5. - </para> + <note> + <para>This also means that if your webserver runs all cgi scripts + as the same user/group, anyone on the system who can run cgi + scripts will be able to take control of your Bugzilla + installation.</para> + </note> - <para>Point releases are normally released when the Bugzilla team feels - that there has been a significant amount of progress made between the - last point release and the current time. These are often proceeded by a - stabilization period and release candidates, however the use of - development versions or release candidates is beyond the scope of this - document. Point releases can be distinguished by an increase in the - second number, or minor version. For example, 2.18.0 is a newer point - release than 2.16.5. - </para> + <para>On Apache, you can use .htaccess files to protect access to + these directories, as outlined in + <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=57161">Bug + 57161</ulink> - <para>The examples in this section are written as if you were updating - to version 2.18.1. The procedures are the same regardless if you are - updating to a new point release or a new revision. However, the chance - of running into trouble increases when upgrading to a new point release, - escpecially if you've made local changes. - </para> + for the localconfig file, and + <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=65572">Bug + 65572</ulink> + + for adequate protection in your data/ directory.</para> + + <para>Note the instructions which follow are Apache-specific. If you + use IIS, Netscape, or other non-Apache web servers, please consult + your system documentation for how to secure these files from being + transmitted to curious users.</para> + + <para>Place the following text into a file named ".htaccess", + readable by your web server, in your $BUGZILLA_HOME/data directory. + <literallayout><Files comments> allow from all </Files> + deny from all</literallayout> + </para> + + <para>Place the following text into a file named ".htaccess", + readable by your web server, in your $BUGZILLA_HOME/ directory. + <literallayout><Files localconfig> deny from all </Files> + allow from all</literallayout> + </para> - <para>These examples also assume that your Bugzilla installation is at - <filename>/var/www/html/bugzilla</filename>. If that is not the case, - simply substitute the proper paths where appropriate. + </listitem> + </orderedlist> </para> + </section> - <example id="upgrade-cvs"> - <title>Upgrading using CVS</title> + <section id="cust-templates"> + <title>Template Customisation</title> + + <para> + One of the large changes for 2.16 was the templatisation of the + entire user-facing UI, using the + <ulink url="http://www.template-toolkit.org">Template Toolkit</ulink>. + Administrators can now configure the look and feel of Bugzilla without + having to edit Perl files or face the nightmare of massive merge + conflicts when they upgrade to a newer version in the future. + </para> + + <para> + Templatisation also makes localised versions of Bugzilla possible, + for the first time. In the future, a Bugzilla installation may + have templates installed for multiple localisations, and select + which ones to use based on the user's browser language setting. + </para> + + <section> + <title>What to Edit</title> + <para> + There are two different ways of editing of Bugzilla's templates, + and which you use depends mainly on how you upgrade Bugzilla. The + template directory structure is that there's a top level directory, + <filename>template</filename>, which contains a directory for + each installed localisation. The default English templates are + therefore in <filename>en</filename>. Underneath that, there + is the <filename>default</filename> directory and optionally the + <filename>custom</filename> directory. The <filename>default</filename> + directory contains all the templates shipped with Bugzilla, whereas + the <filename>custom</filename> directory does not exist at first and + must be created if you want to use it. + </para> - <para>Every release of Bugzilla, whether it is a revision or a point - release, is tagged in CVS. Also, every tarball we have distributed - since version 2.12 has been primed for using CVS. This does, however, - require that you are able to access cvs-mirror.mozilla.org on port - 2401. + <para> + The first method of making customisations is to directly edit the + templates in <filename>template/en/default</filename>. This is + probably the best method for small changes if you are going to use + the CVS method of upgrading, because if you then execute a + <command>cvs update</command>, any template fixes will get + automagically merged into your modified versions. + </para> - <tip> - <para>If you can do this, updating using CVS is probably the most - painless method, especially if you have a lot of local changes. - </para> - </tip> + <para> + If you use this method, your installation will break if CVS conflicts + occur. </para> - <programlisting> -bash$ <command>cd /var/www/html/bugzilla</command> -bash$ <command>cvs login</command> -Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401/cvsroot -CVS password: <command>anonymous</command> -bash$ <command>cvs -q update -r BUGZILLA-2_18_1 -dP</command> -P checksetup.pl -P collectstats.pl -P globals.pl -P docs/rel_notes.txt -P template/en/default/list/quips.html.tmpl - </programlisting> + <para> + The other method is to copy the templates into a mirrored directory + structure under <filename>template/en/custom</filename>. The templates + in this directory automatically override those in default. + This is the technique you + need to use if you use the overwriting method of upgrade, because + otherwise your changes will be lost. This method is also better if + you are using the CVS method of upgrading and are going to make major + changes, because it is guaranteed that the contents of this directory + will not be touched during an upgrade, and you can then decide whether + to continue using your own templates, or make the effort to merge your + changes into the new versions by hand. + </para> <para> - <caution> - <para>If a line in the output from <command>cvs update</command> - begins with a <computeroutput>C</computeroutput> that represents a - file with local changes that CVS was unable to properly merge. You - need to resolve these conflicts manually before Bugzilla (or at - least the portion using that file) will be usable. - </para> - </caution> + If you use this method, your installation may break if incompatible + changes are made to the template interface. If such changes are made + they will be documented in the release notes, provided you are using a + stable release of Bugzilla. If you use using unstable code, you will + need to deal with this one yourself, although if possible the changes + will be mentioned before they occur in the deprecations section of the + previous stable release's release notes. + </para> - <note> - <para>You also need to run <command>./checksetup.pl</command> - before your Bugzilla upgrade will be complete. - </para> - </note> + <note> + <para> + Don't directly edit the compiled templates in + <filename class="directory">data/template/*</filename> - your + changes will be lost when Template Toolkit recompiles them. + </para> + </note> + </section> + + <section> + <title>How To Edit Templates</title> + + <para> + 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 + <ulink url="http://www.template-toolkit.org">Template Toolkit home + page</ulink>. However, you should particularly remember (for security + reasons) to always HTML filter things which come from the database or + user input, to prevent cross-site scripting attacks. + </para> + + <para> + However, one thing you should take particular care about is the need + to properly HTML filter data that has been passed into the template. + This means that if the data can possibly contain special HTML characters + such as <, and the data was not intended to be HTML, they need to be + converted to entity form, ie &lt;. You use the 'html' filter in the + Template Toolkit to do this. If you fail to do this, you may open up + your installation to cross-site scripting attacks. </para> - </example> - <example id="upgrade-tarball"> - <title>Upgrading using the tarball</title> + <para> + Also note that Bugzilla adds a few filters of its own, that are not + in standard Template Toolkit. In particular, the 'url_quote' filter + can convert characters that are illegal or have special meaning in URLs, + such as &, to the encoded form, ie %26. This actually encodes most + characters (but not the common ones such as letters and numbers and so + on), including the HTML-special characters, so there's never a need to + HTML filter afterwards. + </para> + + <para> + 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. + </para> + + <note> + <para> + 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 + <ulink url="http://www.bugzilla.org/developerguide.html">Developers' + Guide</ulink>. + </para> + </note> + </section> + + + <section> + <title>Template Formats</title> + + <para> + Some CGIs have the ability to use more than one template. For + example, buglist.cgi can output bug lists as RDF or two + different forms of HTML (complex and simple). (Try this out + by appending <filename>&format=simple</filename> to a buglist.cgi + URL on your Bugzilla installation.) This + mechanism, called template 'formats', is extensible. + </para> + + <para> + To see if a CGI supports multiple output formats, grep the + CGI for "ValidateOutputFormat". If it's not present, adding + multiple format support isn't too hard - see how it's done in + other CGIs. + </para> + + <para> + 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. + </para> + + <para> + Write your template in whatever markup or text style is appropriate. + </para> + + <para> + You now need to decide what content type you want your template + served as. Open up the <filename>localconfig</filename> file and find the + <filename>$contenttypes</filename> + variable. If your content type is not there, add it. Remember + the three- or four-letter tag assigned to you content type. + This tag will be part of the template filename. + </para> + + <para> + Save the template as <filename><stubname>-<formatname>.<contenttypetag>.tmpl</filename>. + Try out the template by calling the CGI as + <filename><cginame>.cgi?format=<formatname></filename> . + </para> + </section> + + + <section> + <title>Particular Templates</title> + + <para> + There are a few templates you may be particularly interested in + customising for your installation. + </para> + + <para> + <command>index.html.tmpl</command>: + This is the Bugzilla front page. + </para> - <para>If you are unable or unwilling to use CVS, another option that's - always available is to download the latest tarball. This is the most - difficult option to use, especially if you have local changes. + <para> + <command>global/header.html.tmpl</command>: + 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. </para> - <programlisting> -bash$ <command>cd /var/www/html</command> -bash$ <command>wget ftp://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.18.1.tar.gz</command> -<emphasis>Output omitted</emphasis> -bash$ <command>tar xzvf bugzilla-2.18.1.tar.gz</command> -bugzilla-2.18.1/ -bugzilla-2.18.1/.cvsignore -bugzilla-2.18.1/1x1.gif -<emphasis>Output truncated</emphasis> -bash$ <command>cd bugzilla-2.18.1</command> -bash$ <command>cp ../bugzilla/localconfig* .</command> -bash$ <command>cp -r ../bugzilla/data .</command> -bash$ <command>cd ..</command> -bash$ <command>mv bugzilla bugzilla.old</command> -bash$ <command>mv bugzilla-2.18.1 bugzilla</command> -bash$ <command>cd bugzilla</command> -bash$ <command>./checksetup.pl</command> -<emphasis>Output omitted</emphasis> - </programlisting> + <para> + <command>global/banner.html.tmpl</command>: + 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 customise 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. + </para> <para> - <warning> - <para>The <command>cp</command> commands both end with periods which - is a very important detail, it tells the shell that the destination - directory is the current working directory. Also, the period at the - beginning of the <command>./checksetup.pl</command> is important and - can not be omitted. - </para> - </warning> + <command>global/footer.html.tmpl</command>: + 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. + </para> - <note> - <para>You will now have to reapply any changes you have made to your - local installation manually. - </para> - </note> + <para> + <command>bug/create/user-message.html.tmpl</command>: + 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. + </para> + + <para> + <command>bug/create/create.html.tmpl</command> and + <command>bug/create/comment.txt.tmpl</command>: + You may wish to get bug submitters to give certain bits of structured + information, each in a separate input widget, for which there is not a + field in the database. The bug entry system has been designed in an + extensible fashion to enable you to define arbitrary fields and widgets, + and have their values appear formatted in the initial + Description, rather than in database fields. An example of this + is the mozilla.org + <ulink url="http://bugzilla.mozilla.org/enter_bug.cgi?format=guided">guided + bug submission form</ulink>. </para> - </example> - - <example id="upgrade-patches"> - <title>Upgrading using patches</title> - - <para>The Bugzilla team will normally make a patch file available for - revisions to go from the most recent revision to the new one. You could - also read the release notes and grab the patches attached to the - mentioned bug, but it is safer to use the released patch file as - sometimes patches get changed before they get checked in. - It is also theoretically possible to - scour the fixed bug list and pick and choose which patches to apply - from a point release, but this is not recommended either as what you'll - end up with is a hodge podge Bugzilla that isn't really any version. - This would also make it more difficult to upgrade in the future. + + <para> + To make this work, create a custom template for + <filename>enter_bug.cgi</filename> (the default template, on which you + could base it, is <filename>create.html.tmpl</filename>), + and either call it <filename>create.html.tmpl</filename> or use a format and + call it <filename>create-<formatname>.html.tmpl</filename>. + Put it in the <filename class="directory">custom/bug/create</filename> + directory. In it, add widgets for each piece of information you'd like + collected - such as a build number, or set of steps to reproduce. </para> - <programlisting> -bash$ <command>cd /var/www/html/bugzilla</command> -bash$ <command>wget ftp://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.18.0-to-2.18.1.diff.gz</command> -<emphasis>Output omitted</emphasis> -bash$ <command>gunzip bugzilla-2.18.0-to-2.18.1.diff.gz</command> -bash$ <command>patch -p1 < bugzilla-2.18.0-to-2.18.1.diff</command> -patching file checksetup.pl -patching file collectstats.pl -patching file globals.pl - </programlisting> + <para> + Then, create a template like + <filename>custom/bug/create/comment.txt.tmpl</filename>, also named + after your format if you are using one, which + references the form fields you have created. When a bug report is + submitted, the initial comment attached to the bug report will be + formatted according to the layout of this template. + </para> <para> - <caution> - <para>If you do this, beware that this doesn't change the entires in - your <filename id="dir">CVS</filename> directory so it may make - updates using CVS (<xref linkend="upgrade-cvs"/>) more difficult in the - future. - </para> - </caution> + For example, if your enter_bug template had a field + <programlisting><input type="text" name="buildid" size="30"></programlisting> + and then your comment.txt.tmpl had + <programlisting>BuildID: [% form.buildid %]</programlisting> + then + <programlisting>BuildID: 20020303</programlisting> + would appear in the initial checkin comment. + </para> + </section> + + </section> + + <section id="cust-change-permissions"> + <title>Change Permission Customisation</title> + + <warning> + <para> + This feature should be considered experimental; the Bugzilla code you + will be changing is not stable, and could change or move between + versions. Be aware that if you make modifications to it, you may have + to re-make them or port them if Bugzilla changes internally between + versions. </para> - </example> + </warning> + + <para> + 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. + </para> + + <para> + For maximum flexibility, customising this means editing Bugzilla's Perl + code. This gives the administrator complete control over exactly who is + allowed to do what. The relevant function is called + <filename>CheckCanChangeField()</filename>, + and is found in <filename>process_bug.cgi</filename> in your + Bugzilla directory. If you open that file and grep for + "sub CheckCanChangeField", you'll find it. + </para> + + <para> + 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: + <programlisting> # Allow the owner to change anything. + if ($ownerid eq $whoid) { + return 1; + }</programlisting> + It's fairly obvious what this piece of code does. + </para> + + <para> + So, how does one go about changing this function? Well, simple changes + can be made just be removing pieces - for example, if you wanted to + prevent any user adding a comment to a bug, just remove the lines marked + "Allow anyone to change comments." And if you want the reporter to have + no special rights on bugs they have filed, just remove the entire section + which refers to him. + </para> + + <para> + More complex customisations 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.: + <programlisting> if ($field eq "qacontact") { + if (UserInGroup("quality_assurance")) { + return 1; + } + else { + return 0; + } + }</programlisting> + This says that only users in the group "quality_assurance" can change + the QA Contact field of a bug. Getting more weird: + <programlisting> if (($field eq "priority") && + ($vars->{'user'}{'login'} =~ /.*\@example\.com$/)) + { + if ($oldvalue eq "P1") { + return 1; + } + else { + return 0; + } + }</programlisting> + 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. + </para> + + <para> + For a list of possible field names, look in + <filename>data/versioncache</filename> for the list called + <filename>@::log_columns</filename>. If you need help writing custom + rules for your organisation, ask in the newsgroup. + </para> + </section> + + <section id="upgrading"> + <title>Upgrading to New Releases</title> + <para>A plain Bugzilla is fairly easy to upgrade from one version to a + newer one. Always read the release notes to see if there are any issues + that you might need to take note of. It is recommended that you take a + backup of your database and your entire Bugzilla installation before attempting an + upgrade. You can upgrade a 'clean' installation by untarring a new + tarball over the old installation. If you are upgrading from 2.12 or + later, and have cvs installed, you can type <filename>cvs -z3 update</filename>, + and resolve conflicts if there are any. + </para> + + <para>However, things get a bit more complicated if you've made + changes to Bugzilla's code. In this case, you may have to re-make or + reapply those changes. One good method is to take a diff of your customised + version against the original, so you can survey all that you've changed. + Hopefully, templatisation will reduce the need for + this in the future.</para> + + <para>From version 2.8 onwards, Bugzilla databases can be automatically + carried forward during an upgrade. However, because the developers of + Bugzilla are constantly adding new + tables, columns and fields, you'll probably get SQL errors if you just + update the code and attempt to use Bugzilla. Always run the + <filename>checksetup.pl</filename> + script whenever you upgrade your installation.</para> + + <para>If you are running Bugzilla version 2.8 or lower, and wish to + upgrade to the latest version, please consult the file, + "UPGRADING-pre-2.8" in the Bugzilla root directory after untarring the + archive.</para> </section> + + <!-- Integrating Bugzilla with Third-Party Tools --> + &integration; + </chapter> <!-- Keep this comment at the end of the file @@ -1124,7 +1324,7 @@ sgml-local-ecat-files:nil sgml-minimize-attributes:nil sgml-namecase-general:t sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") +sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter") sgml-shorttag:t sgml-tag-region-if-active:t End: |