From 78e29c8900fa96d67163a34a0c02c7cecb31b55f Mon Sep 17 00:00:00 2001 From: "jake%bugzilla.org" <> Date: Wed, 23 Apr 2003 09:04:01 +0000 Subject: The source files for the Bugzilla Guide have long been using the XML version of DocBook but still residing in the sgml/ directory with an extension of .sgml. In an effort to maintain CVS history, the raw files were copied on the CVS server to the xml/ directory and renamed to have .xml for the extension; any checkins before this one did have the .sgml extension. --- docs/sgml/administration.sgml | 1640 ----------------------------------------- 1 file changed, 1640 deletions(-) delete mode 100644 docs/sgml/administration.sgml (limited to 'docs/sgml/administration.sgml') diff --git a/docs/sgml/administration.sgml b/docs/sgml/administration.sgml deleted file mode 100644 index f04e2b5ce..000000000 --- a/docs/sgml/administration.sgml +++ /dev/null @@ -1,1640 +0,0 @@ - - - Administering Bugzilla - -
- Bugzilla Configuration - - Bugzilla is configured by changing various parameters, accessed - from the "Edit parameters" link in the page footer. Here are - some of the key parameters on that page. You should run down this - list and set them appropriately after installing Bugzilla. - - - checklist - - - - - - maintainer: - The maintainer parameter is the email address of the person - responsible for maintaining this - Bugzilla installation. The address need not be that of a valid Bugzilla - account. - - - - - urlbase: - This parameter defines the fully qualified domain name and web - server path to your Bugzilla installation. - - For example, if your Bugzilla query page is - http://www.foo.com/bugzilla/query.cgi, - set your urlbase - to http://www.foo.com/bugzilla/. - - - - - makeproductgroups: - This dictates whether or not to automatically create groups - when new products are created. - - - - - - useentrygroupdefault: - Bugzilla products can have a group associated with them, so that - certain users can only see bugs in certain products. When this - parameter is set to on, this - causes the initial group controls on newly created products - to place all newly-created bugs in the group - having the same name as the product immediately. - After a product is initially created, the group controls - can be further adjusted without interference by - this mechanism. - - - - - shadowdb: - You run into an interesting problem when Bugzilla reaches a - high level of continuous activity. MySQL supports only table-level - write locking. What this means is that if someone needs to make a - change to a bug, they will lock the entire table until the operation - is complete. Locking for write also blocks reads until the write is - complete. Note that more recent versions of mysql support row level - locking using different table types. These types are slower than the - standard type, and Bugzilla does not yet take advantage of features - such as transactions which would justify this speed decrease. The - Bugzilla team are, however, happy to hear about any experiences with - row level locking and Bugzilla - - The shadowdb - parameter was designed to get around this limitation. While only a - single user is allowed to write to a table at a time, reads can - continue unimpeded on a read-only shadow copy of the database. - Although your database size will double, a shadow database can cause - an enormous performance improvement when implemented on extremely - high-traffic Bugzilla databases. - - - As a guide, mozilla.org began needing - shadowdb - when they reached around 40,000 Bugzilla users with several hundred - Bugzilla bug changes and comments per day. - - The value of the parameter defines the name of the - shadow bug database. You will need to set the host and port settings - from the params page, and set up replication in your database server - so that updates reach this readonly mirror. Consult your database - documentation for more detail. - - - - - shutdownhtml: - - If you need to shut down Bugzilla to perform administration, enter - some descriptive HTML here and anyone who tries to use Bugzilla will - receive a page to that effect. Obviously, editparams.cgi will - still be accessible so you can remove the HTML and re-enable Bugzilla. - :-) - - - - - - passwordmail: - - Every time a user creates an account, the text of - this parameter (with substitutions) is sent to the new user along with - their password message. - - Add any text you wish to the "passwordmail" parameter box. For - instance, many people choose to use this box to give a quick training - blurb about how to use Bugzilla at your site. - - - - - - movebugs: - - This option is an undocumented feature to allow moving bugs - between separate Bugzilla installations. You will need to understand - the source code in order to use this feature. Please consult - movebugs.pl in your Bugzilla source tree for - further documentation, such as it is. - - - - - - useqacontact: - - This allows you to define an email address for each component, in - addition - to that of the default owner, who will be sent carbon copies of - incoming bugs. - - - - usestatuswhiteboard: - This defines whether you wish to have a free-form, overwritable field - associated with each bug. The advantage of the Status Whiteboard is - that it can be deleted or modified with ease, and provides an - easily-searchable field for indexing some bugs that have some trait - in common. - - - - - - whinedays: - Set this to the number of days you want to let bugs go - in the NEW or REOPENED state before notifying people they have - untouched new bugs. If you do not plan to use this feature, simply do - not set up the whining cron job described in the installation - instructions, or set this value to "0" (never whine). - - - - - commenton*: - All these - fields allow you to dictate what changes can pass without comment, - and which must have a comment from the person who changed them. - Often, administrators will allow users to add themselves to the CC - list, accept bugs, or change the Status Whiteboard without adding a - comment as to their reasons for the change, yet require that most - other changes come with an explanation. - - Set the "commenton" options according to your site policy. It - is a wise idea to require comments when users resolve, reassign, or - reopen bugs at the very least. - - It is generally far better to require a developer comment - when resolving bugs than not. Few things are more annoying to bug - database users than having a developer mark a bug "fixed" without - any comment as to what the fix was (or even that it was truly - fixed!) - - - - - - - supportwatchers: - - Turning on this option allows users to ask to receive copies of - all a particular other user's bug email. This is, of - course, subject to the groupset restrictions on the bug; if the - watcher - would not normally be allowed to view a bug, the watcher cannot get - around the system by setting herself up to watch the bugs of someone - with bugs outside her privileges. They would still only receive email - updates for those bugs she could normally view. - - -
- -
- User Administration - -
- Creating the Default User - - When you first run checksetup.pl after installing Bugzilla, it - will prompt you for the administrative username (email address) and - password for this "super user". If for some reason you delete - the "super user" account, re-running checksetup.pl will again prompt - you for this username and password. - - - If you wish to add more administrative users, add them to - the "admin" group and, optionally, add edit the tweakparams, editusers, - creategroups, editcomponents, and editkeywords groups to add the - entire admin group to those groups. - - -
- -
- Managing Other Users - -
- Creating new users - - Your users can create their own user accounts by clicking the - "New Account" link at the bottom of each page (assuming they - aren't logged in as someone else already.) However, should you - desire to create user accounts ahead of time, here is how you do - it. - - - - After logging in, click the "Users" link at the footer of - the query page, and then click "Add a new user". - - - - Fill out the form presented. This page is self-explanatory. - When done, click "Submit". - - - Adding a user this way will - not - - send an email informing them of their username and password. - While useful for creating dummy accounts (watchers which - shuttle mail to another system, for instance, or email - addresses which are a mailing list), in general it is - preferable to log out and use the - New Account - - button to create users, as it will pre-populate all the - required fields and also notify the user of her account name - and password. - - - -
- -
- Modifying Users - - To see a specific user, search for their login name - in the box provided on the "Edit Users" page. To see all users, - leave the box blank. - - You can search in different ways the listbox to the right - of the text entry box. You can match by - case-insensitive substring (the default), - regular expression, or a - reverse - regular expression match, which finds every user name which does NOT - match the regular expression. (Please see - the man regexp - manual page for details on regular expression syntax.) - - - Once you have found your user, you can change the following - fields: - - - - - Login Name: - This is generally the user's full email address. However, if you - have are using the emailsuffix Param, this may just be the user's - login name. Note that users can now change their login names - themselves (to any valid email address.) - - - - - - Real Name: The user's real name. Note that - Bugzilla does not require this to create an account. - - - - - Password: - You can change the user's password here. Users can automatically - request a new password, so you shouldn't need to do this often. - If you want to disable an account, see Disable Text below. - - - - - - Disable Text: - If you type anything in this box, including just a space, the - user is prevented from logging in, or making any changes to - bugs via the web interface. - The HTML you type in this box is presented to the user when - they attempt to perform these actions, and should explain - why the account was disabled. - - Don't disable the administrator account! - - - - The user can still submit bugs via - the e-mail gateway, if you set it up, even if the disabled text - field is filled in. The e-mail gateway should - not - be enabled for secure installations of Bugzilla. - - - - - - - <groupname>: - If you have created some groups, e.g. "securitysensitive", then - checkboxes will appear here to allow you to add users to, or - remove them from, these groups. - - - - - - canconfirm: - This field is only used if you have enabled the "unconfirmed" - status. If you enable this for a user, - that user can then move bugs from "Unconfirmed" to a "Confirmed" - status (e.g.: "New" status). - - - - - creategroups: - This option will allow a user to create and destroy groups in - Bugzilla. - - - - - editbugs: - Unless a user has this bit set, they can only edit those bugs - for which they are the assignee or the reporter. Even if this - option is unchecked, users can still add comments to bugs. - - - - - - editcomponents: - This flag allows a user to create new products and components, - as well as modify and destroy those that have no bugs associated - with them. If a product or component has bugs associated with it, - those bugs must be moved to a different product or component - before Bugzilla will allow them to be destroyed. - - - - - - editkeywords: - If you use Bugzilla's keyword functionality, enabling this - feature allows a user to create and destroy keywords. As always, - the keywords for existing bugs containing the keyword the user - wishes to destroy must be changed before Bugzilla will allow it - to die. - - - - - editusers: - This flag allows a user to do what you're doing right now: edit - other users. This will allow those with the right to do so to - remove administrator privileges from other users or grant them to - themselves. Enable with care. - - - - - - tweakparams: - This flag allows a user to change Bugzilla's Params - (using editparams.cgi.) - - - - - <productname>: - This allows an administrator to specify the products in which - a user can see bugs. The user must still have the - "editbugs" privilege to edit bugs in these products. - - -
-
-
- -
- Product, Component, Milestone, and Version Administration - -
- Products - - - - Products - - are the broadest category in Bugzilla, and tend to represent real-world - shipping products. E.g. if your company makes computer games, - you should have one product per game, perhaps a "Common" product for - units of technology used in multiple games, and maybe a few special - products (Website, Administration...) - - Many of Bugzilla's settings are configurable on a per-product - basis. The number of "votes" available to users is set per-product, - as is the number of votes - required to move a bug automatically from the UNCONFIRMED status to the - NEW status. - - To create a new product: - - - - Select "products" from the footer - - - - - Select the "Add" link in the bottom right - - - - Enter the name of the product and a description. The - Description field may contain HTML. - - - - Don't worry about the "Closed for bug entry", "Maximum Votes - per person", "Maximum votes a person can put on a single bug", - "Number of votes a bug in this Product needs to automatically get out - of the UNCOMFIRMED state", and "Version" options yet. We'll cover - those in a few moments. - -
- -
- Components - - Components are subsections of a Product. E.g. the computer game - you are designing may have a "UI" - component, an "API" component, a "Sound System" component, and a - "Plugins" component, each overseen by a different programmer. It - often makes sense to divide Components in Bugzilla according to the - natural divisions of responsibility within your Product or - company. - - - Each component has a owner and (if you turned it on in the parameters), - a QA Contact. The owner should be the primary person who fixes bugs in - that component. The QA Contact should be the person who will ensure - these bugs are completely fixed. The Owner, QA Contact, and Reporter - will get email when new bugs are created in this Component and when - these bugs change. Default Owner and Default QA Contact fields only - dictate the - default assignments; - these can be changed on bug submission, or at any later point in - a bug's life. - - To create a new Component: - - - - Select the "Edit components" link from the "Edit product" - page - - - - Select the "Add" link in the bottom right. - - - - Fill out the "Component" field, a short "Description", - the "Initial Owner" and "Initial QA Contact" (if enabled.) - The Component and Description fields may contain HTML; - the "Initial Owner" field must be a login name - already existing in the database. - - - -
- -
- Versions - - Versions are the revisions of the product, such as "Flinders - 3.1", "Flinders 95", and "Flinders 2000". Version is not a multi-select - field; the usual practice is to select the most recent version with - the bug. - - - To create and edit Versions: - - - - From the "Edit product" screen, select "Edit Versions" - - - - You will notice that the product already has the default - version "undefined". Click the "Add" link in the bottom right. - - - - Enter the name of the Version. This field takes text only. - Then click the "Add" button. - - - -
- -
- Milestones - - Milestones are "targets" that you plan to get a bug fixed by. For - example, you have a bug that you plan to fix for your 3.0 release, it - would be assigned the milestone of 3.0. - - - Milestone options will only appear for a Product if you turned - on the "usetargetmilestone" Param in the "Edit Parameters" screen. - - - - To create new Milestones, set Default Milestones, and set - Milestone URL: - - - - Select "Edit milestones" from the "Edit product" page. - - - - Select "Add" in the bottom right corner. - text - - - - Enter the name of the Milestone in the "Milestone" field. You - can optionally set the "sortkey", which is a positive or negative - number (-255 to 255) that defines where in the list this particular - milestone appears. This is because milestones often do not - occur in alphanumeric order For example, "Future" might be - after "Release 1.2". Select "Add". - - - - From the Edit product screen, you can enter the URL of a - page which gives information about your milestones and what - they mean. - - - If you want your milestone document to be restricted so - that it can only be viewed by people in a particular Bugzilla - group, the best way is to attach the document to a bug in that - group, and make the URL the URL of that attachment. - - - -
-
- -
- Voting - - Voting allows users to be given a pot of votes which they can allocate - to bugs, to indicate that they'd like them fixed. - This allows developers to gauge - user need for a particular enhancement or bugfix. By allowing bugs with - a certain number of votes to automatically move from "UNCONFIRMED" to - "NEW", users of the bug system can help high-priority bugs garner - attention so they don't sit for a long time awaiting triage. - - To modify Voting settings: - - - - Navigate to the "Edit product" screen for the Product you - wish to modify - - - - Maximum Votes per person: - Setting this field to "0" disables voting. - - - - Maximum Votes a person can put on a single - bug": - It should probably be some number lower than the - "Maximum votes per person". Don't set this field to "0" if - "Maximum votes per person" is non-zero; that doesn't make - any sense. - - - - Number of votes a bug in this product needs to - automatically get out of the UNCONFIRMED state: - Setting this field to "0" disables the automatic move of - bugs from UNCONFIRMED to NEW. - - - - - Once you have adjusted the values to your preference, click - "Update". - - -
- -
- Groups and Group Security - - Groups allow the administrator - to isolate bugs or products that should only be seen by certain people. - The association between products and groups is controlled from - the product edit page under Edit Group Controls. - - - - If the makeproductgroups param is on, a new group will be automatically - created for every new product. - - - - On the product edit page, there is a page to edit the - Group Controls - for a product and determine which groups are applicable, default, - and mandatory for each product as well as controlling entry - for each product and being able to set bugs in a product to be - totally read-only unless some group restrictions are met. - - - - For each group, it is possible to specify if membership in that - group is... - - - - - required for bug entry, - - - - - Not applicable to this product(NA), - a possible restriction for a member of the - group to place on a bug in this product(Shown), - a default restriction for a member of the - group to place on a bug in this product(Default), - or a mandatory restriction to be placed on bugs - in this product(Mandatory). - - - - - Not applicable by non-members to this product(NA), - a possible restriction for a non-member of the - group to place on a bug in this product(Shown), - a default restriction for a non-member of the - group to place on a bug in this product(Default), - or a mandatory restriction to be placed on bugs - in this product when entered by a non-member(Mandatory). - - - - - required in order to make any change - to bugs in this product including comments. - - - - - To create Groups: - - - - Select the groups - link in the footer. - - - - Take a moment to understand the instructions on the Edit - Groups screen, then select the Add Group link. - - - - Fill out the Group, Description, - and User RegExp fields. - User RegExp allows you to automatically - place all users who fulfill the Regular Expression into the new group. - When you have finished, click Add. - - The User Regexp is a perl regexp and, if not anchored, will match - any part of an address. So, if you do not want to grant access - into 'mycompany.com' to 'badperson@mycompany.com.hacker.net', use - '@mycompany\.com$' as the regexp. - - - - After you add your new group, edit the new group. On the - edit page, you can specify other groups that should be included - in this group and which groups should be permitted to add and delete - users from this group. - - - - - Note that group permissions are such that you need to be a member - of all the groups a bug is in, for whatever - reason, to see that bug. Similarly, you must be a member - of all of the entry groups for a product - to add bugs to a product and you must be a member - of all of the canedit groups for a product - in order to make any change to bugs in that - product. - -
- - -
- Bugzilla Security - - - Poorly-configured MySQL and Bugzilla installations have - given attackers full access to systems in the past. Please take these - guidelines seriously, even for Bugzilla machines hidden away behind - your firewall. 80% of all computer trespassers are insiders, not - anonymous crackers. - - - - These instructions must, of necessity, be somewhat vague since - Bugzilla runs on so many different platforms. If you have refinements - of these directions, please submit a bug to &bzg-bugs;. - - - - - This is not meant to be a comprehensive list of every possible - security issue regarding the tools mentioned in this section. There is - no subsitute for reading the information written by the authors of any - software running on your system. - - - -
- TCP/IP Ports - - - TCP/IP defines 65,000 some ports for trafic. Of those, Bugzilla - only needs 1... 2 if you need to use features that require e-mail such - as bug moving or the e-mail interface from contrib. You should audit - your server and make sure that you aren't listening on any ports you - don't need to be. You may also wish to use some kind of firewall - software to be sure that trafic can only be recieved on ports you - specify. - -
- -
- MySQL - - MySQL ships by default with many settings that should be changed. - By defaults it allows anybody to connect from localhost without a - password and have full administrative capabilities. It also defaults to - not have a root password (this is not the same as - the system root). Also, many installations default to running - mysqld as the system root. - - - - - Consult the documentation that came with your system for - information on making mysqld run as an - unprivleged user. - - - - - You should also be sure to disable the anonymous user account - and set a password for the root user. This is accomplished using the - following commands: - - -bash$ mysql mysql -mysql> DELETE FROM user WHERE user = ''; -mysql> UPDATE user SET password = password('new_password') WHERE user = 'root'; -mysql> FLUSH PRIVILEGES; - - From this point forward you will need to use - mysql -u root -p and enter - new_password when prompted when using the - mysql client. - - - - - If you run MySQL on the same machine as your httpd server, you - should consider disabling networking from within MySQL by adding - the following to your /etc/my.conf: - - -[myslqd] -# Prevent network access to MySQL. -skip-networking - - - - - You may also consider running MySQL, or even all of Bugzilla - in a chroot jail; however, instructions for doing that are beyond - the scope of this document. - - - - - -
- -
- Daemon Accounts - - Many daemons, such as Apache's httpd and MySQL's mysqld default to - running as either root or nobody. Running - as root introduces obvious security problems, but the - problems introduced by running everything as nobody may - not be so obvious. Basically, if you're running every daemon as - nobody and one of them gets comprimised, they all get - comprimised. For this reason it is recommended that you create a user - account for each daemon. - - - - You will need to set the webservergroup to - the group you created for your webserver to run as in - localconfig. This will allow - ./checksetup.pl to better adjust the file - permissions on your Bugzilla install so as to not require making - anything world-writable. - - - -
- -
- Web Server Access Controls - - There are many files that are placed in the Bugzilla directory - area that should not be accessable from the web. Because of the way - Bugzilla is currently layed out, the list of what should and should - not be accessible is rather complicated. A new installation method - is currently in the works which should solve this by allowing files - that shouldn't be accessible from the web to be placed in directory - outside the webroot. See - bug - 44659 for more information. - - - - - In the main Bugzilla directory, you should: - - - Block: - - *.pl - *localconfig* - runtests.sh - - - - - But allow: - - localconfig.js - localconfig.rdf - - - - - - - - In data: - - - Block everything - - - But allow: - - duplicates.rdf - - - - - - - - In data/webdot: - - - If you use a remote webdot server: - - - Block everything - - - But allow - - *.dot - - only for the remote webdot server - - - - - Otherwise, if you use a local GraphViz: - - - Block everything - - - But allow: - - *.png - *.gif - *.jpg - *.map - - - - - - - And if you don't use any dot: - - - Block everything - - - - - - - - In Bugzilla: - - - Block everything - - - - - - In template: - - - Block everything - - - - - - - Bugzilla ships with the ability to generate - .htaccess files instructing - Apache which files - should and should not be accessible. For more information, see - . - - - - You should test to make sure that the files mentioned above are - not accessible from the Internet, especially your - localconfig file which contains your database - password. To test, simply point your web browser at the file; for - example, to test mozilla.org's installation, we'd try to access - . You should - get a 403 Forbidden - error. - - - - Not following the instructions in this section, including - testing, may result in sensitive information being globally - accessible. - - - - - You should check to see if instructions - have been included for your web server. You should also compare those - instructions with this list to make sure everything is properly - accounted for. - - - -
- -
- -
- Template Customization - - - One of the large changes for 2.16 was the templatization of the - entire user-facing UI, using the - Template Toolkit. - Administrators can now configure the look and feel of Bugzilla without - having to edit Perl files or face the nightmare of massive merge - conflicts when they upgrade to a newer version in the future. - - - - Templatization also makes localized versions of Bugzilla possible, - for the first time. In the future, a Bugzilla installation may - have templates installed for multiple localizations, and select - which ones to use based on the user's browser language setting. - - -
- What to Edit - - There are two different ways of editing of Bugzilla's templates, - and which you use depends mainly on how you upgrade Bugzilla. The - template directory structure is that there's a top level directory, - template, which contains a directory for - each installed localization. The default English templates are - therefore in en. Underneath that, there - is the default directory and optionally the - custom directory. The default - directory contains all the templates shipped with Bugzilla, whereas - the custom directory does not exist at first and - must be created if you want to use it. - - - - The first method of making customizations is to directly edit the - templates in template/en/default. This is - probably the best method for small changes if you are going to use - the CVS method of upgrading, because if you then execute a - cvs update, any template fixes will get - automagically merged into your modified versions. - - - - If you use this method, your installation will break if CVS conflicts - occur. - - - - The other method is to copy the templates into a mirrored directory - structure under template/en/custom. The templates - in this directory automatically override those in default. - This is the technique you - need to use if you use the overwriting method of upgrade, because - otherwise your changes will be lost. This method is also better if - you are using the CVS method of upgrading and are going to make major - changes, because it is guaranteed that the contents of this directory - will not be touched during an upgrade, and you can then decide whether - to continue using your own templates, or make the effort to merge your - changes into the new versions by hand. - - - - If you use this method, your installation may break if incompatible - changes are made to the template interface. If such changes are made - they will be documented in the release notes, provided you are using a - stable release of Bugzilla. If you use using unstable code, you will - need to deal with this one yourself, although if possible the changes - will be mentioned before they occur in the deprecations section of the - previous stable release's release notes. - - - - - Don't directly edit the compiled templates in - data/template/* - your - changes will be lost when Template Toolkit recompiles them. - - -
- -
- How To Edit Templates - - - The syntax of the Template Toolkit language is beyond the scope of - this guide. It's reasonably easy to pick up by looking at the current - templates; or, you can read the manual, available on the - Template Toolkit home - page. However, you should particularly remember (for security - reasons) to always HTML filter things which come from the database or - user input, to prevent cross-site scripting attacks. - - - - However, one thing you should take particular care about is the need - to properly HTML filter data that has been passed into the template. - This means that if the data can possibly contain special HTML characters - such as <, and the data was not intended to be HTML, they need to be - converted to entity form, ie &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. - - - - Also note that Bugzilla adds a few filters of its own, that are not - in standard Template Toolkit. In particular, the 'url_quote' filter - can convert characters that are illegal or have special meaning in URLs, - such as &, to the encoded form, ie %26. This actually encodes most - characters (but not the common ones such as letters and numbers and so - on), including the HTML-special characters, so there's never a need to - HTML filter afterwards. - - - - Editing templates is a good way of doing a "poor man's custom fields". - For example, if you don't use the Status Whiteboard, but want to have - a free-form text entry box for "Build Identifier", then you can just - edit the templates to change the field labels. It's still be called - status_whiteboard internally, but your users don't need to know that. - - - - - If you are making template changes that you intend on submitting back - for inclusion in standard Bugzilla, you should read the relevant - sections of the - Developers' - Guide. - - -
- - -
- Template Formats - - - Some CGIs have the ability to use more than one template. For - example, buglist.cgi can output bug lists as RDF or two - different forms of HTML (complex and simple). (Try this out - by appending &format=simple to a buglist.cgi - URL on your Bugzilla installation.) This - mechanism, called template 'formats', is extensible. - - - - To see if a CGI supports multiple output formats, grep the - CGI for "ValidateOutputFormat". If it's not present, adding - multiple format support isn't too hard - see how it's done in - other CGIs. - - - - To make a new format template for a CGI which supports this, - open a current template for - that CGI and take note of the INTERFACE comment (if present.) This - comment defines what variables are passed into this template. If - there isn't one, I'm afraid you'll have to read the template and - the code to find out what information you get. - - - - Write your template in whatever markup or text style is appropriate. - - - - You now need to decide what content type you want your template - served as. Open up the localconfig file and find the - $contenttypes - variable. If your content type is not there, add it. Remember - the three- or four-letter tag assigned to you content type. - This tag will be part of the template filename. - - - - Save the template as <stubname>-<formatname>.<contenttypetag>.tmpl. - Try out the template by calling the CGI as - <cginame>.cgi?format=<formatname> . - -
- - -
- Particular Templates - - - There are a few templates you may be particularly interested in - customizing for your installation. - - - - index.html.tmpl: - This is the Bugzilla front page. - - - - global/header.html.tmpl: - This defines the header that goes on all Bugzilla pages. - The header includes the banner, which is what appears to users - and is probably what you want to edit instead. However the - header also includes the HTML HEAD section, so you could for - example add a stylesheet or META tag by editing the header. - - - - global/banner.html.tmpl: - This contains the "banner", the part of the header that appears - at the top of all Bugzilla pages. The default banner is reasonably - barren, so you'll probably want to customize this to give your - installation a distinctive look and feel. It is recommended you - preserve the Bugzilla version number in some form so the version - you are running can be determined, and users know what docs to read. - - - - global/footer.html.tmpl: - This defines the footer that goes on all Bugzilla pages. Editing - this is another way to quickly get a distinctive look and feel for - your Bugzilla installation. - - - - bug/create/user-message.html.tmpl: - This is a message that appears near the top of the bug reporting page. - By modifying this, you can tell your users how they should report - bugs. - - - - bug/process/midair.html.tmpl: - This is the page used if two people submit simultaneous changes to the - same bug. The second person to submit their changes will get this page - to tell them what the first person did, and ask if they wish to - overwrite those changes or go back and revisit the bug. The default - title and header on this page read "Mid-air collision detected!" If - you work in the aviation industry, or other environment where this - might be found offensive (yes, we have true stories of this happening) - you'll want to change this to something more appropriate for your - environment. - - - - bug/create/create.html.tmpl and - bug/create/comment.txt.tmpl: - You may wish to get bug submitters to give certain bits of structured - information, each in a separate input widget, for which there is not a - field in the database. The bug entry system has been designed in an - extensible fashion to enable you to define arbitrary fields and widgets, - and have their values appear formatted in the initial - Description, rather than in database fields. An example of this - is the mozilla.org - guided - bug submission form. - - - - To make this work, create a custom template for - enter_bug.cgi (the default template, on which you - could base it, is create.html.tmpl), - and either call it create.html.tmpl or use a format and - call it create-<formatname>.html.tmpl. - Put it in the custom/bug/create - directory. In it, add widgets for each piece of information you'd like - collected - such as a build number, or set of steps to reproduce. - - - - Then, create a template like - custom/bug/create/comment.txt.tmpl, also named - after your format if you are using one, which - references the form fields you have created. When a bug report is - submitted, the initial comment attached to the bug report will be - formatted according to the layout of this template. - - - - For example, if your enter_bug template had a field - <input type="text" name="buildid" size="30"> - and then your comment.txt.tmpl had - BuildID: [% form.buildid %] - then - BuildID: 20020303 - would appear in the initial checkin comment. - -
- -
- -
- Change Permission Customization - - - - This feature should be considered experimental; the Bugzilla code you - will be changing is not stable, and could change or move between - versions. Be aware that if you make modifications to it, you may have - to re-make them or port them if Bugzilla changes internally between - versions. - - - - - Companies often have rules about which employees, or classes of employees, - are allowed to change certain things in the bug system. For example, - only the bug's designated QA Contact may be allowed to VERIFY the bug. - Bugzilla has been - designed to make it easy for you to write your own custom rules to define - who is allowed to make what sorts of value transition. - - - - For maximum flexibility, customizing this means editing Bugzilla's Perl - code. This gives the administrator complete control over exactly who is - allowed to do what. The relevant function is called - CheckCanChangeField(), - and is found in process_bug.cgi in your - Bugzilla directory. If you open that file and grep for - "sub CheckCanChangeField", you'll find it. - - - - This function has been carefully commented to allow you to see exactly - how it works, and give you an idea of how to make changes to it. Certain - marked sections should not be changed - these are the "plumbing" which - makes the rest of the function work. In between those sections, you'll - find snippets of code like: - # Allow the owner to change anything. - if ($ownerid eq $whoid) { - return 1; - } - It's fairly obvious what this piece of code does. - - - - So, how does one go about changing this function? Well, simple changes - can be made just be removing pieces - for example, if you wanted to - prevent any user adding a comment to a bug, just remove the lines marked - "Allow anyone to change comments." And if you want the reporter to have - no special rights on bugs they have filed, just remove the entire section - which refers to him. - - - - More complex customizations are not much harder. Basically, you add - a check in the right place in the function, i.e. after all the variables - you are using have been set up. So, don't look at $ownerid before - $ownerid has been obtained from the database. You can either add a - positive check, which returns 1 (allow) if certain conditions are true, - or a negative check, which returns 0 (deny.) E.g.: - if ($field eq "qacontact") { - if (UserInGroup("quality_assurance")) { - return 1; - } - else { - return 0; - } - } - This says that only users in the group "quality_assurance" can change - the QA Contact field of a bug. Getting more weird: - if (($field eq "priority") && - ($vars->{'user'}{'login'} =~ /.*\@example\.com$/)) - { - if ($oldvalue eq "P1") { - return 1; - } - else { - return 0; - } - } - This says that if the user is trying to change the priority field, - and their email address is @example.com, they can only do so if the - old value of the field was "P1". Not very useful, but illustrative. - - - - For a list of possible field names, look in - data/versioncache for the list called - @::log_columns. If you need help writing custom - rules for your organization, ask in the newsgroup. - -
- -
- Upgrading to New Releases - - Upgrading Bugzilla is something we all want to do from time to time, - be it to get new features or pick up the latest security fix. How easy - it is to update depends on a few factors. - - - - - If the new version is a revision or a new point release - - - How many, if any, local changes have been made - - - - There are also three different methods to upgrade your installation. - - - - - Using CVS () - - - Downloading a new tarball () - - - Applying the relevant patches () - - - - Which options are available to you may depend on how large a jump - you are making and/or your network configuration. - - - Revisions are normally released to fix security vulnerabilities - and are distinguished by an increase in the third number. For example, - when 2.16.2 was released, it was a revision to 2.16.1. - - - Point releases are normally released when the Bugzilla team feels - that there has been a significant amount of progress made between the - last point release and the current time. These are often proceeded by a - stabilization period and release candidates, however the use of - development versions or release candidates is beyond the scope of this - document. Point releases can be distinguished by an increase in the - second number, or minor version. For example, 2.16.2 is a newer point - release than 2.14.5. - - - The examples in this section are written as if you were updating - to version 2.16.2. The procedures are the same regardless if you are - updating to a new point release or a new revision. However, the chance - of running into trouble increases when upgrading to a new point release, - escpecially if you've made local changes. - - - These examples also assume that your Bugzilla installation is at - /var/www/html/bugzilla. If that is not the case, - simply substitute the proper paths where appropriate. - - - - Upgrading using CVS - - Every release of Bugzilla, whether it is a revision or a point - release, is tagged in CVS. Also, every tarball we have distributed - since version 2.12 has been primed for using CVS. This does, however, - require that you are able to access cvs-mirror.mozilla.org on port - 2401. - - - If you can do this, updating using CVS is probably the most - painless method, especially if you have a lot of local changes. - - - - - -bash$ cd /var/www/html/bugzilla -bash$ cvs login -Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401/cvsroot -CVS password: anonymous -bash$ cvs -q update -r BUGZILLA-2_16_2 -dP -P checksetup.pl -P collectstats.pl -P globals.pl -P docs/rel_notes.txt -P template/en/default/list/quips.html.tmpl - - - - - If a line in the output from cvs update - begins with a C that represents a - file with local changes that CVS was unable to properly merge. You - need to resolve these conflicts manually before Bugzilla (or at - least the portion using that file) will be usable. - - - - - You also need to run ./checksetup.pl - before your Bugzilla upgrade will be complete. - - - - - - - Upgrading using the tarball - - If you are unable or unwilling to use CVS, another option that's - always available is to download the latest tarball. This is the most - difficult option to use, especially if you have local changes. - - - -bash$ cd /var/www/html -bash$ wget ftp://ftp.mozilla.org/pub/webtools/bugzilla-2.16.2.tar.gz -Output omitted -bash$ tar xzvf bugzilla-2.16.2.tar.gz -bugzilla-2.16.2/ -bugzilla-2.16.2/.cvsignore -bugzilla-2.16.2/1x1.gif -Output truncated -bash$ cd bugzilla-2.16.2 -bash$ cp ../bugzilla/localconfig* . -bash$ cp -r ../bugzilla/data . -bash$ cd .. -bash$ mv bugzilla bugzilla.old -bash$ mv bugzilla-2.16.2 bugzilla -bash$ cd bugzilla -bash$ ./checksetup.pl -Output omitted - - - - - The cp commands both end with periods which - is a very important detail, it tells the shell that the destination - directory is the current working directory. Also, the period at the - beginning of the ./checksetup.pl is important and - can not be omitted. - - - - - You will now have to reapply any changes you have made to your - local installation manually. - - - - - - - Upgrading using patches - - The Bugzilla team will normally make a patch file available for - revisions to go from the most recent revision to the new one. You could - also read the release notes and grab the patches attached to the - mentioned bug, but it is safer to use the released patch file as - sometimes patches get changed before they get checked in (for minor - spelling fixes and the like). It is also theorectically possible to - scour the fixed bug list and pick and choose which patches to apply - from a point release, but this is not recommended either as what you'll - end up with is a hodge podge Bugzilla that isn't really any version. - This would also make it more difficult to upgrade in the future. - - - -bash$ cd /var/www/html/bugzilla -bash$ wget ftp://ftp.mozilla.org/pub/webtools/bugzilla-2.16.1-to-2.16.2.diff.gz -Output omitted -bash$ gunzip bugzilla-2.16.1-to-2.16.2.diff.gz -bash$ patch -p1 < bugzilla-2.16.1-to-2.16.2.diff -patching file checksetup.pl -patching file collectstats.pl -patching file globals.pl - - - - - If you do this, beware that this doesn't change the entires in - your CVS directory so it may make - updates using CVS () more difficult in the - future. - - - - - -
- - - &integration; - - - - - -- cgit v1.2.3-24-g4f1b