From ffb9c3003dd963d239196b4a3ba9898058df0495 Mon Sep 17 00:00:00 2001 From: "barnboy%trilobyte.net" <> Date: Fri, 4 Apr 2008 11:46:54 +0000 Subject: Fix for confusing language regarding protection of data/ & shadow/ directories and localconfig file. --- docs/en/xml/administration.xml | 2057 +++++++++++++++++++++------------------- 1 file changed, 1106 insertions(+), 951 deletions(-) (limited to 'docs/en/xml/administration.xml') diff --git a/docs/en/xml/administration.xml b/docs/en/xml/administration.xml index b261f4ee2..a35ba047d 100644 --- a/docs/en/xml/administration.xml +++ b/docs/en/xml/administration.xml @@ -1,966 +1,1121 @@ - - - Administering Bugzilla - -
- Bugzilla Configuration - - Bugzilla is configured by changing various parameters, accessed - from the "Edit parameters" link in the page footer. Here are - some of the key parameters on that page. You should run down this - list and set them appropriately after installing Bugzilla. - - - checklist - - - - - - maintainer: - The maintainer parameter is the email address of the person - responsible for maintaining this - Bugzilla installation. The address need not be that of a valid Bugzilla - account. - - - - - urlbase: - This parameter defines the fully qualified domain name and web - server path to your Bugzilla installation. - - For example, if your Bugzilla query page is - http://www.foo.com/bugzilla/query.cgi, - set your urlbase - to http://www.foo.com/bugzilla/. - - - - - makeproductgroups: - This dictates whether or not to automatically create groups - when new products are created. - - - - - - useentrygroupdefault: - Bugzilla products can have a group associated with them, so that - certain users can only see bugs in certain products. When this - parameter is set to on, this - causes the initial group controls on newly created products - to place all newly-created bugs in the group - having the same name as the product immediately. - After a product is initially created, the group controls - can be further adjusted without interference by - this mechanism. - - - - - shadowdb: - You run into an interesting problem when Bugzilla reaches a - high level of continuous activity. MySQL supports only table-level - write locking. What this means is that if someone needs to make a - change to a bug, they will lock the entire table until the operation - is complete. Locking for write also blocks reads until the write is - complete. Note that more recent versions of mysql support row level - locking using different table types. These types are slower than the - standard type, and Bugzilla does not yet take advantage of features - such as transactions which would justify this speed decrease. The - Bugzilla team are, however, happy to hear about any experiences with - row level locking and Bugzilla. - - The shadowdb - parameter was designed to get around this limitation. While only a - single user is allowed to write to a table at a time, reads can - continue unimpeded on a read-only shadow copy of the database. - Although your database size will double, a shadow database can cause - an enormous performance improvement when implemented on extremely - high-traffic Bugzilla databases. - - - As a guide, on reasonably old hardware, mozilla.org began needing - shadowdb - when they reached around 40,000 Bugzilla users with several hundred - Bugzilla bug changes and comments per day. - - The value of the parameter defines the name of the - shadow bug database. You will need to set the host and port settings - from the params page, and set up replication in your database server - so that updates reach this readonly mirror. Consult your database - documentation for more detail. - - - - - shutdownhtml: - - If you need to shut down Bugzilla to perform administration, enter - some descriptive HTML here and anyone who tries to use Bugzilla will - receive a page to that effect. Obviously, editparams.cgi will - still be accessible so you can remove the HTML and re-enable Bugzilla. - :-) - - - - - - passwordmail: - - Every time a user creates an account, the text of - this parameter (with substitutions) is sent to the new user along with - their password message. - - Add any text you wish to the "passwordmail" parameter box. For - instance, many people choose to use this box to give a quick training - blurb about how to use Bugzilla at your site. - - - - - - movebugs: - - This option is an undocumented feature to allow moving bugs - between separate Bugzilla installations. You will need to understand - the source code in order to use this feature. Please consult - movebugs.pl in your Bugzilla source tree for - further documentation, such as it is. - - - - - - useqacontact: - - This allows you to define an email address for each component, in - addition - to that of the default owner, who will be sent carbon copies of - incoming bugs. - - - - usestatuswhiteboard: - This defines whether you wish to have a free-form, overwritable field - associated with each bug. The advantage of the Status Whiteboard is - that it can be deleted or modified with ease, and provides an - easily-searchable field for indexing some bugs that have some trait - in common. - - - - - - whinedays: - Set this to the number of days you want to let bugs go - in the NEW or REOPENED state before notifying people they have - untouched new bugs. If you do not plan to use this feature, simply do - not set up the whining cron job described in the installation - instructions, or set this value to "0" (never whine). - - - - - commenton*: - All these - fields allow you to dictate what changes can pass without comment, - and which must have a comment from the person who changed them. - Often, administrators will allow users to add themselves to the CC - list, accept bugs, or change the Status Whiteboard without adding a - comment as to their reasons for the change, yet require that most - other changes come with an explanation. - - Set the "commenton" options according to your site policy. It - is a wise idea to require comments when users resolve, reassign, or - reopen bugs at the very least. - - It is generally far better to require a developer comment - when resolving bugs than not. Few things are more annoying to bug - database users than having a developer mark a bug "fixed" without - any comment as to what the fix was (or even that it was truly - fixed!) - - - - - - - supportwatchers: - - Turning on this option allows users to ask to receive copies of - all a particular other user's bug email. This is, of - course, subject to the groupset restrictions on the bug; if the - watcher - would not normally be allowed to view a bug, the watcher cannot get - around the system by setting herself up to watch the bugs of someone - with bugs outside her privileges. They would still only receive email - updates for those bugs she could normally view. - - -
- -
- User Administration - -
- Creating the Default User - - When you first run checksetup.pl after installing Bugzilla, it - will prompt you for the administrative username (email address) and - password for this "super user". If for some reason you delete - the "super user" account, re-running checksetup.pl will again prompt - you for this username and password. - - - If you wish to add more administrative users, add them to - the "admin" group and, optionally, add edit the tweakparams, editusers, - creategroups, editcomponents, and editkeywords groups to add the - entire admin group to those groups. - - -
- -
- Managing Other Users - -
- Creating new users - - Your users can create their own user accounts by clicking the - "New Account" link at the bottom of each page (assuming they - aren't logged in as someone else already.) However, should you - desire to create user accounts ahead of time, here is how you do - it. - - - - After logging in, click the "Users" link at the footer of - the query page, and then click "Add a new user". - - - - Fill out the form presented. This page is self-explanatory. - When done, click "Submit". - - - Adding a user this way will - not - - send an email informing them of their username and password. - While useful for creating dummy accounts (watchers which - shuttle mail to another system, for instance, or email - addresses which are a mailing list), in general it is - preferable to log out and use the - New Account - - button to create users, as it will pre-populate all the - required fields and also notify the user of her account name - and password. - - - -
- -
- Modifying Users - - To see a specific user, search for their login name - in the box provided on the "Edit Users" page. To see all users, - leave the box blank. - - You can search in different ways the listbox to the right - of the text entry box. You can match by - case-insensitive substring (the default), - regular expression, or a - reverse - regular expression match, which finds every user name which does NOT - match the regular expression. (Please see - the man regexp - manual page for details on regular expression syntax.) - - - Once you have found your user, you can change the following - fields: - - - - - Login Name: - This is generally the user's full email address. However, if you - have are using the emailsuffix Param, this may just be the user's - login name. Note that users can now change their login names - themselves (to any valid email address.) - - - - - - Real Name: The user's real name. Note that - Bugzilla does not require this to create an account. - - - - - Password: - You can change the user's password here. Users can automatically - request a new password, so you shouldn't need to do this often. - If you want to disable an account, see Disable Text below. - - - - - - Disable Text: - If you type anything in this box, including just a space, the - user is prevented from logging in, or making any changes to - bugs via the web interface. - The HTML you type in this box is presented to the user when - they attempt to perform these actions, and should explain - why the account was disabled. - - Don't disable all the administrator accounts! - - - - The user can still submit bugs via - the e-mail gateway, if you set it up, even if the disabled text - field is filled in. The e-mail gateway should - not - be enabled for secure installations of Bugzilla. - - - - - - - <groupname>: - If you have created some groups, e.g. "securitysensitive", then - checkboxes will appear here to allow you to add users to, or - remove them from, these groups. - - - - - - canconfirm: - This field is only used if you have enabled the "unconfirmed" - status. If you enable this for a user, - that user can then move bugs from "Unconfirmed" to a "Confirmed" - status (e.g.: "New" status). - - - - - creategroups: - This option will allow a user to create and destroy groups in - Bugzilla. - - - - - editbugs: - Unless a user has this bit set, they can only edit those bugs - for which they are the assignee or the reporter. Even if this - option is unchecked, users can still add comments to bugs. - - - - - - editcomponents: - This flag allows a user to create new products and components, - as well as modify and destroy those that have no bugs associated - with them. If a product or component has bugs associated with it, - those bugs must be moved to a different product or component - before Bugzilla will allow them to be destroyed. - - - - - - editkeywords: - If you use Bugzilla's keyword functionality, enabling this - feature allows a user to create and destroy keywords. As always, - the keywords for existing bugs containing the keyword the user - wishes to destroy must be changed before Bugzilla will allow it - to die. - - - - - editusers: - This flag allows a user to do what you're doing right now: edit - other users. This will allow those with the right to do so to - remove administrator privileges from other users or grant them to - themselves. Enable with care. - - - - - - tweakparams: - This flag allows a user to change Bugzilla's Params - (using editparams.cgi.) - - - - - <productname>: - This allows an administrator to specify the products in which - a user can see bugs. The user must still have the - "editbugs" privilege to edit bugs in these products. - - -
-
-
- -
- Products - - - - Products - - are the broadest category in Bugzilla, and tend to represent real-world - shipping products. E.g. if your company makes computer games, - you should have one product per game, perhaps a "Common" product for - units of technology used in multiple games, and maybe a few special - products (Website, Administration...) - - Many of Bugzilla's settings are configurable on a per-product - basis. The number of "votes" available to users is set per-product, - as is the number of votes - required to move a bug automatically from the UNCONFIRMED status to the - NEW status. - - To create a new product: - - - - Select "products" from the footer - - - - - Select the "Add" link in the bottom right - - - - Enter the name of the product and a description. The - Description field may contain HTML. - - - - Don't worry about the "Closed for bug entry", "Maximum Votes - per person", "Maximum votes a person can put on a single bug", - "Number of votes a bug in this Product needs to automatically get out - of the UNCOMFIRMED state", and "Version" options yet. We'll cover - those in a few moments. - -
- -
- Components - - Components are subsections of a Product. E.g. the computer game - you are designing may have a "UI" - component, an "API" component, a "Sound System" component, and a - "Plugins" component, each overseen by a different programmer. It - often makes sense to divide Components in Bugzilla according to the - natural divisions of responsibility within your Product or - company. - - - Each component has a owner and (if you turned it on in the parameters), - a QA Contact. The owner should be the primary person who fixes bugs in - that component. The QA Contact should be the person who will ensure - these bugs are completely fixed. The Owner, QA Contact, and Reporter - will get email when new bugs are created in this Component and when - these bugs change. Default Owner and Default QA Contact fields only - dictate the - default assignments; - these can be changed on bug submission, or at any later point in - a bug's life. - - To create a new Component: - - - - Select the "Edit components" link from the "Edit product" - page - - - - Select the "Add" link in the bottom right. - - - - Fill out the "Component" field, a short "Description", - the "Initial Owner" and "Initial QA Contact" (if enabled.) - The Component and Description fields may contain HTML; - the "Initial Owner" field must be a login name - already existing in the database. - - - -
- -
- Versions - - Versions are the revisions of the product, such as "Flinders - 3.1", "Flinders 95", and "Flinders 2000". Version is not a multi-select - field; the usual practice is to select the earliest version known to have - the bug. - - - To create and edit Versions: - - - - From the "Edit product" screen, select "Edit Versions" - - - - You will notice that the product already has the default - version "undefined". Click the "Add" link in the bottom right. - - - - Enter the name of the Version. This field takes text only. - Then click the "Add" button. - - - -
- -
- Milestones - - Milestones are "targets" that you plan to get a bug fixed by. For - example, you have a bug that you plan to fix for your 3.0 release, it - would be assigned the milestone of 3.0. - - - Milestone options will only appear for a Product if you turned - on the "usetargetmilestone" Param in the "Edit Parameters" screen. - - - - To create new Milestones, set Default Milestones, and set - Milestone URL: - - - - Select "Edit milestones" from the "Edit product" page. - - - - Select "Add" in the bottom right corner. - text - - - - Enter the name of the Milestone in the "Milestone" field. You - can optionally set the "sortkey", which is a positive or negative - number (-255 to 255) that defines where in the list this particular - milestone appears. This is because milestones often do not - occur in alphanumeric order For example, "Future" might be - after "Release 1.2". Select "Add". - - - - From the Edit product screen, you can enter the URL of a - page which gives information about your milestones and what - they mean. - - -
- -
- Voting - - Voting allows users to be given a pot of votes which they can allocate - to bugs, to indicate that they'd like them fixed. - This allows developers to gauge - user need for a particular enhancement or bugfix. By allowing bugs with - a certain number of votes to automatically move from "UNCONFIRMED" to - "NEW", users of the bug system can help high-priority bugs garner - attention so they don't sit for a long time awaiting triage. - - To modify Voting settings: - - - - Navigate to the "Edit product" screen for the Product you - wish to modify - - - - Maximum Votes per person: - Setting this field to "0" disables voting. - - - - Maximum Votes a person can put on a single - bug: - It should probably be some number lower than the - "Maximum votes per person". Don't set this field to "0" if - "Maximum votes per person" is non-zero; that doesn't make - any sense. - - - - Number of votes a bug in this product needs to - automatically get out of the UNCONFIRMED state: - Setting this field to "0" disables the automatic move of - bugs from UNCONFIRMED to NEW. - - - - - Once you have adjusted the values to your preference, click - "Update". - - -
- -
- Groups and Group Security - - Groups allow the administrator - to isolate bugs or products that should only be seen by certain people. - The association between products and groups is controlled from - the product edit page under Edit Group Controls. - + + + - - If the makeproductgroups param is on, a new group will be automatically - created for every new product. - + + Administering Bugzilla +Or, I just got this cool thing installed. Now what the heck do I do with it? + + +So you followed the README isntructions to the letter, and +just logged into bugzilla with your super-duper god account and you are sitting at the query +screen. Yet, you have nothing to query. Your first act of business needs to be to setup the +operating parameters for bugzilla. + +
+ Post-Installation Checklist + + After installation, follow the checklist below to ensure that + you have a successful installation. + If you do not see a recommended setting for a parameter, + consider leaving it at the default + while you perform your initial tests on your Bugzilla setup. + + + checklist + + + + + Bring up "editparams.cgi" in your web browser. For instance, to edit parameters + at mozilla.org, the URL would be + http://bugzilla.mozilla.org/editparams.cgi, also available under the "edit parameters" + link on your query page. + + + + + Set "maintainer" to your email address. + This allows Bugzilla's error messages + to display your email + address and allow people to contact you for help. + + + + + Set "urlbase" to the URL reference for your Bugzilla installation. + If your bugzilla query page is at http://www.foo.com/bugzilla/query.cgi, + your url base is http://www.foo.com/bugzilla/ + + + + + Set "usebuggroups" to "1" only + if you need to restrict access to products. + I suggest leaving this parameter off + while initially testing your Bugzilla. + + + + + Set "usebuggroupsentry" to "1" if you want to restrict access to products. + Once again, if you are simply testing your installation, I suggest against + turning this parameter on; the strict security checking may stop you from + being able to modify your new entries. + + + + + Set "shadowdb" to "bug_shadowdb" if you will be + running a *very* large installation of Bugzilla. + The shadow database enables many simultaneous users + to read and write to the database + without interfering with one another. + + + Enabling "shadowdb" can adversely affect the stability + of your installation of Bugzilla. + You may frequently need to manually synchronize your databases, + or schedule nightly syncs + via "cron" + + + Once again, in testing you should + avoid this option -- use it if or when you need to use it, and have + repeatedly run into the problem it was designed to solve -- very long wait times while + attempting to commit a change to the database. + + + 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! + + + + + If you have custom logos or HTML you must put in place to fit within your site design guidelines, + place the code in the "headerhtml", "footerhtml", "errorhtml", + "bannerhtml", or "blurbhtml" text boxes. + + + The "headerhtml" text box is the HTML printed out + before any other code on the page. + If you have a special banner, put the code for it in "bannerhtml". + You may want to leave these + settings at the defaults initially. + + + + + + + Add any text you wish to the "passwordmail" parameter box. For instance, + many people choose to use this box to give a quick training blurb about how to + use Bugzilla at your site. + + + + + Ensure "newemailtech" is "on". + Your users will thank you. This is the default in the post-2.12 world, and is + only an issue if you are upgrading. + + + + + Do you want to use the qa contact ("useqacontact") + and status whiteboard ("usestatuswhiteboard") fields? + These fields are useful because they allow for more flexibility, + particularly when you have an existing + Quality Assurance and/or Release Engineering team, + but they may not be needed for smaller installations. + + + + + Set "whinedays" to the amount of days you want to let bugs go + in the "New" or "Reopened" state before + notifying people they have untouched new bugs. If you do not plan to use this feature, simply do + not set up the whining cron job described in the README, or set this value to "0". + + + + + Set the "commenton" options according to your site policy. + It is a wise idea to require comments when users + resolve, reassign, or reopen bugs. + + + It is generally far better to require a developer comment when resolving bugs than not. + Few things are more annoying to bug database users than having a developer + mark a bug "fixed" without any comment as to what the fix was (or even that it was truly fixed!) + + + + + + + Set "supportwatchers" to "On". This feature is helpful for team leads to monitor progress in their + respective areas, and can offer many other benefits, such as allowing a developer to pick up a + former engineer's bugs without requiring her to change all the information in the bug. + + + +
+ +
+ User Administration + + User administration is one of the easiest parts of Bugzilla. + Keeping it from getting out of hand, however, can become a challenge. + + +
+ Creating the Default User + + + When you first run checksetup.pl after installing Bugzilla, it will prompt you + for the administrative username (email address) and password for this "super user". + If for some reason you were to delete the "super user" account, re-running + checksetup.pl will again prompt you for this username and password. + + + + If you wish to add more administrative users, you must use the MySQL interface. + Run "mysql" from the command line, and use these commands ("mysql>" denotes the + mysql prompt, not something you should type in): + mysql> use bugs; + mysql> update profiles set groupset=0x7ffffffffffffff + where login_name = "(user's login name)"; + + +
+ +
+ Managing Other Users + +
+ Logging In + + + + Open the index.html page for your Bugzilla installation in your browser window. + + + + + Click the "Query Existing Bug Reports" link. + + + + + Click the "Log In" link at the foot of the page. + + + + + Type your email address, and the password which was emailed to you when you + created your Bugzilla account, into the spaces provided. + + + + Congratulations, you are logged in! +
+ +
+ Creating new users + + Your users can create their own user accounts by clicking the "New Account" + link at the bottom of each page. + However, should you desire to create user accounts ahead of time, here is how you do it. + + + + + After logging in, click the "Users" link at the footer of the query page. + + + + + To see a specific user, type a portion of their login name + in the box provided and click "submit". + To see all users, simply click the "submit" button. + You must click "submit" here to be able to add a new user. + + + + More functionality is available via the list on the right-hand side + of the text entry box. + You can match what you type as a case-insensitive substring (the default) + of all users on your system, a case-sensitive regular expression + (please see the "man regexp" manual page for details on regular expression syntax), + or a reverse regular expression match, + where every user name which does NOT match the regular expression + is selected. + + + + + + Click the "Add New User" link at the bottom of the user list + + + + + Fill out the form presented. This page is self-explanatory. When done, click "submit". + + + + Adding a user this way will not send an email + informing them of their username and password. + In general, it is preferable to log out and use the "New Account" + button to create users, as it will pre-populate all the required fields and also notify + the user of her account name and password. + + + + +
+ +
+ Disabling Users + + I bet you noticed that big "Disabled Text" entry box available from the "Add New User" screen, + when you edit an account? + By entering any text in this box and selecting "submit", + you have prevented the user from using Bugzilla via the web interface. + Your explanation, written in this text box, will be presented to the user + the next time she attempts to use the system. + + + Don't disable your own administrative account, or you will hate life! + + + +
+ +
+ Modifying Users + + Here I will attempt to describe the function of each option on the user edit screen. + + + + + Login Name: This is generally the user's email address. + However, if you have edited your system parameters, + this may just be the user's login name or some other identifier. + + + For compatability reasons, you should probably + stick with email addresses as user login names. It will make your life easier. + + + + + + + Real Name: Duh! + + + + + Password: You will only see asterisks in versions + of Bugzilla newer than 2.10 or early 2.11. You can change the user password here. + + + + + Email Notification: You may choose from one of three options: + + + + All qualifying bugs except those which I change: + The user will be notified of any change to any bug + for which she is the reporter, assignee, Q/A contact, CC recipient, or "watcher". + + + + + Only those bugs which I am listed on the CC line: + The user will not be notified of changes to bugs where she is the assignee, + reporter, or Q/A contact, but will receive them if she is on the CC list. + + + She will still receive whining cron emails if you set up the "whinemail" feature. + + + + + + + All Qualifying Bugs: This user is a glutton for punishment. + If her name is in the reporter, Q/A contact, CC, assignee, or is a "watcher", + she will get email updates regarding the bug. + + + + + + Disable Text: If you type anything in this box, + including just a space, the user account is disabled from making any changes + to bugs via the web interface, and what you type in this box is presented as the reason. + + Don't disable the administrator account! + + + + As of this writing, the user can still submit bugs via the e-mail gateway, + if you set it up, despite the disabled text field. The e-mail gateway should + not be enabled for secure installations of Bugzilla. + + + + + + + CanConfirm: This field is only used if you have enabled + "unconfirmed" status in your parameters screen. If you enable this for a user, + that user can then move bugs from "Unconfirmed" to "Confirmed" status (ergo: "New" status). + Be judicious about allowing users to turn this bit on for other users. + + + + + Creategroups: This option will allow a user to create and + destroy groups in Bugzilla. Unless you are using the Bugzilla GroupSentry security + option "usebuggroupsentry" in your parameters, this setting has no effect. + + + + + Editbugs: Unless a user has this bit set, they can only edit + those bugs for which they are the assignee or the reporter. + + + Leaving this option unchecked does not prevent users from adding + comments to a bug! They simply cannot change a bug priority, severity, + etc. unless they are the assignee or reporter. + + + + + + + Editcomponents: This flag allows a user to create new + products and components, as well as modify and destroy those that have no bugs + associated with them. If a product or component has bugs associated with it, + those bugs must be moved to a different product or component before Bugzilla + will allow them to be destroyed. The name of a product or component can be + changed without affecting the associated bugs, but it tends to annoy + the hell out of your users when these change a lot. + + + + + Editkeywords: If you use Bugzilla's keyword functionality, + enabling this feature allows a user can create and destroy keywords. + As always, the keywords for existing bugs containing the keyword + the user wishes to destroy must be changed before Bugzilla will allow it to die. + You must be very careful about creating too many new keywords + if you run a very large Bugzilla installation; keywords are global variables + across products, and you can often run into a phenomenon called "keyword bloat". + This confuses users, and then the feature goes unused. + + + + + Editusers: This flag allows a user do what you're doing + right now: edit other users. + This will allow those with the right to do so to remove administrator + priveleges from other users or grant them to themselves. Enable with care. + + + + + PRODUCT: PRODUCT bugs access. This allows an administrator, + with product-level granularity, to specify in which products a user can edit bugs. + The user must still have the "editbugs" privelege to edit bugs in this area; + this simply restricts them from even seeing bugs outside these boundaries if the administrator + has enabled the group sentry parameter "usebuggroupsentry". Unless you are using bug groups, + this option has no effect. + + + +
+
+
+ +
+ Product, Component, Milestone, and Version Administration + + + Dear Lord, we have to get our users to do WHAT? + + + +
+ Products + Formerly, and in some spots still, called "Programs" + + Products are the + broadest category in Bugzilla, and you should have the least of these. + If your company makes computer games, you should have one product per game, + and possibly a few special products + (website, meetings...) + + + A Product (formerly called "Program", and still referred to that way + in some portions of the source code) controls some very important functions. + The number of "votes" available for users to vote for the most important bugs + is set per-product, as is the number of votes required to move a bug automatically + from the UNCONFIRMED status to the NEW status. One can close a Product for further + bug entry and define various Versions available from the Edit Product screen. + + To create a new product: + + + + Select "components" from the yellow footer + + + + It may seem counterintuitive to click "components" when you want + to edit the properties associated with Products. This is one of a long + list of things we want in Bugzilla 3.0... + + + + + + Select the "Add" link to the right of "Add a new product". + + + + + Enter the name of the product and a description. + The Description field is free-form. + + + + + + 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. + + +
- - On the product edit page, there is a page to edit the - Group Controls - for a product and determine which groups are applicable, default, - and mandatory for each product as well as controlling entry - for each product and being able to set bugs in a product to be - totally read-only unless some group restrictions are met. - +
+ Components + + Components are subsections of a Product. + + + Creating some Components + + + The computer game you are designing may a "UI" component, an "API" component, + a "Sound System" component, and a "Plugins" component, each overseen by a different + programmer. It often makes sense to divide Components in Bugzilla according to the + natural divisions of responsibility within your Product or company. + + + + + Each component has a owner and (if you turned it on in the parameters), a qa + contact. The owner should be the primary person who fixes bugs in that component. The QA + Contact should be the person who will ensure these bugs are completely fixed. The Owner, + QA Contact, and Reporter will get email when new bugs are created in this Component and + when these bugs change. Default Owner and Default QA Contact fields only dictate the + default assignments; the Owner and Q/A Contact fields in a bug + are otherwise unrelated to the Component. + + + + To create a new Component: + + + + + Select the "Edit components" link from the "Edit Product" page + + + + + Select the "Add" link to the right of the "Add a new component" text + on the "Select Component" page. + + + + + Fill out the "Component" field, a short "Description", and the "Initial Owner". + The "Component" field should not contain a space. The "Description" field is + free-form. The "Initial Owner" field must be that of a valid user already + existing in the database. If the initial owner does not exist, Bugzilla + will refuse to create the component. + + + Is your "Default Owner" a user who is not yet in the database? + No problem. + + + + Select the "Log out" link on the footer of the page. + + + + + Select the "New Account" link on the footer of the "Relogin" page + + + + + Type in the email address of the default owner you want to create + in the "E-mail address" field, and her full name in the "Real name" + field, then select the "Submit Query" button. + + + + + Now select "Log in" again, type in your login information, and you + can modify the product to use the Default Owner information + you require. + + + + + + + + + + Either "edit" more components or return to the "query" page on the ensuing + "Addming new component" page. To return to the Product you were editing, you + must select the "components" link as before. + + + +
- - For each group, it is possible to specify if membership in that - group is... - - - - - required for bug entry, - - - - - Not applicable to this product(NA), - a possible restriction for a member of the - group to place on a bug in this product(Shown), - a default restriction for a member of the - group to place on a bug in this product(Default), - or a mandatory restriction to be placed on bugs - in this product(Mandatory). - - - - - Not applicable by non-members to this product(NA), - a possible restriction for a non-member of the - group to place on a bug in this product(Shown), - a default restriction for a non-member of the - group to place on a bug in this product(Default), - or a mandatory restriction to be placed on bugs - in this product when entered by a non-member(Mandatory). - - - - - required in order to make any change - to bugs in this product including comments. - - - +
+ Versions + + Versions are the revisions of the product, such as "Flinders 3.1", "Flinders 95", + and "Flinders 2000". Using Versions helps you isolate code changes and are an aid + in reporting. + + + Common Use of Versions + + + A user reports a bug + against Version "Beta 2.0" of your product. The current Version of your software + is "Release Candidate 1", and no longer has the bug. This will + help you triage and classify bugs according to their relevance. It is also + possible people may report bugs against bleeding-edge beta versions that are + not evident in older versions of the software. This can help isolate code + changes that caused the bug + + + + + A Different Use of Versions + + + This field has been used to good effect by an online service provider in a slightly + different way. They had three versions of the product: "Production", "QA", + and "Dev". Although it may be the same product, a bug in the development + environment is not normally as critical as a Production bug, nor does it + need to be reported publicly. When used in conjunction with Target Milestones, + one can easily specify the environment where a bug can be reproduced, and + the Milestone by which it will be fixed. + + + + + + To create and edit Versions: + + + + + From the "Edit Product" screen, select "Edit Versions" + + + + + You will notice that the product already has the default version "undefined". + If your product doesn't use version numbers, you may want to leave this as it is + or edit it so that it is "---". You can then go back to the edit versions page + and add new versions to your product. + + + Otherwise, click the "Add" button to the right of the "Add a new version" text. + + + + + Enter the name of the Version. This can be free-form characters up to the limit of the + text box. Then select the "Add" button. + + + + + At this point you can select "Edit" to edit more Versions, or return to the "Query" + page, from which you can navigate back to the product through the "components" link + at the foot of the Query page. + + + +
- To create Groups: - - - - Select the groups - link in the footer. - - - - Take a moment to understand the instructions on the Edit - Groups screen, then select the Add Group link. - - - - Fill out the Group, Description, - and User RegExp fields. - User RegExp allows you to automatically - place all users who fulfill the Regular Expression into the new group. - When you have finished, click Add. - - 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. - - - - After you add your new group, edit the new group. On the - edit page, you can specify other groups that should be included - in this group and which groups should be permitted to add and delete - users from this group. - - - - - Note that group permissions are such that you need to be a member - of all the groups a bug is in, for whatever - reason, to see that bug. Similarly, you must be a member - of all of the entry groups for a product - to add bugs to a product and you must be a member - of all of the canedit groups for a product - in order to make any change to bugs in that - product. - -
- -
- Upgrading to New Releases - - - 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. - - - - Upgrading Bugzilla is something we all want to do from time to time, - be it to get new features or pick up the latest security fix. How easy - it is to update depends on a few factors. - - - - - If the new version is a revision or a new point release - - - How many, if any, local changes have been made - - - - There are also three different methods to upgrade your installation. - - - - - Using CVS () - - - Downloading a new tarball () - - - Applying the relevant patches () - - - - Which options are available to you may depend on how large a jump - you are making and/or your network configuration. - - - Revisions are normally released to fix security vulnerabilities - and are distinguished by an increase in the third number. For example, - when 2.16.2 was released, it was a revision to 2.16.1. - - - Point releases are normally released when the Bugzilla team feels - that there has been a significant amount of progress made between the - last point release and the current time. These are often proceeded by a - stabilization period and release candidates, however the use of - development versions or release candidates is beyond the scope of this - document. Point releases can be distinguished by an increase in the - second number, or minor version. For example, 2.16.2 is a newer point - release than 2.14.5. - - - The examples in this section are written as if you were updating - to version 2.16.2. The procedures are the same regardless if you are - updating to a new point release or a new revision. However, the chance - of running into trouble increases when upgrading to a new point release, - escpecially if you've made local changes. - - - These examples also assume that your Bugzilla installation is at - /var/www/html/bugzilla. If that is not the case, - simply substitute the proper paths where appropriate. - - - - Upgrading using CVS - - Every release of Bugzilla, whether it is a revision or a point - release, is tagged in CVS. Also, every tarball we have distributed - since version 2.12 has been primed for using CVS. This does, however, - require that you are able to access cvs-mirror.mozilla.org on port - 2401. - - - If you can do this, updating using CVS is probably the most - painless method, especially if you have a lot of local changes. - - - - - -bash$ cd /var/www/html/bugzilla -bash$ cvs login -Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401/cvsroot -CVS password: anonymous -bash$ cvs -q update -r BUGZILLA-2_16_2 -dP -P checksetup.pl -P collectstats.pl -P globals.pl -P docs/rel_notes.txt -P template/en/default/list/quips.html.tmpl - - - - - If a line in the output from cvs update - begins with a C that represents a - file with local changes that CVS was unable to properly merge. You - need to resolve these conflicts manually before Bugzilla (or at - least the portion using that file) will be usable. - - - - - You also need to run ./checksetup.pl - before your Bugzilla upgrade will be complete. - - - - - - - Upgrading using the tarball - - If you are unable or unwilling to use CVS, another option that's - always available is to download the latest tarball. This is the most - difficult option to use, especially if you have local changes. - - - -bash$ cd /var/www/html -bash$ wget ftp://ftp.mozilla.org/pub/webtools/bugzilla-2.16.2.tar.gz -Output omitted -bash$ tar xzvf bugzilla-2.16.2.tar.gz -bugzilla-2.16.2/ -bugzilla-2.16.2/.cvsignore -bugzilla-2.16.2/1x1.gif -Output truncated -bash$ cd bugzilla-2.16.2 -bash$ cp ../bugzilla/localconfig* . -bash$ cp -r ../bugzilla/data . -bash$ cd .. -bash$ mv bugzilla bugzilla.old -bash$ mv bugzilla-2.16.2 bugzilla -bash$ cd bugzilla -bash$ ./checksetup.pl -Output omitted - - - - - The cp commands both end with periods which - is a very important detail, it tells the shell that the destination - directory is the current working directory. Also, the period at the - beginning of the ./checksetup.pl is important and - can not be omitted. - - - - - You will now have to reapply any changes you have made to your - local installation manually. - - - - - - - Upgrading using patches - - The Bugzilla team will normally make a patch file available for - revisions to go from the most recent revision to the new one. You could - also read the release notes and grab the patches attached to the - mentioned bug, but it is safer to use the released patch file as - sometimes patches get changed before they get checked in. - 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. - - - -bash$ cd /var/www/html/bugzilla -bash$ wget ftp://ftp.mozilla.org/pub/webtools/bugzilla-2.16.1-to-2.16.2.diff.gz -Output omitted -bash$ gunzip bugzilla-2.16.1-to-2.16.2.diff.gz -bash$ patch -p1 < bugzilla-2.16.1-to-2.16.2.diff -patching file checksetup.pl -patching file collectstats.pl -patching file globals.pl - - - - - If you do this, beware that this doesn't change the entires in - your CVS directory so it may make - updates using CVS () more difficult in the - future. - - - - +
+ Milestones + + Milestones are "targets" that you plan to get a bug fixed by. For example, you have a bug that + you plan to fix for your 3.0 release, it would be assigned the milestone of 3.0. Or, you have a + bug that you plan to fix for 2.8, this would have a milestone of 2.8. + + + + Milestone options will only appear for a Product if you turned the "usetargetmilestone" field + in the "Edit Parameters" screen "On". + + + + To create new Milestones, set Default Milestones, and set Milestone URL: + + + + + Select "edit milestones" + + + + + Select "Add" to the right of the "Add a new milestone" text + + + + + Enter the name of the Milestone in the "Milestone" field. + You can optionally set the "Sortkey", which is a positive or negative number (-255 to 255) + that defines where in the list this particular milestone appears. + Select "Add". + + + Using SortKey with Target Milestone + + + Let's say you create a target milestone called "Release 1.0", with Sortkey set to "0". + Later, you realize that you will have a public beta, called "Beta1". + You can create a Milestone called "Beta1", with a Sortkey of "-1" in order to ensure + people will see the Target Milestone of "Beta1" earlier on the list than "Release 1.0" + + + + + + + If you want to add more milestones, select the "Edit" link. + If you don't, well shoot, you have to go back to the "query" page and select "components" + again, and make your way back to the Product you were editing. + + + This is another in the list of unusual user interface decisions that + we'd like to get cleaned up. Shouldn't there be a link to the effect of + "edit the Product I was editing when I ended up here"? In any case, + clicking "components" in the footer takes you back to the "Select product" + screen, from which you can begin editing your product again. + + + + + + + From the Edit Product screen again (once you've made your way back), enter the URL + for a description of what your milestones are for this product in the "Milestone URL" field. + It should be of the format "http://www.foo.com/bugzilla/product_milestones.html" + + + Some common uses of this field include product descriptions, product roadmaps, + and of course a simple description of the meaning of each milestone. + + + + + If you're using Target Milestones, the "Default Milestone" field must have some + kind of entry. If you really don't care if people set coherent Target Milestones, + simply leave this at the default, "---". However, controlling and regularly updating the Default + Milestone field is a powerful tool when reporting the status of projects. + + Select the "Update" button when you are done. + + + + + + + +
+ +
+ Voting + + The concept of "voting" is a poorly understood, yet powerful feature for the management + of open-source projects. Each user is assigned so many Votes per product, which they can + freely reassign (or assign multiple votes to a single bug). + This allows developers to gauge user need for a particular enhancement + or bugfix. By allowing bugs with a certain number of votes to automatically move from + "UNCONFIRMED" to "NEW", users of the bug system can help high-priority bugs garner + attention so they don't sit for a long time awaiting triage. + + + The daunting challenge of Votes is deciding where you draw the line for a "vocal majority". If you + only have a user base of 100 users, setting a low threshold for bugs to move from UNCONFIRMED + to NEW makes sense. As the Bugzilla user base expands, however, these thresholds must be + re-evaluated. You should gauge whether this feature is worth the time and close monitoring involved, + and perhaps forego implementation until you have a critical mass of users who demand it. + + To modify Voting settings: + + + + Navigate to the "Edit Product" screen for the Product you wish to modify + + + + + Set "Maximum Votes per person" to your calculated value. Setting this field + to "0" disables voting. + + + + + Set "Maximum Votes a person can put on a single bug" to your calculated value. It + should probably be some number lower than the "Maximum votes per person". + Setting this field to "0" disables voting, but leaves the voting options open + to the user. This is confusing. + + + + + Set "Number of votes a bug in this product needs to automatically get out of the + UNCONFIRMED state" to your calculated number. Setting this field to "0" + disables the automatic move of bugs from UNCONFIRMED to NEW. Some people + advocate leaving this at "0", but of what use are Votes if your Bugzilla + user base is unable to affect which bugs appear on Development radar? + + + You should probably set this number to higher than a small coalition of + Bugzilla users can influence it. Most sites use this as a "referendum" + mechanism -- if users are able to vote a bug out of UNCONFIRMED, it + is a really bad bug! + + + + + + + Once you have adjusted the values to your preference, select the "Update" button. + + + +
+ +
+ Groups and Group Security + + Groups can be very useful in bugzilla, because they allow users to isolate + bugs or products that should only be seen by certain people. Groups can also + be a complicated minefield of interdependencies and weirdness if mismanaged. + + + When to Use Group Security + + + Many Bugzilla sites isolate "Security-related" bugs from all other bugs. + This way, they can have a fix ready before the security vulnerability + is announced to the world. You can create a "Security" product which, by + default, has no members, and only add members to the group (in their individual + User page, as described under User Administration) who should have + priveleged access to "Security" bugs. Alternately, you may create a Group + independently of any Product, and change the Group mask on individual bugs + to restrict access to members only of certain Groups. + + + + + Groups only work if you enable the "usebuggroups" paramater. + In addition, if the "usebuggroupsentry" parameter is "On", one can restrict access + to products by groups, so that only members of a product group are able to view + bugs within that product. + Group security in Bugzilla can be divided into two categories: + Generic and Product-Based. + + + + Groups in Bugzilla are a complicated beast that evolved out of very simple user + permission bitmasks, apparently itself derived from common concepts in UNIX access + controls. A "bitmask" is a fixed-length number whose value can describe one, and + only one, set of states. For instance, UNIX file permissions are assigned bitmask + values: "execute" has a value of 1, "write" has a value of 2, + and "read" has a value of 4. Add them together, + and a file can be read, written to, and executed if it has a bitmask of "7". (This + is a simplified example -- anybody who knows UNIX security knows there is much + more to it than this. Please bear with me for the purpose of this note.) The only + way a bitmask scheme can work is by doubling the bit count for each value. Thus + if UNIX wanted to offer another file permission, the next would have to be a value of + 8, then the next 16, the next 32, etc. + + + Similarly, Bugzilla offers a bitmask to define group permissions, with an internal + limit of 64. Several are already occupied + by built-in permissions. The way around this limitation is + to avoid assigning groups to products if you have many products, avoid bloating + of group lists, and religiously prune irrelevant groups. In reality, most installations + of Bugzilla support far fewer than 64 groups, so this limitation has not hit + for most sites, but it is on the table to be revised for Bugzilla 3.0 + because it interferes with the security schemes of some administrators. + + + + To enable Generic Group Security ("usebuggroups"): + + + + + Turn "On" "usebuggroups" in the "Edit Parameters" screen. + + + + + You will generally have no groups set up. Select the "groups" link + in the footer. + + + + + Take a moment to understand the instructions on the "Edit Groups" screen. + Once you feel confident you understand what is expected of you, select the + "Add Group" link. + + + + + Fill out the "New Name" (remember, no spaces!), "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. + + + Creating a New Group + + + I created a group called "DefaultGroup" with a description of "This is simply + a group to play with", and a "New User RegExp" of "*@velio.com". This + new group automatically includes all Bugzilla users with "@velio.com" at the + end of their user id. When I finished, my new group was assigned bit #128. + + + + + When you have finished, select the "Add" button. + + + + + + To enable Product-Based Group Security ("usebuggroupsentry"): + + + + Don't forget that you only have 64 groups masks available, total, for + your installation of Bugzilla! If you plan on having more than 50 + products in your individual Bugzilla installation, and require group + security for your products, you should + consider either running multiple Bugzillas or using Generic Group Security + instead of Product-Based ("usebuggroupsentry") Group Security. + + + + + + Turn "On" "usebuggroups" and "usebuggroupsentry" in the "Edit Parameters" screen. + + + + "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. + + + + + + You will generally have no Groups set up, unless you enabled "usebuggroupsentry" + prior to creating any Products. To create "Generic Group Security" groups, + follow the instructions given above. To create Product-Based Group security, + simply follow the instructions for creating a new Product. If you need to + add users to these new groups as you create them, you will find the option + to add them to the group available under the "Edit User" screens. + + + +
+
+ +
+ Bugzilla Security + + + Putting your money in a wall safe is better protection than depending on the fact that + no one knows that you hide your money in a mayonnaise jar in your fridge. + + + + + Poorly-configured MySQL, Bugzilla, and FTP 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. + + + + First thing's first: Secure your installation. + + + 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 mozilla-webtools@mozilla.org + + + + + + Ensure you are running at least MysQL version 3.22.32 or newer. Earlier versions had + notable security holes and poorly secured default configuration choices. + + + + There is no substitute for understanding the tools on your system! + Read + The MySQL Privelege System until you can recite it from memory! + + At the very least, ensure you password the "mysql -u root" account and the "bugs" account, establish grant + table rights (consult the Keystone guide in Appendix C: The Bugzilla Database for some easy-to-use details) + that do not allow CREATE, DROP, RELOAD, SHUTDOWN, and PROCESS for user "bugs". I wrote up the Keystone + advice back when I knew far less about security than I do now : ) + + + + + 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. + + + + Do not run Apache as "nobody". 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. + + + + Ensure you have adequate access controls for the $BUGZILLA_HOME/data/ and + $BUGZILLA_HOME/shadow/ directories, as well as the $BUGZILLA_HOME/localconfig file. + The localconfig file stores your "bugs" user password, + which would be terrible to have in the hands + of a criminal. Also some files under $BUGZILLA_HOME/data/ store sensitive information, and + $BUGZILLA_HOME/shadow/ stores bug information for faster retrieval. If you fail to secure + these directories and this file, you will expose bug information to those who may not + be allowed to see it. + + + On Apache, you can use .htaccess files to protect access to these directories, as outlined + in Bug 57161 for the + localconfig file, and + Bug 65572 for adequate protection in your data/ and shadow/ directories. + + + 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. + + + Place the following text into a file named ".htaccess", readable by your web server, + in your $BUGZILLA_HOME/data directory. + + <Files comments> + allow from all + </Files> + deny from all + + + + Place the following text into a file named ".htaccess", readable by your web server, + in your $BUGZILLA_HOME/ directory. + + <Files localconfig> + deny from all + </Files> + allow from all + + + + Place the following text into a file named ".htaccess", readable by your web server, + in your $BUGZILLA_HOME/shadow directory. + + deny from all + + + + + +
+ -
- - -- cgit v1.2.3-24-g4f1b